View source for RMF/Contributor Guide/Presentations

= Tutorial =

This is a brief Howto that describes the creation of a new Presentation Plug-In for ProR. 

== Headline Presentation Plugin: The Requirements ==

The requirements are:

* The Presentation shows the configured attribute in a bigger font.
* The Presentation does not support automatic line wrapping.
* The font size can be configured. 

== Implementation ==

Step by step instructions.

=== Create a new Plug-In Project ===

* Create a new "Empty EMF Project".
* As a convention, start its name ''org.eclipse.rmf.reqif10.pror.presentation.xxx''. We call it ''org.eclipse.rmf.reqif10.pror.presentation.headline''.

=== Create the EMF Model Extension ===

Every Presenation must extend the ReqIF Model. This is fairly important to get right. 

* Create a new "Ecore Model"
* Store it in the folder ''model'' (should already exist) and call it ''Headline.ecore''.
* Leave all the other Defaults and create the model. It should consist of a top-level element (starting with "platform:/...") and an empty package.
* Select the package and configure it in the Properties-View as follows:
** Name: headline
** Ns Prefix: headline
** Ns URI: http://eclipse.org/rmf/pror/presentation/headline 
* We need to refer to the ProR UI Model to extend it.
** Make sure that the Project ''org.eclipse.rmf.reqif10.pror'' is in your workspace and open.
** In your model editor for Headline.ecore, right-click and select "Load Resource..."
** Select configuration.ecore (platform:/resource/org.eclipse.rmf.reqif10.pror/model/configuration.ecore) 
* Now we create the required new Configuration Class
** Right-Click on the "headline" package
** Create a new Child of type "EClass"
** Configure it in the Properties as follows:
*** ESuperTypes: ProrPresentationConfiguration
*** Name: HeadlineConfiguration 
* We may as well add the Attribute for Font Size at this time:
** Right-Click on HeadlineConfiguration and create a new Child of type EAttribute
*** Name: size
*** EType: EInt
*** Lower Bound: 1 (required field) 

Your model editor should look as follows:

[[Image:rmf_dev_pres1.png]]

=== Create the GenModel ===

Here, too, things can go wrong. Pay particular attention to how the referred Models are handled.

