Note: You are currently viewing documentation for Moodle 4.0. Up-to-date documentation for the latest stable version of Moodle may be available here: YUI.

Development:YUI: Difference between revisions

From MoodleDocs
mNo edit summary
(Wrong url)
 
(9 intermediate revisions by 4 users not shown)
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].
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.  


==Getting started==
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].
 
==Note==


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.  
Some of the following information will be out of date when Moodle 2.0 is released. Please see [[Development:JavaScript guidelines]] for the latest information.


YUI works with a single global object called YAHOO, which all other functions are added to via namespacing. You then use them like this:
==Getting started==
YAHOO.util.Event.onDOMready(//do something );


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


<code php>
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:
<?php
<code javascript>
require_js(array('yui_yahoo', 'yui_event'));  
YAHOO.util.Event.onDOMReady(...);
?>
</code>
</code>


You can see that you can use shortcuts for many of the libraries. The [http://xref.moodle.org/lib/ajax/ajaxlib.php.html#ajax_get_lib ajax_get_lib()] function in ''/lib/ajax/ajaxlib.php'' has details. Otherwise, you use the full path like this:
=== Dependencies ===
 
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:


<code php>
<code php>
<?php
require_js(array('yui_yahoo', 'yui_event'));  
require_js(array(
    $CFG->dirroot.'/lib/yui/yahoo/yahoo-min.js',
    $CFG->dirroot.'/lib/yui/event/event-min.js')
    );  
?>
</code>
</code>


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


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


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


=== Skinning ===
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:
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';
 
<code php>
document.body.className += ' yui-skin-sam';
</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
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);
 
<code php>
background: url(../../whatever.png);
</code>
 
and paste them into your styles.php below the css include you've added, but looking like this:
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);
 
<code php>
background: url(<?php echo $CFG->wwwroot ?>/lib/yui/whatever.png);
</code>


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


== Debugging ==
== Debugging ==
* 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 [[Development:Firebug]] and [[Web developer extension]]).  
* 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 [[Development: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.
* 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.
== Documentation for specific libraries ==
* [[Yahoo Global Object]] (/lib/yui/yahoo/yahoo.js)
* [[Development:YUI event utility|YUI event utility]] (/lib/yui/event/event.js)
* [[Yahoo DOM Manipulation ]] (/lib/yui/dom/dom.js)
* [[Yahoo Connection Manager]] (/lib/yui/connection/connection.js)
* [[Yahoo Drag and Drop Utility]] (/lib/yui/dragdrop/dragdrop.js)
* [[Yahoo Animation Utility]] (/lib/yui/animation/animation.js)
* [[Development:YUI TreeView|YUI TreeView]] (/lib/yui/treeview/treeview.js)
* [[Yahoo logger]] (/lib/yui/logger/logger-min.js)


== See also ==
== See also ==


* [[Javascript FAQ]]
* [http://developer.yahoo.com/yui/ The official YUI documentation]
* [[JavaScript FAQ]]


[[Category:Javascript|YUI]]
[[Category:Javascript|YUI]]
[[Category:AJAX|YUI]]
[[Category:AJAX|YUI]]
{{CategoryDeveloper}}
{{CategoryDeveloper}}

Latest revision as of 10:36, 8 February 2011

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 Yahoo Developer Website.

Note

Some of the following information will be out of date when Moodle 2.0 is released. Please see Development:JavaScript guidelines for the latest information.

Getting started

One approach is to find an example that is close to what you want, either in the Moodle code, or on the Yahoo Developer Website. Then adapt it to your needs.

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: YAHOO.util.Event.onDOMReady(...);

Dependencies

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:

require_js(array('yui_yahoo', 'yui_event'));

As you can see, you need only refer to the libraries by name. You don't need to know the full path. The ajax_get_lib() function in /lib/ajax/ajaxlib.php has the complete list of libraries.

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.

Skinning

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);

Performance

Remember to use 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.

Debugging

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

See also

Template:CategoryDeveloper