Skip to content

Latest commit

 

History

History
234 lines (177 loc) · 12.2 KB

1.2-javascript-jquery.md

File metadata and controls

234 lines (177 loc) · 12.2 KB
Raw

Javascript/jQuery

Javascript is a very large subject matter, and the presumption is that you understand at least the bare essentials to take the certification exam, and there are plenty of places to learn Javascript online. As such the notes for this section will just cover Drupal-related Javascript topics.

One change from Drupal 7 to Drupal 8, is that jQuery is no longer automatically loaded. This means jQuery must be manually pulled in as a dependency. There are examples of that below.

Adding Javascript Libraries

Theme and module Javascript should be loaded in using asset libraries (i.e. *.libraries.yml files where * is the name of the theme or module).

Local Javascript Libraries

Suppose you have a theme named mytheme, which needs to include the following Javascript files:

fancy-ui-tabs.js
fancy-ui-accordion.js
fancy-ui-tables.js (dependent on underscore and jQuery)

It would follow that you would create mytheme.libraries.yml with the following contents:

fancy-ui:
  version: 1.x
  js:
    js/fancy-ui-tabs.js: {}
    js/fancy-ui-accordion.js: {}
fancy-ui-tables:
  version: 1.x
  js:
    js/fancy-ui-tables.js: {}
  dependencies:
    - core/underscore
    - core/jquery

External Javascript Libraries

Though it can be problematic for performance and security reasons, there are times when you will need to load external Javascript into your site.

For example loading AngularJS via a CDN, from Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 theme:

angular.angularjs:
  remote: https://github.com/angular
  version: 1.4.4
  license:
    name: MIT
    url: https://github.com/angular/angular.js/blob/master/LICENSE
    gpl-compatible: true
  js:
    https://ajax.googleapis.com/ajax/libs/angularjs/1.4.4/angular.min.js: { type: external, minified: true }

Attaching Javascript

Once libraries have been defined, they need to be attached where they are needed.

Attaching to All Pages

To attach Javascript to all pages:

Under the libraries: section of mytheme.info.yml:

libraries:
  - 'mytheme/global-styling'
  - 'mytheme/bootstrap-scripts'
  - 'mytheme/fancy-ui'

Attaching to a Subset of Pages

You can use hooks to add conditionally.

For example, to only load on nodes (skipping other entities), add the following function to your mytheme.theme file.

function mytheme_preprocess_node(&$variables) {
  $variables['#attached']['library'][] = 'mytheme/fancy-tables';
}

Or if you only want to load on the maintenance page:

function mytheme_preprocess_maintenance_page(&$variables) {
  $variables['#attached']['library'][] = 'mytheme/fancy-tables';
}

Drupal.behaviors

Instead of using $(document).ready(function() {}), as is common in jQuery development, it is better to make use of Drupal.behaviors as it will ensure code runs on normal page loads, ajax calls and inside BigPipe.

To enable Drupal.behaviors you must add core/drupal as a Javascript dependency in your theme/module.

my-js-lib:
  version: 1.x
  js:
    js/my-js-lib.js: {}
  dependencies:
    - core/drupal

Example from Javascript API Overview:

Drupal.behaviors.myBehavior = {
  attach: function (context, settings) {
    // Using once() to apply the myCustomBehaviour effect when you want to do just run one function.
    $(context).find('input.myCustomBehavior').once('myCustomBehavior').addClass('processed');

    // Using once() with more complexity.
    $(context).find('input.myCustom').once('mySecondBehavior').each(function () {
      if ($(this).visible()) {
          $(this).css('background', 'green');
      }
      else {
        $(this).css('background', 'yellow').show();
      }
    });
  }
};

attach() is called once the DOM has loaded for all Drupal.behaviors properties, both on the initial page load, and any subsequent ajax calls.

Closures

Since Drupal's implementation of jQuery uses jQuery.noConflict(), it is also considered good practice to wrap your custom Drupal javascript inside of a closure like this:

(function ($, Drupal) {
  Drupal.behaviors.myModuleBehavior = {
    ...
  };
})(jQuery, Drupal);

Translating Strings in Javascript

When necessary, string translation can be performed in Javascript using Drupal.t():

var translatedString = Drupal.t('This is a string about @subject that needs to be translated', {@subject: 'Javascript in Drupal'});

Distinguish between plural and singular translations in Javascript using Drupal.formatPlural():

var typeVar = 'list';
var countingString = Drupal.formatPlural(count, 'I have 1 @type item', 'I have @count @type items', {@type: typeVar});

^ Note: @count is a special placeholder and does need to be defined in your variable array, like @type does. Additionally @count should never be used in the singular string, only the plural.

Preventing Cross-site Scripting (XSS)

Any user-provided input that has not been properly sanitized previously via Twig or PHP should be passed through Drupal.checkPlain() in JavaScript.

Strict Mode

From developer.mozilla.org - Strict mode:

ECMAScript 5's strict mode is a way to opt in to a restricted variant of JavaScript, thereby implicitly opting-out of "sloppy mode". Strict mode isn't just a subset: it intentionally has different semantics from normal code. Browsers not supporting strict mode will run strict mode code with different behavior from browsers that do, so don't rely on strict mode without feature-testing for support for the relevant aspects of strict mode. Strict mode code and non-strict mode code can coexist, so scripts can opt into strict mode incrementally.

Strict mode makes several changes to normal JavaScript semantics:

  1. Eliminates some JavaScript silent errors by changing them to throw errors.
  2. Fixes mistakes that make it difficult for JavaScript engines to perform optimizations: strict mode code can sometimes be made to run faster than identical code that's not strict mode.
  3. Prohibits some syntax likely to be defined in future versions of ECMAScript.

To place javascript in strict mode add 'use strict'; to the top of the document, closure, or function. For example:

(function ($, Drupal) {
  'use strict';

  Drupal.behaviors.myModuleBehavior = {
    ...
  };
})(jQuery, Drupal);

Strict Mode Restrictions

From docs.microsoft.com - Strict Mode (JavaScript):

Language element Restriction Error Example
Variable Using a variable without declaring it. SCRIPT5042: Variable undefined in strict mode testvar = 4;
Read-only property Writing to a read-only property. SCRIPT5045: Assignment to read-only properties is not allowed in strict mode var testObj = Object.defineProperties({}, { prop1: { value: 10, writable: false // by default }, prop2: { get: function () { } } }); testObj.prop1 = 20; testObj.prop2 = 30;
Non-extensible property Adding a property to an object whose extensible attribute is set to false. SCRIPT5046: Cannot create property for a non-extensible object var testObj = new Object(); Object.preventExtensions(testObj); testObj.name = "Bob";
delete Deleting a variable, a function, or an argument. Deleting a property whose configurable attribute is set to false. SCRIPT1045: Calling delete on is not allowed in strict mode var testvar = 15; function testFunc() {}; delete testvar; delete testFunc; Object.defineProperty(testObj, "testvar", { value: 10, configurable: false }); delete testObj.testvar;
Duplicating a property Defining a property more than once in an object literal. SCRIPT1046: Multiple definitions of a property not allowed in strict mode var testObj = { prop1: 10, prop2: 15, prop1: 20 };
Duplicating a parameter name Using a parameter name more than once in a function. SCRIPT1038: Duplicate formal parameter names not allowed in strict mode function testFunc(param1, param1) { return 1; };
Future reserved keywords Using a future reserved keyword as a variable or function name. SCRIPT1050: The use of a future reserved word for an identifier is invalid. The identifier name is reserved in strict mode. - implement
- interface
- package
- private
- protected
- public
- static
- yield
Octals Assigning an octal value to a numeric literal, or attempting to use an escape on an octal value. SCRIPT1039: Octal numeric literals and escape characters not allowed in strict mode var testoctal = 010;
var testescape = \010;
this The value of this is not converted to the global object when it is null or undefined. function testFunc() { return this; } var testvar = testFunc();

In non-strict mode, the value of testvar is the global object, but in strict mode the value is undefined.
eval as an identifier The string "eval" cannot be used as an identifier (variable or function name, parameter name, and so on). var eval = 10;
Function declared inside a statement or a block You cannot declare a function inside a statement or a block. SCRIPT1047: In strict mode, function declarations cannot be nested inside a statement or block. They may only appear at the top level or directly inside a function body. var arr = [1, 2, 3, 4, 5]; var index = null; for (index in arr) { function myFunc() {}; }
Variable declared inside an eval function If a variable is declared inside an eval function, it cannot be used outside that function. SCRIPT1041: Invalid usage of 'eval' in strict mode eval("var testvar = 10"); testvar = 15;

Indirect evaluation is possible, but you still cannot use a variable declared outside the eval function.

var indirectEval = eval; indirectEval("var testvar = 10;"); document.write(testVar);

This code causes an error SCRIPT5009: 'testVar' is undefined.
Arguments as an identifier The string "arguments" cannot be used as an identifier (variable or function name, parameter name, and so on). SCRIPT1042: Invalid usage of 'arguments' in strict mode var arguments = 10;
arguments inside a function You cannot change the values of members of the local arguments object. function testArgs(oneArg) { arguments[0] = 20; }

In non-strict mode, you can change the value of the oneArg parameter by changing the value of arguments[0], so that the value of both oneArg and arguments[0] is 20. In strict mode, changing the value of arguments[0] does not affect the value of oneArg, because the arguments object is merely a local copy.
arguments.callee Not allowed. function (testInt) { if (testInt-- == 0) return; arguments.callee(testInt--); }
with Not allowed. SCRIPT1037: 'with' statements are not allowed in strict mode with (Math){ x = cos(3); y = tan(7); }

Additional Resources

<< Previous Page | Next Page >>