Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: for the plan.

Jump to: navigation, search

Papyrus for Information Modeling/Customization Guide

< Papyrus for Information Modeling
Revision as of 10:55, 29 June 2016 by (Talk | contribs) (Minor typos)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Papyrus Information Modeling is a Papyrus-based modeling product that is customized and streamlined for users interested in modeling the static structure of information with UML class diagrams.

This guide serves as an overview of the customizations that have been performed to provide an information modeling product based on Papyrus and Eclipse. In particular, this guide includes a description of the product definition with the specific product branding and the specification of the included main features, the customization of Papyrus to constrain the modeling capabilities to the UML subset needed for information modeling, the contributions to the Intro pages to support the user when the product is started, an example project to showcase the model capabilities, a tutorial to ease the learning curve, and overall UI simplifications to hide functionality that is not necessarily needed in information modeling.

Product Definition

An Eclipse- and Papyrus-based product is a stand-alone program built upon the Papyrus infrastructure which itself is based on the Eclipse platform. A product in general includes all the code and plugins needed to run it, including the JRE and the Eclipse platform code.

In Eclipse terms, a product is a unit of branding that is defined declaratively as an org.eclipse.core.runtime.products extension. A product always refers to an application class which is the actual program that is executed in an Eclipse plugin environment. A product configuration defines and manages all aspects of an Eclipse product. The creation of a valid product configuration file is supported by a [dedicated editor]. This configuration is a pure development-time artifact and is neither interpreted nor read by the runtime. However, we can use the product configuration to synchronize the information of the configuration with the respective product extension point and we can use the product configuration to build and deploy the final product.

Within the product configuration, we can specify the following aspects:

  • Overview: product name, ID, version, and application
  • Contents: Plug-ins or features that constitute the product
  • Configuration: Defining the config.ini properties file containing Eclipse runtime options
  • Launching: Name and Icon of the launcher, launching arguments (program and VM)
  • Splash: Application-specific splash screen that appears when the product is launched
  • Branding: Window Images, About Dialog and Welcome Page (Intro)
  • Customization: Default Eclipse preferences and CSS styling
  • Licensing: License URL and text
  • Updates: Repository locations for product updates

The Papyrus Information Modeling product is an Eclipse Rich Client Platform (RCP) application and re-uses the Eclipse IDE as application class, as specified in the product configuration file depicted below:

Using our product configuration, we can synchronize the information to the respective product definition extension point:

<extension id="product" point="org.eclipse.core.runtime.products">
         description="Papyrus Information Modeling..."
         name="Papyrus Information Modeling">
      <property name="appName" value="Papyrus Information Modeling" />
      <property name="introTitle" value="Welcome to Papyrus Information Modeling" />
      <property name="preferenceCustomization" value="plugin_customization.ini" />

Besides several specific branding options, we specify that the following main components should be included in our product:

  • Papyrus as modeling infrastructure
  • EGit to enable Git version control
  • EMF Compare to support collaborative information modeling

Another important aspect of the product configuration is the customization of the default Eclipse preferences. These preferences are used throughout the customization process to ensure that the product starts with the best options for information modeling. The preferences are given in a properties file, which allows the specification of preferences as simple key-value pairs. For information modeling, we define the default perspective and the default collaborative modeling preferences among others:

# perspective that the workbench opens initially

# new-style tabs by default

# put the perspective switcher on the top right

# show progress on startup

# Configure collaborative modeling preferences
org.eclipse.egit.core/core_preferredMergeStrategy=model recursive

Using the product definition and configuration, we can already deploy our product. However, at this point, we get a normal Eclipse IDE application with a customized UI and some pre-defined preferences. The actual streamlining for information modeling is done by customizing, restricting, and extending the included main components. This includes adapting the Papyrus modeling environment, contributing to the Intro, providing examples and tutorials, and simplifying the UI to focus on information modeling-specific capabilities.

Papyrus Customization

Papyrus is an industrial-grade open source Model-Based Engineering tool implementing many standards such as UML 2.5.0, SysML 1.1 and 1.4, OCL 2.3.1, fUML 1.1 and ALF 1.0.1. To enable domain-specific modeling, every part of Papyrus such as the model explorer, the palette, the creation menus, the properties views, and the diagram notation and style may be customized.

