This session outlines and explains Drupal 8 AJAX callback commands and how to use them. AJAX callback commands are the sets of PHP and JavaScript functions that control all AJAX functionality on a Drupal site. You will be surprised about how simple and straight forward they are. Mastering these commands will allow your AJAX calls to do so much more then just return rendered HTML. This session is presented in three parts. - First, explaining what AJAX callback commands are. - Second, explaining how to use AJAX callback commands. - Third, explaining how to create and use your own custom commands. Each section provides example code and a real world Drupal 8 scenario.

1. Demystifying AJAX Callback
Commands
(in Drupal 8)
2016.midcamp.org/node/48
MidCamp 2016
Background image modified version of "Chicago Bean" by Sergey Gabdurakhmanov

2. Mike Miles
@mikemiles86
Genuine ( )wearegenuine.com
mike­miles.com

3. Goals of this Session
Explain AJAX callback commands
Demonstrate AJAX callback commands
Outline custom AJAX callback commands

4. What are Callback Commands
Functions returned and invoked by all Ajax responses
Allow server to dictate client functionality
Defined by Drupal core (25) and Modules

5. Callback Commands: Server Side
Follows naming convention [CommandName]Command(.php)
Class that implements CommandInterface
Defines a 'render' method
Returns an associative array
Contains element with key of 'command'
'Command' value is name of JavaScript method

