MidCamp 2016 - Demystifying AJAX Callback Commands in Drupal 8

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

Mike Miles
@mikemiles86
Genuine ( )wearegenuine.com
mikemiles.com

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

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

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

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.

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

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.

Callback Commands Are...
PHP Classes that implement CommandInterface
Methods attached to 'Drupal.AjaxCommands.prototype'

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'

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

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.

03 use DrupalCoreAjaxAjaxResponse;
04 use DrupalCoreAjaxRemoveCommand;
05
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 }
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).

To Use Callback Commands...
Create callback method that returns AjaxResponse
Attach commands to AjaxResponse object with 'addCommand'

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

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

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).

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

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).

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).

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

Using Custom Callback Commands
Attach custom library to the requesting page

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.

03
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 }
Custom Javascript library needs to be included on requesting page, so that methods are attached.
Attaching library to render array on line #11.

03 use DrupalCoreAjaxAjaxResponse;
04 use DrupalCoreremove_exampleSlideRemoveCommand;
05
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 }
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).

To Use Custom Callback Commands...

AJAX Callback Commands Are...
PHP Classes implementing CommandInterface
Methods attached to 'Drupal.AjaxCommands.prototype' object

To Use AJAX Callback Commands...
Create callback method that returns AjaxResponse

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

To Use Custom AJAX Callback Commands...
Same process as using core commands

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

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

MidCamp 2016 - Demystifying AJAX Callback Commands in Drupal 8

More Related Content

What's hot

Similar to MidCamp 2016 - Demystifying AJAX Callback Commands in Drupal 8

More from Michael Miles

Recently uploaded

MidCamp 2016 - Demystifying AJAX Callback Commands in Drupal 8