Visa källa för Broken/JavaScript guidelines

{{Moodle 2.0}}

These guidelines can only be applied fully from Moodle 2.0 onwards, because they rely on our new API to facilitate use of JavaScript.

When writing JavaScript for earlier versions of Moodle, please try to follow these guidelines in spirit and use the '''require_js''' function in place of $PAGE->requires->js_module/yui2_lib.

==General principles==

===Moodle should be usable without JavaScript===

Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript|unobtrusive JavaScript]] and [[Development:Progressive_enhancement|progressive enhancement]].

===Minimise inline JavaScript===

Almost all JavaScript code should be in separate .js files. There should be the smallest possible amount of JavaScript inline in the HTML code of pages.

The only &lt;script> tags in the HTML should be
# &lt;script src=... tags to include the necessary .js files.
# Simple function calls to trigger initialisation and pass data from PHP to JavaScript. For example &lt;script type="text/javascript">initialise_my_widget('some', 'data', 123);&lt;/script>.

Even these small amounts of JS you should not output directly. They will be generated automatically by calls to the $PAGE->requries->js_init_call() API. See below for details.

You should not use old-fashioned onXXX="event_handler" attributes in the HTML. Use Modern DOM events. The YUI events library makes this easy.

=== JavaScript libraries ===

* The official JavaScript library for Moodle is [[Development:YUI|YUI]]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.

* Moodle also has its own JavaScript library code, packaged into in various JavaScript modules.

* Moodle uses the '''TinyMCE''' HTML editor.

===When to include the JavaScript===

