Architecture of Papyrus-Model2Doc

This framework has been developed to be hightly independant of Papyrus, with some execptions, like the reuse of the Papyrus Expressions framework.

Git Architecture

DocumentStructureTemplate metamodel

This metamodel defines how to parse a model, what information to extract from it and how to include them in the final Document. This metamodel is provided by the plugin org.eclipse.papyrus.model2doc.emf.documentstructuretemplate.

This snapshot shows the basic elements of this metamodel.

On the next snapshot we show the construction of the EReferencePartTemplate and EClassPartTemplate. As indicated previously, this construction allows the navigation between an object and a property of this object recursively.

DocumentStructureTemplate editor

The editor provided to edit the DocumentStructureTemplate metamodel is not exactly the version generated by EMF. We customized it in order to use a TransactionalEditingDomain (to ease the Papyrus integration).

How to provide new part template for the Body of a TextDocumentTemplate?

We can't explain all the EMF tricks employed, configuration and so on, but we will detail the most important ones.

  1. You must have installed the Papyrus Toolsmiths plugins
  2. You must have installed the feature UML2 SDK Extender to be able to generate a EMF model from a UML one.

Create a new PartTemplate in a UML model

  1. There is 2 choices about the way to proceed
    1. You can either edit one of the DocumentStructureTemplate metamodel provided by Papyrus-Model2Doc and contribute it to the Eclipse Project
    2. Or you can create a new metamodel (and share it with Papyrus-Model2Doc project or not)
  1. You then need to define what you want to do:
    1. A new navigation looking like an EMF EStructuralFeature?
      1. With possible sub-elements -> implements the interface IComposedBodyPartTemplate
      2. With no sub-element -> implements the interface ILeafBodyPartTemplate
    2. A new navigation looking like an EMF EClass?
      1. With possible sub-elements -> implements the interface IComposedSubBodyPartTemplate
      2. With no sub-element -> implements the interface ILeafSubBodyPartTemplate

N.B.: The UML element to implement a UML Interface in a UML model is the element InterfaceRealization . We advise against extending other elements of this metamodel.

In general, to provide a new view, we consider that such an element has no children and we use a feature to calculate the contents of the view. That's why TreeListView and EReferenceTableView implements ILeafBodyPartTemplate.

To illustrate this description, we advise you to look at the UMLDocumentStructureTemplate metamodel which extends the base DocumentStructureTemplate metamodel to provide support for UML Stereotype and Stereotype's properties. In this metamodel, StereotypePartTemplate is defined to be at the same level than EClassPartTemplate and StereotypePropertyReferencePartTemplate to be at the same level than EReferencePartTemplate. In addition, this metamodel provides the CommentAsParagraph object, considered as a view and described as a ILeafBodyPartTemplate, which is at the same level than the EReferencePartTemplate.

Generate

Once you created your new element, you need to generate it.

  1. Just open the existing genmodel file, then Right-Click->Reload (or create a new one, in case of new uml model).
  2. On the root of this file, Right-Click->Generate Model, then Generate Edit (you can Generate Editor, but this should only be necessary if you need to work on the DocumentStructureTemplate metamodel).

N.B. if you add a property to an interface and if this interface is implemented in sub-metamodel, you will need to regenerate all these sub-metamodels too!!!

Implementation of IBodyPartTemplate#buildPartTemplateTitle

