Pre-requisites

The reader should have a minimal knowledge about MDA concepts, the eclipse platform, Android and the java language.

Documentation for Acceleo

This tutorial is part of a set offered by Obeo. Each document of this set deals with a different aspect of mastering Acceleo:

• Acceleo Operations Reference: description and explanation of each operation of the Acceleo script syntax;
• User Guide : documentation of Acceleo's functions;
• Acceleo Tutorial : how to create a new Acceleo project.

Goals

This is a quick tutorial.

• Beginners will see a simple but concrete case-study;
• Acceleo addicts will discover some new killing features;
• Android experts will learn enough of the basics to be able to create advanced code generator in few days.

Eclipse

This tutorial is performed on Eclipse 3.5 (Galileo) Modeling Tools Bundle. This bundle contains all the required components to realize the tutorial (EMF, Acceleo...). You can download the appropriate Eclipse Bundle here : http://www.eclipse.org/downloads/.

Android

Android works like Java. You need an Android Runtime in order to execute your Android applications.

You can download Android SDK and Android Development Tool (ADT) Eclipse Plugin here : http://developer.android.com/sdk/index.html.

For the installation, see the following instructions : http://developer.android.com/sdk/installing.html.

For this tutorial, the Android SDK starter package version is the R05, and the SDK platform is the 2.1. The ADT Plugin version is the 0.9.6.

The last step of installation is to link Eclipse with the SDK:

1. In Eclipse, choose Window > Preferences.
2. Select Android in the left panel.
3. Click Browse and navigate to where the SDK is installed.
4. Click Apply. The list of SDK targets will be reload.
5. Click OK.

Create an Android Virtual Device

To run an Android application, you have to create an Android Virtual Device (AVD). With Eclipse, select Window > Android SDK and AVD Manager.

Create a new AVD.

For more information about the AVDs : http://developer.android.com/guide/developing/tools/avd.html.

Presentation

The example presented in this tutorial is the creation of a classic Android application : MyContacts. This application is a contact manager with a screen to edit people information.

You will see how you can create an Acceleo code generator in an Android context but it also works on other domains...

Creation of a Prototype

The Android meta-model

The Ecore meta-model describes what a simple Android application is with the Activity and the Widget concepts. For more informations about EMF and Ecore, visit : http://www.eclipse.org/modeling/emf/.

Create the Ecore meta-model :

1. Click File > New > Other > Eclipse Modeling Framework > Ecore Model. Click Next.

2. Choose the source folder where the model will be create and name it. Click Next.

3. Select the Model Object and the encoding. Click Finish

Construct the Ecore meta-model :

An Android application is made up of a Project, Activities and Widgets. A Project contains activities. An Activity contains widgets. Several kind of widgets exist like TextFields, Spinners, Buttons... In our case, the meta-model only contains concepts we need for the application. Add more widgets or other concepts if needed.

The root package must contains a Namespace URI (i.e. a unique identification) :

A Project can contains 0 or an infinity of activities (representing by -1 in the Upper Bound) :

The Widget EClass is an interface for the differnt widgets types :

The Text EClass is a subclass of Widget :

Create the EMF Generator model :

The EMF Generator model allows to generate the code representing the meta-model.

1. Click File > New > Other > Eclipse Modeling Framework > EMF Generator Model. Click Next.

2. Choose the source folder where the generator model will be create and name it. Click Next.

3. Select a model importer. Click Next.

4. Import your Ecore meta-model. Click Next.

5. Select the root package. Click Finish.

6. Open the .genmodel file and edit the Base Package in the Property View :

7. Edit generation directories :

8. Right-click on the root element and click Generate Model Code, Generate Edit Code, and Generate Editor Code.

9. Your Package Explorer must look like this :

The Runtime environment

Once the meta-model created, you have to create a Run Configuration that will allows you to use the meta-model (as a plugin).

1. Right-click and run: Run > Run Configuration.

2. Right-Click on the Eclipse Application item and select New. Rename the configuration, choose a location, and run it.

The Android Project

In the new Eclipse Runtime environment, you are going to create a new Android Project.

1. Click File > New > Other... > Android > Android Project.

2. Fill in the project name an the package name fields.

3. Your Package Explorer must look like this :

The prototype sources

TODO INSERT the link to retrieve the source application

The model of the application MyContacts

We are going to create the model of our MyContacts application.

1. Click File > New > Other.... In the list, select Example EMF Creation Wizard > Android Model. Click Next >.

2. Select the parent source folder and fill in the name of the model. Click Next >.

3. Select the Model Object and the XML Encoding. Click Finish.

4. Using the java sources of the application, try to create a model representing it.

5. Your model must look like this. TextFields Widgets for the name, the phone number and the e-mail address. A Spinner for the country and a save Button.

Initialize the Acceleo code generation project

Now the Android project, the Android meta-model and the MyContacts model have been created, we are going to create the code generation project:

1. In the Acceleo perspective, run File > New > Acceleo Project. In this tutorial, the project will be named org.eclipse.acceleo.module.sample.example.android.
2. Click Next >.