As per [http://developer.yahoo.com/performance/rules.html Yahoo's best practice guidelines], load and execute the JavaScript as late as possible, ideally the script tags should be the last thing before the &lt;/body> close tag. (This is the default behaviour with Moodle's JavaScript handling functions like $PAGE->requries->js_init_call().)

Since everything should work without JavaScript, load and initialising your scripts only after everything else on the page has loaded should not be a problem and will increase the perceived page-load performance for users.

===Minimise the number of .js files===

Try not to use too many different .js files. Each separate file that the browser has to load incurs an overhead.

On the other hand, organise the JavaScript logically to ease maintenance, and don't include large amounts of irrelevant JavaScript code. Code that is loaded but never used is a waste of time.

So, if you are writing a new module that needs its own JavaScript, try starting with a single file mod/mymod/module.js. If you find that you are writing a lot of JavaScript that is only needed when the teacher edits your module, but is not needed by students, then consider splitting that code into a separate file like mod/mymod/edit.js, and only including it where needed.

==How to achive these general principles in Moodle==

The rest of this page explains how you can achieve the above goals. Note that this particularly applies to loading and using the YUI 3 library which is Moodle 2.0's default. You should check which version of YUI Moodle is using as it may lag behind the latest YUI release (and, hence, the documentation).

===Getting Moodle to load your JavaScript files===

Everything required by the current page is tracked by the $PAGE->requires object, which is an instance of the [http://phpdocs.moodle.org/HEAD/moodlecore/page_requirements_manager.html page_requirements_manager] class defined in lib/outputrequirementslib.php.

The most important method in this class is the ->js_init_call(...) method. You use it like this:

<code php> 
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'));
</code>

Note that this will implicitly load the JavaScript code in mod/mymod/module.js, and then call the M.mod_mymod.init_something function passing four string arguments 'some', 'data', 'from', 'PHP'. You can pass any PHP type as an argument. The PHP values are encoded with json_encode before being passed to JavaScript, so numbers, strings, arrays and objects all work.

Sometimes, the code in the JavaScript module mod/mymod/module.js may require some other JavaScript libraries to be loaded, or it may require some language strings. In that case you need to use the full form of js_init_call:

<code php>
$jsmodule = array(
    'name'     => 'mod_mymod',
    'fullpath' => '/mod/mymod/module.js',
    'requires' => array('base', 'io', 'node', 'json'),
    'strings' => array(
        array('something', 'mymod'),
        array('confirmdelete', 'mymod'),
        array('yes', 'moodle'),
        array('no', 'moodle')
    )
);
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'), false, $jsmodule);
</code>
(Naturally, it would be a good idea to put the definition of the $jsmodule array somewhere central like in the locallib.php file.)

The third (boolean) parameter is defined as "Wait for DOM Ready".

The libraries in the 'requires' sub-array are YUI3 (or YUI2) libraries. Moodle contains YUIs 'phploader' which understands what the library dependencies are, so this is all taken care of for you. 

The strings are Moodle language strings. In order for Moodle to have correctly determined the user's language, you should only call js_init_call after the call to require_login, which sets the current course, and ensures the user is logged in.
Strings that are passed to Javascript in this way are then available from Javascript using M.util.get_string(), which works just like the PHP function.

$PAGE->requires keeps track of which files have been included. For example if two other modules both require the YUI base module, then it is only included once.

Your 'module.js' file in your plugin's directory will look something like this:

<code javascript>
M.mod_mymod = {};

M.mod_mymod.init = function(Y) {

    // example to submit a form field on change
    Y.on('change', function(e) {
        Y.one('#mform1').submit();
    }, '#id_fieldname' );
};
</code>

''mod_mymod'' needs changed to reflect the plugin type (see [[Development:Frankenstyle]]) and the name of your plugin throughout.

===JavaScript coding style===

Moodle JavaScript code should should follow the same [[Development:Coding_style|coding style as Moodle PHP code]], allowing for the differences between PHP and JavaScript.

For example, all the rules on ''function_names'', ''class_names'' and ''variablenames'' apply. You should document your code with [http://jsdoc.sourceforge.net/ JSDoc] comments. Layout your JavaScript expressions and statements like the equivalent PHP ones.

Normally, your .js files should simply define things like functions, classes and variables. When the file is loaded, no JavaScript code should actually be executed that has any effect unless it is the sort of code that can safely be executed once per HTML page. This is so that it plays nicely with the require_once-like behaviour of $PAGE->requires->js.

Do not pollute the global JavaScript name-space. Try to package your JavaScript into objects, and put all objects inside the global M object, like the M.mod_mymod example above. 

===Different content when JavaScript is on or off===

Remember the overriding principals that everything should work with JavaScript off, and we should adopt a [[Progressive enhancement]] approach. However, there are valid reasons why sometimes you need different content with JavaScript is on or off. We can break it down into three cases:

====Content that should only be visible with JavaScript off====

An example of this is the automatic search when you are looking for a user to assign a role to. With JavaScript on, the search automatically starts after a delay. With JavaScript off, we want an explicit Search button visible.

To handle this case, Moodle automatically add a class 'jsenabled' to the body tag using JavaScript. So you just need to add a rule like
<code css>
body.jsenebled .mywidget .submitbutton {
    display: none;
}
</code>
to the stylesheet, and the button will be invisible if JavaScript is enabled.

An alternative strategy is to remove the particular bits of HTML from the page using DOM methods. However, if your JavaScript is only loaded at the end of the page, it may take some time for the extra content to disappear, which leads to a disconcerting flicker in the page.

Yet another approach is the old-fashioned <noscript> tag.

====Content that needs to be visible right away when JavaScript is on====

An example is the <nowiki>[+] or [-]</nowiki> icon that can be used to expand/collapse each block if JavaScript is on.

We can divide this into two subcases:

=====Content generated by PHP code=====

Where the HTML for the JavaScript only widget is generated by PHP, we can make it invisible when JavaScript is off using just CSS:
<code css>
.mywidget {
    display: none;
}
body.jsenabled .mywidget {
    display: block;
}
</code>
However, it could be argued that this approach is not really progressive enhancement.

=====Content generated by JavaScript code=====

This is more in keeping with progressive enhancement, and this is the way that the expand/collapse block icon is handled.

We build the icon using DOM methods. The only problem is that as the JavaScript is loaded in the footer, there is a small delay before the icons appear. Since when the icons appear, they do not cause other content on the page to move around, that is OK. Also, this delayed appearance is becoming more common on the web. For example, on http://twitter.com/, some things only appear a moment after the main part of the page has finished loading.

However, it the delayed appearance is really a problem, then the only solution is to embed the JavaScript that generates the extra content in the middle of the HTML, using the js_writer class.

====Content that only appears when the user does something, when JavaScript is on====

An example of this is something like file picker dialog that appears when you add an image to some content in the HTML editor, or the one that pops up when you click 'Add new question' in the quiz editing interface.

We have the same two sub-cases:

=====Content generated by PHP code=====

In this case, you need to make sure the content is always covered by a ''display: none;'' rule in the CSS, but then when the user takes an action like clicking a button to reveal the extra content, you need to override that class name some how, perhaps by adding or removing a className using JavaScript.

=====Content generated by JavaScript code=====

In this case, there is no problem. When the use triggers the extra content to appear, it is constructed using DOM methods. There may be a tiny delay, but the chances are that it will hardly be noticeable to the human eye.

If the content generation may be slow (perhaps because it is waiting for an Ajax request) then you should display a progress icon. See, for example, the loading of the tooltip for help icons.

===Don't break XHTML strict!===

Remember that all Moodle output must be [[Development:XHTML|XHTML strict]], and that means that the HTML output must be well-formed XML. Inline JavaScript is a great way to break that. (JavaScript uses the < and & symbols that must be escaped in XML.) Therefore any JavaScript inline in the HTML should be escaped in a CDATA section:

<code xml>
<script type="text/javascript">
//<![CDATA[

   // Your JavaScript code goes here.

//]]>
</script>
</code>

Of course, if you are following the above guidelines and putting most of your JavaScript in separate .js files, and using $PAGE->requires->js_init_call, then this is taken care of for you automatically.

==Testing==

JavaScript support varies a lot between browsers. JavaScript needs to be tested in IE, Firefox and Safari. Ideally, Moodle will support [http://developer.yahoo.com/yui/articles/gbs/ all the browsers that YUI does].

==See also==

* [[Development:Coding|The rest of Moodle coding guidelines]]
* [http://developer.yahoo.com/yui/ YUI documentation]
* [[Javascript FAQ]]
* [[Javascript and YUI 3 FAQ]]
* [[Development:Unobtrusive Javascript]]
* [[Development:JavaScript functions]]
* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

[[Category:Coding guidelines|JavaScript guidelines]]
[[Category:Javascript|JavaScript guidelines]]
[[Category:AJAX|JavaScript guidelines]]

[[ja:開発:Javaスクリプトガイドライン]]