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.
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).
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-tabs.js: {}
js/fancy-accordion.js: {}
fancy-ui-tables:
version: 1.x
js:
js/fancy-tables.js: {}
dependencies:
- core/underscore
- core/jquery
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 }
Once libraries have been defined, they need to be attached where they are needed.
To attach Javascript to all pages:
Under the libraries: section of mytheme.info.yml:
libraries:
- 'mytheme/global-styling'
- 'mytheme/bootstrap-scripts'
- 'mytheme/fancy-ui'
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';
}
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.
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);
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 ever be used in the singular string, only the plural.
Any user-provided input that has not been properly sanitized previously via Twig or PHP should be passed through Drupal.checkPlain() in JavaScript.
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:
- Eliminates some JavaScript silent errors by changing them to throw errors.
- 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.
- 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);
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); } |
- drupal.org: Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 theme
- drupal.org: Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 module
- drupal.org: Javascript API Overview
- developer.mozilla.org - Strict mode
- docs.microsoft.com - Strict Mode (JavaScript)