Overview

The M2Doc project provides Word document (.docx files) generation. It’s based on document template and Ecore model. The M2Doc template is applied on one or mode variables to produce the generated document.

Installation

The simplest way to start using M2Doc is to download an Eclipse modeling tools bundle from the Eclipse packages page. Then you need to unpack it and launch the Eclipse executable. The next step is to install M2Doc from one for the following update sites

Generate a document

To generate a document you will need at least a template file (.docx file) and a generation configuration model (.genconf file). If you don’t have the template you can read the template authoring section. To create a generation model file you can read the initialize generation section.

Launching generation

To launch the generation you can right click on the generation configuration model (.genconf file) or the Generation object and select the «Generate Documentation menu» has shown here:

The Generate Documentation menu.

If you don’t have the the generation model configuration file you can create it using the initialize generation section.

Initializing generation

To initialize a generation you will need a template file (.docx file). If you don’t have the template you can read the template authoring section.

Right click on the template file and select the «Initialize Documentation Configuration» menu:

The Initialize Documentation Configuration menu.

To edit the created generation model file you can use the generation configuration editor.

Validating a generation

To validate the configuration you can right click on the generation configuration model (.genconf file) or the Generation object and select the «Validate Documentation menu» has shown here:

The Validate Documentation menu.

If you don’t have the the generation model configuration file you can create it using the initialize generation section. If the validation succeed with no informations, warnings, or errors you will be promted. If something went wrong a .docx file with the name of the template and sufixed with «info», «warning», or «error» will be created. This new file contains details of the validation issues.

Generation configuration editor

The generation configuration model (.genconf file) references the template URI and the result URI. It also binds the variables defined using the template editor to the desired value. It can also contains a set of options to configure specific services.

The generation configuration editor.

In this example we reference the template named «template.docx» using a relative URI and the result URI is set to «template-generated.docx». Absolute URI can be used as well.

The first table of the editor is used to bind variables. The first column is the variable name and the second column is the value. The value can be a reference an EMF model element or be a primitive type value. Two menus are accessible using right click on the variable table.

The variable menu.

An other menu can be useful to set EMF model values. It’s the «Load Resource...» menu. It add the EMF elements of the selected resources to possible values of a variable.

The second table of the editor at the bottom can be used to set options for specific services. For instance if you use the Sirius integration an option should be set to define the Sirius session model. Three menus are accessible using right click on the option table.

The option menu.

Template authoring

The template should be edited using your word document editor. M2Doc use Word fields to declare dynamic elements. In MS work you can make fields visible by using ALT+F9 and insert a new field by using CTRL+F9.

Syntax

All syntax elements of M2Doc should by placed into fields using ALT+F9 to show fields and CTRL+F9 to insert a field in MS Word. M2Doc is a imperative template language build on top of AQL for querying. The language support type inference and can be extented using custom services.

In the following table ‹{› and ‹}› denote a Word field.

Comment ( example)

A simple comment, nothing is generated.

` {m:comment any text} `

Static statement

anything that is not a M2Doc field is generated as is.

Query ( example)

The AQL expression is evaluated and its result is inserted in the generated document. M2Doc services and provided services can be used. Some specific return types will be interpreted by M2Doc.

` {m: AQL expression } `

Conditional ( example)

if the condition is true the «then block» is inserted in the generated document. if it’s false and the «else if» condition is true the «else if block» is inserted. if all condition are false the «else block» is inserted. You can have zero or more «elseif blocks», zero or one «else block». All AQL expressions should evaluate to a Boolean.

` {m:if AQL expression } ...then block... {m:elseif AQL expression } ...else if block... {m:else} ...else block... {m:endif} `

Repetition ( example)

Generates the «repetition block» for each value of the AQL expression.

` {m:for variable | AQL expression } ...repetition block... {m:endfor} `

Let ( example)

Declare the variable named «variable» with the result of the AQL expression as value. The variable is accessible in the «let block».

` {m:let variable = AQL expression } ...let block... {m:endlet} `

Bookmark ( example)

Generates a bookmark with the result of the AQL expression as identifier and the «bookmark block» as content.

` {m:bookmark AQL expression } ...bookmark block... {m:endbookmark} `

User Documentation ( example)

Generate a user content block in the resulting document. If the generated document exists and already has a use content with the same id the previous user content is preserved, otherwise the «userdoc block» is generated.

