Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 270 lines (224 sloc) 17.055 kb
965ec05 @cauld Moving the main index page location and adding a 2nd example index page
cauld authored
1 <?PHP include("./examples/inc/config.inc"); ?>
2 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3 <html>
4 <head>
5 <title>YUI Library: YUI Loader Utility</title>
6 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
7 <link rel="stylesheet" href="examples/assets/reset-fonts-grids-min.css" type="text/css">
8 <link rel="stylesheet" type="text/css" href="examples/assets/dpSyntaxHighlighter.css">
9 <link rel="stylesheet" type="text/css" href="examples/assets/yui.css">
10 <link rel="shortcut icon" href="examples/assets/favicon.ico" type="image/x-icon">
11 </head>
12 <body id="yahoo-com" class=" yui-skin-sam">
13 <div id="doc3" class="yui-t7">
14 <div id="hd">
15 <div id="ygunav">
16 <p><em>
17 <a href="http://developer.yahoo.com">Developer Network Home</a> <i> - </i>
18 <a href="http://help.yahoo.com/help/us/ysearch">Help</a>
19 </em>
20 </p>
21 </div>
22 <div id="ygma"><a href="/"><img src="http://l.yimg.com/a/i/us/nt/ma/ma_devnet_1.gif" border="0"></a></div>
23 <div id="pagetitle"><h1>YUI Library: YUI PHP Loader Utility</h1></div>
24 </div>
25 <div id="bd">
20723b4 @cauld Making the api and example documentation part of the phploader package i...
cauld authored
26 <div id="yui-main">
27 <div class="yui-b">
28 <div class="yui-ge">
29 <div class="yui-u first">
30
31 <div id="promo" class="component">
32 <h1>Yahoo! UI Library: YUI PHP Loader</h1>
33
34 <p>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.</p>
35
36 <p>YUI PHP Loader adds value in the following ways:</p>
37 <ol>
38 <li><strong>Reliable, sorted loading of dependencies:</strong> YUI comprises more than two-dozen components, many of which work together to provide the best possible compromise between compartmentalization and code reuse. Because of this, YUI components often need to load with specific dependencies in a specific order. YUI PHP Loader understands which components depend on one another, and based on this knowledge it ensures that the right resources are loaded in the right order.</li>
39 <li><strong>Automatic use of rolled-up files.</strong> YUI PHP Loader knows about all of the built-in rollup files that ship with YUI — like the yahoo-dom-event.js file that contains the <a href="http://developer.yahoo.com/yui/yahoo/">Yahoo Global Object</a>, the <a href="http://developer.yahoo.com/yui/dom/">Dom Collection</a>, and the <a href="http://developer.yahoo.com/yui/event/">Event Utility</a>, 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 <a href="http://yuiblog.com/blog/2006/11/28/performance-research-part-1/">reduce HTTP requests</a> and thereby keep your page as efficient as possible.</li>
40
41 </ol>
42
43 <p>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:</p>
44 <ul>
45 <li>"<a href="http://yuiblog.com/blog/2008/10/17/loading-yui/">Loading YUI: Seeds, Core, and Combo-handling</a>", by Eric Miraglia on <a href="http://yuiblog.com/">YUIBlog</a>.<br />(<em>Note</em>: While this reference talks mostly about client side loading the basic concepts are still applicable)</li>
46 </ul>
47
48 <div>
49 <h4>On This Page:</h4>
50 <ul>
51 <li><a href="#start">Getting Started</a></li>
52 <li><a href="#using">Simple Use Case: Adding YUI Components to the Page with the <code>load()</code> Method</a> </li>
53 <li><a href="#config">Configuration Options</a> </li>
54 <li><a href="#modulenames">YUI Module Names</a>
55 <li><a href="#using2">Refining Our Use Case: Cutting out extra HTTP requests</a> </li>
56 <li><a href="#metainfo">Understanding the Metadata</a> </li>
57 <li><a href="#support">Support &amp; Community</a></li>
58 <li><a href="#filingbugs">Filing Bugs and Feature Requests</a></li>
59 </ul>
60 </div>
61 <div id="quicklinks">
62 <h4>Quick Links:</h4>
63 <ul>
5a52dbf @cauld Doc and example cleanup. Fixing combo.php query string explode bug. Modi...
cauld authored
64 <li><a href="api_docs/index.html">API Documentation</a></li>
20723b4 @cauld Making the api and example documentation part of the phploader package i...
cauld authored
65 <li><a href="http://yuilibrary.com/downloads/">Download YUI PHP Loader</a> from YUILibrary.com: YUI PHP Loader is available from the YUI project website, but it is a separate download from the YUI JavaScript/CSS library.</li>
66 </ul>
67 </div>
68 </div>
69
70 <h2 class="first" id="start">Getting Started</h2>
71
72 <p>After downloading YUI PHP Loader the archive needs to be extracted somewhere within the servers 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 <a href="#metainfo">metadata</a> available within your local YUI PHP Loader installation.</p>
73 <textarea name="code" class="PHP" cols="60" rows="1">
74 //Include the loader class file
75 include("loader.php");
76
77 //Get an instance
78 $loader = new YAHOO_util_Loader("<?PHP echo($yuiCurrentVersion);?>");
79 </textarea>
80
81 <h2 id="using">Simple Use Case: Adding YUI Components to the Page with the <code>load()</code> Method</a></h2>
82
83 <p>YUI 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 <code>tags()</code> method. Since we will cover the benefits of using rollup files later in this document we will turn them off for this first example.</p>
84 <textarea name="code" class="PHP" cols="60" rows="1">
85 include("loader.php");
86 $loader = new YAHOO_util_Loader("<?PHP echo($yuiCurrentVersion);?>");
87
88 //Turn off rollups
89 $loader->allowRollups = false;
90
91 //Specify YUI components to load
92 $loader->load("yahoo", "dom", "event", "tabview", "grids", "fonts", "reset");
93
94 //Output the tags (this call would most likely be placed in the document head)
95 $loader->tags();
96
97 /*
98 This call will produce an output similar to the following:
99 <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/fonts/fonts-min.css" />
100 <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/grids/grids-min.css" />
101 <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/reset/reset-min.css" />
102 <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/tabview/assets/skins/sam/tabview.css" />
103 <script type="text/javascript" src="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/yahoo/yahoo-min.js"></script>
104 <script type="text/javascript" src="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/dom/dom-min.js"></script>
105 <script type="text/javascript" src="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/event/event-min.js"></script>
106 <script type="text/javascript" src="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/element/element-min.js"></script>
107 <script type="text/javascript" src="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/tabview/tabview-min.js"></script>
108 */
109 </textarea>
110
111
112 <h2 id="config">Configuration Options</h2>
113
114 <p>The following configuration options are supported by the YUI PHP Loader Utility.
115 These can be set individually on a YUI PHP Loader instance:</p>
116
117 <div class="apisummary">
118 <table>
119 <thead>
120 <tr>
121 <th>Configuration Option</th>
122 <th>Purpose</th>
123 </tr>
124 </thead>
125 <tbody>
126 <tr>
127 <td>base</td>
128 <td>(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 <a href="http://developer.yahoo.com/yui/articles/hosting/">serve files from Yahoo's servers</a>.</td>
129 </tr>
130 <tr class="odd">
131 <td>filter</td>
132 <td>
133 (string) A filter to apply to result urls. This filter will modify the default
134 path for all modules. The default path for the YUI library is the
135 minified version of the files (e.g., event-min.js). The valid filters are:
136 <dl>
137 <dt>YUI_DEBUG</dt>
138 <dd>Selects the debug versions of the library (e.g., event-debug.js).
139 This option will automatically include the logger widget</dd>
140 <dt>YUI_RAW</dt>
141 <dd>Selects the non-minified version of the library (e.g., event.js).
142 </dl>
143 </td>
144 </tr>
145 <tr>
146 <td>allowRollups</td>
147 <td>(boolean) Should Loader use aggregate files (like <code>yahoo-dom-event.js</code> or <code>utilities.js</code>) that combine several YUI components in a single HTTP request? Default: true.</td>
148 </tr>
149 <tr class="odd">
150 <td>loadOptional</td>
151 <td>(boolean) Should loader load optional dependencies for the components you're requesting? (Note: If you only want <em>some</em> but not <em>all</em> optional dependencies, you can list out the dependencies you want as part of your <code>required</code> list.) Default: false.</td>
152 </tr>
153 <tr>
154 <td>combine</td>
155
156 <td>(boolean) If set to true, YUI files will be combined into a single request using the combo service provided on the Yahoo! CDN</td>
157 </tr>
158 <tr class="odd">
159 <td>comboBase</td>
160 <td>
161 (string) The base path to the Yahoo! CDN service. Default: http://yui.yahooapis.com/combo?<br/>
162 Note: YUI PHP Loader also ships with an intrinsic, lightweight combo-handler (see combo.php). Refer to the included examples for a use case on this.
163 </td>
164 </tr>
165 </tbody>
166 </table>
167 </div>
168
169 <h2 id="modulenames">YUI Module Names</h2>
170
171 <p>Each YUI component has a corresponding module name that is used as a unique identifier within YUI scripts. For example, the <a href="http://developer.yahoo.com/yui/event/">Event Utility</a> is internally referred to as <code>"event"</code>. 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.</p>
172
173 <div class="apisummary">
174 <?PHP
965ec05 @cauld Moving the main index page location and adding a 2nd example index page
cauld authored
175 include "./examples/inc/moduleNames.inc";
20723b4 @cauld Making the api and example documentation part of the phploader package i...
cauld authored
176 echo $moduleNamesTable;
177 ?>
178 </div>
179
180 <p>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.</p>
181
182 <p>When you choose to <code><a href="http://developer.yahoo.com/yui/docs/YAHOO.util.YUILoader.html#property_allowRollup">allowRollup</a></code>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:</p>
183
184 <div class="apisummary">
185 <?PHP
186 echo $rollupNamesTable;
187 ?>
188 </div>
189
190 <h2 id="using2">Refining Our Use Case: Cutting out extra HTTP requests</h2>
191
192 <p>As noted in the <a href="#config">configuration table</a> 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.</p>
193 <textarea name="code" class="PHP" cols="60" rows="1">
194 include("loader.php");
195 $loader = new YAHOO_util_Loader("<?PHP echo($yuiCurrentVersion);?>");
196
197 //Turn on rollups (this is actually on by default)
198 $loader->allowRollups = true;
199
200 //Specify YUI components to load
201 $loader->load("yahoo", "dom", "event", "tabview", "grids", "fonts", "reset");
202
203 /*
204 A call to tags method here would produce an output similar to the following:
205 <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/reset-fonts-grids/reset-fonts-grids.css" />
206 <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/tabview/assets/skins/sam/tabview.css" />
207 <script type="text/javascript" src="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/yahoo-dom-event/yahoo-dom-event.js"></script>
208 <script type="text/javascript" src="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/element/element-min.js"></script>
209 <script type="text/javascript" src="http://yui.yahooapis.com/<?PHP echo($yuiCurrentVersion);?>/build/tabview/tabview-min.js"></script>
210 */
211
212 //Enable combo handling
213 $loader->combine = true;
214
215 //Output the tags (this call would most likely be placed in the document head)
216 $loader->tags();
217
218 /*
219 The final output would now be similar to the following, a single HTTP request for each type (i.e.) CSS and JavaScript:
220 <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/combo?<?PHP echo($yuiCurrentVersion);?>/build/reset-fonts-grids/reset-fonts-grids.css&<?PHP echo($yuiCurrentVersion);?>/build/tabview/assets/skins/sam/tabview.css" />
221 <script type="text/javascript" src="http://yui.yahooapis.com/combo?<?PHP echo($yuiCurrentVersion);?>/build/yahoo-dom-event/yahoo-dom-event.js&<?PHP echo($yuiCurrentVersion);?>/build/element/element-min.js&<?PHP echo($yuiCurrentVersion);?>/build/tabview/tabview-min.js"></script></head>
222 */
223 </textarea>
224
225 <p>In addition to the <code>tags()</code> 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 &amp; JavaScript seperately which is not a bad idea since there are <a href="http://developer.yahoo.com/performance/rules.html">well known performance benefits</a> 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.</p>
226
227 <h2 id="metainfo">Understanding the Metadata</h2>
228
229 <p>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 <em>config_{yui version}.php</em> (e.g.) config_<?PHP echo($yuiCurrentVersion);?>.php. The naming convention for JSON config files is <em>json_{yui version}.txt</em> (e.g.) json_<?PHP echo($yuiCurrentVersion);?>.txt.</p>
230
965ec05 @cauld Moving the main index page location and adding a 2nd example index page
cauld authored
231 <?PHP include "./examples/inc/support.inc"; ?>
20723b4 @cauld Making the api and example documentation part of the phploader package i...
cauld authored
232
233 </div>
234
235 <div class="yui-u">
236
237 <div id="examples">
965ec05 @cauld Moving the main index page location and adding a 2nd example index page
cauld authored
238 <h3>YUI PHP Loader Utility Examples:</h3>
239 <ul>
240 <li><a href='examples/phploader-basic.php'>Using YUI PHP Loader to Load the Calendar Control (Basic)</a></li>
241 <li><a href='examples/phploader-advanced.php'>Using YUI PHP Loader to Load the Calendar Control (Advanced)</a></li>
6a7e5ad @cauld Adding new example link
cauld authored
242 <li><a href='examples/phploader-mixed-loading.php'>Mixed Loading Methods</a></li>
965ec05 @cauld Moving the main index page location and adding a 2nd example index page
cauld authored
243 <li><a href='examples/phploader-custom-modules.php'>Adding Custom (Non-YUI) Content with YUI PHP Loader</a></li>
244 <li><a href='examples/phploader-custom-modules-with-yui.php'>Adding Custom Modules with YUI Dependencies</a></li>
245 <li><a href='examples/phploader-local-combo-handler.php'>Using the Local Combo Handler</a></li>
246 </ul>
20723b4 @cauld Making the api and example documentation part of the phploader package i...
cauld authored
247 </div>
248
249
250 </div>
251 </div>
252
253 </div>
254 </div>
965ec05 @cauld Moving the main index page location and adding a 2nd example index page
cauld authored
255 <div id="ft">
256 <p class="first">Copyright &copy; <?PHP print strftime("%Y"); ?> Yahoo! Inc. All rights reserved.</p>
257 <p><a href="http://info.yahoo.com/privacy/us/yahoo/devel/details.html">Privacy Policy</a> -
258 <a href="http://docs.yahoo.com/info/terms/">Terms of Service</a> -
259 <a href="http://docs.yahoo.com/info/copyright/copyright.html">Copyright Policy</a> -
260 <a href="http://careers.yahoo.com/">Job Openings</a></p>
261 </div>
262 </div>
263
264 <script src="examples/assets/dpSyntaxHighlighter.js"></script>
265 <script language="javascript">
266 dp.SyntaxHighlighter.HighlightAll('code');
267 </script>
20723b4 @cauld Making the api and example documentation part of the phploader package i...
cauld authored
268
965ec05 @cauld Moving the main index page location and adding a 2nd example index page
cauld authored
269 </body>
270 </html>
Something went wrong with that request. Please try again.