GraniteDS Wizard (technology preview)

The new GraniteDS Wizard Plugin is intended to facilitate the creation of new GraniteDS project under Eclipse.

1. Quick setup and usage:

In order to install and use it, you need at least an Eclipse 3.4+ bundle and, preferably, if you want to benefit from all of its features, the folowing plugins:

• FlashBuilder 4.
• GraniteDS Builder 2.2.
• JBoss Tools 3 (with at least the archives tool, see here is you don't know what it is about).

You will also need a JBoss 5.1 distribution, as the default template that comes the wizard targets this application server.

Once you have setup this environment, donwload the new GraniteDS Wizard plugin on Github here and unzip it into your eclipse/plugins directory. Restart Eclipse and you should now be able to see a "GraniteDS" section in the "New Project" dialog when you select "File" -> "New" -> "Project..." in your Eclipse menu:

Select "GraniteDS Projects", click on the "Next" button and select the first available template in the next dialog:

Click again on the "Next" button and you should now see a standard project creation dialog with a specific "Template variables" section at the bottom:

Enter a project name, change the "JBoss installation directory" to your JBoss installation directory, accept all other default options (or change them if you want) and click on "Finish".

You should now see a new Flex / JavaEE project, configured for both FlashBuilder and GraniteDS builder, and with a ".package" file that automatically deploy the project in the choosen JBoss deployment directory.

Tip: unfortunatly, you should also have an error when the project is first build... This is FlashBuilder error (actually a known bug), complaining that it hasn't been able to create the html templates. Just right click on the error and ask it to recreate the template files.


2. Under the hood, modifying the template:

Project templates in this GraniteDS wizard tool are mostly made of Groovy scripts. Go to your "eclipse/plugin/org.granite.wizard_1.0.0.alpha1/resources" directory. You should see two subdirectories, "libs" and "templates".

The "libs" directory contains GraniteDS libraries that are referenced by templates (see below).

The "templates" directory contains actual templates. There is only one template at this time, in a directory called "jboss". If you open this directory, you will see two files and one directory:

• template.properties: this file contains the name and description of the template, as they appear in the second screenshot above. The "title" property is the title of the third screenshot above. The last property ("controller") is for advanced use only, don't change it!
• bindings.groovy: this file defines variables that are displayed in the "Template variables" section of the third screenshot and that will be used later for the actual project creation. You may modify the values in this file in order to get default values that fit your environment (in particular, you should change the "jbossDir" value so it will be set by default to your JBoss installation directory). The good thing is that you may do this change without restarting Eclipse: template files are reloaded each time you run the wizard.
• project: this directory contains all files and directories that the template is made of. As you can see, some directory names are enclosed between ${} characters: this means that their names will be resolved against the actual values of templates variables, as defined in the bindings.groovy file and adjusted in the third dialog shown above. Some other files are ending with a ".gsp" extension: these are Groovy templates, similar to GraniteDS builder templates. Finally, you will even see files named "@libs!...": these files will be resolved by copying GDS libraries found in the "resources/lib" directory.

As you may now understand, this GraniteDS Wizard is completely generic and could be used in order to make projects that have nothing to do with GraniteDS: it is simply a general mecanism for displaying and editing variables before copying template files and directories.

Some more informations before a future proper documentation:

• Binding variables use Groovy closures with dependencies: the jbossDeployDir value is { new File(jbossDir.value, "server/default/deploy") }, a closure that uses the value of the jbossDir variable. If you change the "JBoss installation directory" in the interface, you will see the JBoss deploy directory value changing accordingly. This is similar to Flex bindings, when you write something like text="The value is {bindableVariable}".
• If a file shoudn't be generated for some configuration, you may throw a CancelFileGenerationException to prevent its generation (see the .flexProperties.gsp file for an example).
• There are currently 4 types of supported UI controls: text input, checkbox, combobox and directory selection. The type of the variable must be set accordingly to String, Boolean, String (again) or File.
• Input validation is made on the fly: use the "validation" and "errorMessage" attributes in the bindings.groovy file to set it up.
• If you omit the "label" attribute, the variable won't be shown in the UI intterface.
• You may disabled by default a variable in the UI interface if you set the "disabled" attribute to false: this may be done with the "false" literal, by a call to a method that returns a boolean value or even by a closure that uses another variable value (see bindings.groovy for examples).
• You may create other templates by copying the "jboss" one and changing whatever you want. Again, you don't need to restart Eclipse in order to see your new template: just rerun the wizard, the new template will be displayed in the list shown in the second screenshot.

Don't forget this is an alpha work: we will improve this JBoss template and provide other ones for different environments.