YUI3 Plugin

  • Authors: Mingfai Ma
0 vote
Dependency:
compile ":yui3:0.1.10"

 Documentation

Summary

Installation

Plugin installation

To install the plugin, run the following command in your project directory:
grails install-plugin yui3

Include YUI3 library on your page

*The following is the easiest way to use YUI3 using local combo source, assume your context root is '/'.
<html>
 <head>
  <script src="/js/yui3/yui/yui-min.js"></script>
 </head>
 <body>
  <script>
    YUI({comboBase:"/combo?"}).use('event', function(Y) {
      Y.on('domready', function() {alert('dom ready')})
    })
  </script>
 </body>
</html>
  • if you script the {comboBase}, YUI3 by default will load js from the global yahooapis server. You are actually commended to use this in production.

Description

About YUI3

YUI 3.x is the next generation release of the YUI Library. There are significant changes in the library in comparison to the 2.x code. As a result, the team is making preview releases available ahead of the first production release to allow the developer community to take an early look at the changes that have been made, test drive the code in some sample applications, and most importantly, provide feedback.

About YUI3 Plugin

  • The Grails YUI3 Plugin addes YUI2 and YUI3 JavaScript libraries to your project in an unobtrusive manner. The provided JavaScript files could be used easily in non-GSP files such as in static HTML.
  • <0.1.5> Pack JavaScript with YUI Compressor
  • Please also check the YUI(2) Plugin before you decide to use this plugin. The original YUI Plugin provides some features such as Grails JavaScript provider that is not available in this plugin.
  • Remarks: This plugin doesn't support deploy-as-WAR mode yet

Features and Usage

Including YUI JavaScript libraries

  • YUI3 Combo Controller
    • The controller combines YUI3 JS files in a way compatiable to YahooAPIs.com. You may use the YUI3 Dependency Configurator to generate a <script> tag
    • by default, the combo controller is enabled and mapped to ${contextPath}/combo. by setting the context to root, you could include Javascript in HTML with:
      <script type="text/javascript" src="/combo?3.0.0pr2/build/yui/yui-debug.js&3.0.0pr2/build/oop/oop-debug.js&3.0.0pr2/build/event/event-debug.js&3.0.0pr2/build/dom/dom-debug.js&3.0.0pr2/build/node/node-debug.js"></script>
    • In a particular scenario, you may map 'yui.yahooapis.com' to '127.0.0.1' in your host file, and set your project to use root context. Then you could use the exact <script> tag from the configurator.
  • JavaScript URL Mapping
    • YUI2 and YUI3 files are mapped to /js/yui2(or yui3)/$yuiModule/$yuiFile by default, your HTML will be like
      <script type="text/javascript" src="/js/yui2/yahoo-dom-event/yahoo-dom-event.js">
      <script type="text/javascript" src="/js/yui3/yui/yui-min.js">
      
  • File caching
    • All files loaded from filesystem or remotely via HTTP are cached permanently and never reloaded.
    • You may programmatically manage the cache via Yui3Service.cache.
  • Other features
    • configurable to use your own version of YUI JavaScript files
    • configurable to use YUI JavaScript files over the Internet. (e.g. load from yui.yahooapis.com) and serves the file from your server.
    • configure your web app to use root context
    • <0.1.1> noCache configuration. by default, all .js in the whole application are set to use no-cache HTTP response header in development mode

JavaScript packing

  • From <0.1.5>, JavaScript packing is supported, it may be used in different ways:
    • map your JavaScript URL and enable packing
    • Sample Config.groovy - <0.1.5>
      'plugins.yui3.mappings' {
        uncompressedJQuery{
          from = '/js/jquery'; to = '/js/lib/jquery';pack=true
        }
      }
      
      use <yui3:pack> tag
    • do it programmatically with the HTMLTemplate or JavaScriptTemplate

Installation and Configuration

  • Installation
    grails install-plugin yui3
  • Configuration
    • This plugin requires file extensions detection be disabled.
      • WARNING by default, this plugin set your grails.mime.file.extensions to false automatically
      • Reference
        grails.mime.file.extensions = false
    • Sample Config.groovy - <0.1.5>
      'plugins.yui3.mappings' {
        combo {
          from = '/combo';
          to = ['/js/yui/2.7.0', // you could individual .js to override the one in zip
                  'zip:/js/yui/yui_2.7.0b.zip!yui', //load from the bundled zip, u don't need to specify /plugins/yui3-0.1.5
                  'zip:/js/yui/yui_3.0.0pr2.zip!yui']
        }
      }
      
    • Sample Config.groovy
      plugins {
        yui3 {
          /**
           * When this is set to true, the project will be mapped to root context. default is false
           */
          rootContext = true
          /**
           * This plugin requires 'grails.mime.file.extensions' be set to true. By default, it will override the settings to true.
           * Setting disableOverride = true will stop this plugin from overriding the project configuration.
           */
          disableOverride = false
      
          /**
           * map from a public uri under contextPath to a physical path under /web-app
           * if not specified, every 'to' is mapped to '/plugins/yui3-$version/js/yui*'
           */
          'mappings' {
            disable = false;//example only, disable = false has no effect
            'combo' {from = '/combo'; to = '/js/yui'}
            'yui3' {from = "/js/yui3"; to = '/js/yui/3.0.0pr2/build'} // remote example: to = "http://yui.yahooapis.com/3.0.0pr2/build"
            'yui2' {from = "/js/yui2"; to = '/js/yui/2.6.0/build'}
          }
        }
      }
      
    • Refer to the Config.groovy at svn trunk for the latest changes
      • <0.1.1> added noCache option

Version and Compatability

  • The plugin is tested on Grails 1.1 beta 3
  • Refer to the Yui3GrailsPlugin.groovy or CHANGE.txt for the version of included YUI JavaScript library.
    • <0.1.x> YUI 2.6.0 and YUI 3.0.0PR2
author: Mingfai Ma