6. Anatomy of a Callback Command: PHP
01 use DrupalCoreAjaxCommandInterface;
02
03 // An AJAX command for calling [commandName]() JavaScript method.
04 class [CommandName]Command implements CommandInterface {
05
06 // Implements DrupalCoreAjaxCommandInterface:render().
07 public function render() {
08 return array(
09 'command' => '[commandName]', // Name of JavaScript Method.
10 // other request arguments...
11 );
12 }
13 }
[CommandName]Command.php
Callback command classes need to implement CommandInterface (lines #1 & #4). Must define a 'render'
method (lines #7 ­ #12), that returns an associative array. Associative array must contain an element
with the key of 'command' and a vlaue that is a name of the javascript method. Additional arguments are
passed as response data.

7. Callback Commands: Client Side
Wrapper for additional javascript
Method attached to 'Drupal.AjaxCommands.prototype' object
Takes 3 arguments
ajax
response
status

8. Anatomy of a Callback Command: JavaScript
01 /**
02 * [commandName description]
03 *
04 * @param {Drupal.Ajax} [ajax]
05 * @param {object} response
06 * @param {number} [status]
07 */
08 Drupal.AjaxCommands.prototype.[commandName] = function(ajax, response, status){
09
10 // Custom javascript goes here ...
11
12 }
Callback Command needs to be attached as a method to the Drupal.AjaxCommands.prototype object
(line #8). Command accepts three arguments and is a wrapper for additional javascript.

9. Callback Commands Are...
Functions returned and invoked by all Ajax responses
PHP Classes that implement CommandInterface
Methods attached to 'Drupal.AjaxCommands.prototype'

10. How to Use Callback Commands
Attach Drupal Ajax library to the requesting page
Create a callback method that returns an AjaxResponse object
Attach commands to AjaxResponse object using 'addCommand'

11. Example: The "Remove" Command
Example of using the remove callback command. Link triggers ajax request which returns response with
'remove' command targeting image id.

12. 01 namespace Drupalremove_exampleController;
02 use DrupalCoreControllerControllerBase;
03
04 class RemoveExampleController extends ControllerBase {
05
06 // Return output for displaying an image and ajax link for removing it.
07 public static function demo() {
08 $output['description']['#markup'] = '<p>' . t('The following is an example of using
09 // ...
10 // Attach the ajax library.
11 $output['#attached']['library'][] = 'core/drupal.ajax';
12 // Return render array
13 return $output;
14 }
15 // ...
16 }
remove_example/src/Controller/RemoveExampleController.php
Pages that want to use Ajax need to include the ajax library. On line #11 attaching the core Drupal Ajax
library to the render array for the page.

13. 01 namespace Drupalremove_exampleController;
02 use DrupalCoreControllerControllerBase;
03 use DrupalCoreAjaxAjaxResponse;
04 use DrupalCoreAjaxRemoveCommand;
05
06 class RemoveExampleController extends ControllerBase {
07 // ...
08 /**
09 * Callback method for removing image from 'remove-example' page.
10 *
11 * @return DrupalCoreAjaxAjaxResponse|mixed
12 */
13 public static function removeImage() {
14 // Create an Ajax Response object.
15 $response = new AjaxResponse();
16 // Add a remove command.
17 $response->addCommand(new RemoveCommand('#example_remove_wrapper'));
18 // Return the response object.
19 return $response;
20 }
21 }
remove_example/src/Controller/RemoveExampleController.php
Classes used for Ajax requests need to include needed classes (line #3, Line #4). Callback method needs
to return an ajax command (line #14) and attach commands using 'addCommand' method (line #16).

14. To Use Callback Commands...
Attach Drupal Ajax library to the requesting page
Create callback method that returns AjaxResponse
Attach commands to AjaxResponse object with 'addCommand'

15. Creating Custom Callback Commands
Requires a custom module
Need to define custom php classes
Need to define custom javascript methods

16. Custom Callback Commands: PHP
Follow naming convention [CommandName]Command(.php)
Implement CommandInterface
Define a 'render' method
Return an associative array with 'command' element
Place in 'src/Ajax/' directory of module

17. Example: SlideRemoveCommand
01 namespace Drupalremove_exampleAjax;
02
03 use DrupalCoreAjaxCommandInterface;
04 // An AJAX command for calling the jQuery slideUp() and remove() methods.
05 class SlideRemoveCommand implements CommandInterface {
06 // Constructs an SlideRemoveCommand object.
07 public function __construct($selector, $duration = NULL) {
08 $this->selector = $selector;
09 $this->duration = $duration;
10 }
11 // Implements DrupalCoreAjaxCommandInterface:render().
12 public function render() {
13 return array(
14 'command' => 'slideRemove',
15 'selector' => $this->selector,
16 'duration' => $this->duration,
17 );
18 }
19 }
remove_example/src/Ajax/SlideRemoveCommand.php
An example of creating a custom 'SlideRemove' callback command PHP Class. Class follows naming
conventions and implements CommandInterface (line #5). Defines a render method (line #12), which
returns an associative array with a 'command' keyed element. (lines #13 ­ #17).

18. Custom Callback Commands: JavaScript
Attach method to 'Drupal.AjaxCommands.prototype' object
Take 3 arguments
ajax
response
status
Add JavaScript to a custom library

19. Example: slideRemove
01 (function ($, window, Drupal, drupalSettings) {
02 'use strict';
03 // Command to slide up content before removing it from the page.
04 Drupal.AjaxCommands.prototype.slideRemove = function(ajax, response, status){
05 var duration = response.duration ? response.duration : "slow";
06
07 $(response.selector).each(function() {
08 $(this).slideUp(duration, function() {
09 $(this).remove();
10 });
11 });
12 }
13 })(jQuery, this, Drupal, drupalSettings);
remove_example/js/ajax.js
An example of creating a custom 'slideRemove' callback command javascript method. Attached to
'Drupal.AjaxCommands.prototype' object and accepts three arguments (line #4). Uses response data for
additional javascript functionality (lines #5 ­ #13).

20. Example: remove_example/remove-example library
01 remove-example:
02 version: VERSION
03 js:
04 js/ajax.js: {}
05 dependencies:
06 - core/drupal.ajax
remove_example.libraries.yml
Javascript file that contains custom 'slideRemove' command is added to a library deffinition (lines #3 ­
#4). Add core Drupal Ajax library as a dependency so that it is included (lines #5 ­ #6).

21. To Create Custom Callback Commands...
Use a custom module
Define classes that implements CommandInterface
Attach JavaScript method(s) to 'Drupal.AjaxCommands.prototype'

22. Using Custom Callback Commands
Attach custom library to the requesting page
Attach commands to AjaxResponse object with 'addCommand'

23. Example: The "slideRemove" Command
Example of using the custom slideRemove callback command. Link triggers ajax request which returns
response with 'slideRemove' command targeting image id.

24. 01 namespace Drupalremove_exampleController;
02 use DrupalCoreControllerControllerBase;
03
04 class RemoveExampleController extends ControllerBase {
05
06 // Return output for displaying an image and ajax link for removing it.
07 public static function demo() {
08 $output['description']['#markup'] = '<p>' . t('The following is an example of using
09 // ...
10 // Attach custom Ajax command library.
11 $output['#attached']['library'][] = 'remove_example/remove-example';
12 // Return render array
13 return $output;
14 }
15 // ...
16 }
remove_example/src/Controller/RemoveExampleController.php
Custom Javascript library needs to be included on requesting page, so that methods are attached.
Attaching library to render array on line #11.

25. 01 namespace Drupalremove_exampleController;
02 use DrupalCoreControllerControllerBase;
03 use DrupalCoreAjaxAjaxResponse;
04 use DrupalCoreremove_exampleSlideRemoveCommand;
05
06 class RemoveExampleController extends ControllerBase {
07 // ...
08 /**
09 * Callback method for removing image from 'remove-example' page.
10 *
11 * @return DrupalCoreAjaxAjaxResponse|mixed
12 */
13 public static function removeImage() {
14 // Create an Ajax Response object.
15 $response = new AjaxResponse();
16 // Add a remove command.
17 $response->addCommand(new SlideRemoveCommand('#example_remove_wrapper', 'slow'
18 // Return the response object.
19 return $response;
20 }
21 }
remove_example/src/Controller/RemoveExampleController.php
Like core callback commands, custom command classes have to be included in callback controller (line
#4) and added to AjaxResponse in callback method (line #17).

26. To Use Custom Callback Commands...
Attach custom library to the requesting page
Attach commands to AjaxResponse object with 'addCommand'

27. Review

28. AJAX Callback Commands Are...
Functions returned and invoked by all Ajax responses
PHP Classes implementing CommandInterface
Methods attached to 'Drupal.AjaxCommands.prototype' object

29. To Use AJAX Callback Commands...
Attach Drupal Ajax library to the requesting page
Create callback method that returns AjaxResponse
Attach commands to AjaxResponse object with 'addCommand'

30. To Create AJAX Callback Commands...
Use a custom module
Define classes that implements CommandInterface
Attach JavaScript methods to 'Drupal.AjaxCommands.prototype'

31. To Use Custom AJAX Callback Commands...
Attach custom library to the requesting page
Same process as using core commands

32. Resources
Drupal 8 AJAX Api: bit.ly/Drupal8Ajax
This Presentation: bit.ly/Mid16Ajax
Presentation Slides: bit.ly/Mid16AjaxSlides
Example Code: bit.ly/Mid16AjaxEx
Creating Commands in D8: bit.ly/D8AjaxCmds

33. #midcamp @WeAreGenuine D8 AJAX / Michael Miles
Thank You!
Feedback/Questions: @mikemiles86