Skip to content

Commit

Permalink
docs(js): modernizes the JS docs to emphasize AMD usage
Browse files Browse the repository at this point in the history 
Documents each AMD module available for public use.
  • Loading branch information
@mrclay
mrclay committed Feb 13, 2016
1 parent 1bb2076 commit d66cae6
Showing 1 changed file with 95 additions and 90 deletions.
185 changes: 95 additions & 90 deletions docs/guides/javascript.rst
View file
Expand Up @@ -5,32 +5,11 @@ JavaScript
:local:
:depth: 2

Third-party assets
==================

We recommend managing third-party scripts and styles with Composer.
Elgg core uses ``fxp/composer-asset-plugin`` for this purpose.
This plugin allows you to pull dependencies from the Bower or NPM package repositories,
but using the Composer command-line tool.

For example, to include jQuery, you could run the following Composer commands:

.. code-block:: shell
composer global require fxp/composer-asset-plugin:~1.1.1
composer require bower-asset/jquery:~2.0
.. note::

``fxp/composer-asset-plugin`` must be installed globally!
See https://github.com/francoispluchino/composer-asset-plugin for more info.

AMD
===

As of Elgg 1.9, we encourage all developers to adopt the `AMD (Asynchronous Module
Developers should use the `AMD (Asynchronous Module
Definition) <http://requirejs.org/docs/whyamd.html>`_ standard for writing JavaScript code in Elgg.
The 1.8 version is still functional and is :ref:`described below<1.8-js>`.

Here we'll describe making and executing AMD modules. The RequireJS documentation for
`defining modules <http://requirejs.org/docs/api.html#define>`_ may also be of use.
Expand Down Expand Up @@ -98,8 +77,8 @@ the greeting:
$('body').append(hello);
});
Passing plugin/Elgg settings to modules
---------------------------------------
Passing settings to modules
---------------------------

You can use a PHP-based module to pass values from the server. To make the module ``myplugin/settings``,
create the view file ``views/default/myplugin/settings.js.php`` (note the double extension
Expand Down Expand Up @@ -146,7 +125,7 @@ The best way to accomplish this is by configuring the path to the file using the
return [
'underscore.js' => 'vendor/bower-asset/underscore/underscore.min.js',
];
If you've copied the script directly into your plugin instead of managing it with Composer,
you can use something like this instead:

Expand Down Expand Up @@ -193,6 +172,8 @@ Some things to note
#. The configuration is also cached in simplecache, and should not rely on user-specific values
like ``get_language()``.

.. _guides/javascript#boot:

Booting your plugin
===================

Expand Down Expand Up @@ -225,66 +206,16 @@ Each boot module **must** return an instance of ``elgg/Plugin``. The constructor

.. warning:: A boot module **cannot** depend on the modules ``elgg/init`` or ``elgg/ready``.

Modules provided with Elgg
==========================

The elgg/init module
--------------------

``elgg/init`` loads and initializes all boot modules in priority order and triggers the [init, system] hook.
Modules ``jquery`` and ``jquery-ui``
------------------------------------

Require this module to make sure all plugins are ready.


The elgg/ready module
---------------------

``elgg/ready`` loads and initializes all plugin boot modules in priority order.

Require this module to make sure all plugins are ready.
You must depend on these modules to use ``$`` or ``$.ui`` methods. In the future Elgg may stop loading these by default.


Migrating JS from Elgg 1.8 to AMD / 1.9
=======================================

**Current 1.8 JavaScript modules will continue to work with Elgg**.

We do not anticipate any backwards compatibility issues with this new direction and will fix any
issues that do come up. The old system will still be functional in Elgg 1.9, but developers are
encouraged to begin looking to AMD as the future of JS in Elgg.

.. _1.8-js:

Traditional JavaScript (1.8)
============================


Register third-party libraries with ``elgg_register_js``:

.. code:: php
elgg_register_js('jquery', $cdnjs_url);
This will override any URLs previously registered under this name.

Load a library on the current page with ``elgg_load_js``:

.. code:: php
elgg_load_js('jquery');
This will include and execute the linked code.

.. warning::

Using inline scripts is NOT SUPPORTED because:
* They are not testable (maintainability)
* They are not cacheable (performance)
* They prevent use of Content-Security-Policy (security)
* They prevent scripts from being loaded with ``defer`` or ``async`` (performance)

Inline scripts in core or bundled plugins are considered legacy bugs.

Core functions available in JS
==============================
Module ``elgg``
---------------

``elgg.echo()``

Expand Down Expand Up @@ -313,8 +244,6 @@ Display an error message to the user.
elgg.register_error(elgg.echo('error'));
``elgg.forward()``

``elgg.normalize_url()``

Normalize a URL relative to the elgg root:
Expand All @@ -324,7 +253,7 @@ Normalize a URL relative to the elgg root:
// "http://localhost/elgg/blog"
elgg.normalize_url('/blog');
``elgg.forward()``

Redirect to a new page.

Expand Down Expand Up @@ -460,6 +389,30 @@ There are a number of configuration values set in the elgg object:
// The Elgg release (X.Y.Z).
elgg.config.release;
Module ``elgg/Ajax``
--------------------

See the :doc:`ajax` page for details.

Module ``elgg/init``
--------------------

``elgg/init`` loads and initializes all boot modules in priority order and triggers the [init, system] hook.

Require this module to make sure all plugins are ready.

Module ``elgg/Plugin``
----------------------

Used to create a :ref:`boot module <guides/javascript#boot>`.

Module ``elgg/ready``
---------------------

``elgg/ready`` loads and initializes all plugin boot modules in priority order.

Require this module to make sure all plugins are ready.

Module ``elgg/spinner``
-----------------------

Expand All @@ -479,13 +432,45 @@ The ``elgg/spinner`` module can be used to create an Ajax loading indicator fixe
});
});
.. note:: The ``elgg/Ajax`` module uses the spinner by default.

