create.mustache revision 9d2003304196a2769a38dca27c76e4fda1e875b0
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>In this example we will show you our recommended approach to creating your own `YUI` modules.</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<h2 id="what">What is a module?</h2>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>A `YUI` module can be described as <em>"any code that can be separated to run on it's own"</em>.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncMany times, this code can be reusable in different ways.</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<h3 id="define">How is a module defined?</h3>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<h2 id="know">How does YUI know about a module?</h2>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>`YUI` gives you a few options on how to tell it about your modules. The simpliest way is to include your modules
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncon the page after the `YUI` seed file.</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<h3 id="local">Local modules</h3>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>If all of your modules are wrapped in a valid `YUI.add` call, `YUI` will know about them just
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncbecause they are on the page. The calls to `YUI.add` tell the `YUI` seed all that it needs to know
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncabout your modules and registers them with the system.</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<script src="/path/to/yui-min.js"></script>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<script src="/path/to/my/module1.js"></script>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<script src="/path/to/my/module2.js"></script>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<script src="/path/to/my/module3.js"></script>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>Once available, they can be <em>used</em> as you would expect:</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncYUI().use('module1', 'module2', 'module3', function(Y) {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<h3 id="config">Configured simple modules</h3>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>The local use case may not be good for you if you have several modules that you would like `YUI` to know about.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncIn this case, you would want to tell `YUI` about your modules so that it can fetch them when they are required.</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>To do this, you need to use one of the <a href="index.html#config">various ways to configure</a> `YUI` and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctell it about your modules.</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>In this example, we will use the `YUI.GlobalConfig` to tell all `YUI` instances about our modules:</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync requires: [ 'node', 'event', 'dd', 'yql']
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>Now that we have told `YUI` about our modules, we can simply use them:</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncYUI().use('module1', 'module2', 'module3', function(Y) {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>The advantage of this approach is that we now have all of our modules information in one simple location
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncthat can be created by a build script and will be much easier to maintain.</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<h3 id="structured">Structured Modules</h3>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>In larger projects, you may need to structure your modules in a common way if you have multiple developers working
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncon the code. In this case, you can follow `YUI`'s modal on this and structure your code to get the most use
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsyncout of Loader.</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync<p>When creating a module like the ones above, you can create your built files like this:</p>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ourmodules/
<p>Now that your files are structed in a parsable manner, `Loader` can handle them without much of a configuration.</p>
<p>By default, when `Loader` is attempting to fetch a static module, it will create a url using a few config options:
<p>There are several combo handlers for different languages, so we won't discuss them here. Basically
a combo handler is an entry point on your server that accepts a query string of a list of files. The
server then combines all those files and returns the output. This allows you to ask for multiple files
<p>`YUI` has always had this support built in for it's core files, but you can have this with your modules too.
Configuring `YUI` to use a custom combo handler is extremely easy, let's modify the above example to use a
<p>When `Loader` is attempting to fetch a set of combined modules, it will create a url using these config options:
<comboBase><root><modulename>/<modulename>(-<filter>).js<comboSep><root><modulename>/<modulename>(-<filter>).js
<p>Now you have a flexible, scalable and dynamic module loading system that will let you build large scale
at our `Ant` based build system tool called <a href="https://github.com/yui/builder/">builder</a>.</p>
<p>`YUI` uses <em>aliases</em> under the hood as module "shortcuts", for example, when you `use` "node"
`Loader` doesn't fetch a `node.js` file, it actually fetches several files under the hood that make up the "node"
YUI.GlobalConfig = {
<p>This will create an alias called `all` for the modules: `'module1', 'module2', 'module3'`. You can then