Configuring YUI in Mojito¶

Benefits of Customizing YUI Configuration¶

Developers can customize YUI configuration in Mojito applications to do the following:

• select which YUI modules are included in the YUI seed file
• configure the combo handler to use a CDN
• optimize performance for environments that may have latency issues or have limited CPU power
• limit the loading of certain YUI modules for specific languages

Seed File in YUI Applications¶

To use YUI in Web pages, you include a small JavaScript file called the YUI seed file. The YUI seed file allows you to load other YUI components on your page. The seed file is added to your Web page by with following <script> tag.

<script src="http://yui.yahooapis.com/3.8.0/build/yui/yui-min.js"></script>

From the URL to the seed file, the YUI library can infer the version of the library that should be used, the filter that you want to use (min, debug or raw), and the CDN that is serving the library.

Seed File in Mojito Applications¶

In Mojito applications, the YUI seed is configured in application.json rather than including a <script> tag in templates. Thus, the information inferred from the URL to the YUI seed file in YUI applications is instead provided in the yui.config.seed object of application.json. We will look at yui.config.seed in Configuration of the Seed File.

Mojito uses configuration for the YUI seed because of the following reasons:

• The YUI library is bundled with the application using npm, so loading modules is done differently.
• Mojito applications may run as mobile applications that have connectivity issues preventing access to the YUI seed file.
• When applications are started, new YUI modules, part of the Mojito code, and part of the application code are loaded in the same way as the YUI Core modules, so it is difficult to simply include the YUI seed file in a template.

What Modules Should Be in the Seed?¶

When including modules as part of the seed, developers need to decide which modules are critical and understand what modules are available to Mojito applications. In theory, all YUI modules that are part of Mojito core, YUI core, and your application can be part of the seed. You can also add non-core YUI modules to be part of the seed, but we recommend that you don’t unless you have a strong reason to do so because the seed file should be as small as possible.

In addition, Mojito generates a few more virtual files (in memory, not actual physical files) that we will call synthetic modules, which you can also include in the seed object. We will discuss synthetic modules and how to use them next.

Synthetic Modules in Mojito¶

Using the YUI Version Bundled with Mojito¶

Mojito comes with YUI, so developers don’t need to worry about getting YUI or which version to use. Using the bundled YUI version also allows Mojito applications to load YUI modules more quickly and efficiently. Developers can use the default configurations, and thus, not need to do any configuration, or configure Mojito to include specific YUI modules to be part of the seed. In either case, Mojito will combo handle the modules in the seed, so that only one HTTP request is needed.

Before looking at the default configurations or configuring Mojito to include specific modules in the seed, let’s look at the pros and cons of using the YUI version bundled with Mojito.

[
  {
    "settings": [ "master" ],
    "yui": {
      "config": {
        "seed": [
          "yui-base",
          "loader-base",
          "loader-yui3",
          "loader-app",
          "loader-app-base{langPath}"
        ]
      }
    }
  }
]

[
  {
    "settings": [ "master" ],
    "yui": {
      "config": {
        "seed": [
          "yui-base",
          "loader-base",
          "loader-yui3",
          "json-parse",
          "json-stringify",
          "loader-app",
          "loader-app-base{langPath}"
        ]
      }
    }
  }
]

Using the YUI CDN¶

You can also fetch YUI directly from the YUI CDN by specifying the URLs to the version of YUI from the YUI CDN in the seed object.

[
  {
    "settings": [ "master" ],
    "yui": {
      "config": {
        "seed": [
          "http://yui.yahooapis.com/combo?3.8.1/yui-base/yui-base-min.js&3.8.1/loader-base/loader-base-min.js&3.8.1/loader-yui3/loader-yui3-min.js",
          "loader-app",
          "loader-app-base{langPath}"
        ]
      }
    }
  }
]

Using a Custom CDN to Load YUI¶

Using a custom CDN to load YUI is done in the same way as loading YUI from the YUI CDN.

[
  {
    "settings": [ "master" ],
    "yui": {
      "config": {
        "seed": [
          "https://mybucket.s3.amazonaws.com/my_yui_version/yui-base/yui-base-min.js",
          "https://mybucket.s3.amazonaws.com/my_yui_version/yui-base/loader-base-min.js",
          "https://mybucket.s3.amazonaws.com/my_yui_version/yui-base/loader-yui3-min.js",
          "loader-app",
          "loader-app-base{langPath}"
        ],
        "gallery": "gallery-2013.01.16-21-05",
        "base": "http://yui.yahooapis.com/3.8.1/build/",
        "comboBase": "http://yui.yahooapis.com/combo?",
        "root": "3.8.1/build/"
      }
    }
  }
]

Using the YUI Bundled With Your Application¶

Unless you have a strong reason for bundling YUI with your application, we strongly recommend that you use the version of YUI that comes with Mojito or load YUI from the YUI CDN.

To bundle YUI with your application, you install YUI in a directory within your application, and then configure the application to point to the directory, so your application can serve it as a static asset. You use the yui.config object in application.json to specify the file path and whether you want to combo handle the modules.

Let’s review the pros and cons and then show you an example configuration for serving YUI bundled with an application.

[
  {
    "settings": [ "master" ],
    "yui": {
      "config": {
        "base": "/static/yui/",
        "combine": false,
        "comboBase": "/combo~",
        "comboSep": "~",
        "root": "/static/yui/"
      }
    }
  }
]

Introduction¶

By default, YUI defines the three groups default, gallery, and yui2. In Mojito v0.5.0, we introduce the group app as part of the loader metadata. This new group aggregates all the YUI modules defined in Mojito core and in the application and contains configuration that define how YUI manages those modules when they are needed.

Configuration of the App Group¶

In the application.json file, you can use the yui.config.groups object to configure the following properties for the combo handler.

In the example application.json, the app group is configured so that YUI modules are loaded from a CDN.

[
  {
    "settings": [ "master" ],
    "yui": {
      "config": {
        "groups": {
          "app": {
            "combine": false,
            "maxURLLength": 516,
            "base": "http://companycdn.com/path/to/files"
          }
        }
      }
    }
  }
]

Default Combo Handler of Mojito¶

Mojito comes with an extended version of the mojito-handler-static middleware that implements a fully functional combo handler that supports cache, fallbacks when proxies cut the URL, and more. This combo handler adheres to the recommendations in the blog post Managing your JavaScript Modules with YUI 3 Stockpile by John Lindal, and it is the default configuration used for the Mojito application if the app group is not configured.

The following are the default configurations for the app group:

• comboBase: "/combo~"
• comboSep: "~"
• root: ""
• maxURLLength: 1024

Inheritance of Default Group Configurations¶

You can inherit the default configurations of the app group by setting the yui.config.combine property to true.

[
  {
    "settings": [ "environment:development" ],
    "yui": {
      "config": {
        "combine": true
      }
    }
  }
]

You can also use the combo property to disable the combo handler. In the example application.json below, the combo handler is disabled in the environment:development context:

[
  {
    "settings": [ "master" ],
    "yui": {
      "config": {
        "combine": true
      }
    }
  },
  {
    "settings": [ "environment:development" ],
    "yui": {
      "config": {
        "combine": false
      }
    }
  }
]

By disabling the combo handler, the YUI Core modules will not be using the combo handler, and the app group will also inherit that configuration.

Shaker Integration¶

The mojito-shaker 3.x extension will be able to control the configurations defined by the app group if you decide to push your assets into a CDN like Amazon. Shaker will also version the files and create the necessary rollups to accelerate caching and booting in the client runtime. To learn how to use the mojito-shaker extension, see the Shaker documentation.