In order to support Information Modeling as a specific domain, we therefore adapt different aspects of Papyrus. Most of these adaptations are restrictions on the original functionality of Papyrus, as the core idea of Information Modeling is the focus on a specific subset of UML. The defined UML subset covers the structural parts of UML class diagrams, supports the specification of instances, and allows the creation and application of UML profiles. Other available diagrams, such as Activity Diagrams or Sequence Diagrams, are not needed and should be hidden from the user.

Information Modeling Viewpoint

In Papyrus, viewpoints enable the specialization and customization of the user experience by constraining what can be seen and interacted with in Papyrus diagrams and tables. A viewpoint configuration is the root configuration element containing the specification of stakeholders, viewpoints, and view categories. A stakeholder represents an archetype of users that can be attributed to viewpoints and thus defines what users of this kind can see. A viewpoint is a set of views, which can be either a diagram view or table view. A view category determines how to categorize a specific view, for instance, as UML or as SysML.

The application of a viewpoint has an impact on the available diagrams in the diagram selection window of the New Model wizard and on the available diagrams and tables of the New Diagram and New Table contextual menus and toolbar elements.

To support information modeling as a domain, we create our own viewpoint with an information modeler as stakeholder and a customized UML class diagram view in the UML category. In order to deploy our viewpoint configuration, we need to register an org.eclipse.papyrus.infra.viewpoints.policy.custom extension with the configuration file and a given priority:

<extension point="org.eclipse.papyrus.infra.viewpoints.policy.custom">
         priority="30" />

The priority of a configuration is a value between 0 and 100 and manages the ordering of the configurations in the preference dialog when the user wants to select a different viewpoint.

In general, users are free to select any viewpoint that is provided to them. Papyrus itself already comes with a default viewpoint that is automatically selected when no other viewpoint is specified. In order to pre-select our Information Modeling viewpoint, we therefore need to set the respective preference in the product preferences.

org.eclipse.papyrus.infra.viewpoints.policy/papyrusViewpointsSelectedStakeholder=Information Modeler
org.eclipse.papyrus.infra.viewpoints.policy/papyrusViewpointsSelectedViewpoint=Information Modeling Viewpoint
UML Class Diagram

In Information Modeling, the view that is needed is a streamlined UML class diagram. Specifically, the class diagram needs to support the structural parts of UML class diagrams, the creation of instances, and the definition and application of UML profiles. The configuration of the information modeling viewpoint is depicted below:

The streamlined UML class diagram is assigned to the UML category and we base our implementation on the physical (hard-coded) UML class diagram in Papyrus (PapyrusUMLClassDiagram). In addition, we provide an optional custom style sheet that is automatically applied to our UML class diagrams.

Palette Elements: Before and After
Modeling Assistants: Before and After

Using the Papyrus UML class diagram as base, we need to constrain the elements available in the diagram to conform to our UML subset. In Papyrus, these constraints can be expressed as configuration rules. Each rule enables us to allow or deny certain behavior.

Model rules
constrain the type of the model elements that can be visualized through the class diagram. In Information Modeling, we allow the visualization of UML Package elements, i.e., packages, models, and profiles.
Owning rules
constrain the type of the model elements that can own the diagram itself. The owner is indicated as the element under which the diagram can be added in the Model Explorer. In Information Modeling, we match this behavior with the elements that can be visualized, i.e., we only allow packages to be owners.
Child rules
constrain the type of the model elements that can be dropped within the diagram from the Model Explorer. In Information Modeling, we allow all modeled elements to be dropped into our class diagram.
Palette rules
constrain the display of the diagram's palette elements. The palette is an area typcially shown at the right side of the editor and contains tools that allow the creation of new elements in the diagram. Palette elements are identified via their element id. In Information Modeling, we only display tools that allow the creation of elements that are part our UML subset. For instance, we allow the palette element clazz.tool.class to support the creation of UML classes.
Assistant rules
constraint the display of modeling assistants in the diagram editor. Modeling assistants are popup menus that are displayed when a user hovers with the mouse over an element in the diagram to support the creation of related elements, for instance, a property within a class. The elements in the menu are identified via their element type id. In Information Modeling, we only support the creation of elements that are part of our UML subset. For instance, we allow the element type with id org.eclipse.papyrus.umldi.Class_Shape to support the creation of UML classes.

