Plugin providing Ext JS resources

  • Tags : ajax, extjs, ria
  • Latest : 3.4.0.0
  • Last Updated: 27 October 2011
  • Grails version : 1.2.0 > *
  • Authors : Matthias Hryniszak
1 vote
Dependency : 
compile "org.grails.plugins.extjs-resources:extjs:3.4.0.0"

Documentation Source Issues

Summary

Installation

grails install-plugin extjs

Description

Please note that all development (including the examples) have recently been migrated to GitHub. Please update your branches!

Please bear in mind that Ext JS license prohibits you to use it in commercial projects if you didn't pay for it. Refer to the Ext JS dual-licensing model for further details.

Remember: this is a fantastic library! Don't mess around creating commercial projects without first paying for it! If you want to earn money with it you've got to pay for it!

See GitHub for known issues.

Sources: http://github.com/padcom/grails-extjs

Continuous integration: http://dev.aplaline.com/hudson/job/grails-extjs/

Installation

grails install-plugin extjs

Sources

You can clone this Git repository to get the sources:

http://dev.aplaline.com/git/grails-extjs.git

Continous integration

You can fetch the latest and the greatest version of this plugin from Hudson:

http://dev.aplaline.com/hudson/job/grails-extjs/

Usage

To use this plugin create your GSP file or HTML file like this:

<html>
<head>
  <meta name="layout" content="ext"/>
  <script type="text/javascript">
    Ext.onReady(function() {
      // your startup code goes here
    });
  </script>
</head>
<body>
</body>
</html>

The template ext takes care of loading all the necessary resources.

The following templates are provided by this plugin:

  • ext - just the basic Ext JS libraries and content
  • ext-ux - the basic Ext JS libraries and ux-all.*
  • ext-jquery - just the basic Ext JS libraries and content with jQuery and the appropriate adapter
  • ext-ux-jquery - the basic Ext JS libraries, ux-all.*, with jQuery and the appropriate adapter
  • ext-prototype - just the basic Ext JS libraries and content with Prototype and the appropriate adapter
  • ext-ux-prototype - the basic Ext JS libraries, ux-all.*, with Prototype and the appropriate adapter
  • ext-desktop - basic Ext JS libraries and content plus a slightly modified version of the desktop example as a ready-to-use platform
  • ext-desktop-jquery - basic Ext JS libraries and content plus a slightly modified version of the desktop example as a ready-to-use platform with jQuery and the appropriate adapter
  • ext-desktop-prototype - basic Ext JS libraries and content plus a slightly modified version of the desktop example as a ready-to-use platform with Prototype and the appropriate adapter
  • ext-desktop-ux - basic Ext JS libraries and content plus a slightly modified version of the desktop example as a ready-to-use platform with ux-all
  • ext-desktop-ux-jquery - basic Ext JS libraries and content plus a slightly modified version of the desktop example as a ready-to-use platform with ux-all, jQuery and the appropriate adapter
  • ext-desktop-ux-prototype - basic Ext JS libraries and content plus a slightly modified version of the desktop example as a ready-to-use platform with ux-all, Prototype and the appropriate adapter

Creating applications using the ext-desktop layouts

Creating an application that has the appearance of a desktop instead of an n-column layout with header and footer is fun and it looks really cool. Using this plugin and the provided templates it's really simple to do so.

Creating the application object

At first you need an application object that's extending the Ext.app.App class. You can do so like this:

MyApp = new Ext.app.App({
    init: function(){
    },
    getModules: function(){
        return [
        ]
    },
    getShortcuts: function(){
        return [
        ]
    },
    getStartConfig: function(){
        return {
        }
    }
});

The application object already contains everything it needs in Ext.onReady event handler so you should put it directly into the script and NOT into the Ext.onReady event handler!

This is the basic template. Let's examine the functions in details.

init function

This function is called once the application starts. Typically you'd want to run any initialization code here, for example code that initializes QuickTips:

init: function(){
    Ext.QuickTips.init();
},

This is also the place to run any application-specific initialization code.

getModules function

The purpose of getModules function is to return an array of objects inheriting from Ext.app.Module, like the Ext.app.Module or Ext.app.EmbeddedModule. You can do so like this:

getModules: function(){
    return [
        new Ext.app.EmbeddedModule({ 
            id: 'example-win',
            url: '/example/modules/example.gsp',
            name: 'Example 1',
            title: 'Example 2',
            iconCls: 'grid-icon',
            width: 800,
            height: 600
        })
    ]
}

This will create an embedded module (more on what an embedded module is later in this doc) and return it to the application.

An application MUST consist of at least one module!

getShortcuts function

The purpose of the getShortcuts function is to return a list of definitions of desktop shortcuts (icons) to be placed on the desktop. Here's an example placing a shortcut to module with the window id example-win:

getShortcuts : function() {
    return [ {
        id: 'example-win',
        title: 'Example Window'
    } ]
}

getStartConfig function

The purpose of getStartConfig is to return the definition of how the start menu will look like. This means the icons in the right column (the so called tools), title and optional icon to be placed left of the title. Here's an example of such function:

getStartConfig: function() {
    return {
        title: 'Jack Slocum',
        iconCls: 'user',
        toolItems: [{
            text:'Settings',
            iconCls:'settings',
            handler: function() { Ext.MessageBox.alert("Information", "You clicked on the Settings tool button"); },
            scope:this
        },'-',{
            text:'Logout',
            iconCls:'logout',
            handler: function() { Ext.MessageBox.alert("Information", "You clicked on the Logout tool button"); },
            scope:this
        }]
    };
},

As you can see here there we have defined 2 tools (Settings and Logout) and the title "Jack Slocum" with icon "user".

Creating modules

To create a module you'll have to instantiate the Ext.app.Module class passing it a configuration object like this:

