Demystifying AJAX CallbackCommands

(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

mike­miles.com

Goals of this SessionExplain AJAX callback commandsDemonstrate AJAX callback commandsOutline custom AJAX callback commands

What are Callback CommandsFunctions returned and invoked by all Ajax responsesAllow server to dictate client functionalityDefined by Drupal core (25) and Modules

Callback Commands: Server SideFollows naming convention [CommandName]Command(.php)Class that implements CommandInterfaceDefines a 'render' method

Returns an associative arrayContains element with key of 'command''Command' value is name of JavaScript method

Anatomy of a Callback Command: PHP01 use Drupal\Core\Ajax\CommandInterface; 02 03 // An AJAX command for calling [commandName]() JavaScript method. 04 class [CommandName]Command implements CommandInterface { 05 06 // Implements Drupal\Core\Ajax\CommandInterface: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 elementwith 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 SideWrapper for additional javascriptMethod attached to 'Drupal.AjaxCommands.prototype' objectTakes 3 arguments

ajaxresponsestatus

Anatomy of a Callback Command: JavaScript01 /** 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...Functions returned and invoked by all Ajax responsesPHP Classes that implement CommandInterfaceMethods attached to 'Drupal.AjaxCommands.prototype'

How to Use Callback CommandsAttach Drupal Ajax library to the requesting pageCreate a callback method that returns an AjaxResponse objectAttach 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 Drupal\remove_example\Controller; 02 use Drupal\Core\Controller\ControllerBase; 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 the remove ajax callback command.'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 Ajaxlibrary to the render array for the page.

01 namespace Drupal\remove_example\Controller; 02 use Drupal\Core\Controller\ControllerBase; 03 use Drupal\Core\Ajax\AjaxResponse; 04 use Drupal\Core\Ajax\RemoveCommand; 05 06 class RemoveExampleController extends ControllerBase { 07 // ... 08 /** 09 * Callback method for removing image from 'remove-example' page. 10 * 11 * @return \Drupal\Core\Ajax\AjaxResponse|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 needsto return an ajax command (line #14) and attach commands using 'addCommand' method (line #16).

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

Creating Custom Callback CommandsRequires a custom moduleNeed to define custom php classesNeed to define custom javascript methods

Custom Callback Commands: PHPFollow naming convention [CommandName]Command(.php)Implement CommandInterface

Define a 'render' methodReturn an associative array with 'command' element

Place in 'src/Ajax/' directory of module

Example: SlideRemoveCommand01 namespace Drupal\remove_example\Ajax; 02 03 use Drupal\Core\Ajax\CommandInterface; 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 Drupal\Core\Ajax\CommandInterface: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 namingconventions 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: JavaScriptAttach method to 'Drupal.AjaxCommands.prototype' objectTake 3 arguments

ajaxresponsestatus

Add JavaScript to a custom library

Example: slideRemove01 (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 library01 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 moduleDefine classes that implements CommandInterfaceAttach JavaScript method(s) to 'Drupal.AjaxCommands.prototype'

Using Custom Callback CommandsAttach custom library to the requesting pageAttach commands to AjaxResponse object with 'addCommand'

Example: The "slideRemove" Command

Example of using the custom slideRemove callback command. Link triggers ajax request which returnsresponse with 'slideRemove' command targeting image id.

01 namespace Drupal\remove_example\Controller; 02 use Drupal\Core\Controller\ControllerBase; 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 the remove ajax callback command.'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.

01 namespace Drupal\remove_example\Controller; 02 use Drupal\Core\Controller\ControllerBase; 03 use Drupal\Core\Ajax\AjaxResponse; 04 use Drupal\Core\remove_example\SlideRemoveCommand; 05 06 class RemoveExampleController extends ControllerBase { 07 // ... 08 /** 09 * Callback method for removing image from 'remove-example' page. 10 * 11 * @return \Drupal\Core\Ajax\AjaxResponse|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).

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

Review

AJAX Callback Commands Are...Functions returned and invoked by all Ajax responsesPHP Classes implementing CommandInterfaceMethods attached to 'Drupal.AjaxCommands.prototype' object

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

To Create AJAX Callback Commands...Use a custom moduleDefine classes that implements CommandInterfaceAttach JavaScript methods to 'Drupal.AjaxCommands.prototype'

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

ResourcesDrupal 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