Using these rules in the viewpoint configuration, we can customize Papyrus to a certain degree. Nevertheless, there are still aspects that can not be customized through the configuration model, such as the Creation Menus and the Properties View.

Creation Menu

Creation Menu: Before and After

The Creation Menu is part of the context menu that is displayed in the Model Explorer. Among others, this context menu contains menu entries that allow the creation of model elements. In Papyrus, these menu entries can be modeled through so called creationmenumodels whereas each model corresponds to one menu entry in the context menu.

In order to provide menu items for the Information Modeling UML subset, we therefore create two new models that allow the creation of new child elements (New Child) such as UML classes and properties and that allow the creation of new edges (New Relationship) such as associations or generalizations. The definition of the New Child creation menu is depicted below.

In this definition, we specify that the main menu entry is called New Child and should include sub-menu entries for the creation of classes, comments, etc.

In order to integrate our menus into the context menu of the Model Explorer, we need to register them using the org.eclipse.papyrus.infra.newchild extension point.

<extension point="org.eclipse.papyrus.infra.newchild">
   <menuCreationModel model="resource/newchild/IMNewChild.creationmenumodel" />
   <menuCreationModel model="resource/newchild/IMNewEdge.creationmenumodel" />

Please note that it is currently only possible to add new menu entries through the extension point. As in Information Modeling, we do not actually want to add domain-specific entries to the UML model set like in SysML, but we want to restrict the initial set to a subset that is needed in information modeling, we need to remove the existing menu entries with the same name. This is done using the respective API in the Activator.

Properties View

In UML, the main information is represented in graphical diagrams. However, it is not always possible to represent the whole semantic of a UML element graphically. As a result, we often need a different view for representing all the properties of a UML Element, without polluting the graphical view.

This view is the Properties view. It is used to show and manipulate the properties of the currently selected UML element. By default, Papyrus shows all element properties as defined in the UML standard. However, many of these properties are not necessary in the context of information modeling, for instance, the list of owned operations of a class which will always be empty as we do need behavior specification. We therefore customize the Properties view to fit to our UML subset and hide properties that are not necessary.

In Papyrus, the configuration of the properties view can be done using a dedicated context model. This context model describes tabs, views associated with the selected element, and a section as part of a view associated with a specific tab. The section contains the actual representation of the element as a widget and a layout. A widget may be a composite widget, a standard widget from the SWT library, or a property editor widget to allow the modification of certain properties. Constraints on a view ensure that the view is only displayed when a specific element is selected, for instance, a single UML class element.

In Information Modeling, we define our own context model and remove unnecessary properties from the views. The specification of the tabs and views in the context model editor is depicted below:

Properties View: Before and After

It should be noted that several property views can be active at any given time, showing the union of all tabs in the view. For instance, Papyrus automatically activates the property views for UML elements, the graphical notation, and the diagram styles. A user may choose to activate or deactivate any provided property views through the Preference dialog.

In order to make our Information Modeling Property view available to the user, we need to register it using the extension point.

      name="UML Subset for Information Modeling"
   <context appliedByDefault="true" contextModel="resource/context/IM-UML.ctx" isCustomizable="true" />

Our extension point is applied by default and may be used as base to perform further customization by the user. As with the creation menu entries, it is currently not possible to deactivate existing property views. However, since we provide a filtered version of the standard UML property view, we need to deactivate this view programmatically. This is done using the respective API in the Activator.


The UML specification provides a few hints to represent graphical elements and only focuses on the general representation of these elements. For instance, it is specified that a class should be depicted as a rectangle. However, we are free to choose the color and border of this rectangle. Therefore, Papyrus offers several ways to provide custom styling of model elements using Cascading StyleSheets (CSS):