* Create a new "EMF Generator Model"
** Call it ''Headline.genmodel'' and put it into the same folder ''model'' where ''Headline.ecore'' is stored
** Select the "Ecore Model" importer
** Select the Model URI for ''Headline.ecore'' model (it it isn't preloaded already). You may have to hit the "Load" button before you can proceed.
** '''Pay attention now''' as the references must be selected correctly. You should be in the "Package Selection". This Dialog has two panes. In the upper pane you should see the headline, configuration and several reqif packages.
** Use the "Add" button to add the Genmodels for reqif. Therefore, select the ''reqif.genmodel'' file from the ''org.eclipse.rmf.reqif10.pror'' plugin. They should now be visible in the lower pane.
** Check the checkboxes for ''Configuration'' and ''XMLNamespace'' in the lower pane. As you do this, the packages should disappear from the upper pane.
*** Here is what happened: In the Ecore, we were referencing two models. When we created the Genmodel for Headline, the default would have been to create Genmodels for all three packages. But we only want a Genmodel for Headline. Thus, we have to provide references to existing Genmodels. 
** Last, check the checkbox for Headline in the upper pane. This should enable the "Finish" button
** Click Finish: The new Genmodel should be open. It should show several package entries. For instance, the entries to Configuration and ReqIF10 should have little arrows, indicating that they are references. 
* We only need to generate the Model and Edit code. By default, the Edit code ends up in a new Plugin Project. This is overkill for such a small project. We will change the configuration to generate the Edit code in the Model Plugin (the one we're currently in).
** Select the Top-Level element "Headline".
** Expand the "Edit" section in the Property View. Change the Properties as follows:
**** Edit Plug-in ID: org.eclipse.rmf.reqif10.pror.presentation.headline (remove the training ".edit")
**** Edit Directory: /org.eclipse.rmf.reqif10.pror.presentation.headline/src
*** Now Select the Package "Headline" (just one element below the one you just worked on). Edit in the properties:
**** Base Package: org.eclipse.rmf.reqif10.pror.presentation (Upon code generation, the package name will be appended. Thus the generated package will be org.eclipse.rmf.reqif10.pror.presentation.headline) 
* Now we should test our settings.
** Right-click on the top-level element and select "Generate Model Code"
** Same with "Generate Edit Code"

** Note: If you want to generate more, please be sure to configure the project accordingly, unless you want to create new Projects.
** After the generation, make sure that no new Projects appear in your workspace. Check the source folder, there should be the following four packages:
*** org.eclipse.rmf.reqif10.pror.presentation.headline (the model interfaces)
*** org.eclipse.rmf.reqif10.pror.presentation.headline.impl (the model implementation)
*** org.eclipse.rmf.reqif10.pror.presentation.headline.provider (the ItemProviders, from the Edit generation)
*** org.eclipse.rmf.reqif10.pror.presentation.headline.util (helper code) 
* Congratulations! You're done with this step.

=== Implementing PresentationEditInterface ===

You will get a number of compile errors, as the interfaces from PresentationEditInterface are not implemented.  This interface is inherited by the (abstract) ConfigurationItemProvider.  The interface has been written carefully to provide information on how to implement it.  So implement it, and refer to the interface documentation if you are stuck.

Next, make the ConfigurationItemProvider stateful by editing the genmodel again, and by regenerating the ItemProviders.  this way, you have one instance per configuration element:

* Go to your genmodel
* Open the tree and select HeadlineConfiguration
* In the properties view, open "Edit" and set "Provider Type" to "Stateful".
* Regenerate - it's enough to right-click on HeadlineConfiguration and select "Generate Edit Code"

=== Extending the Extension Point ===

Now we will create an extension to tell ProR about the new Presentation:

* Open the Plugin-Manifest (plugin.xml) or the MANIFEST.MF if no plugin.xml exists
* Go to Dependencies and add ''org.eclipse.rmf.reqif10.pror.editor''
* Add a new Extension as follows: 

<source lang="xml">
 <extension
         point="org.eclipse.rmf.reqif10.pror.editor.presentation">
      <presentation
            name="Headline"
            service="org.eclipse.rmf.pror.presentation.headline.ui.HeadlinePresentationService">
      </presentation>
   </extension>
</source>

We created a new package (ui) to prevent mixing generated and hand-written code.

=== Implementing the PresentationService ===

* Next, we'll implement the service (you can generate a stub by clicking on "service" in the Extension View)
* We won't describe the interface methods in detail - please check the JavaDoc, the Interface is well-documented. For simple methods, the JavaDoc even provides the recommended Implementation code.
* We decide not to modify getCellEditor(). By returning null, the default implementation is returned (doesn't matter that the font is small while editing)
* To actually do the proper rendering, we have to modify getCellRenderer() to return a new cell renderer that renders the content in a bigger font.
** We change the code to 

<source lang="java">
public IProrCellRenderer getCellRenderer(AttributeValue av) {
  if (headlineCellRenderer == null) {
        // Get the headline configuration
        HeadlineConfiguration headlineConfiguration = (HeadlineConfiguration) ConfigurationUtil.getPresentationConfig(av, null);
        // Create a new headline cell renderer
	headlineCellRenderer = new HeadlineCellRenderer();
        // Set the font size from the configuration
        headlineCellRenderer.setFontSize(headlineConfiguration.getSize());
  }
  return headlineCellRenderer;
}		
</source>

All that's missing is that class. 

=== Implementing the Cell Renderer ===

In order to create a Cell Renderer for the presentation we have to create a new class ''HeadlineCellRenderer'' and to implement the interface ''IProrCellRenderer''. Here is a very basic implementation: 

<source lang="java">
public class HeadlineCellRenderer implements IProrCellRenderer {

	private Font font;
	private int fontSize;

	public void setFontSize(int fontSize) {
		this.fontSize = fontSize;
	}

	public int doDrawCellContent(GC gc, Rectangle rect, Object value) {
		AttributeValueSimple av = (AttributeValueSimple) value;
		String text = ReqIF10Util.getTheValue(av).toString();
		FontData[] fontData = { new FontData("Arial", fontSize, SWT.BOLD) };
		if (font != null)
			font.dispose();
		font = new Font(Display.getDefault(),fontData);
		gc.setFont(font);
		gc.drawText(text, rect.x, rect.y);
		return gc.textExtent(text).y;
	}

	public String doDrawHtmlContent(Object value) {
		AttributeValueSimple av = (AttributeValueSimple) value;
		return "<div style='font-size: " + fontSize
				+ "pt; font-weight: bold; padding-top: 4pt;'>"
				+ ReqIF10Util.getTheValue(av) + "</div>";
	}

}
</source>

* The ''doDrawCellContent'' method is responsible for rendering the cell in the Specification Editor.
* The ''doDrawHtmlContent'' method is used for generating the HTML representation of the attribute. Sell also [[RMF/Documentation_Guideline#ReqIF_to_HTML_Generator]]

=== Testing ===

You can test the new Presentation by creating a new entry with ProR > Presentation Configuration... 

=== Updating the LabelProvider ===

* The generated Label is fairly meaningless. We can fix this in the following way:
* Edit plugin.properties and update the following entry:
** _UI_HeadlineConfiguration_type = Headline for: {0} (size: {1}) 
* We also need to set the substitutions To do that, open the generated ''HeadlineConfigurationItemProvider.java'' class in the ''org.eclipse.rmf.pror.presentation.headline.provider'' package
** Find public String ''getText(Object object)''
** change @generated into @generated NOT (this will prevent the change from being overwritten at the next code generation) 

<source lang="java">
         /**
	 * This returns the label text for the adapted class.
	 * <!-- begin-user-doc -->
	 * <!-- end-user-doc -->
	 * @generated NOT
	 */
	@Override
	public String getText(Object object) {
		HeadlineConfiguration headlineConfiguration = (HeadlineConfiguration)object;
		String[] subst = new String[2];
		subst[0] = headlineConfiguration.getDatatype() == null ? "(PLEASE SET TYPE)"
				: headlineConfiguration.getDatatype().getLongName();
		subst[1] = headlineConfiguration.getSize() + "";
		return getString("_UI_HeadlineConfiguration_type", subst);
	}
</source>

* Optionally, you can also change the icon
** You can simply change the icon in the icons folder, but...
** We prefer to also change the ''getImage()'' method to provide a png. pngs have better transparency handling
** You can copy the standard icon for Presentations from one of the other Presentation Plugins. 

[[Category:RMF]]
[[Category:RMF/Contributor Guide]]