View source for Texo/Template Overriding

__TOC__

== Introduction ==

'''Note:''' Texo uses xtend2 as its templating technology, for overriding Texo supports xpand. For some additional info see this [http://martintaal.wordpress.com/2012/10/12/emft-texo-using-xtend2-for-faster-generation/ blog post].

Texo makes it really easy to override specific Texo templates or even completely replace the templates used by Texo. This can be done for each Eclipse java project differently, so different Eclipse project can have different generation patterns.

Overriding/implementing your templates within Texo has the following main advantages:
* '''Easy''': it is easy, you just need to place your xpt files in a java project, Texo template files are small and easy to understand (and therefore easy to adapt).
* '''Organize imports in generated java files''': Texo takes care of organizing your inputs (following the project settings), so in your template you just need to use fully-qualified names, Texo resolves and organizes them.
* '''Java Source Formatting''': Texo takes care of formatting your code according to your project settings.
* '''EMF-like-merging''': Texo supports the EMF merge approach, this is available out-of-the-box for your code also. You can mix manual and automatic code in your code.
* '''Model annotations''': the Texo model annotations are available for your templates. The model annotation contain extra information relevant for code generation (java class, java type information, etc.).

By overriding Texo templates you don't need to work directly with MWE workflows, this is taken care of by Texo.

Texo uses xtend templates for generating different parts of the model code. For overriding xpand is used, example templates for overriding can be found  [http://git.eclipse.org/c/texo/org.eclipse.emf.texo.git/tree/generator/org.eclipse.emf.texo.modelgenerator/src/org/eclipse/emf/texo/modelgenerator/templates/ org.eclipse.emf.texo.modelgenerator.templates] package in the org.eclipse.emf.texo.modelgenerator plugin. You can find this plugin in [[Texo/Developing#GIT|GIT]] or in your eclipse plugins folder (after installing).

== Templates to override ==

Example templates can be found in [http://git.eclipse.org/c/texo/org.eclipse.emf.texo.git/tree/generator/org.eclipse.emf.texo.modelgenerator/src/org/eclipse/emf/texo/modelgenerator/templates/ git]. 

There are a few templates which are particularly interesting to override:
* '''addition.xpt''': this template is intended to be overridden to generate additional files, it is called for each EPackage, EClass and EEnum in the model.
* '''entity_addition.xpt''': this template is called from within the body of the entity.xpt. It can be used to generate additional methods in the entity classes.
* '''interface_addition.xpt''': this template is called from within the body of the interface.xpt. It can be used to generate additional methods when an interface is generated.
* '''enum_addition.xpt''': this template is called from within the body of the enum.xpt. It can be used to generate additional methods when an enum class is generated.

The xtend templates used by Texo for code generation can be found  [http://git.eclipse.org/c/texo/org.eclipse.emf.texo.git/tree/generator/org.eclipse.emf.texo.modelgenerator/src/org/eclipse/emf/texo/modelgenerator/xtend/ here] in git. 

Most xtend templates can be overridden/replaced with custom xpand templates. Here is a short description of some of the main xtend templates which can be overridden:
* EcoreFileTemplate.xtend: this template takes care of saving the ecore file in the same package as the entity classes.
* EntityTemplate.xtend: an important template, takes care of generating the entity classes
* InterfaceTemplate.xtend: handles the EClasses which are interfaces
* ModelFactory.xtend: generates the ModelFactory class
* ModelPackage.xpt: responsible for generating the ModelPackage.

== Overriding a template ==

When generating model code, Texo checks the project properties to see if a template folder has been set in the Texo project properties. If this is the case, first this folder is checked for templates before using the standard Texo templates.

Note, Texo checks the project properties of the project which contains the model file. So if your model files are in different projects then each project needs such a templates folder set in the project properties. Currently (March 2010) the templates folder must be in the same project as the model file, in future versions it will probably be possible to select a workspace or filesystem folder outside of the project.

Overriding Texo templates is done like this:
* create a template folder in the same project as the model file, set the template folder in the Texo project properties. To enable the Texo project properties right click on the project and in the configure submenu choose add/remove texo nature.
* create a directory structure inside this folder corresponding to the Texo templates package: org/eclipse/emf/texo/modelgenerator/templates
* create your template file inside the org/eclipse/emf/texo/modelgenerator/templates folder with the same name ('''but using xpt as the file extension''') as the template file used by Texo. For example to override the generation of the main model classes you need to create an entity.xpt file (probably copy an example from the templates directory).


[[Image:org.eclipse.emf.texo.override.template.png|center|700px]]

== Template input: model annotations ==

The template is called with model annotations as the main class. The model annotation enriches the domain model with code generation specific information (for example the java class). In addition you have access to the underlying model element (EPackage, etc.). There are model annotation for each of the main model elements (EPackage, EClass, EStructuralFeature, EReference, EAttribute, EDataType, EEnum).

The model annotation definition (ecore and java files) can be found in the [http://git.eclipse.org/c/texo/org.eclipse.emf.texo.git/tree/generator/org.eclipse.emf.texo.modelgenerator org.eclipse.emf.texo.modelgenerator] plugin. The ecore file defining the model annotations can be found [http://git.eclipse.org/c/texo/org.eclipse.emf.texo.git/tree/generator/org.eclipse.emf.texo.modelgenerator/model/texo-annotations-modelgenerator.ecore here].

Texo will be extended with additional annotation sets (JPA, Hibernate Search, etc.), this means that over time more types of annotations are available to the templates.

== Template Tips ==

* '''Generating additional files''': the addition.xpt is ment to be overridden for generating additional files. 
* '''Organize imports''': Texo takes care of organizing imports and safely resolving fully qualified names. This means that in your template you should use fully qualified names.
* '''Merging support''': Texo also incorporates your additional files in the EMF-like merge process. This means that you can easily implement the same EMF-like-merge-support in your files (just place the @generated tag in the javadoc of classes, methods, members).
* '''Clean up''': to prevent orphaned files Texo removes files which are not regenerated. So be aware that generation should only be done in packages/directories which contain files which are always generated together.