Revision as of 09:11, 10 January 2008

This tutorial will walk you through creating your own Tigerstripe Plugin plug-in for your code. By writing your own plugin, you can define your own rules and conventions for the code that is generated from a Tigerstripe Model Project.

In many cases, you may want to write your own plugin so that you can create code according to your own organizations standards, or you may need some HTML to document your project model. Furthermore, by creating your own plugin you can distribute it to other users within your organization to ensure that all users are using the same coding rules and conventions when generating code.

As you work through this tutorial, you will generate a simple java class, based on a single entity. You will see how easy it is to modify and enhance the generated code in templates.

Create a new Tigerstripe Plug-in Project

Tigerstripe Plugin Projects share some common behavior with standard Tigerstripe Model Projects except that a plugin project contains details of a plug-in that you can use to generate output based on a model.

A Tigerstripe Plugin Project includes the following:

• Global Properties – Used to allow specific information for use in a given Tigerstripe Project. For example, the name of a directory where certain file types should be created.
• Rules] – Define the actual behavior of the plug-in.
• Runtime references – Specify additional files required by the plug-in at run-time (eg .jar files).
• Velocity templates.
• Java source files for enhanced behavior.
• Additional .jar files

To create a new Tigerstripe Plugin Project:

1. From the File menu, select New and click Project. Select the Tigerstripe Plugin Project under the Tigerstripe heading. The New Tigerstripe Plug-in Project dialog box opens.
2. Enter a name for the plug-in.
   • For this tutorial, the name is SimplePluginProject.
3. Click Finish to create the new plug-in. An editor displays that appears similar to the standard Tigerstripe Project Editor.
4. Enter a description and version number for your new plug-in in the appropriate text boxes and click Save.

Note: Click Help and select Help Contents for more information about the other options available in the New Tigerstripe Plug-in Project dialog box.

Create Global Plug-in Properties

In many situations, you may want the user of your plug-in to be able to specify the value for a particular property when they run the plug-in. Such as:

• Setting the name of a Directory
• Flagging the adoption of certain optional behavior

These tasks can be accomplished by creating Global Properties.

To create Global Properties:

1. Click the Properties tab in the Plug-in Project Editor.
2. Select Global Properties and click Add to create a new property.
3. Enter a name for your property and click OK.
   • For this tutorial, the name is directoryName.
4. Complete step 1 through step 3 to create a second property named flag.
5. Change the flag property type to Boolean.
6. Review the Global Properties for the plug-in and add any required Tool tip text or Default values.
7. Click Save.

Create Velocity Templates

A plug-in contains one or more Velocity Templates, which describe how output will be generated based on the artifacts contained within a particular project against which the plug-in is run. Tigerstripe uses an apache utility called Velocity to create the output. For more information about Velocity, refer to the [[1]].

In this step, you will create a template.

1. Select the templates directory on your plugin project in the Tigerstripe Explorer.
2. From the File menu, click New, and select Other.
   • You can also accomplish this step by right-clicking on the templates directory. From the shortcut menu, click New and select Other.
3. Select General and click File from then specify a filename for the file you wish to create.
   • For this tutorial, name the file simpleTemplate.vm.
4. Your template must be saved in the templates directory of your SimplePluginProject, and the .vm file extension is mandatory.

A text editor will open. Within a template you will need to use Velocity syntax. Some brief points are about Velocity are as follows:

• Use ## to indicate a Velocity comment.
• Use # to call Velocity directives. For example, #set.
• Use $ to indicate variables.
• All other text entered will appear in the output file.

We will now create a template that will output a basic Java class file based on an Managed Entity Artifact.

Enter the following text into your text editor:

     ## This is simpleTemplate.vm
     // This file was generated using $templateName
     public class  $artifact.Name {
         private boolean myBoolean = $pluginRef.getProperty("flag") ;
     }

Save your changes.