3. Key in the Android meta-model in the Metamodel URI field or select it with the Browse button. Then, select the Activity type in the Generate for type list.
4. In our case we are going to use the Advanced mode to use the Initializing a Project with an Example feature. Push the Advanced button and check the Initialize contents checkbox. Then choose Copy example content in the list, and browse the first java source file of the MyAccounts application.
5. Key in the name of the template file.
6. Check the This will generate a file checkbox.
7. Uncheck the Create a main annotation @main checkbox (we will see what this checkbox means later).
8. Repeat the operation for each kind of generated file.

The new project will appear in the package browser and a small Acceleo decorator will indicate that it is a generation project.

The This will generate a file checkbox means that the file will generate text in a file. Concretely, a File Tag appears in the template. The first argument is the filepath.

9. Update filepath of each module in order that they generate in the right folders.

Initialize the workflow - The main entry point

As mentioned in the OMG specification, an MTL file do calls the other ones.

1. In the Acceleo perspective, in the modules package folder, right-clik and run: New > Acceleo Module File. If you are not in the Acceleo perspective, right-click and run: New > Other > Acceleo Model To Text > Acceleo Module File.
2. Push the Advanced button and check the Create a main annotation @main checkbox.

3. This template will call all the other modules that generate text. Import all the modules and call their templates that generate text.

Editing the code generator

Quick replacement

With Acceleo, you can select any part of a static text in a template and the completion will propose you to replace it by a dynamic Acceleo expression. It shows the number of occurrences will be replaced too. In our case, replace all the occurrences of the String MyContacts in the different modules by the [a.name.toUpperFirst()] Acceleo expression. In our case, note that the default Acceleo Expression proposed is [name.toUpperFirst()], but you can write any expression you want.

The expressions are automatically update.

Quick hierarchy tree

As For/If

In the Android meta-model, you have different type of Widgets, like Text, Spinner, Button... Acceleo provides a way to customize quickly your code, and manage the different possibilities. With the combo For/If, you can apply a specific traitment to each kind of Widgets.

1. In the modules that contains Widgets declarations or calls, select them and then right-click and run: Source > As For/If.

Each kind of Widget is separate.

2. Then key in the appropriate type of Widget in each condition.

3. Let just one TextField declaration and delete the other ones. Complete by change the static name of Widgets with a dynamic Acceleo expression by using the Quick replacement tool.

4. Repeat for the other files.

Be careful with the For Loop. Inside the For Loop, use an explicit call to call the name of the Activity.

Extract Template

You can also use the Extract Template tool by selecting a static text, right-click and run: Refactor > Extract Template....

Rename and edit your new template.

Quick fixes

The Quick fixes allows you to create templates and queries easily. When you are in an Acceleo expression, write the name of the template/query you want to create and then right-click and run: Quick Fix. Then, you can choose the adapted operation you want, like Create template - after last member.

Fill in the template.

Use the new template.

Run and test the generated version of the prototype

You are ready to run and test your own version of the application.

Generate the code

1. Delete the original source files.

2. Create the generator Run configuration. Right-click on the main entry point module and run: Run As > Launch Acceleo Application.
3. Select the MyContacts model in the Model field.
4. Select the target folder, where the new source files will be generated.

5. Push the Run button. The files have been generated in the Android project.

Run the application

1. Create the Android application Run configuration. Right-click on the Android project and run: Run As > Run Configurations.
2. Right-clik on the Android Application item in the list and select New.
3. Change the configuration name.
4. In the Project panel, click Browse to select the Android application.
5. In the Launch Action panel, select the Launch radiobutton and choose MyContactsList Activity.

6. Push the Run button. Here we go ! Your own Android MyContacts application is running.

Run on another model to create new application...

Your generation project is reusable with another model. In a few clicks, you can create a model of an application that will count the OlympicGames medals and generate it !

1. Create the model.

2. Update the Acceleo Run Configuration.

3. Generate the code.

4. Update the Android Run Configuration.

5. Launch and see the result !

A little bit about incremental generation

The incremental generation consist to define specific zones with user tags [protected] in order to keep you own code between the generations.

1. Select the code you want to keep, right-click and run: Source > As Protected Area.

User tags have been added around your code selection.

2. Comment the User tags, and cut the code inside the tags.

3. Launch a generation. You can see the User tags in the generated file.

4. Paste the code inside the protected tags in the generated source file.

From now on, the code inside the User tags will be keep by the future generations. The code outside the User tags will be ignored and overwritten at the next generation. In this example, the BAD CODE will not be there at the next generation, because it have been written outside the User tags in the generated file.

Workbench Acceleo views

Acceleo provides tools to easily edit and maintain the code.

The Result View

The Result View shows how the text, the templates, and the models are synchronized. After a generation, select any element in the Result View and the generated code associate will be highlighted. In the same way, select any piece of code in a generated file, and you will see the associate element in the Result View.

You can also right-click on element in the Result View and run: Open declaration. This will open the Acceleo expression associate to the element.

The Patterns View

The Patterns View is a tooling view where you can define you own completion proposal item for the Acceleo editor.

As an example, if you want to define a query for each kind of Widget, check [query] for all selected types and each kind of Widgets. Then, in a module, the completion will propose the pattern you defined.

Just rename the queries and add the return type.

The Overrides View

The Overrides View is an entry point to easily override an existing template behavior.

In the Overrides View, select the template you want to override. Then, in a module, the completion will propose to override the template you selected.