Table Developer Documentation

General Presentation

The Papyrus Table uses the NatTable widget. Its documentation is available here and here. These new table are available since the Papyrus Release 0.10 in June 2013. The NatTable source code can be downloaded with git http://git.eclipse.org/gitroot/nattable/org.eclipse.nebula.widgets.nattable.git Before starting, we advice you to read the User documentation here, particularly these points :

Papyrus_User_Guide/Table_Documentation#Glossary
Papyrus_User_Guide/Table_Documentation#Table areas
Papyrus_User_Guide/Table_Documentation#General presentation

Papyrus provides tables to edit features of UML Element. In general way, the UML Element are displayed as rows and their features are displayed as columns. These tables can be flat or hierarchical and filled by the user or synchronized on the context of the table. The Papyrus integration should allow to create Matrix, but currently Papyrus doesn't yet provide Matrix editors.

The Papyrus team created an EMF metamodel to describe the Tabular editor and to store it. This metamodel is provided by the plugin org.eclipse.papyrus.infra.nattable.model. This metamodel declares all elements useful to manipulate the table concept. Here, we will describe some of them :

1. NamedStyle
   • an abstract object to store information, identified by name. Implementations of this element allow you to store boolean, int, list, string, ... It is the same way than in GMF notation metamodel used by Papyrus Diagram.
