|
|
| (22 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| {{Moodle 2.0}}This document provides an brief overview of Moodle's use of YUI. | | {{Template:Migrated|newDocId=/docs/guides/javascript/yui/}} |
| | |
| 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.
| |
| | |
| == 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 [http://yuilibrary.com/yui/docs/api/ 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:
| |
| * [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]
| |
| | |
| 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.
| |
| | |
| 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 [http://www.youtube.com/watch?v=XdM0GJEnlNU 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:
| |
| | |
| <code javascript>
| |
| YUI.add('moodle-block_fruit-fruitbowl', function(Y) {
| |
| // Your module code goes here.
| |
| }, '@VERSION@', {
| |
| requires: ['panel']
| |
| }); | |
| </code>
| |
| | |
| 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:
| |
| | |
| <code javascript>
| |
| YUI().use('moodle-block_fruit-fruitbowl', function(Y) {
| |
| // Use the class you defined earlier.
| |
| }); | |
| </code>
| |
| | |
| == Documentation and further information ==
| |
| Other YUI documentation you may find useful:
| |
| * [[How_to_create_a_YUI_3_module]]
| |
| * [http://yuilibrary.com/yui/docs/api/ API Documentation for the main YUI library]
| |
| * [http://yuilibrary.com/yui/docs/guides/ YUI User Guides]
| |
| * [http://yuilibrary.com/yui/docs/tutorials/ YUI Tutorials]
| |
| * [http://yuilibrary.com/yui/docs/examples/ YUI Examples]
| |
| * [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.
| |
| | |
| == 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:
| |
| | |
| === 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.
| |
| | |
| We will soon start shipping a yuidoc.json configuration file if you'd like to generate your own documentation.
| |
| | |
| ==== Installation ====
| |
| Installation is relatively simple:
| |
| <code bash>
| |
| npm install yuidoc -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]
| |
| | |
| === Shifter ===
| |
| 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.
| |
| | |
| 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 -g
| |
| </code>
| |
| | |
| ==== 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>
| |
| | |
| Read more about shifter: https://moodle.org/mod/forum/discuss.php?d=217450
| |
| | |
| == See Also ==
| |
| * [[Javascript and YUI 3 FAQ]]
| |
| * [[JavaScript FAQ]]
| |
| | |
| [[Category:AJAX]]
| |
| [[Category:Javascript]]
| |
| [[Category:Javascript|YUI]]
| |
