Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

YUI: Difference between revisions

From MoodleDocs
mNo edit summary
(Complete overhaul of the page to update for YUI3)
Line 1: Line 1:
{{obsolete}}
{{Moodle 2.0}} This document provides an overview of Moodle's use of YUI.


'''NOTE: This documentation related to use of YUI in Moodle prior to Moodle 2.0 and refers to use of YUI2. From Moodle 2.0 onwards, YUI3 is the preferred JavaScript library and development of YUI2 has ceased. The new way to work with JavaScript is described in [[JavaScript guidelines]]'''
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.


= Benefits =
YUI is an extremely extensible 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.


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.  
= The Basics =
Since version 2.4, Moodle has included SimpleYUI rather than YUI, which includes several modules as standard including:
* [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]


All components in the YUI Library have been released as open source under a BSD license and are free for all uses.
We recommend writing your code within a [[How_to_create_a_YUI_3_module|YUI module]], but it is also possible to use one of the other methods to include your JavaScript. These include:
* use within a javascript file included by a theme; and
* inclusion of a module.js file.


Details of the YUI can be found at the [http://developer.yahoo.com/yui/index.html Yahoo Developer Website].
= 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]


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


Some of the following information will be out of date when Moodle 2.0 is released. Please see [[JavaScript guidelines]] for the latest information.
= 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 <a href="http://nodejs.org">Node.js</a> which is relatively trivial to install on most operating systems:


==Getting started==
== JSHint ==
<a href="http://jshint.com">JSHint</a> is a JSLint derivative for checking your code. This includes checking for errors and recommended stylistic approaches to writing JavaScript.


One approach is to find an example that is close to what you want, either in the Moodle code, or on the [http://developer.yahoo.com/yui/ Yahoo Developer Website]. Then adapt it to your needs.
Since Moodle 2.5, a JSHint configuration is also included in the Moodle codebase to inform the tester of our preferences and recommendations.


The entire YUI libraries are all part of a single YAHOO object, so they will not clash with other code. You then use them like this:
=== Installation ===
<code javascript>
Installation is relatively simple:
YAHOO.util.Event.onDOMReady(...);
<code bash>
    npm install jshint -g
</code>
</code>


=== Dependencies ===
=== 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.


In order to make the ''onDOMReady'' method available to you, you first include a .js 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:
To run jshint on the command line, simply pass it the file that you wish to check:
 
<code bash>
<code php>
    jshint blocks/fruit/yui/fruitbowl/fruitbowl.js
require_js(array('yui_yahoo', 'yui_event'));
</code>
</code>


As you can see, you need only refer to the libraries by name. You don't need to know the full path. The [http://xref.moodle.org/lib/ajax/ajaxlib.php.source.html#l6 ajax_get_lib()] function in ''/lib/ajax/ajaxlib.php'' has the complete list of libraries.
=== Documentation ===
There's a variety of documentation on JSHint and the error messages it returns. Start off with the jshint website:
* <a href="http://jshint.com">JSHint</a>
* <a href="http://jslinterrors.com/">JSLint Error Explanations</a>


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.
== YUIDoc ==
<a href="http://yui.github.com/yuidoc/">YUIDoc</a> 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.


=== Skinning ===
We will soon start shipping a yuidoc.json configuration file if you'd like to generate your own documentation.


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:
=== Installation ===
Installation is relatively simple:
<code bash>
    npm install yuidoc -g
</code>


<code php>
=== Use ===
document.body.className += ' yui-skin-sam';
To run yuidoc across the entirety of Moodle JavaScript, from the root directory run:
<code bash>
    yuidoc
</code>
</code>


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
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.


<code php>
=== Documentation ===
background: url(../../whatever.png);
There's a variety of documentation on JSHint and the error messages it returns. Start off with the jshint website:
</code>
* <a href="http://yui.github.com/yuidoc/">YUIDoc Project Documentation</a>
* <a href="http://yui.github.com/yuidoc/syntax/index.html">YUIDoc Syntax Reference</a>


and paste them into your styles.php below the css include you've added, but looking like this:
== Shifter ==
The upstream YUI project use a tool called <a href="http://yuilibrary.com/shifter">Shifter</a> 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.


<code php>
=== Installation ===
background: url(<?php echo $CFG->wwwroot ?>/lib/yui/whatever.png);
Installation is relatively simple from the node.js Packaging Manager:
<code bash>
    npm install shifter -g
</code>
</code>


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


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.
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>


== Debugging ==
For more general use, you can run shifter across the whole of Moodle using --walk:
<code bash>
    shifter --walk --recursive
</code>


* Ideally, you should use '''Firefox''', with the [https://addons.mozilla.org/en-US/firefox/addon/60 Web Developer Toolbar], [https://addons.mozilla.org/en-US/firefox/addon/1843 Firebug] and [https://addons.mozilla.org/en-US/firefox/addon/5369 YSlow] extensions loaded (see also [[Firebug]] and [[Web developer extension]]).


* 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.
[[Category:AJAX]]
 
[[Category:Javascript]]
== See also ==
[[Category:Javascript|YUI]]


* [http://developer.yahoo.com/yui/ The official YUI documentation]
== See Also ==
* [[Javascript and YUI 3 FAQ]]
* [[JavaScript FAQ]]
* [[JavaScript FAQ]]
[[Category:Javascript|YUI]]
[[Category:AJAX|YUI]]

Revision as of 19:37, 1 March 2013

Moodle 2.0 

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

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

Benefits

YUI is an extremely extensible 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.

The Basics

Since version 2.4, Moodle has included SimpleYUI rather than YUI, which includes several modules as standard including:

We recommend writing your code within a YUI module, but it is also possible to use one of the other methods to include your JavaScript. These include:

  • use within a javascript file included by a theme; and
  • inclusion of a module.js file.

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.

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 <a href="http://nodejs.org">Node.js</a> which is relatively trivial to install on most operating systems:

JSHint

<a href="http://jshint.com">JSHint</a> 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

<a href="http://yui.github.com/yuidoc/">YUIDoc</a> 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: 

   npm install yuidoc -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:

Shifter

The upstream YUI project use a tool called <a href="http://yuilibrary.com/shifter">Shifter</a> 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.

Installation

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

   npm install shifter -g

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

See Also

Retrieved from "https://docs.moodle.org/dev/index.php?title=YUI&oldid=38073"
Powered by MediaWiki