YUI: Difference between revisions

Revision as of 18:17, 2 August 2015

Moodle 2.4

Moodle 2.5

Moodle 2.6

Moodle 2.7

This document provides an brief overview of Moodle's use of YUI.

Note: As of Moodle 2.9 we are transitioning away from YUI to AMD modules and JQuery. This transition will take a long time, but it is important because the YUI team have stopped all new development on the YUI library ( http://yahooeng.tumblr.com/post/96098168666/important-announcement-regarding-yui ). See Javascript Modules and jQuery for information on the new framework for Javascript.

The Yahoo! User Interface (YUI) framework is a fast, powerful, modular, and well-documented framework with a powerful loading system.

The Basics

YUI is an extremely extensible, fast, modular, and powerful JavaScript framework with a very capable loading system. A number of modules are available for YUI providing a wide range of functionality to suit most situations. All of the core YUI modules are documented on their API. We are working to put together documentation for moodle's YUI modules too.

Since version 2.4, Moodle has included SimpleYUI to expose several features natively without requiring you to specify which features you wish to use. Prior to this a basic YUI was included. SimpleYUI loads a number of standard modules and makes them available on the global Y namespace. These include:

Whilst accessing the global Y variable will suffice for many uses, we highly recommend that you look at writing your code within a YUI module. It is also possible to use one of the other methods to include your JavaScript. These include:

inclusion of a javascript file (e.g. a file included by a theme); and
inclusion of a module.js file.

It is also possible to use JavaScript within a Database module - see the JavaScript template setting for further information.

Modularity

YUI is extremely modular with different components, features, plugins, and tasks broken down into YUI Modules. When using YUI, you can choose which modules you wish to use and the YUI loader will go away and retrieve those modules, determining their dependencies automatically. This has the effect of separating out the load and execution phases of JavaScript component loading and also allows for asynchronous loading of the code. For a deeper dive on the benefits of this separation, it's well worth watching this video entitled YUI3 Below the Surface.

In order to benefit from these features, it is necessary to wrap your code in a registration function. This wrapper defines the name of the module, wraps the code in a closure to offer module sandboxing, and defines meta-data to inform the loader of any specific dependencies. A complete wrapper is shown below:

YUI.add('moodle-block_fruit-fruitbowl', function(Y) {

 // Your module code goes here.

}, '@VERSION@', {

 requires: ['panel']

});

Note: From Moodle 2.5, it is possible to write your modules in such a way that you do not have to explicitly specify write the YUI.add() wrapper.

To then make use of this code, you then have to use it. For example:

YUI().use('moodle-block_fruit-fruitbowl', function(Y) {

 // Use the class you defined earlier.

});

Documentation and further information

Other YUI documentation you may find useful:

We will soon be adding API Documentation for Moodle-specific YUI modules in addition to the core YUI library.

Books:

Some good books:

YUI 3 Cookbook by Evan Goer
Maintainable JavaScript by Nicholas C. Zakas

Useful tools

JavaScript authoring have moved along considerably in recent years, and we highly recommend that you look at using some of the available tools to help you in your development. Most of these tools are available through Node.js which is relatively trivial to install on most operating systems:

Shifter

Shifter is a tool to help manage your YUI modules. It takes away some of the confusion associated with creating a YUI module (like the YUI.add line) and moves the metadata out of your module, and into a separate json file. This means that it can be picked up by Moodle to reduce the number of HTTP transactions through use of the YUI combo loader. Shifter also lints your code with jshint, and minifies your code too.

The upstream YUI project use a tool called Shifter to wrap up meta-data, rollup files, minify, and strip out debugging information from files. We will shortly be shifting to use of Shifter for core Moodle as it offers us many potential benefits.

Note: More information on the use of Shifter within Moodle is discussed at Javascript/Shifter.

Installation

Installation is relatively simple from the node.js Packaging Manager:

   npm install shifter@SUPPORTEDVERSION -g

For information on the current support version see Javascript/Shifter#Supported_version_of_Shifter

Use

There are two ways to run shifter depending on your intended use.

During development, we recommend you run shifter in --watch mode. To do so, enter the src directory of the module you are working on and run: cd lib/yui/src shifter --watch

For more general use, you can run shifter across the whole of Moodle using --walk: shifter --walk --recursive ...from your Moodle wwwroot.

Read more about shifter: https://moodle.org/mod/forum/discuss.php?d=217450

JSHint

JSHint is a JSLint derivative for checking your code. This includes checking for errors and recommended stylistic approaches to writing JavaScript.

Since Moodle 2.5, a JSHint configuration is also included in the Moodle codebase to inform the tester of our preferences and recommendations.

Installation

Installation is relatively simple:

   npm install jshint -g

Use

Many IDEs and editors will automatically detect if you have JSHint installed and pass your code through it for you, reporting any errors as you go.

To run jshint on the command line, simply pass it the file that you wish to check:

   jshint blocks/fruit/yui/fruitbowl/fruitbowl.js

Documentation

There's a variety of documentation on JSHint and the error messages it returns. Start off with the jshint website:

YUIDoc

YUIDoc is a documentation system. It can work with any type of code, but is designed with JavaScript in mind. It's the documentation system used to create the YUI core API documentation, and will soon be used to create API documentation for Moodle-specific YUI modules in core.

Installation

Installation is relatively simple:

   npm install yuidocjs -g

Use

To run yuidoc across the entirety of Moodle JavaScript, from the root directory run:

   yuidoc

Whilst writing your documentation, you may also like to run yuidoc in server mode. See the --server option for help on how to do this.

Documentation

There's a variety of documentation on JSHint and the error messages it returns. Start off with the jshint website:

Moodle Settings for Javascript Development

The following settings will ensure that the js loaded by your browser is relatively readable.

Make sure that :

your Development / Debugging / Debug messages is set to "Developer : Extra Debug Moodle Messages ...." - Moodle will then use the debug non-minified and thus more readable YUI 2 and YUI 3 library files.
You will probably want to change some of the settings at "Home / Site administration / Appearance / AJAX and Javascript" :
- YUI combo loading - you probably want to turn this off so that files are not combined.
- Javascript caching and compressing - turn this off so that your custom JS code is not minified.
- Check the other settings on this page to see that they are as you would expect them to be.

You might want to add the following code to your config.php file when developing or debugging javascript code:

// For javascript development or debugging. $CFG->cachejs = false; $CFG->yuicomboloading = false; $CFG->yuiloglevel = 'debug'; $CFG->debug = 32767;

Documentation

YUI: Difference between revisions

Revision as of 18:17, 2 August 2015

Contents

The Basics

Modularity

Documentation and further information

Books:

Useful tools

Shifter

Installation

Use

JSHint

Installation

Use

Documentation

YUIDoc

Installation

Use

Documentation

Moodle Settings for Javascript Development

See Also

@@ Line 1: / Line 1: @@
-The Yahoo! User Interface (YUI) Library is a set of utilities and controls, written in JavaScript, for building richly interactive web applications using techniques such as DOM scripting, DHTML and AJAX. All components in the YUI Library have been released as open source under a BSD license and are free for all uses. Details of the YUI can be found at the [http://developer.yahoo.com/yui/index.html Yahoo Developer Website].
+{{Moodle 2.4}}
+{{Moodle 2.5}}
+{{Moodle 2.6}}
+{{Moodle 2.7}}
-==Getting started==
+This document provides an brief overview of Moodle's use of YUI.
-Broadly speaking, you find an example you'd like to implement e.g. from [http://developer.yahoo.com/yui/examples/slider/index.html here], then add it to an existing page, then tweak it to do what you want.
+Note: As of Moodle 2.9 we are transitioning away from YUI to AMD modules and JQuery. This transition will take a long time, but it is important because the YUI team have stopped all new development on the YUI library ( http://yahooeng.tumblr.com/post/96098168666/important-announcement-regarding-yui ). See [[ Javascript Modules ]] and [[ jQuery ]] for information on the new framework for Javascript.
-YUI works with a single global object called YAHOO, which all other functions are added to via namespacing. You then use them like this:
+The [http://yuilibrary.com Yahoo! User Interface (YUI)] framework is a fast, powerful, modular, and [http://yuilibrary.com/yui/docs/api/ well-documented] framework with a powerful loading system.
- YAHOO.util.Event.onDOMready(//do something );
-===Dependencies===
+== The Basics ==
-In order to make the onDOMready method available to you, you first include a .j file that sets up the global object, then the events library .js file that adds all of the events methods to it. Moodle's way of doing this is with the require_js() function:
+YUI is an extremely extensible, fast, modular, and powerful JavaScript framework with a very capable loading system.
- <?php require_js(array('yui_yahoo', 'yui_event')); ?>
+A number of modules are available for YUI providing a wide range of functionality to suit most situations.
-You can see that you can use shortcuts for many of the libraries. the ajax_get_lib() function in /lib/ajax/ajaxlib.php has details. Otherwise, you use the full path like this:
+All of the core YUI modules are documented on their [http://yuilibrary.com/yui/docs/api/ API]. We are working to put together documentation for moodle's YUI modules too.
- <?php require_js(array($CFG->dirroot.'/lib/yui/yahoo/yahoo-min.js', $CFG->dirroot.'/lib/yui/event/event-min.js')); ?>
-You notice that the files are called xxx-min.js. This is because they have been minified to make them as small as possible for fast page loading. Every file comes in a non-minifed version too called xxx-debug.js, which will give you accurate error messages as well as letting you follow progress in the YUI logger console.
-Once you have included the various .js dependency files with require_js() as outlined above, then write your own source .js file and add that to the require_js array '''after''' the other YUI ones. Many of the YUI files have other dependencies, so you'll often need to include more than one and the order matters for them too. Just follow the examples.
+Since version 2.4, Moodle has included SimpleYUI to expose several features natively without requiring you to specify which features you wish to use. Prior to this a basic YUI was included. SimpleYUI loads a number of standard modules and makes them available on the global Y namespace. These include:
+* [http://yuilibrary.com/yui/docs/api/classes/YUI.html YUI]
+* [http://yuilibrary.com/yui/docs/api/modules/oop.html oop]
+* [http://yuilibrary.com/yui/docs/api/classes/DOM.html dom]
+* [http://yuilibrary.com/yui/docs/api/modules/event-custom-base.html event-custom-base]
+* [http://yuilibrary.com/yui/docs/api/modules/event-base.html event-base]
+* [http://yuilibrary.com/yui/docs/api/modules/pluginhost.html pluginhost]
+* [http://yuilibrary.com/yui/docs/api/classes/Node.html node]
+* [http://yuilibrary.com/yui/docs/api/modules/event-delegate.html event-delegate]
+* [http://yuilibrary.com/yui/docs/api/modules/io-base.html io-base]
+* [http://yuilibrary.com/yui/docs/api/modules/json-parse.html json-parse]
+* [http://yuilibrary.com/yui/docs/api/modules/transition.html transition]
+* [http://yuilibrary.com/yui/docs/api/modules/selector-css3.html selector-css3]
+* [http://yuilibrary.com/yui/docs/api/modules/dom-style-ie.html dom-style-ie]
+* [http://yuilibrary.com/yui/docs/api/modules/querystring-stringify-simple.html querystring-stringify-simple]
-You can also inject libraries dynamically if you really want to using [http://developer.yahoo.com/yui/yuiloader/ YUI loader], which adds <script> and <link> tags on the fly and can keep initial page load lighter.
+Whilst accessing the global Y variable will suffice for many uses, we highly recommend that you look at writing your code within a [[How_to_create_a_YUI_3_module|YUI module]]. It is also possible to use one of the other methods to include your JavaScript. These include:
+* inclusion of a javascript file (e.g. a file included by a theme); and
+* inclusion of a module.js file.
-===Skinning===
+It is also possible to use JavaScript within a Database module - see the JavaScript template setting for further information.
-For CSS, you include the css dependency files in either your theme styles.php or module/block styles.php using the standard PHP include() function. You will often need to apply the yui-skin-sam style to the body tag to get the skins to work right, so add something near the top of your script like:
- document.body.className += ' yui-skin-sam';
-As a caveat, the paths in the CSS files assume that yui is placed in the site's web root and have no reference to $CFG->wwwroot, so none of the images work. The solution is to go through the CSS files, pulling out any that have
- background: url(../../whatever.png);
-and paste them into your styles.php below the css include you've added, but looking like this:
- background: url(<?php echo $CFG->wwwroot ?>/lib/yui/whatever.png);
+== Modularity ==
+YUI is extremely modular with different components, features, plugins, and tasks broken down into YUI Modules. When using YUI, you can choose which modules you wish to use and the YUI loader will go away and retrieve those modules, determining their dependencies automatically. This has the effect of separating out the load and execution phases of JavaScript component loading and also allows for asynchronous loading of the code. For a deeper dive on the benefits of this separation, it's well worth watching this video entitled [http://www.youtube.com/watch?v=XdM0GJEnlNU YUI3 Below the Surface].
-==Performance==
+In order to benefit from these features, it is necessary to wrap your code in a registration function. This wrapper defines the name of the module, wraps the code in a closure to offer module sandboxing, and defines meta-data to inform the loader of any specific dependencies. A complete wrapper is shown below:
-Remember to use [http://developer.yahoo.com/yui/examples/event/event-delegation.html event bubbling] wherever possible so that instead of adding a drag-drop listener to every page element, you just add one to the content div which catches all of the events lower down the DOM tree and does what's needed.
+<code javascript>
+YUI.add('moodle-block_fruit-fruitbowl', function(Y) {
+  // Your module code goes here.
+}, '@VERSION@', {
+  requires: ['panel']
+});
+</code>
-==Debugging==
+Note: From Moodle 2.5, it is possible to write your modules in such a way that you do not have to explicitly specify write the YUI.add() wrapper.
-Ideally, you should use Firefox, with the [https://addons.mozilla.org/en-US/firefox/addon/60 webdeveloper], [https://addons.mozilla.org/en-US/firefox/addon/1843 Firebug] and [https://addons.mozilla.org/en-US/firefox/addon/5369 YSlow] extensions loaded. The YUI logger will need to be included as a dependency if you want to use the xxx-debug.js versions of the files, so you need to add it to require_js() before them.
+To then make use of this code, you then have to use it. For example:
-==Documentation for specific libraries==
+<code javascript>
+YUI().use('moodle-block_fruit-fruitbowl', function(Y) {
+  // Use the class you defined earlier.
+});
+</code>
-*[[Yahoo Global Object]] (/lib/yui/yahoo/yahoo.js)
+== Documentation and further information ==
-*[[YUI event utility|YUI event utility]] (/lib/yui/event/event.js)
+Other YUI documentation you may find useful:
-*[[Yahoo DOM Manipulation ]] (/lib/yui/dom/dom.js)
+* [[How_to_create_a_YUI_3_module]]
-*[[Yahoo Connection Manager]] (/lib/yui/connection/connection.js)
+* [http://yuilibrary.com/yui/docs/api/ API Documentation for the main YUI library]
-*[[Yahoo Drag and Drop Utility]] (/lib/yui/dragdrop/dragdrop.js)
+* [http://yuilibrary.com/yui/docs/guides/ YUI User Guides]
-*[[Yahoo Animation Utility]] (/lib/yui/animation/animation.js)
+* [http://yuilibrary.com/yui/docs/tutorials/ YUI Tutorials]
-*[[YUI TreeView|YUI TreeView]] (/lib/yui/treeview/treeview.js)
+* [http://yuilibrary.com/yui/docs/examples/ YUI Examples]
-*[[Yahoo logger]] (/lib/yui/logger/logger-min.js)
+* [http://yuilibrary.com/forum/ YUI Forums]
+We will soon be adding API Documentation for Moodle-specific YUI modules in addition to the core YUI library.
+== Books: ==
+Some good books:
+* [http://shop.oreilly.com/product/0636920013303.do YUI 3 Cookbook] by Evan Goer
+* [http://shop.oreilly.com/product/0636920025245.do Maintainable JavaScript] by Nicholas C. Zakas
+== Useful tools ==
+JavaScript authoring have moved along considerably in recent years, and we highly recommend that you look at using some of the available tools to help you in your development. Most of these tools are available through [http://nodejs.org Node.js] which is relatively trivial to install on most operating systems:
+=== Shifter ===
+[[Javascript/Shifter|Shifter]] is a tool to help manage your YUI modules. It takes away some of the confusion associated with creating a YUI module (like the YUI.add line) and moves the metadata out of your module, and into a separate json file. This means that it can be picked up by Moodle to reduce the number of HTTP transactions through use of the YUI combo loader. Shifter also lints your code with jshint, and minifies your code too.
+The upstream YUI project use a tool called [http://yuilibrary.com/shifter Shifter] to wrap up meta-data, rollup files, minify, and strip out debugging information from files.
+We will shortly be shifting to use of Shifter for core Moodle as it offers us many potential benefits.
+'''Note: More information on the use of Shifter within Moodle is discussed at [[Javascript/Shifter]].'''
+==== Installation ====
+Installation is relatively simple from the node.js Packaging Manager:
+<code bash>
+    npm install shifter@SUPPORTEDVERSION -g
+</code>
+For information on the current support version see [[Javascript/Shifter#Supported_version_of_Shifter]]
+==== Use ====
+There are two ways to run shifter depending on your intended use.
+During development, we recommend you run shifter in --watch mode. To do so, enter the src directory of the module you are working on and run:
+<code bash>
+cd lib/yui/src
+shifter --watch
+</code>
+For more general use, you can run shifter across the whole of Moodle using --walk:
+<code bash>
+shifter --walk --recursive
+</code>
+...from your Moodle wwwroot.
+Read more about shifter: https://moodle.org/mod/forum/discuss.php?d=217450
+=== JSHint ===
+[http://jshint.com JSHint] is a JSLint derivative for checking your code. This includes checking for errors and recommended stylistic approaches to writing JavaScript.
+Since Moodle 2.5, a JSHint configuration is also included in the Moodle codebase to inform the tester of our preferences and recommendations.
+==== Installation ====
+Installation is relatively simple:
+<code bash>
+    npm install jshint -g
+</code>
+==== Use ====
+Many IDEs and editors will automatically detect if you have JSHint installed and pass your code through it for you, reporting any errors as you go.
+To run jshint on the command line, simply pass it the file that you wish to check:
+<code bash>
+    jshint blocks/fruit/yui/fruitbowl/fruitbowl.js
+</code>
+==== Documentation ====
+There's a variety of documentation on JSHint and the error messages it returns. Start off with the jshint website:
+* [http://jshint.com JSHint]
+* [http://jslinterrors.com JSLint Error Explanations]
+=== YUIDoc ===
+[http://yui.github.com/yuidoc/ YUIDoc] is a documentation system. It can work with any type of code, but is designed with JavaScript in mind.
+It's the documentation system used to create the YUI core API documentation, and will soon be used to create API documentation for Moodle-specific YUI modules in core.
+==== Installation ====
+Installation is relatively simple:
+<code bash>
+    npm install yuidocjs -g
+</code>
+==== Use ====
+To run yuidoc across the entirety of Moodle JavaScript, from the root directory run:
+<code bash>
+    yuidoc
+</code>
+Whilst writing your documentation, you may also like to run yuidoc in server mode. See the --server option for help on how to do this.
+==== Documentation ====
+There's a variety of documentation on JSHint and the error messages it returns. Start off with the jshint website:
+* [http://yui.github.com/yuidoc/ YUIDoc Project Documentation]
+* [http://yui.github.com/yuidoc/syntax/index.html YUIDoc Syntax Reference]
+==Moodle Settings for Javascript Development==
+The following settings will ensure that the js loaded by your browser is relatively readable.
+Make sure that :
+* your  Development / Debugging / Debug messages is set to "Developer : Extra Debug Moodle Messages ...." - Moodle will then use the debug non-minified and thus more readable YUI 2 and YUI 3 library files.
+* You will probably want to change some of the settings at "Home / Site administration / Appearance / AJAX and Javascript" :
+** YUI combo loading - you probably want to turn this off so that files are not combined.
+** Javascript caching and compressing - turn this off so that your custom JS code is not minified.
+** Check the other settings on this page to see that they are as you would expect them to be.
+You might want to add the following code to your config.php file when developing or debugging javascript code:
+<code php>
+// For javascript development or debugging.
+$CFG->cachejs = false;
+$CFG->yuicomboloading = false;
+$CFG->yuiloglevel = 'debug';
+$CFG->debug = 32767;
+</code>
+== See Also ==
+* [[ Javascript Modules ]]
+* [[ jQuery ]]
+* [[JavaScript FAQ]]
+[[Category:AJAX]]
+[[Category:Javascript]]
 [[Category:Javascript|YUI]]
-[[Category:AJAX|YUI]]
-{{CategoryDeveloper}}