Information Modeling CSS Style
  • Elements can be styled directly via the 'Appearance' tab in the properties view.
  • Models can be styled directly via a model style sheet in the 'Style' tab in the properties view of the root element.
  • Diagrams of a certain type can be styled via diagram stylesheets defined in the viewpoint configuration of the diagram.
  • Diagrams in a project can be styled via project stylesheets defined in the Project properties.
  • The general appearance of diagram elements can be defined product-wide through a CSS theme.

Please note that often several stylesheets are applied at the same time. In such a case, the style closer to the element overrides a previously defined style, for instance, a model style sheet may override a style defined in a theme.

In Papyrus Information Modeling, we provide a dedicated style for all our UML class diagrams and additionally provide our style as a theme. An excerpt of the Information Modelign CSS is shown below:

/* light-blue background and slightly darker border color */
AssociationClass, Class, DataType, Enumeration {
   fillColor: #EDFBFF;
   lineColor: #109DC4;

/* hide compartments by default */
AssociationClass > Compartment, Class > Compartment, DataType > Compartment {
   visible: false;

/* show attribute compartment without title */
AssociationClass > Compartment[kind="attributes"], Class > Compartment[kind="attributes"], DataType > Compartment[kind="attributes"] {
   visible: true;
   showTitle: false;

/* show name, type and multiplicity of properties in the compartment */
Property {
   maskLabel: name type multiplicity;

In order to deploy our theme within Papyrus, we need to register a new theme and contribute our CSS file to this theme using the org.eclipse.papyrus.infra.gmfdiag.css.theme extension point:

<extension point="org.eclipse.papyrus.infra.gmfdiag.css.theme">
         label="Information Modeling" />
   <themeContribution id="org.eclipse.papyrus.information.modeling.core.css.im_theme">
      <stylesheet stylesheetPath="resource/style/im_style.css" />

Using this extension, our theme will show up with the provided name in the Eclipse Preferences. To select our theme by default, we need to set the option in the product preference file:


Intro Contribution

Besides customizing different aspects that relate directly to the modeling aspect of our product, we also want to provide user assistance through the standard Eclipse platform, such as the Intro. The Welcome or Intro pages are the very first content a user sees when launching the product for the first time. The idea of these pages is to guide the user into discovering the product's functionality. The intro content can be either implemented from scratch or integrated into the Universal Intro offered by Eclipse.

The Universal Intro provides a standardized set of pages and page anchors that can be populated using intro config extensions. Furthermore, the Universal Intro comes with a set of Intro themes to control the layout of the provided page content.

In order to use the Universal Intro, we need to bind it to our product in the product configuration and in a org.eclipse.ui.intro extension point:

<extension point="org.eclipse.ui.intro">
         productId="org.eclipse.papyrus.information.modeling.rcp.product" />

The Universal Intro provides the following, standardized pages to which content can be contributed. An initial root page automatically provides links to these pages on startup.

  • Overview: Overview of features provided by the product
  • Tutorials: Step-by-step guides for specific tasks
  • Samples: Example projects ready to be imported into the workspace
  • What's New: Links to recent news and changes
  • First Steps: Resources for initial steps to start working with the product
  • Web Resources: Links to further resources on the web
  • Migrate: Resources to guide the migration to new releases

To ensure that the intro is shown at the first startup, we need to add preferences to the product preferences.


In Papyrus Information Modeling, we additionally configure the Universal Intro to only use the Overview, the Tutorials, and the Samples page.

Extending Page Content

The standard pages of the Universal Intro can be populated with content provided through intro config extensions (extension point: org.eclipse.ui.intro.configExtension). Such an extension connects a configurer class which can customize specific parts of a page with the provided content:

<extension point="org.eclipse.ui.intro.configExtension">
         content="extensions/samplesExtensionContent.xml" />

The id org.eclipse.ui.intro.universalConfig refers to the universal intro configurer that provides dynamic configuration of the shared intro implementation based on a data file associated with the product. The content links to a file that provides the actual data that should be added to a specific page.

The example below shows one content extension we contribute in Papyrus Information Modeling. The page to which the content should be added is specified using a partial target path, i.e., samples/@. The remaining part of the path that completes the exact position, is given in the layout data file, for instance, page-content/top-left.

<?xml version="1.0" encoding="UTF-8" ?>
         name="Information Modeling Tutorials"
         alt-style="css/" style="css/samples.css"
      <group label="Information Modeling" id="org.eclipse.papyrus.information.modeling.intro.tutorial-group" style-id="content-group">
         <text style-id="group-description">The following samples demonstrate the capabilities and features of Papyrus Information Modeling.</text>
         <link label="Project Management Example" id="im-sample-project-management" style-id="content-link"
            <text>This Project Management example uses the most common elements...</text>

Besides linking to web pages, link elements in the config extension can be used to execute intro actions. When calling an action, the url needs to conform to the IntroURL format that starts with runAction and has at least two parameters: the id of the plugin that contains the action class and the qualified name of the class that implements the IIntroAction interface. Any further parameters are passed to the respective action. In Papyrus Information Modeling, we implemented a dedicated ShowWizardAction to enable users to call the example wizard from the samples page.


The universal intro configurer enables us to control the layout of the pages through a specific data file associated with our product. In this data file, we can specify how the extensions should be added to the pages, i.e., at what position, and whether the extension should be highlighted based on its importance.

An excerpt of the intro layout data used in Papyrus Information Modeling is shown below:

   <page id="samples">
      <group path="page-content/top-left">
         <extension id="org.eclipse.papyrus.information.modeling.intro.samples" importance="high" />
         <extension id="org.eclipse.jdt" importance="low" />
Highlighted Sample Contribution in Intro

In this excerpt, we specify that we want to add our samples extension to the top left corner of the samples page. The extension is marked with high importance to additionally highlight the content on the page. How the content is highlighted is managed by the theme of the intro and style used by the respective page. For instance, in the Solstice theme we use, high importance is shown with a blue gradient background.

Furthermore, we can use the layout data file to specify which intro extensions should be hidden by default. In Information Modeling, we hide the JDT extension as it is not within the focus of our product.

The default layout data file and the intro theme can be configured using the product customization:


Example Project

Example Installer Wizard

An example project allows the user to import an existing, already pre-defined example into the workspace to discover how certain functionality aspects may be used.

In Eclipse, we can use the ExampleInstallerWizard for realize this functionality. This wizard simply copies or unzips a number of files and directories into the workspace and creates the necessary projects to hold them. The wizard can be declared directly using the org.eclipse.ui.newWizards extension point. The content that should be copied into the workspace needs to be declared as an example with the org.eclipse.emf.common.ui.examples extension point.

In Information Modeling, we use this mechanism to provide a Project Management Example model which covers most elements available in the Information Modeling UML subset. The wizard and the example are defined in the plugin.xml of the examples project:

<extension point="org.eclipse.emf.common.ui.examples">
            description="This project contains an example model for project management."
            name="ProjectManagement" />
      <fileToOpen location="ProjectManagement/ProjectManagement.di" />

In the excerpt above, we refer to a typical new wizard extension based on the ExampleInstallerWizard. The Project Management models are stored in the ProjectManagement directory of the plugin are copied into a newly created project in the workspace when the wizard is executed. After the wizard has finished, we automatically open the ProjectManagement.di diagram file in the default editor.


Even when we filter out unneeded functionality from the UI, there is still a steep learning curve faced by a new user. Tutorials can be used to help users to get to know the functionality of a product in a step-by-step manner.

In Eclipse, cheat sheets can be used to realize tutorials and guide a user through a series of steps. In order to provide a cheat sheet, we need to create an XML content file and register the cheat sheet in an extension point. The XML content file contains the information that will be presented to the user and consists of a short introduction and a series of steps called items. At its simplest, an item is just a detailed description of the step that the user should take. However, an item can also specify an action that can be run to perform the step automatically on behalf of the user.

In Papyrus Information Modeling, we provide a 'Getting Started' tutorial that introduces the basic user interface and demonstrates how to create a project with a UML class diagram. A figure of the steps defined in the Cheat Sheet Editor and the resulting cheat sheet is depicted below.

The registration is performed in an extension described in the plugin.xml:

<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent">
   <category id="org.eclipse.papyrus.information.modeling.intro.category.papyrus" name="Papyrus" />
         name="Getting Started" />

Please note that the $nl$ variable in the directory name means that the file will be located in a directory specific to the national language of the target environment. This allows for language-specific customization of the cheat sheet. If no such directory is found, the cheat sheet without language-specific customization is used.

UI Simplifications

Besides customizing the modeling environment and providing assistance to the user, the UI is still cluttered with functionality that is not needed for information modeling. The easiest way to get rid of unwanted UI elements is to not include their provided functionality in the first place. However, sometimes you need to include such plugins in your product as other features that you do need depend on them. As a result, we need to specifically target the unwanted UI contributions and remove them through activities, perspective extensions, or when loading our product.

Activities and Capabilities

Activities are logical groupings of functionality and can be used to declutter UI elements pertaining to such a functionality. When a certain activity is disabled, all UI contributions associated with that activity are hidden. In Eclipse, there are two types of activities:

  • Conventional activities hide functionality, but allow the user to show the functionality in certain dialogs or in the preferences under the name Capabilities.
  • Expression-based activites hide UI contributions permanently from the user and the API based on certain an expressions, e.g., evaluating access rights.

Activities can be declared as extensions (org.eclipse.ui.activities) and are associated with UI contributions using activity pattern bindings. These bindings can refer to UI contributions via id or through pattern matching and need to conform to the format plug-in-identifier + "/" + local-identifier. Any matching UI contributions will be hidden unless the activity is enabled by default. Specifically, the bindings affect the views and editors, the perspectives, the preference and property pages, the menus and toolbars, the new wizards, and the Common Navigator Action Providers.

For instance, to remove the UI contributions of Ant, we use the following activity and activity pattern binding:

<extension point="org.eclipse.ui.activities">
         name="Hide Ant Functionality" />
         pattern="org\.eclipse\.ant\.ui\/.*" />

This pattern hides all UI elements that are contributed by the plugin org.eclipse.ant.ui. Please note that in a Regex pattern dots ('.') and forward slashes ('/') need to be escaped with a backslash ('\') to use them as normal characters and that '.*' matches any character any number of times, so all local identifiers will match. To ensure that the pattern is interpreted as a regular expression and not as a given ID, we set the isEqualityPattern to false.

In Papyrus Information Modeling, we use activities and their related patterns to hide the following functionality by default:

Perspectives: Before and After
  • Plugin Development (PDE)
  • Java Development Tools (JDT) and Debugging
  • Xtend/Xbase/Xtext
  • Ant
  • Equinox P2
  • External Tools
  • Selected Papyrus Functionality
  • Selected EMF and OCL Functionality

Perspective Extensions

In Eclipse, a perspective defines the content, views, and layout of a workbench. Perspective extensions, on the other hand, can be used to extend perspectives registered by other plugins. A perspective extension may refer to a specific perspective or all perspectives (extension point: org.eclipse.ui.perspectiveExtensions) and enables us to hide menus and toolbar items, provide perspective and wizard shortcuts, and define views.

In Papyrus Information Modeling, we use this mechanism to hide the 'Run' menu item in all perspectives:

<extension point="org.eclipse.ui.perspectiveExtensions">
   <perspectiveExtension targetID="*">
      <hiddenMenuItem id="" />

Another perspective extension we use is to hide certain Papyrus items from the toolbar in the Papyrus perspective.


In situations where the UI contributions of certain plugins cannot be hidden through activities or perspective extensions, the only option is to adapt the UI programmatically. As such, the best place to perform these adaptations is the Activator of a UI plugin. An activator is a Java class that controls a plugin's life cycle and is called as soon as the plugin is loaded. By placing the UI adaptation in a UI Plugin, we can ensure that at the time the plugin is loaded, we have access to the preferences, dialogs and images.

In Papyrus Information Modeling, we use the Activator of our simplification plugin to perform the following tasks:

Back to the top