The YUI PHP Loader Utility is a server-side utility that allows you to load specific YUI components and their dependencies into your page via PHP. YUI PHP Loader can operate as a holistic solution by loading all of your necessary YUI components, or it can be used to add one or more components to a page on which some YUI content already exists.
YUI also contains a client-side loader, which provides similar functionality from JavaScript.
YUI PHP Loader adds value in the following ways:
yahoo-dom-event.js
file that contains the Yahoo Global Object, the Dom Collection, and the Event Utility, three components that are commonly used together. By automatically using rolled-up files when it makes sense to do so, the YUI PHP Loader helps you reduce HTTP requests and thereby keep your page as efficient as possible.As you think about how you want to load YUI on the page, you may find it useful to refer to this overview of some of the most common loading strategies and their relative merits:
After downloading YUI PHP Loader, the archive needs to be extracted somewhere within the server's webroot (e.g. htdocs/phploader
). To begin using the Loader you must include the base class file and call the YAHOO_util_Loader
constructor with a YUI version number to create an instance of the Loader. The chosen version must have corresponding metadata available within your local YUI PHP Loader installation.
//Include the loader class file include("loader.php"); //Get an instance $loader = new YAHOO_util_Loader("2.9.0");
//Include the loader class file include("loader.php"); //Get an instance $loader = new YAHOO_util_Loader("2.9.0");
load()
MethodYUI PHP Loader makes it a simple thing to get started using YUI components. After creating an instance of YAHOO_util_Loader
tell it what you want to load, and let it sort out all of the dependencies on your behalf. When you are ready to output the CSS and/or JavaScript files simply call the tags()
method. Since we will cover the benefits of using rollup files later in this document we will turn them off for this first example.
include("loader.php"); $loader = new YAHOO_util_Loader("2.9.0"); //Turn off rollups $loader->allowRollups = false; //Specify YUI components to load $loader->load("yahoo", "dom", "event", "tabview", "grids", "fonts", "reset"); //Output the tags (this call would most likely be placed in the document head) $loader->tags(); /* This call will produce an output similar to the following: <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/fonts/fonts-min.css" /> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/grids/grids-min.css" /> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/reset/reset-min.css" /> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/tabview/assets/skins/sam/tabview.css" /> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/dom/dom-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/event/event-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/tabview/tabview-min.js"></script> */
include("loader.php"); $loader = new YAHOO_util_Loader("2.9.0"); //Turn off rollups $loader->allowRollups = false; //Specify YUI components to load $loader->load("yahoo", "dom", "event", "tabview", "grids", "fonts", "reset"); //Output the tags (this call would most likely be placed in the document head) $loader->tags(); /* This call will produce an output similar to the following: <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/fonts/fonts-min.css" /> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/grids/grids-min.css" /> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/reset/reset-min.css" /> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/tabview/assets/skins/sam/tabview.css" /> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/dom/dom-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/event/event-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/tabview/tabview-min.js"></script> */
The following configuration options are supported by the YUI PHP Loader Utility. These can be set individually on a Loader instance:
Configuration Option | Purpose |
---|---|
base | (string) Allows you to specify a different location (as a full or relative filepath) for the YUI build directory. By default, YUI PHP Loader will serve files from Yahoo's servers. |
filter |
(string) A filter to apply to result urls. This filter will modify the default
path for all modules. The default path for the YUI library is the
minified version of the files (e.g., event-min.js ). The valid filters are:
|
allowRollups | (boolean) Should Loader use aggregate files (like yahoo-dom-event.js or utilities.js ) that combine several YUI components in a single HTTP request? Default: true . |
loadOptional | (boolean) Should loader load optional dependencies for the components you're requesting? (Note: If you only want some but not all optional dependencies, you can list out the dependencies you want as part of your required list.) Default: false . |
combine | (boolean) If set to true, YUI files will be combined into a single request using the combo service provided on the Yahoo! CDN |
comboBase |
(string) The base path to the Yahoo! CDN service. Default: "http://yui.yahooapis.com/combo? Note: YUI PHP Loader also ships with an intrinsic, lightweight combo-handler (see combo.php ). Refer to the included examples for example code and an illustration of how you might want to use this functionality.
|
Each YUI component has a corresponding module name that is used as a unique identifier within YUI scripts. For example, the
Event Utility is internally referred to as "event"
. YUI PHP Loader loads components based on these unique module names. Here is the full list of YUI module names. All except YUI PHP Loader itself can be loaded via the Loader component.
YUI ships with some aggregate or "rollup" files, each comprising two or more modules, to help you reduce the number of HTTP requests you make while loading YUI content. Each aggregate file has its own module name. Moreover, some modules provide the functionality of one or more modules in the above list.
When you choose to allowRollup
s, YUI PHP Loader will choose the most appropriate set of files to meet your requirements while using the smallest number of included files. You can also specify an aggregate file directly as a requirement by requesting it by its own module name. The following is a list of modules that aggregate or include multiple modules:
YUI Rollup | Provides |
---|---|
container | containercore |
editor | simpleeditor |
reset-fonts | reset, fonts |
reset-fonts-grids | reset, fonts, grids, reset-fonts |
utilities | yahoo, event, dragdrop, animation, dom, connection, element, get, yuiloader, yahoo-dom-event |
yahoo-dom-event | yahoo, dom, event |
yuiloader | yahoo, get |
yuiloader-dom-event | yahoo, dom, event, get, yuiloader, yahoo-dom-event |
As noted in the configuration table the YUI PHP Loader provides some additional parameters that give us even more control over the loading and performance of our component selections. By simply enabling rollups in this example we can cut down the total HTTP requests from 9 to 5. If we enabled combo handling in addition to rollups we can reduce this down to just 2 HTTP requests; one per tag type (i.e.) link and script. When combo-handling is enabled, it is often most efficient to disallow rollups, whose principal purpose is to reduce HTTP requests; because combo-handling minimizes requests at a foundational level, allowing rollups may increase the size of your JS/CSS payload without delivering any addtional functionality required by your application.
include("loader.php"); $loader = new YAHOO_util_Loader("2.9.0"); //Turn on rollups (this is actually on by default) $loader->allowRollups = true; //Specify YUI components to load $loader->load("yahoo", "dom", "event", "tabview", "grids", "fonts", "reset"); /* A call to tags method here would produce an output similar to the following: <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/reset-fonts-grids/reset-fonts-grids.css" /> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/tabview/assets/skins/sam/tabview.css" /> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/tabview/tabview-min.js"></script> */ //Enable combo handling $loader->combine = true; //Output the tags (this call would most likely be placed in the document head) $loader->tags(); /* The final output would now be similar to the following, a single HTTP request for each type (i.e.) CSS and JavaScript: <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/combo?2.9.0/build/reset-fonts-grids/reset-fonts-grids.css&2.9.0/build/tabview/assets/skins/sam/tabview.css" /> <script type="text/javascript" src="http://yui.yahooapis.com/combo?2.9.0/build/yahoo-dom-event/yahoo-dom-event.js&2.9.0/build/element/element-min.js&2.9.0/build/tabview/tabview-min.js"></script></head> */
include("loader.php"); $loader = new YAHOO_util_Loader("2.9.0"); //Turn on rollups (this is actually on by default) $loader->allowRollups = true; //Specify YUI components to load $loader->load("yahoo", "dom", "event", "tabview", "grids", "fonts", "reset"); /* A call to tags method here would produce an output similar to the following: <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/reset-fonts-grids/reset-fonts-grids.css" /> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/tabview/assets/skins/sam/tabview.css" /> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.9.0/build/tabview/tabview-min.js"></script> */ //Enable combo handling $loader->combine = true; //Output the tags (this call would most likely be placed in the document head) $loader->tags(); /* The final output would now be similar to the following, a single HTTP request for each type (i.e.) CSS and JavaScript: <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/combo?2.9.0/build/reset-fonts-grids/reset-fonts-grids.css&2.9.0/build/tabview/assets/skins/sam/tabview.css" /> <script type="text/javascript" src="http://yui.yahooapis.com/combo?2.9.0/build/yahoo-dom-event/yahoo-dom-event.js&2.9.0/build/element/element-min.js&2.9.0/build/tabview/tabview-min.js"></script></head> */
In addition to the tags()
method, there are a number of other class methods that will allow you to do things like embed the code inline and fetch the CSS and JavaScript seperately (which is not a bad idea since there are well known performance benefits to placing CSS in the document head and JavaScript near the bottom of your document). For more information on these and other methods, please refer to the API documents.
YUI PHP Loader relies on metadata files to calculate module dependencies, rollups, sort order, etc. The metadata files are located in the lib/meta folder. By default YUI PHP Loader ships with metadata for the latest YUI releases; both versions 2 and 3. Additional metadata can be added as needed to support older and/or newer YUI releases. YUI PHP Loader uses pre-built PHP config files first, but is capable of parsing YUI JSON metadata files if no PHP config file is available. The naming convention for PHP config files is config_{yui version}.php
(e.g. config_2.9.0.php
). The naming convention for JSON config files is json_{yui version}.txt
(e.g. json_2.9.0.txt
).
The YUI Library and related topics are discussed on the on the YUILibrary.com forums.
Also be sure to check out YUIBlog for updates and articles about the YUI Library written by the library's developers.
The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.
All YUI 2.x users should review the YUI 2.8.2 security bulletin, which discusses a vulnerability present in YUI 2.4.0-2.8.1.
Copyright © 2013 Yahoo! Inc. All rights reserved.