` {m:userdoc AQL expression } ...user block... {m:enduserdoc} ` `

If you want examples of templates you can have a look at the nominal cases in unit tests.

Services

All AQL services are available, on top that specific services are provided by M2Doc. See the following reference documentation. If you don’t find your needs in this list, you can provide services.

Template editor

The template editor can set M2Doc specific custom properties in your Word template. Those properties are used to define variables, EMF packages URI, and service imports. When editing a template you need to be in a Java or a plug-in project to be able to add services.

The template editor.

The first table at the top lists variables needed by the template. Each variable has a declared type. This type is used to validate the template and to select a value in the generation configuration editor. Three menus are accessible using right click on the variable table.

The variables menu.

The second table in the middle lists packages used in the template. It reference EMF EPackages used to type expressions in the template. Two menus are accessible using right click on the package table.

The variables menu.

The package selection dialog.

The last table at the bottom lists services used in the template. If you have created your own services you can add them here to be able to use them in the template. Three menus are accessible using right click on the service table.

The variables menu.

The service selection dialog.

The service token selection dialog.

Provide new services

You can extends M2Doc by adding services to your templates using the template editor. A service is a simple Java method with at least one parameter and a return value.

Service class

You have two cases for the containing class either it has a default constructor or a constructor with a parameter.

Default constructor

When the class has no explicit constructor or the constructor don’t have any parameters. In this case you don’t need any specific development except for your service method. You can have a look at specific return types if you want to insert images, table, etc... To use your services in your template simply add them in the template editor.

Custom constructor

When there is an explicit constructor with at least a parameter M2Doc can’t instantiate your class since there is no default constructor. You need to implement the IServicesConfigurator interface. This interface link one or more options in the generation configuration to the service class in order to instantiate it. You need to use the org.obeonetwork.m2doc.ide.servicesConfigurator extension point to declare your implementation of IServicesConfigurator. If you want to use your implementation in standalone you can register it programmatically using M2DocUtils.registerServicesConfigurator().

An example of implementation can be found in the Sirius integration plug-in see the class SiriusConfigurationProvider and the extension in the plugin.xml.

Service token

The service token extension point org.obeonetwork.m2doc.ide.services.register can be used to reference a set of service classes using a token name. This token can be selected using «Select tokens» menu in the template editor.

Special return types

M2Doc evaluation engine convert any object to a string in order to insert it in the generated document. To add flexibility in the produced document we chose to expose some special types to service creators. Those types are MElement allow to directly insert document artifacts:

Default implementations are also provided by M2Doc in this package.

Template testing

To simplify testing while developing M2Doc, a JUnit test suite has been implemented. It use a given folder as input and list each sub directory following a naming pattern as a test case. You can use the same test suite for your own tests. And example of the test suite implementation QueryTests with the folder resources/query.

Maven

You can launch your generation using Maven and Tycho. An example is available here. You probably have a look at the pom.xml file. To launch the build and the generation you can simply use the following command:

` mvn clean verify `

Using M2Doc programmatically

This section is for developers wanting to integrate M2Doc in there own project. It will show how to use main features of M2Doc programmatically. Since M2Doc use AQL for expressions it can be useful to have a look at Using AQL programmatically.

Parsing

the following sample code shows how to load a template .docx file using M2Doc:

`java final IQueryEnvironment queryEnvironment = org.eclipse.acceleo.query.runtime.Query.newEnvironmentWithDefaultServices(null); final Map<String, String> options = ...; // can be empty M2DocUtils.prepareEnvironmentServices(queryEnvironment, templateURI, options); // delegate to IServicesConfigurator final IClassProvider classProvider = new ClassProvider(this.getClass().getClassLoader()); // use M2DocPlugin.getClassProvider() when running inside Eclipse try (DocumentTemplate template = M2DocUtils.parse(templateURI, queryEnvironment, classProvider)) { // use the template } `

Validation

The validation is optional:

`java final ValidationMessageLevel validationLevel = M2DocUtils.validate(template, queryEnvironment); if (validationLevel != ValidationMessageLevel.OK) { final URI validationResulrURI = ...; // some place to serialize the result of the validation M2DocUtils.serializeValidatedDocumentTemplate(documentTemplate, validationResulrURI); } `

Generation

The generation will produce the final document where M2Doc template is evaluated against the given variables. There are two level of API for the generation: direclty from the DocumentTemplate or from the Generation.

Core generation API

`java final Map<String, Object> variables = ...; // your variables and values final URI outputURI = ...; // some place to serialize the result of the generation M2DocUtils.generate(template, queryEnvironment, variables, outputURI, monitor); `

Generation configuration API

`java final Generation generation = ...; // load from a serialized EMF model or create in memory final IClassProvider classProvider = new ClassProvider(this.getClass().getClassLoader()); // use M2DocPlugin.getClassProvider() when running inside Eclipse GenconfUtils.generate(generation, classProvider, monitor); `