Due to the root interface IBodyPartTemplate of these element, you must provide an implementation of the method buildPartTemplateTitle. There is 2 ways to do this:

  1. solution1:
    1. Provide a factory override for your metamodel, then provides a custom implementation of the generated class implementing this method (see the "org.eclipse.emf.ecore.factory_override" extension point).
  2. solution2:
    1. Create a new buildPartTemplateTitle operation in your element, in the UML model, then, in the Advanced tab of the Property View, edit the field redefined operations referencing the operation ' ''buildPartTemplateTitle of the parent interface.
    2. In your UML model, create an EAnnotation as child of your element (from the Papyrus ModelExplorer view, Right-Click->Create EAnnotation;
      1. In the Property View, set http://www.eclipse.org/emf/2002/GenModel as source.
    3. From the Model Explorer view, create a Details Entry as child of the EAnnotation;
      1. In the Property View, set body as key and the java body of the method in the value field.
    4. Finally, return into the genmodel file, reload model and regenerate it all as previously explained.

You can also provide a nicer icon in the edit plugin for your created element, just replace the default icon provided by the generation.

At this step, the new element will be available in the Creation menu of the DocumentTemplate editor.

How to contribute to the EMF property view?

The default property view is already managed by the EMF-Framework. If you need to change the default edition of a property, you need to create an EAnnotation with a Details Entry in your UML model as child of the property for which you need to provide a custom editor.

Then, you must register a new class extending org.eclipse.emf.edit.provider.PropertyEditorFactory to the extension point org.eclipse.emf.edit.propertyEditorFactories in the edit plugin for your model.

How to contribute to the EMF property view embedded in Papyrus (Advanced Tab)?

This code should be done in a plugin called org.eclipse.papyrus.integration.xxx to respect the naming convention. We advise you to manage the EMF property view, before embedding it in Papyrus (because there is shared code between them).

In case of new DocumentStructureTemplate metamodel

  <extension
        point="org.eclipse.ui.views.properties.tabbed.propertySections">
     <propertySections
           contributorId="TreeOutlinePage">
        <propertySection
              class="org.eclipse.papyrus.model2doc.integration.emf.documentstructuretemplate.properties.internal.DocumentStructureTemplatePropertySection"
              filter="org.eclipse.papyrus.model2doc.integration.emf.documentstructuretemplate.properties.internal.DocumentStructureTemplatePackageSectionFilter"
              id="org.eclipse.papyrus.model2doc.emf.documentstructuretemplate.properties.propertySection1"
              tab="advanced">
           <input
                 type="java.lang.Object">
           </input>
        </propertySection>
     </propertySections>
  </extension>

In case of new property in an existing metamodel

You just need to manage your new feature in the method PropertySource.createPropertyDescriptor(IItemPropertyDescriptor) of the existing PropertySource

How to contribute a new mapper?

The mappers are in charge of reading the model and the DocumentTemplate to create the DocumentStructure. As an example, you can look the plugin org.eclipse.papyrus.model2doc.emf.template2structure.

How to create a new DocumentTemplatePrototype from an existing DocumentTemplate?

The Papyrus-Model2Doc Developper Tools must be installed in your Eclipse.

How to contribute new Document Structure generator

This generator is in charge to generate the DocumentStructure from your model and a DocumentStructureTemplate. You must create a new class implementing org.eclipse.papyrus.model2doc.emf.template2structure.generator.ITemplate2StructureGenerator. We recommend to extend the class org.eclipse.papyrus.model2doc.emf.template2structure.generator.AbstractDocumentStructureGenerator This class must be registered with the extension point org.eclipse.papyrus.model2doc.emf.template2structure.structuregenerator. The extension point allows you to declare a parent generator (field inheritsMapperFromGenerator) to reuse mapper declared on this parent generator.

How to contribute a new Document generator

This generator is in charge to generate the final document from a DocumentStructure. You must create a new class implementing org.eclipse.papyrus.model2doc.emf.structure2document.generator.IStructure2DocumentGenerator. This class must be registered with the extension point org.eclipse.papyrus.model2doc.emf.structure2document.documentgenerator.

Styles

The org.eclipse.papyrus.model2doc.core.styles plugin provide style metamodel. It define NamedStyle for Integer, String, Boolean and Double using single or multiple references.

How to add new NamedStyle

Existing NamedStyles

Name Description Value type Applies to Odt Docx
mergedWithRightCell Merge the cell with the cell located just to the right Boolean Cell
mergedWithBottomCell Merge the cell with the cell located just to below Boolean Cell

Markup Language

All the code to support markup languages is located into the markup folder. The provided template elements and their mappers are:

The template elements are generic, so the final user can define the input format ( Markdown, html, mediawiki, textile, ...) and the output format of the file to create ( html, ...) .

Currently, we only provides mappers from Markdown and html to html. To contribute new format, you just need to create new mappers looking existing ones and to override the method doHandlesInput to filter the supported input/output format.