Tigerstripe Simple Plugin Tutorial

< To: Tigerstripe_Tutorials

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.(Other types of rule that do not use templates are covered in the next tutorial, however the basic steps below apply for all rule types.).

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:

• 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: Describes how output will be generated based on the artifacts contained within a particular project against which the plug-in is run.
• 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, name it 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. Leave the type as String property.
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 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 a Session Facade 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 = $pluginConfig.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 which 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 $pluginConfig.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 rule to 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.
   • Select the optionArtifact Template 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 by searching for Expander in the 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 Session Facade.
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

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

To test your plugin in your local Environment:

1. Open the Plugin Project Descriptor (ts-plugin.xml) by double clicking on it in the Tigerstripe Explorer.
2. Click on 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!
3. Run your plug-in from a Tigerstripe project.
   1. Select a Tigerstripe Project' and open the descriptor editor for that project by double clicking on tigerstripe.xml file.
   2. Open the Plugin Settings tab and a section for the plug-in you just deployed will be present. At this stage, your plug-in is disabled.
   3. Open your section for your plug-in and click Enable to enable your plug-in. 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 for now.
   4. Click Save to save the Tigerstripe project.
      • Note: You may wish to disable all other plug-ins when testing your new plug-in.
   5. Make sure you have the project in scope and click Generate .
   6. 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 contains a file called Order.out.

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

Further Testing

Note: Tigerstripe Workbench does not delete files in your target directory by default; therefore you may want to delete the default directory before re-testing your plug-in. Alternatively visit the "Advanced Settings" tab of your project and enable the feature "Clear target directory before generate".

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 when you run generate, however if you change the associated template, add new rules, or change property definitions, don't forget to re-deploy your plugin before running it again.

You are now ready to package your plug-in for others to use.

Distribute your Plug-in

To package and distribute your plug-in to other users.:

1. Navigate to your plug-in editor and click on the Package up this plugin link in the Packaging section on the Overview tab.
2. Navigate to where you want to save your plugin and click Open.
3. 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 Workbench users who can deploy your plugin by placing the .zip file in their Tigerstripe plug-ins directory. (ECLIPSE_HOME\tigerstripe\plugins)

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

Un-deploying a plugin

You can undeploy plugins in one of two ways. The first option only works if you have the original Plugin Project in your workspace - the second option is always available.

If you have the Plugin Project :

1. Open the Plugin Project Descriptor (ts-plugin.xml) by double clicking on it in the Tigerstripe Explorer.
2. Click on Un-deploy this plugin within the Testing section on the Overview tab of the editor.

Alternatively to un-deploy any previously deployed plug-in:

1. Click the Tigerstripe menu and click Deployed Generators... to view a list of deployed plug-ins in your workspace,. The Deployed Tigerstripe Plugins dialog box opens.
2. Right-click on the plug-in and select Un-deploy.