The first line is a comment internal to the template and this text will not appear in the final output. The following line (starting //) will appear in the final output. The reference $templateName will be replaced by the name of the template when the template is rendered - in this case it will be replaced with templates/simpleTemplate.vm. (It is good practice to enter this information so you can easily determine what template your generated files utilized.)

The $artifact.Name in the public class .... line will be replaced with the name of the Artifact against which this template is run. For example, in the Simple Tutorial Project this would be either Order or OrderFacade.

Finally the reference $pluginRef.getProperty("flag") is replaced with the value of the property flag from the Tigerstripe Model Project.

The next step is to set when this template is executed.

Define a Plug-in Rule

In this step we will create an Artifact Rule. Artifact Rules are run once per artifact in the model (in fact some control of the artifacts is possible, but that is covered in a later tutorial).

Now that you have a template, you are going to need to configure the ruleto populate your template.

To configure your rule:

1. Select the Rules tab in the editor for the plug-in project.
2. Select the Artifact Rules section, and click Add to add a new rule.
   • For this tutorial, name your rule Simplerule.
3. Click OK.
4. Define your rule. A set of options for defining your rule will display. Some options are self-explanantory, while others are beyond the scope of this tutorial. The ones you need to look at are:
   1. Template - Click Browse button and select the template you created.
   2. Output File - Select the directory to where you want the output file created. The file name must be unique for each artifact that you process. The following file format will achieve this:
      ${ppProp.directoryName}/${artifact.Name}.out
      Where ${xxx} signals the plug-in to replace text, ppProp signals the plug-in that a plug-in property should be used, and similarly for the artifact. (Details of this syntax can be found be searching for Expander in teh on-line help).
   3. ArtifactType - Select the type of artifact that the rule applies to from the drop-down list. An Artifact Rule normally only processes one type of artifact (although there is an option for all artifact types). For this tutorial, use Managed Entity Artifact.
5. Click Save to save your plug-in.

• You can have many rules in each plugin.
• You can have several rules that use the same template, eg that are run for different artifact types..

Test the Plug-in

In your local Environment.

Before distributing your plug-in, you should perform some testing to make sure you obtain the output you want.

To test your plug-in:

  1. Click Package and deploy this plugin within the Testing section on the Overview tab of the editor. Your plug-in is now available to all projects in your workspace!
  2. Run your plug-in from a Tigerstripe project.
  3. Select a Tigerstripe project and open the editor for that project by double clicking on tigerstripe.xml file.
  4. Open the Generation tab and a new section for the plug-in you just deployed will appear. At this stage, your plug-in is disabled. 
  5. Open your plug-in and click Enable to enable your plug-in on the Generation tab. Enabling your plug-in will also enable all of the other controls for that plug-in.  You can override the defaults specified during definition of your plug-in however, don't change these values.
  6. Click Save to save the Tigerstripe project.

     Note: You may wish to disable all other plug-ins when testing your new plug-in.

  7. Make sure you have the project in scope and click Generate (generateIcon).
  8. Review your generated code. 

If you used the settings as described above, you should find a new directory in the target directory of your project. This new directory is named default and contains a file called Order.out.

Note: Your default directory may contain additional files if you have more than one entity in your project.

The content of the file should look similar to the below image:

Further Testing

Note: Tigerstripe does not delete files in your target directory; therefore you may want to delete the default directory before re-testing your plug-in.

Add more entities to your project, and change the value of the directoryName property.

Changes to your model (artifacts) and property values are specific to the Tigerstripe Project so they will automatically be picked up by your plug-in, however if you change the associated template, add new rules, or change property definitions, don't forget to re-deploy your plug-in before running it again.

You are now ready to package your plug-in for others to use. Distribute your Plug-in To other users.

To package and distribute your plug-in:

  1. Navigate to your plug-in editor and locate the Package up this plugin link in the Packaging section on the Overview tab.
  2. Click the packaging link and name your plug-in.
  3. Navigate to where you want to save your plug-in and click Open.
  4. A message box appears upon successfully packaging your plug-in. Click OK to close the message box.

You can then distribute the resultant .zip file to other Tigerstripe users who can deploy your plug-in by placing the .zip file in their Tigerstripe plug-ins directory. (ECLIPSE_HOME\tigerstripe\plugins)

Complete the following procedure to see a list of deployed plug-ins in your Tigerstripe plug-ins directory.

To view a list of deployed plug-ins:

   * Click the Tigerstripe menu and click Plugins. The Deployed Tigerstripe Plugins dialog box opens.

To un-deploy a previously deployed plug-in:

  1. Open the Deployed Tigerstripe Plugins dialog box.
  2. Right-click on the plug-in and select Un-deploy.

Note: Remember that you will need to enable this plug-in manually in your Tigerstripe project if you wish to utilize it in another project.

Everyone in your organization will now be able to apply the same rules to their model and you can be sure of generating consistent results for all projects.