JavaScript scripting in the browser
At some point, your plugin’s user interface will need to use JavaScript in the browser.
The client side JavaScript is placed in the static
directory of your plugin to make it available over HTTP. The full pathname of the file will be different in every application, and vary over time as it’s upgraded. There is no access control on static files, so they can be downloaded by anyone who knows the URL.
To include a <script>
tag with the correct pathname, use the std:plugin:resources() template function. For example, if the client side JavaScript file is named userinterface.js
, you would include
std:plugin:resources("userinterface.js")
at the top of your template. This will include the script in the page sent to the browser. It can be placed in any template, and if multiple templates including it are rendered in one request, only one <script>
tag will be sent to the browser.
This works whether you’re responding to an HTTP request, or generating some HTML to add user interface to the main application’s pages, such as an Element.
JavaScript Libraries
The standard jQuery and underscore.js JavaScript libraries are included in every page, and so are available by default.
The libraries are updated frequently, so you should assume that updates to the latest version will happen within weeks of their release.
Be careful if you include additional browser JavaScript libraries. If multiple plugins include different versions of the same library on the same page, there may be conflicts.
jQuery global
You must use the jQuery library through the jQuery
global, not $
. To access it using the $()
syntax, use the recommended coding style below.
Coding style
The following coding style is recommended to encapsulate your client side scripting, and avoid clashing with the core Haplo scripting and other plugins.
(function($) { // Define a variable, accessible to this script only var exampleData = {}; // Define a function, accessible to this script only var exampleFunction = function(arg) { // ... do something here exampleData[arg] = true; // ... }; // Use jQuery to set an event handler $("#example").click(function() { // ... exampleFunction("ABC"); // ... }); })(jQuery);
An anonymous function is used to encapsulate all the code, and rename jQuery
to $
for the encapsulated code only. Because of the encapsulation, you need to use a slightly different syntax for defining functions than you might otherwise use.
Note that underscore.js is available through the _
global without any renaming required.
Syntax checking & minimisation
While you are developing your plugin, the Plugin Tool will check the syntax of the browser JavaScript each time you save the file. While plugins will be accepted with some warnings for browser JavaScript, it’s recommended that you follow the suggestions above.
Browser JavaScript must not have any “'variable' is not defined
” warnings, as these indicate issues which may cause scripting to clash. Well tested library code with these warnings may be accepted — get in touch for advice.
In deployment, your browser JavaScript will be minimised to reduce the amount of data sent to the browser. This will remove comments and whitespace, and rename variables to reduce file size. The recommended style is particularly suitable for minimisation, as the encapsulation allows the minimiser to rename all variables.