Traditional scripts
===================

Although we highly recommend using AMD modules, you can register scripts with ``elgg_register_js``:

.. code:: php
elgg_register_js('jquery', $cdnjs_url);
This will override any URLs previously registered under this name.

Load a library on the current page with ``elgg_load_js``:

.. code:: php
elgg_load_js('jquery');
This will load the library in the page footer. You must use the ``require()`` function to depend on
modules like ``elgg`` and ``jquery``.

.. warning::

Using inline scripts is NOT SUPPORTED because:
* They are not testable (maintainability)
* They are not cacheable (performance)
* They prevent use of Content-Security-Policy (security)
* They prevent scripts from being loaded with ``defer`` or ``async`` (performance)

Inline scripts in core or bundled plugins are considered legacy bugs.

Hooks
-----
=====

The JS engine has a hooks system similar to the PHP engine's plugin hooks: hooks are triggered and plugins can register functions to react or alter information. There is no concept of Elgg events in the JS engine; everything in the JS engine is implemented as a hook.

Registering hook handlers
^^^^^^^^^^^^^^^^^^^^^^^^^
-------------------------

Handler functions are registered using ``elgg.register_hook_handler()``. Multiple handlers can be registered for the same hook.

Expand All @@ -507,7 +492,7 @@ The following example registers the ``handleFoo`` function for the ``foo, bar``
});
The handler function
^^^^^^^^^^^^^^^^^^^^
--------------------

The handler will receive 4 arguments:

Expand All @@ -519,7 +504,7 @@ The handler will receive 4 arguments:
The ``value`` will be passed through each hook. Depending on the hook, callbacks can simply react or alter data.

Triggering custom hooks
^^^^^^^^^^^^^^^^^^^^^^^
-----------------------

Plugins can trigger their own hooks:

Expand All @@ -535,7 +520,7 @@ Plugins can trigger their own hooks:
.. note:: Be aware of timing. If you don't depend on elgg/init, other plugins may not have had a chance to register their handlers.

Available hooks
^^^^^^^^^^^^^^^
---------------

**init, system**
Plugins should register their init functions for this hook. It is fired after Elgg's JS is loaded and all plugin boot modules have been initialized. Depend on the ``elgg/init`` module to be sure this has completed.
Expand All @@ -554,3 +539,23 @@ Available hooks

**ajax_response_data, \***
This filters the response data returned to users of the ``elgg/Ajax`` module. See :doc:`ajax` for details.

Third-party assets
==================

We recommend managing third-party scripts and styles with Composer.
Elgg core uses ``fxp/composer-asset-plugin`` for this purpose.
This plugin allows you to pull dependencies from the Bower or NPM package repositories,
but using the Composer command-line tool.

For example, to include jQuery, you could run the following Composer commands:

.. code-block:: shell
composer global require fxp/composer-asset-plugin:~1.1.1
composer require bower-asset/jquery:~2.0
.. note::

``fxp/composer-asset-plugin`` must be installed globally!
See https://github.com/francoispluchino/composer-asset-plugin for more info.

0 comments on commit d66cae6

Please sign in to comment.