The Acceleo Perspective

The Acceleo perspective allows users to work in an environment which provides every facility to increase productivity while working with Acceleo. For instance, Acceleo-specific menus are available by default in the Acceleo perspective in order to make it easy to create projects or templates, and so on.

To switch to the Acceleo perspective, click on Window > Open Perspective > Other... Select the perspective named Acceleo (Beware, if you have Acceleo 2.x installed, you may see two Acceleo perspectives available.)

The views displayed by default in this perspective are : - Package explorer - Editor area (okay, it's not a view) - Outline - Problems - Error Log

In the Acceleo perspective, the pop-up menu available on the package explorer allows users to easily create Acceleo artifacts (such as projects or modules).

The Acceleo Views

Acceleo provides a few specific views to improve productivity when working with templates. These views will be detailed later in the relevant chapters. Let's just summarize their purpose to get the big picture.

As usual, they can be opened by clicking on Window > Show View and selecting the appropriate view in the menu. Note that in the Acceleo perspective, Acceleo views are proposed by default directly in this menu, which will not be the case in another perspective.

Creating an Acceleo Project "From Scratch"

The aim of an Acceleo project is to generate text from a model (or from a set of models). For this tutorial, we will create a new Acceleo module for generating java beans from a UML model.

To create a new Acceleo project, right click on the package explorer view then select New->Acceleo Project.

Choose a correct plugin name for the project, then click next.

This wizard's page allows you to initialize the project by creating one or several Acceleo module files.

• Select the folder in which you want to create the new module file.
• Fill in the module name
• Optionally, you can select an existing file which will be copied into the new module file. This could be useful to create a module from an existing file.
• Then, select the metamodel from which your generation file will take its types (in this example, UML)
• Finally, choose the metaclass that will be used to generate the file (in this example, Class). This can be modified later at any time directly in the module files.

Note: Other options are available to initialize the new module with exiting content. These options will be discussed later.

You can create more than one module file in this project by using the "Add" button on the left.

Clicking on finish will create the module file(s), and some files automatically generated from it (more on these below).

back to Contents

Creating an Acceleo UI Project

This action can only be performed on an existing Acceleo project.

It allows you to create and initialize a plugin project that will contain everything needed to launch the Acceleo generations of your project through actions available in pop-up menus, integrated in eclipse. This facilitates a lot the deployment of Acceleo generators in the eclipse platform.

To perform this, just right-click on your Acceleo project, then select Acceleo > Create Acceleo UI Launcher Project. This will start a wizard that will guide you through the creation process. The created project consists in an eclipse plugin project that you can afterward maintain as you would any plugin project.

Transforming an Existing Project into an Acceleo Project

Acceleo provides a facility to convert an existing project into an eclipse project. Technically, this means that the Acceleo nature will be added to the project's natures.

This can be achieved by right-clicking in the package explorer, then selecting New > Convert to an Acceleo Project. This will start a wizard which will guide you through the conversion process.

The Acceleo nature can be removed from an Acceleo project simply by right-clicking on the project and selecting Acceleo > Remove Acceleo Nature.

Templates

Templates are sets of Acceleo statements used to generate text. They are delimited by [template]...[/template] tags.

Queries

Queries are sets of OCL statements used to extract information form the model. Queries return values, or collections of values. They use the OCL language.

Syntax Highlighting

The editor uses specific colors for Acceleo templates:

• red is used for template tags
• purple is used for other tags (queries, modules, imports, ...)
• blue is used for dynamic expressions in templates or other places
• green is used for comments and String literals
• black is used for static text or query bodies

Content Assistant

The content assistant is traditionally invoked with Ctrl + space. It proposes a choice of all elements that make sense at the place of invocation. It is available everywhere, so don't hesitate to hit Ctrl + space anywhere!

Comments

Comments are entered in [comment] blocks, and appear in some shade of green. The [comment] tag can be self closed:

[comment Here is some comment of utter importance/]

But you can also surround a block of text between comment tags:

[comment]
Here is some commented text, which cannot contain a right bracket character.
[/comment]

Such comments are part of the official MTL specification. They cannot be placed inside OCL code, such as queries for instance.

It is possible to comment some portion of code or text of an Acceleo module with the Ctrl + / shortcut, or by right-clicking on the selected text and then Source > Comment. The behavior depends on what is selected: If nothing is selected, the current line (not the line you right-clicked on, but the line where the cursor is located) is surrounded with [comment]...[\comment] tags. If some text is selected, it is surrounded with [comment]...[\comment] tags, whether it spans multiple lines or not.

Code Folding

Templates, comments, queries, can be folded thanks to a marker located in the left margin in front of each of these elements.

The Dynamic Outline

The traditional eclipse outline view is used be Acceleo to display the module's structure. imports, templates, queries can be seen there, and double-clicking on any of them places the cursor at the corresponding position in the module (in the editor).

The Quick Outline

The quick outline, which can be displayed using Ctrl + O, displays just the necessary information to access any element in the current module. So, hitting Ctrl + O displays a pop-up with a list of templates and queries. A filter at the top allows you to quickly filter the content in order to easily find what you are looking for.

Open Declaration

The traditional shortcut F3 is supported by Acceleo, along with Ctrl + click, which both take you to the declaration of the selected or clicked element. This is supported for all kinds of elements: templates, queries, metamodels, metamodel elements, EOperations, etc.

This can also be achieve by right-clicking on an element, then Open Declaration.

Search References

Conversely, it is possible to get all the elements that refer to a given element. The shortcut is Ctrl + Shift + G, but it can also be achieved by right-clicking on the element then Search References.

The relevant elements are displayed in the Search view.

Error Markers

Obviously, Acceleo displays error markers when errors are detected. Error markers also appear in the eclipse Problems view, as usual. Files with errors also appear with an error decorator.

Just hover the marker in the editor margin with the mouse to get a tooltip to appear with an explanation of the problem.

Quick Fixes

Quick fixes are available with the shortcut Ctrl + 1.

Currently, quick fixes propose to create a supposedly missing template or query, before or after the current template.

More quick fixes will be provided in the next versions of Acceleo.

Extract as Template

When you develop Acceleo templates, you will sooner or later (and probably sooner than later) wish to extract a piece of code into a template in order to prevent the copy/paste syndrom.

Well, don't worry : you can do it with no effort!

Just select the piece of text you want to extract in another template, and right-click then choose Refactor > Extract Template (or just hit Ctrl + Shift + T ).

The selected text is then extracted in another template. Note that the selected text needs to be consistent : you cannot of course extract text that partially spans blocks of code and get an adequate result.

Transform to Protected Area

Similarly, it is very useful to mark some code area as protected. Rather than manually entering the [protected] blocks, you can just select the portion of code to protect, right-click on it then choose Source > As Protected Area... (or use the Alt + Shift + P shortcut).

The selected text is then surrounded with [protected] markers, with an automatically inferred id.

Please note that you may have to modify the id used to make sure the marker works like you want.

Transform to For/If Block

TODO Describe this feature

Wrapping Java Services

It is sometimes useful to invoke some java code from inside an Acceleo template. The acceleo non-standard library provides a service invoke which allows just that. The invoked java service is wrapped in an Acceleo query.

To facilitate the creation of such a wrapper, proceed like this:

1. Right-click on the package you want to create your Acceleo module in, and select New > Acceleo Module File
2. In the wizard, enter the relevant information in the usual fields, then click on the Advanced >> button
3. Check the Initialize Content checkbox
4. Select Create a Java services wrapper in the listbox below
5. Select the java file that contains the services to wrap
6. Click on the Finish button

That's it!

An Acceleo module is created, with a query for each service found in the original java class.

Initializing a Project with an Example

It is often useful (actually, it is recommended) to use a bottom-up approach to develop Acceleo templates. So, before beginning to write templates, start by prototyping your target files, make sure they work as expected, and then you are ready to start generating them.

At that time, you'd like to import the content of some files into a new template.

1. Right-click on the package you want to create your Acceleo module in, and select New > Acceleo Module File
2. In the wizard, enter the relevant information in the usual fields, then click on the Advanced >> button
3. Check the Initialize Content checkbox
4. Select Copy example content in the listbox below (which should be selected by default)
5. select the file that contains the example code
6. Click on the Finish button

An Acceleo module is created, and the content of the example java file is copied into this module's primary template.

Migrating Acceleo 2.x templates

Warning: This feature will probably evolve in future versions.

TODO Describe this feature

Launch Acceleo Application

Right-click on a .mtl Acceleo module file, then select Run As > Launch Acceleo Application.

This opens a wizard to create a launch configuration if such a configuration does not already exist for this file. If a launch configuration already exists, the generation is launched immediately.

Launch Configurations

Launch configurations for Acceleo can be created like described above, or by opêning the Run Configurations window, and then right-clicking on the Acceleo Application category to the left, and selecting New or Duplicate.

An acceleo launch configuration requires:

• A project (which contains the java entry point to run)
• A java class to run (contained in the above project)
• An input model
• An output folder (where every file will be generated)

Optionally, properties can be specified directly in the launch configuration.

The Generated API

To help users, Acceleo creates an API able to launch an Acceleo template. This API can easily be customized to fit your specificities -- if you have any.

It is important to note that Acceleo inspects modules to look for @main annotations in comments, and treats those templates specially. For every module containing at meast one @main annotation, a java file is generated beside the template. This class contains whatever plumbing code is needed to run the generator.

The generation can then be run by calling the main() of the class, or instantiating it.

API	Meaning
addProperties()	This method allows you to add properties or properties files that will subsequently be available during the generation
API	Meaning

Standalone Execution

Breakpoints

Step by Step Execution