First generator module

You have landed on 2.x maintenance stream website.

The last version is now available on the Eclipse website.



In this tutorial we will tackle the creation of a generator module. A generator module is a set of templates generating text from a model (UML for instance). We will present Acceleo creating a generator script in order to get XHTML from an UML 2 model.

Fundamentals

Acceleo principle is basically the following : Acceleo uses templates in order to generate text from an abstract model. Then, creating a new generator module comes down to creating templates.


Acceleo - general principle
Acceleo - general principle

In this tutorial we will create a template generating HTML from an UML2 model.

Generator project

You should first swith to the Acceleo perspective.

Then you need to create a new generator project thanks to the New -> Generator Project menu action.

New generator project
New generator project

The project now has a new decorator (green arrows) identifying it as a generator project.

Empty generator project
Empty generator project

In order to realize a generator template we first need a prototype model.

Model creation

In order to create a new model you may use many differents softwares. Acceleo provides a very good compatibily with UML modelers. Acceleo can use models from ArgoUML, Poseidon, Umbrello or Rational Rose. In order to get a detailed list of the compatible modelers, please refer to the compatibility page.

We are here using the TopCased modeler. It is integrated within Eclipse.

The sample UML2 model of this tutorial can be downloaded : WebLog_fr.uml

If you want to use an UML 1.3 or UML 1.4 model, you first need to convert it to EMF using the action Acceleo->Convert Xmi.
WebLog UML2 model
WebLog UML2 model

This model is in the model directory of the project.

First template

We created a model, we can now create our first generator template.

Click on New then Empty Generator.

New generator template
New generator template

We want to create a generator for UML2, we then need to choose the UML2 URI in wizard. The Types values combo list allow you to specify which kind of object you want to generate a file for.

Here we want to generate a file for each class. Then the Types values is uml.Class.

New generator template for UML2
New generator template for UML2

The wizard creates an empty generator template.

Empty template for UML2
Empty template for UML2

Using meta-model classes in Java services

In order to code Java services using meta-model entities (UML2 or any other meta-model), one should first import the classes generated for this meta-model.

This is made possible by editing the Manifest.mf file in the META-INF directory and adding the required plugins.

For instance in order to use UML2 within java services, one need to add org.eclipse.uml2.uml in the project dependencies.

Importing UML2
Importing UML2 in a generator project

The Acceleo reflective editor

The model created previously will help us create the generator template. This operation is made far easier thanks to the reflective editor. This editor can open any model and provides a dynamic preview of the generated code.

In order to open the reflective editor, you should right-click on a model then choose the action Open As->Acceleo XMI.

Opening the reflective editor
Opening the reflective editor

The reflective editor shows the model as a tree.

Acceleo reflective editor
Acceleo reflective editor

Preview of the generated code

Once the model is opened in the reflective editor, one can associate a generator template with the model. Click on Acceleo -> Select Template in the reflective editor and choose the empty template we previously created.

Selecting a generator template
Selecting a generator template

Once the template is loaded in the reflective editor, some decorators appear on the classes in the Outline view.

Generation decorators
Generation decorators

These decorators mean that the template can generate a file for each decorated object. Here it means the template generate a file for each class.

We will now fill the template in order to generate text.

The next screenshot shows a template generating an HTML description for each class, using it's attributes and comments.

Generator template to XHTML
Generator template to XHTML

You can download the sample template from UML2 to XHTML.
In order to get more information about the templates syntax please refer to the documentation section and the sample generator modules.

Once the template is written and saved you can update the preview using a right-click and the Acceleo -> Reload Template action.

Reloading a template
Reloading a template

Generation decorators are still there. When clicking on a class displaying this decorator the reflective editor shows a preview of the generated code in the source tab.

Preview of a generation
Preview of a generation

You can repeat this step as much as needed in order to adjust the generator template.

Generating the files

Once the template is adjusted one would want to generate files. This is made possible using the Generate files action in the Obeo menu.

Generating the files
Generating the files

You're then able to choose in which directory you would like to generate the files (here we choose doc). Acceleo generates an HTML file for each UML2 class.

Generated files
Generated files

Massive generation

Massive generation is provided via chain files.

  • Create a new project : New -> Project -> Simple -> Simple Project
  • Create an executing chain : New -> Chain
  • Customize the meta-model as previously described
  • Select the model, the template and a name for the chain
  • On the .chain created file, right click -> Launch
  • The files are automatically generated and you can view them in a web browser

This tutorial was about creating a first generator module using UML2. The next tutorial : Using Acceleo with GMF tackles the creation of a generator module with a DSL using GMF.

You may also have a look at the documentation section

.

A problem ?

Many ways to solve it :