Ext.ns("Modules");
Modules.Example = Ext.extend(Ext.app.Module, {
    id: 'example-win',
    init : function(){
        this.launcher = {
            text: 'Example 1',
            iconCls: 'icon-example',
            handler : this.createWindow,
            scope: this,
            windowId: this.id
        }
    },
    createWindow : function(src){
        var desktop = this.app.getDesktop();
        var win = desktop.getWindow(this.id);
        if(!win){
            win = desktop.createWindow({
                id: this.id,
                title: 'Example 2',
                iconCls: 'icon-example',
                width: 800,
                height: 600,
                layout: 'fit',
                html: 'Put something useful here...',
                shim:false,
                animCollapse:true,
                constrainHeader:true
            });
        }
        win.show();
    }
});

This will create a text-only module displaying the text 'Put something useful here...' in the body of the window with the following properties:

  • text to be displayed in menu start is 'Example 1'
  • window title will be 'Example 2'
The rest is pretty much self-explanatory.

Creating embedded modules

An embedded module is a module that has its content downloaded from some other file. This is very similar to when you're instantiating the Ext.app.Module but it assumes that the content will be downloaded from a URL:

new Ext.app.EmbeddedModule({ 
    id: 'example-win',
    url: '/example/modules/example.gsp',
    name: 'Example 1',
    title: 'Example 2',
    iconCls: 'grid-icon',
    width: 800,
    height: 600
})

Once again this will create a module with the following properties:

  • text to be displayed in menu start is 'Example 1'
  • window title will be 'Example 2'
  • the content will be downloaded from /example/modules/example.gsp

Creating loadable content for Ext.app.EmbeddedModule

To use the embedded module you need to provide it with some content that will be loaded into the window's body. You can provide any type of content as long as you remember the following rule:

Everything you load is de facto being included in the same window as the application itself.

This means of course that all Ext JS resources will be automatically available. Since the ext-desktop* layouts include the ScriptLoader it's also possible to load additional JavaScript files to be used.

<script type="text/javascript">
  Ext.ns("Modules.Example");
  Modules.Example.config = {
    parentId: '${params.parentId}'
  }
  Ext.ScriptMgr.load({
    disableCaching: true,
    scripts: [
      '/example/js/modules/example.js'
    ],
    callback: function() {
      Modules.Example.main();
    }
  });
</script>

There are 2 things you need to remember:

  • This code is executed every time you open this module so it needs to be safe this way.
  • The params.parentId contains the id of the module's window. This is the one defined as id in the embedded module.
The callback method is executed once every single JavaScript file has been loaded and executed.

Here's an example of JavaScript file mentioned in the example above:

Modules.Example.main = function() {
  var win = Ext.getCmp(Modules.Example.config.parentId);
  var count = 0;
  var panel = new Ext.Panel({
      layout: 'fit',
      title: 'My panel',
      items: {
        xtype: 'button',
        text: 'clickme1',
        handler: function() {
          Ext.MessageBox.alert("Info", "You clicked me " + (++count) + " times.");
        }
      }
  });
  win.add(panel);
  win.doLayout();
};

The definition of panel is kind of self explanatory so we'll not drill to it. What you need to remember though is:

Do not use the renderTo option with modules. This will make the object impossible to fit into the parent's window (in this case the module's one)

Styling

There are 3 things you might want to apply styles to:

  • Desktop
  • Shortcuts on the desktop
  • Menu start items
Let's start by looking at the first one in the list which is...

Desktop

To style the desktop (change its color and possibly wallpaper) create a style for the x-desktop element like this:

#x-desktop {
   background: black url(${resource(dir:'images', file: 'grails_logo.png')}) no-repeat center;
}

This will change the background color to black (which is what I like the most :)) and set the image grails_logo.png (available to all grails applications if you didn't remove it manually) to be displayed in the center.

Shortcuts on the desktop

Every shortcut should have a meaningful icon for the user to better recognize what this particular application does. A desktop icon here consts of an empty image (the s.gif one) and some text. Let's have a look at how we might make it more interesting.

#example-win-shortcut img {
    width:48px;
    height:48px;
    background-image: url(${resource(dir:"images", file: "favicon.ico")});
    filter:progid:DXImageTransform.Microsoft.AlphaImageLoader(
        src='${resource(dir:"images", file: "favicon.ico")}', sizingMethod='scale'
    );
}

As you can see here the actual element's ID is build using the module id with "-shortcut" appendix. Here we set the size of the icon to be 48x48 and to be taken from the always available favicon.ico file. The filter in the last line is so that IE6 can display transparency for PNGs. In case you're wondering if specifying the size is necessary I rush to explain that it is. The default image is 1x1 pixel in size so other wise you'd only see the top-left pixel of your icon instead of the whole thing.

Start menu icons and windows icons.

Styling menu start icons and icons for windows is exactly the same as adding an icon to a button element. You define a custom style and specify it in the module's configuration:

new Ext.app.EmbeddedModule({ 
    id: 'example-win',
    url: '/example/modules/example.gsp',
    name: 'Example 1',
    title: 'Example 2',
    iconCls: 'grid-icon',
    width: 800,
    height: 600
})

Note the iconCls in the code above. Here's how its defined:

.grid-icon {
    background-image: url(http://cdn1.blackberryforums.com/images/icons/icon11.gif);
}

Make sure your image for the icon is exactly 16x16 or else it will look really bad :(

Example

There's an example usage for ext-desktop template here:

http://dev.aplaline.com/git/grails-extjs-example.git

Since this is an example that uses this plugin in source form you need to clone the http://dev.aplaline.com/git/grails-extjs.git project on the same level as the http://dev.aplaline.com/git/grails-extjs-example.git so that the directory structure looks like this:

grails-extjs
grails-extjs-example