2. StyledElement
   • It is an abstract element which allow to reference style NamedStyle. Each elements provided by the table metamodel must inherit from this one. By this way, the developper can add easily information to element, without modifying the table metamodel. (Please, be clever; in some case, it is better to create new metamodel element than use could be clever to add your information to the metamodel than to use NamedStyle.
3. TableConfiguration
   • This element contains all informations required to create a table. The user can't modify it.
4. Table
   • This element is created from a TableConfiguration. The user modifies it using the tabular editor. It always references a TableConfiguration.
5. IAxis
   • abstract object used to reference elements represented by columns and rows.

How to create your own table configuration

The aim of this topic is to provide a tutorial for customizing a table within Papyrus. The Papyrus Table can be synchronized or not and can be flat or hierarchical. In this tutorial, we will describe the creation of these 3 kinds of table:

• a table not synchronized, so filled by the user, called UMLDnDBlockTable in this documentation
  • This table will only accepts Class stereotyped by SysML Block
  • Its allowed context will be Package
  • 3 columns will be provided : name and visibility (UML features) and isEncapsulated (SysML feature)
• a synchronized table, called UMLSynchronizedBlockTable in this documentation
  • This table will only accepts Class stereotype by Block
  • Its allowed context will be Package
  • 3 columns will be provided : name and visibility (UML features) and isEncapsulated (SysML feature)
• a tree table, called UMLSynchronizedBlockTreeTable in this documentation
  • This table will only accepts Class as root elements
  • Its allowed context will be Package
  • 3 columns will be provided : name and visibility (UML features) and isEncapsulated (SysML feature)

Create a new Table Configuration

For this step, first of all, you must to create a new Eclipse Plugin Project. In this one, you have to create a new Nattableconfiguration Modelfile, for example, called block.nattableconfiguration. Once a block.nattableconfiguration has been created, you have to open it for setting your customizing table.

To set the Block Table you have to follow the following steps:

Flat or Tree table

You must declare a Table Display Style has children of the Table Configuration

• Tree Table (UMLSynchronizedBlockTreeTable) : the value must be HIERARCHIC_SINGLE_TREE_COLUMN to display hierarchy on a single column or HIERARCHIC_MULTI_TREE_COLUMN to display the hierarchy on several columns
• Flat Table ( UMLSynchronizedBlockTable and UMLDnDBlockTable ) : the value must be NORMAL (if no display style is defined, the configuration will be interpreted than a NORMAL table.

Add Java Table Tester

The tester will be used to test if your table can be created using the selected element as context.
Since the implementation of the viewpoint, the tester is not yet called, but it could be better to continue to provide it! Click with the right mouse button on the Table Configuration item and create a New Child of type Java Table Tester. Once added, define its properties:

Tester: declare the id of your java tester, then create a java class implementing org.eclipse.papyrus.infra.nattable.tester. in the plugin.xml of your project, this class must contribute to the extension point org.eclipse.papyrus.infra.nattable.tester.

/*****************************************************************************
 * Copyright (c) 2013 CEA LIST.
 *
 *
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *  Vincent Lorenzo (CEA LIST) vincent.lorenzo@cea.fr - Initial API and implementation
 *
 *****************************************************************************/
package org.eclipse.papyrus.sysml.nattable.block.tester;
 
import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.Status;
import org.eclipse.papyrus.infra.nattable.tester.ITableTester;
import org.eclipse.papyrus.sysml.blocks.BlocksPackage;
import org.eclipse.papyrus.sysml.nattable.block.Activator;
import org.eclipse.uml2.uml.Element;
import org.eclipse.uml2.uml.Package;
import org.eclipse.uml2.uml.util.UMLUtil;
 
/**
 * The tester used to know if we can create requirement table
 *
 * @author Vincent Lorenzo
 *
 */
public class BlockTableTester implements ITableTester {
 
	public IStatus isAllowed(Object context) {
		if (context instanceof Element) {
			Element el = (Element) context;
			boolean result = context instanceof Package ;
			if (result) {
				final String packageQN = UMLUtil.getProfile(BlocksPackage.eINSTANCE, el).getQualifiedName();
				result = result && el.getNearestPackage().getAppliedProfile(packageQN, true) != null;
				if (result) {
					return new Status(IStatus.OK, Activator.PLUGIN_ID, "The context allowed to create a Block Table");
				} else {
					return new Status(IStatus.ERROR, Activator.PLUGIN_ID, String.format("The profile {0} is not applied on the model", packageQN));
				}
			}
		}
		return new Status(IStatus.ERROR, Activator.PLUGIN_ID, "The context is not an UML Element");
	}
 
}

Add one Row Header Axis Configuration Table Header Axis Configuration

Click with the right mouse button on the Table Configuration item and create a New Child of type Row Header Axis Configuration Table Header Axis Configuration. Once added, define its properties:

Add one Object Label Provider Configuration

Click with the right mouse button on your new created Table Header Axis Configuration item and create a New Child of type Object Label Provider Configuration. Once added, define its properties:

Add one EStructural Feature Value Filling Configuration

Click with the right mouse button on your new created Table Header Axis Configuration item and create a New Child of type EStructural Feature Value Filling Configuration. But, before setting its properties, you have to load the UML.ecore model. Follow these steps:

1. Open the block.nattableconfiguration file with Sample Reflective Ecore Model Editor;

2. Click with the right mouse button on the editor and choose Load Resource… in the popup menu;

3. Click on the Browse Target Platform Packages…;

4. Select http://www.eclipse.org/uml2/4.0.0/UML.

Still in the Sample Reflective Ecore Model Editor, define the EStructural Feature Value Filling Configuration properties:

At the end, open block.nattableconfiguration file with Text Editor and replace

<listenFeature xsi:type="ecore:EReference" href="../../org.eclipse.uml2.uml/model/UML.ecore#//Namespace/ownedMember"/>

by

<listenFeature xsi:type="ecore:EReference" href="http://www.eclipse.org/uml2/5.0.0/UML#//Namespace/ownedMember"/>

Add one Axis Manager Representation

Come back to use the Nattableconfiguration Model Editor, click with the right mouse button on your new created Table Header Axis Configuration item and create a New Child of type Axis Manager Representation. Once added, define its properties:

Axis Manager Id: define the Id that you will use to set the extension org.eclipse.papyrus.infra.nattable.axismanager.

Add one Column Header Axis Configuration Table Header Axis Configuration

Click with the right mouse button on the Table Configuration item and create a New Child of type Column Header Axis Configuration Table Header Axis Configuration (Fig. 7). Once added, define its properties:

Add one Feature Label Provider Configuration

Click with the right mouse button on your new created Table Header Axis Configuration item and create a New Child of type Feature Label Provider Configuration. Once added, define its properties:

Add two Axis Manager Representation

Click with the right mouse button on your new created Table Header Axis Configuration item and create a New Child of type Axis Manager Representation. Once added, define its properties:

And again, create a second New Child of type Axis Manager Representation. Once added, define its properties:

Add one Column Axis Providers Slave Object Axis Provider

Click with the right mouse button on the Table Configuration item and create a New Child of type Column Axis Providers Slave Object Axis Provider (Fig. 7). Once added, define its properties:

Add one EStructural Feature Axis

Click with the right mouse button on your new created Slave Object Axis Provider item and create a New Child of type EStructural Feature Axis. Once added, define its properties:

Open block.nattableconfiguration file with Text Editor and verify if the Element name has the correct href:

<axis xsi:type="nattableaxis:EStructuralFeatureAxis" manager="//@columnHeaderAxisConfiguration/@axisManagers.0"> <element xsi:type="ecore:EAttribute" href="http://www.eclipse.org/uml2/5.0.0/UML#//NamedElement/name"/> </axis>

Add one Feature Id Axis

Click with the right mouse button on your new created Slave Object Axis Provider item and create a New Child of type Feature Id Axis. Once added, define its properties:

Element: define the path for a property of a stereotype.

Path format: property_of_stereotype:/QUALIFIED_NAME::STEREOTYPE::PROPERTY

Manager: define your Axis Manager set previously[[1]].

Add one Row Axis Providers Master Object Axis Provider

Click with the right mouse button on the Table Configuration item and create a New Child of type Row Axis Providers Master Object Axis Provider. Once added, define its properties:

Configure Table Configuration

Set the Table Configuration properties:

Viewpoints configuration

For this step, first of all, you have to create a new Viewpoints configuration, for example, called blocktableViewpoint.configuration.

Once a blocktableViewpoint.configuration has been created, you have to open it for setting the viewpoint. The basic sets for viewpoints are:

1. Add a Stakeholder and name;

2. Set the Papyrus Configuration with the Stakeholder in the Default Stakeholder field and http://www.eclipse.org/uml2/5.0.0/UML in the Metamodel field;

3. Load the resource: platform:plugin/org.eclipse.papyrus.infra.viewpoints.policy/builtin/default.configuration

4. Add a Papyrus Viewpoint, name BlockTable Viewpoint and set the Parent field with the value Default Papyrus Viewpoint;

5. Add a View Category and name blockTable;

6. Set the Stakeholder with the BlockTable Viewpoint in the Viewpoints field.

Now, you must to add one Papyrus Table in BlockTable Viewpoint and set its properties.

Very impotant: the name must be the same to defined in block.nattableconfiguration (see in the subsection Configure Table Configuration [[2]] ;

Under the BlockTble Viewpoint, add one Model Rule:

And add one Owning Rule:

Axis Manager Class

Create a new class BlockAxisManager. This class extends AbstractStereotypedElementUMLSynchronizedOnFeatureAxisManager<Block> and its role is synchronize with the model and get all Block elements directly associated with it.

Setting the Extensions Plug-in Setup

In this step you have to add two Extensions:

1. org.eclipse.papyrus.infra.nattable.axismanager

In this extension you need to add a new axisManager for linking BlockAxisManager class presented in the previously subsection (see in the subsetion Axis Manager Class [[3]]) with the Axis Manager Id defined in block.nattableconfiguration, the table configuration’s file previously done (see in the subsection Add one Axis Manager Representation [[4]]) .

2. org.eclipse.papyrus.infra.viewpoints.policy.custom

In this extension you need to add a new configuration and set with the viewpoint file (blockTableBiewpoint.configuration).

Result

Creating a new Block Table

You can create the Block Table directly under a model :

Synchronization between table and model

The illustration of the table sychronization when a block is added or removed:

After added Block2

Affter removed Block1

Contribute to menu with a new Papyrus Table (must be completed)

The contribution must be done using viewpoint with a file .configuration. The viewpoint metamodel provides 2 ways to register new tables. the first one used the Element Papyrus Sync Table. You must fill the field :

• categories
• Icon
• ImplementationID : the type of the table, with the same value than in the field type declared in the file .nattableConfiguration of your table
• Name : the name of the table

Then you can declare Rules to allow/forbid the creation of the table according to the selected element

The second way with viewpoint using Papyrus Table element In this case you must fill the field configuration with the path of your table configuration file.

Label Providers

For the label provider, we divided the tables into 2 areas :

1. Headers
   
2. Body
   

for each areas we declared a label provider context (using the Papyrus Label Provider extension point):

1. org.eclipse.papyrus.infra.nattable.full.labelprovider : the context to use to find the label provider used in the table. This one calls the others label providers according to the region for which we are looking for the text/image to display.
   
2. org.eclipse.papyrus.infra.nattable.body.labelprovider : the context to use to find the label provider used to get the text in the body of the table
   
3. org.eclipse.papyrus.infra.nattable.header.labelprovider : the context to use to find the label provider used to get the text in the header of the table (display icon, display label)
4. org.eclipse.papyrus.infra.nattable.header.feature.labelprovider : the context to use to find the label provider used to display feature in a header. This label provider allows to define the text to display according to the configuration of the axis ( display icon, display label, display multiciplicity, display type, display a "/" for the derived feature)

These contexts are declared into the plugin org.eclipse.papyrus.infra.nattable.

All label provider declared on these context must accept elements implementing ILabelProviderCellContextElement. This object encapsulate the cell for which we want display a text AND useful elements which can be used to define the text/image/color/... to display in the cell.

Papyrus Extension Point For Table :

1. Axis Manager
2. Cell Manager
3. Cell Editor Configuration

Selection synchronization

Some changes have been applied to the code in order to allow a selection synchronization between the tables and the model explorer. The affected classes are the following :
In these changes, IRevealSemanticElement and its associated method revealSemanticElement is at the core of the modifications.

1. org/eclipse/papyrus/infra/nattable/common/editor/AbstractEMFNattableEditor.java
   • where we implement the interface and add the call for the newly created revealSemanticElement method in AbstractNattableWidgetManager and giving it the list of selected objects.
     
2. org/eclipse/papyrus/infra/nattable/manager/table/AbstractNattableWidgetManager.java
   • the method goes through the lines and columns of the tables to find all the elements contained in the list and then proceed to select them graphically in the table.
   • the method used for this is org.eclipse.nebula.widgets.nattable.selection.SelectionLayer.doCommand(ILayerCommand command)
     
3. org/eclipse/papyrus/infra/gmfdiag/common/SynchronizableGmfDiagramEditor.java
   • in the original method the selection only allowed the first selected element found to show. we now collect all found IGraphicalEditParts and proceed to set the selection in the graphicalViewer.
     
4. org/eclipse/papyrus/views/modelexplorer/ModelExplorerView.java
   • in the handleSelectionChangedFromDiagramEditor method the principal problem was that, if revealSemanticElement was called, it shunned the model explorer as it was not an IEditPart and the redundacy of the IAdaptable verification crashed the process.
   • when we are in an IIeditorPart, as we were interested in the Eobject for the contruction of the list of selected elements and that org.eclipse.papyrus.infra.emf.utils.EMFHelper.getEObject(Object source) already checked for the IAdaptability, the direct replacement of the verification was done.
   • as for the selection in the model explorer, we went through org.eclipse.ui.navigator.LinkHelperService.getLinkHelpersFor(Object anObject) to get the list of LinkHelpers and used the LinkHelper in org.eclipse.papyrus.views.modelexplorer.LinkHelper.activateEditor(IWorkbenchPage aPage, IStructuredSelection aSelection) to handle the selection with revealSemantiElement.
     

Modifying the graphical representation of the tables

Resizing Axis and Headers

Three listeners have been added to the AbstractNattableWidgetManager class in order to capture the graphical changes and edit the model.

1. addAxisResizeListener(final BodyLayerStack bodyLayerStack) that listens to the BodyLayerStack
2. addColumnHeaderResizeListener(final ColumnHeaderLayerStack columnHeaderLayerStack) that listens to the ColumnHeaderLayerStack
3. addRowHeaderResizeListener(final RowHeaderLayerStack rowHeaderLayerStack) that listens to the RowHeaderLayerStack

Those methods verify the model in order to know if the graphical values are already present and if not create them and write them using a CompositeCommand and executing it.

The major change introduced in order to accomplish this is the modification of the table's model by adding new Styles, more particularly intValueStyles that are used to carry this specific information. These styles are introduced in the Axis elements, if the changes of size modify axis, or to a newly, or existing, LocalHeaderAxisConfiguration if the changes modify headers. Of course, both of them are now StyledElements and therefore can call on the method getNamedStyle().

• NamedStyle org.eclipse.papyrus.infra.nattable.model.nattable.nattablestyle.StyledElement.getNamedStyle(EClass eClass, String name)
  

Two init methods will also be called when refreshing or opening the table in order to show the modified table.

1. initTableAxis() that gets the list of the displayed axis and check their styles
2. initTableHeaders() that gets the AbstractHeaderAxisConfigurationUsedInTable, allowing the method to get around the invertAxis configuration, and check their styles

Both have a default behavior, in case no styles were attached to an element, to apply its default size to its graphical representation.

Merging cells inside their Axis

The merge is based on nebula's AutomaticSpanningDataProvider (org.eclipse.nebula.widgets.nattable.data.AutomaticSpanningDataProvider) allowing us to apply a spanProvider to the table's BodyLayerStack and, with minor modification of the method valuesNotEqual(), triggering the desired span (i.e. merge) throughout the layer. It is to be noted that the cells are merged using their values and not their types.
To accomplish this four new merge handlers were created, piloted by a menu constituted of exclusive choices.

1. org.eclipse.papyrus.infra.nattable.handler.MergeColumnsHandler
2. org.eclipse.papyrus.infra.nattable.handler.MergeRowsHandler
3. org.eclipse.papyrus.infra.nattable.handler.MergeSelectedRowsHandler
4. org.eclipse.papyrus.infra.nattable.handler.MergeSelectedColumnsHandler

The handlers' model modification behavior are similar to the resize listeners' one, where the style's value is researched in the model and created, or modified, depending on the case, set inside a CompositeCommand and executed inside the core AbstractMergeHandler. The merge boolean will then be carried by the LocalHeaderAxisConfiguration if the user chose to merge all the columns/rows inside the table or by the Axis if the user chose to merge only selected Axis.

To access these handlers, new extensions have been added in the form of a new menu to call on the handlers and a property tester to check the availability of the menu's options or not depending on the merge state of the table; and to update the toggles of each menu, new updateToggleCommandState() have also been added to NattableModelManager, calling on the getToggleState[...]() methods in AbstractNattableManager.
One init method and two Listeners, one for the resourceSet and another for the Layer, are used to update the graphical view throughout the changes.

1. initTableMerge() in wich the list of the displayed axis is obtained and their styles checked
2. resourceSetListener inside the updateCellMap() method in which the notifications due to the modification of the resourceSet are filtered to keep the styles we want to apply or unapply, depending on the user's choices, and enable the use of the undo/redo behavior

Editing merged cells

A PapyrusSpanningDataLayer has been added and @Overrides the setDataValue of nebula's org.eclipse.nebula.widgets.nattable.layer.SpanningDataLayer#setDataValue(int, int, java.lang.Object) to allow the edition of multiple cells inside a merged selection.
The edition will then verify if the value to be inputted can indeed be, see org.eclipse.papyrus.infra.nattable.manager.cell.AbstractCellManager.setValue(), and edit the cell accordingly. Of course, the merge selection is updated after this so that, inside a previuosly merged selection, only the cells of equal values are still merged.

Matrix

The Papyrus tabular editor should allow to the developper to create matrix, we doesn't really try to do that. Here, we give some points which should allow you to create matrix :

1. the column axis must manage object instead of manage features
2. you must declare a cell manager specific to your table to get and edit the values in the cell
3. you probably need to declare your own label provider
4. others things to do?
5. to conclude, don't forget to implements required methods to allow (or forbid) all features already supported by the table framework. The list of the supported feature is available here.