View source for Papyrus for Information Modeling/Customization Guide

''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|product definition]] with the specific product branding and the specification of the included main features, the [[#Papyrus Customization|customization of Papyrus]] to constrain the modeling capabilities to the UML subset needed for information modeling, the [[#Intro Contribution|contributions to the Intro pages]] to support the user when the product is started, an [[#Example|example project]] to showcase the model capabilities, a [[#Tutorial|tutorial]] to ease the learning curve, and overall [[#UI Simplifications|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 [http://help.eclipse.org/neon/topic/org.eclipse.pde.doc.user/concepts/product.htm 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 <code>org.eclipse.core.runtime.products</code> 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 [[http://help.eclipse.org/neon/topic/org.eclipse.pde.doc.user/guide/tools/editors/product_editor/editor.htm 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 [http://help.eclipse.org/neon/topic/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html 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 Contribution|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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/releng/org.eclipse.papyrus.information.modeling.product/papyrusInformationModeling.product product configuration file] depicted below:

<div style="text-align: center">
  <gallery mode="nolines" widths="620px" heights="250px">
    File:Papyrus_for_Information_Modeling_ProductDefinition_Configuration.png|''Custom Product Configuration''
  </gallery>
</div>

Using our product configuration, we can synchronize the information to the respective [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/releng/org.eclipse.papyrus.information.modeling.rcp/plugin.xml#n18 product definition] extension point:
 <extension id="product" point="org.eclipse.core.runtime.products">
    <product
          application="org.eclipse.ui.ide.workbench"
          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" />
       ...
    </product>
 </extension>

Besides several specific branding options, we specify that the following main components should be included in our product:
* [https://eclipse.org/papyrus/ Papyrus] as modeling infrastructure
* [https://www.eclipse.org/egit/ EGit] to enable Git version control
* [https://www.eclipse.org/emf/compare/ 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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/releng/org.eclipse.papyrus.information.modeling.rcp/plugin_customization.ini 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
 org.eclipse.ui/defaultPerspectiveId=org.eclipse.papyrus.infra.core.perspective
 
 # new-style tabs by default
 org.eclipse.ui/SHOW_TRADITIONAL_STYLE_TABS=false
 
 # put the perspective switcher on the top right
 org.eclipse.ui/DOCK_PERSPECTIVE_BAR=topRight
 
 # show progress on startup
 org.eclipse.ui/SHOW_PROGRESS_ON_STARTUP=true
 
 # Configure collaborative modeling preferences
 org.eclipse.emf.compare.ide.ui/org.eclipse.emf.compare.ide.ui.preference.resolutionScope=WORKSPACE
 org.eclipse.egit.ui/enable_logical_model=true
 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 Customization|Papyrus modeling environment]], contributing to the [[#Intro Contribution|Intro]], providing [[#Example Project|examples]] and [[#Tutorial|tutorials]], and [[#UI Simplifications|simplifying the UI]] to focus on information modeling-specific capabilities.

=== Papyrus Customization ===
[https://eclipse.org/papyrus/ Papyrus] is an industrial-grade open source Model-Based Engineering tool implementing many standards such as [http://www.omg.org/spec/UML/ UML 2.5.0], [http://www.omg.org/spec/SysML/ SysML 1.1 and 1.4], [http://www.omg.org/spec/OCL/ OCL 2.3.1], [http://www.omg.org/spec/FUML/ fUML 1.1] and [http://www.omg.org/spec/ALF/ 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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.core/resource/configuration/InformationModeling.configuration viewpoint configuration], we need to register an <code>org.eclipse.papyrus.infra.viewpoints.policy.custom</code> extension with the configuration file and a given priority:
 <extension point="org.eclipse.papyrus.infra.viewpoints.policy.custom">
    <configuration
          file="resource/configuration/InformationModeling.configuration"
          priority="30" />
 </extension>
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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/releng/org.eclipse.papyrus.information.modeling.rcp/plugin_customization.ini#n22 product preferences].
 org.eclipse.papyrus.infra.viewpoints.policy/papyrusViewpointsConfigurationType=extension
 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:

<div style="text-align: center">
<gallery mode="nolines" widths="620px" heights="250px">
File:Papyrus_for_Information_Modeling_PapyrusCustomizations_UMLClassDiagram.png|''Viewpoint and Class Diagram Configuration''
</gallery>
</div>

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 (<code>PapyrusUMLClassDiagram</code>).
In addition, we provide an optional [[#Styling|custom style sheet]] that is automatically applied to our UML class diagrams.

[[File:Papyrus_for_Information_Modeling_PapyrusCustomization_PaletteUI.png|thumb|250px|<div style="text-align:center; margin-bottom: 15px">''Palette Elements: Before and After''</div>]]
[[File:Papyrus_for_Information_Modeling_PapyrusCustomization_ModelingAssistantsUI.png|thumb|250px|<div style="text-align:center">''Modeling Assistants: Before and After''</div>]]
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 <code>clazz.tool.class</code> 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 <code>org.eclipse.papyrus.umldi.Class_Shape</code> 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 Menu|Creation Menus]] and the [[#Properties View|Properties View]].
<br clear=all>
==== Creation Menu ====
[[File:Papyrus_for_Information_Modeling_PapyrusCustomization_CreationMenuUI.png|thumb|250px|<div style="text-align:center">''Creation Menu: Before and After''</div>]]
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 <code>creationmenumodels</code> 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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.core/resource/newchild/IMNewChild.creationmenumodel creation of new child elements] (''New Child'') such as UML classes and properties and that allow the [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.core/resource/newchild/IMNewEdge.creationmenumodel creation of new edges] (''New Relationship'') such as associations or generalizations.
The definition of the ''New Child'' creation menu is depicted below.

<div style="text-align: center">
<gallery mode="nolines" widths="620px" heights="250px">
File:Papyrus_for_Information_Modeling_PapyrusCustomization_CreationMenu.png|''Creation Menu Modeling''
</gallery>
</div>

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 <code>org.eclipse.papyrus.infra.newchild</code> extension point.
 <extension point="org.eclipse.papyrus.infra.newchild">
    <menuCreationModel model="resource/newchild/IMNewChild.creationmenumodel" />
    <menuCreationModel model="resource/newchild/IMNewEdge.creationmenumodel" />
 </extension>

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|Activator]].
<br clear=all>
==== 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 [https://www.eclipse.org/swt/ 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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.core/resource/context/IM-UML.ctx 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:

[[File:Papyrus_for_Information_Modeling_PapyrusCustomization_PropertiesViewUI.png|thumb|250px|<div style="text-align:center">''Properties View: Before and After''</div>]]
<div style="text-align: center">
<gallery mode="nolines" widths="620px" heights="250px">
File:Papyrus_for_Information_Modeling_PapyrusCustomization_PropertiesView.png|''Properties View Modeling''
</gallery>
</div>

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 <code>org.eclipse.papyrus.infra.properties.contexts</code> extension point.
 <extension
       name="UML Subset for Information Modeling"
       point="org.eclipse.papyrus.infra.properties.contexts">
    <context appliedByDefault="true" contextModel="resource/context/IM-UML.ctx" isCustomizable="true" />
 </extension>

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|Activator]].
<br clear=all>
==== Styling ====
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 [https://wiki.eclipse.org/MDT/Papyrus/UserGuide/CSS Cascading StyleSheets (CSS)]:
[[File:Papyrus_for_Information_Modeling_PapyrusCustomization_StyleExample.png|thumb|250px|<div style="text-align:center">''Information Modeling CSS Style''</div>]]
* 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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.core/resource/style/im_style.css 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 <code>org.eclipse.papyrus.infra.gmfdiag.css.theme</code> extension point:
 <extension point="org.eclipse.papyrus.infra.gmfdiag.css.theme">
    <themeDefinition
          icon="icons/papyrus.png"
          id="org.eclipse.papyrus.information.modeling.core.css.im_theme"
          label="Information Modeling" />
    <themeContribution id="org.eclipse.papyrus.information.modeling.core.css.im_theme">
       <stylesheet stylesheetPath="resource/style/im_style.css" />
    </themeContribution>
 </extension>

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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/releng/org.eclipse.papyrus.information.modeling.rcp/plugin_customization.ini#n28 product preference file]:
 org.eclipse.papyrus.infra.gmfdiag.css/currentTheme=org.eclipse.papyrus.information.modeling.core.css.im_theme

=== 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 [http://help.eclipse.org/neon/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/ua_intro.htm 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 [http://help.eclipse.org/neon/topic/org.eclipse.platform.doc.isv/guide/ua_intro_universal.htm 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 <code>org.eclipse.ui.intro</code> extension point:
 <extension point="org.eclipse.ui.intro">
    <introProductBinding
          introId="org.eclipse.ui.intro.universal"
          productId="org.eclipse.papyrus.information.modeling.rcp.product" />
 </extension>

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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/releng/org.eclipse.papyrus.information.modeling.rcp/plugin_customization.ini#n37 product preferences].
 org.eclipse.ui/showIntro=true
 org.eclipse.ui.intro.universal/INTRO_ROOT_PAGES=overview,tutorials,samples

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: <code>org.eclipse.ui.intro.configExtension</code>).
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">
    <configExtension
          configId="org.eclipse.ui.intro.universalConfig"
          content="extensions/samplesExtensionContent.xml" />
 </extension>

The id <code>org.eclipse.ui.intro.universalConfig</code> refers to the universal intro configurer that provides dynamic configuration of the shared intro implementation based on a [[#Layout|data file]] associated with the product. 
The <code>content</code> 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., <code>samples/@</code>.
The remaining part of the path that completes the exact position, is given in the [[#Layout|layout data file]], for instance, <code>page-content/top-left</code>.
 <?xml version="1.0" encoding="UTF-8" ?>
 <introContent>
    <extensionContent 
          id="org.eclipse.papyrus.information.modeling.intro.samples"
          name="Information Modeling Tutorials"
          alt-style="css/samples.properties" style="css/samples.css"
          path="samples/@">
       <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"
  	            url="<nowiki>http://org.eclipse.ui.intro/runAction?pluginId=org.eclipse.papyrus.information.modeling.intro</nowiki>
  	    	    &amp;amp;class=org.eclipse.papyrus.information.modeling.intro.internal.action.ShowWizardAction
  	    	    &amp;amp;id=org.eclipse.papyrus.information.modeling.examples.wizard.projectmanagement">
             <text>This Project Management example uses the most common elements...</text>
          </link>
       </group>
    </extensionContent>
 </introContent>

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 <tt>IntroURL</tt> format that starts with <code>runAction</code> 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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.intro/src/org/eclipse/papyrus/information/modeling/intro/internal/action/ShowWizardAction.java ShowWizardAction] to enable users to call the example wizard from the samples page.

==== Layout ====
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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/releng/org.eclipse.papyrus.information.modeling.rcp/welcome/introData.xml intro layout data] used in Papyrus Information Modeling is shown below:
 <extensions>
    <page id="samples">
       <group path="page-content/top-left">
          <extension id="org.eclipse.papyrus.information.modeling.intro.samples" importance="high" />
       </group>
       <hidden>
          <extension id="org.eclipse.jdt" importance="low" />
       </hidden>
    </page>
 </extensions>

[[File:Papyrus_for_Information_Modeling_Intro_SamplesContributionUI.png|thumb|250px|<div style="text-align:center">''Highlighted Sample Contribution in Intro''</div>]]
In this excerpt, we specify that we want to add our samples extension to the top left corner of the <code>samples</code> page. 
The extension is marked with <code>high</code> 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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/releng/org.eclipse.papyrus.information.modeling.rcp/plugin_customization.ini#n43 product customization]:
 org.eclipse.ui.intro.universal/INTRO_DATA=product:welcome/introData.xml
 org.eclipse.ui.intro/INTRO_THEME=org.eclipse.ui.intro.universal.solstice

=== Example Project ===
[[File:Papyrus_for_Information_Modeling_Example_WizardUI.png|thumb|250px|<div style="text-align:center">''Example Installer Wizard''</div>]]
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 <tt>ExampleInstallerWizard</tt> 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 <code>org.eclipse.ui.newWizards</code> extension point.
The content that should be copied into the workspace needs to be declared as an example with the <code>org.eclipse.emf.common.ui.examples</code> 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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.intro/plugin.xml plugin.xml of the examples project]:
 <extension point="org.eclipse.emf.common.ui.examples">
    <example
          id="org.eclipse.papyrus.information.modeling.examples.projectmanagement"
          pageImage="icons/PapyrusLogo_48x48.png"
          wizardID="org.eclipse.papyrus.information.modeling.examples.wizard.projectmanagement">
       <projectDescriptor
             contentURI="ProjectManagement/"
             description="This project contains an example model for project management."
             name="ProjectManagement" />
       <fileToOpen location="ProjectManagement/ProjectManagement.di" />
    </example>
 </extension>

In the excerpt above, we refer to a typical [http://help.eclipse.org/neon/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/dialogs_wizards_newWizards.htm new wizard] extension based on the ExampleInstallerWizard.
The Project Management models are stored in the <code>ProjectManagement</code> 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 <code>ProjectManagement.di</code> diagram file in the default editor.

=== Tutorial ===
Even when we [[#UI Simplifications|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, [http://help.eclipse.org/neon/topic/org.eclipse.platform.doc.isv/guide/ua_cheatsheet.htm 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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.intro/cheatsheet/getting_started.xml '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.

<div style="text-align: center">
<gallery mode="nolines" widths="620px" heights="250px">
File:Papyrus_for_Information_Modeling_Tutorial_GettingStarted.png|''Getting Started Tutorial''
</gallery>
</div>

The registration is performed in an extension described in the  [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.intro/plugin.xml#n45 plugin.xml]:
 <extension point="org.eclipse.ui.cheatsheets.cheatSheetContent">
    <category id="org.eclipse.papyrus.information.modeling.intro.category.papyrus" name="Papyrus" />
    <cheatsheet
          category="org.eclipse.papyrus.information.modeling.intro.category.papyrus"
          contentFile="$nl$/cheatsheet/getting_started.xml"
          id="org.eclipse.papyrus.information.modeling.intro.cheatsheet.GettingStarted"
          name="Getting Started" />
 </extension>

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 and Capabilities|activities]], [[#Perspective Extensions|perspective extensions]], or [[#Activator|when loading our product]].

==== Activities and Capabilities ====
[http://help.eclipse.org/neon/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/workbench_advext_activities.htm 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 (<code>org.eclipse.ui.activities</code>) 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 <code>plug-in-identifier + "/" + local-identifier</code>.
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 [https://www.eclipse.org/eclipse/ant/ Ant], we use the following activity and activity pattern binding:
 <extension point="org.eclipse.ui.activities">
    <activity
          id="org.eclipse.papyrus.information.modeling.simplifiedui.hideAnt"
          name="Hide Ant Functionality" />
    <activityPatternBinding
          activityId="org.eclipse.papyrus.information.modeling.simplifiedui.hideAnt"
          isEqualityPattern="false"
          pattern="org\.eclipse\.ant\.ui\/.*" />
 </extension>

This pattern hides all UI elements that are contributed by the plugin <code>org.eclipse.ant.ui</code>. 
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 <code>isEqualityPattern</code> to false.

In Papyrus Information Modeling, we use [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.simplifiedui/plugin.xml activities and their related patterns] to hide the following functionality by default:
[[File:Papyrus_for_Information_Modeling_UISimplification_PerspectiveUI.png|thumb|250px|<div style="text-align:center">''Perspectives: Before and After''</div>]]
* 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 [http://help.eclipse.org/neon/index.jsp?topic=/org.eclipse.platform.doc.user/concepts/concepts-4.htm 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: <code>org.eclipse.ui.perspectiveExtensions</code>) 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 [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.simplifiedui/plugin.xml#n410 hide the 'Run' menu item] in all perspectives:

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

Another perspective extension we use is to hide   [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.simplifiedui/plugin.xml#419 certain Papyrus items from the toolbar]  in the Papyrus perspective.

==== Activator ====
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  [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.simplifiedui/src/org/eclipse/papyrus/information/modeling/simplifiedui/Activator.java Activator] of our simplification plugin to perform the following tasks:
* [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.simplifiedui/src/org/eclipse/papyrus/information/modeling/simplifiedui/internal/CreationMenuCleaner.java Hide the 'New Child' and 'New Relationship' menu entry] in the context menu of the Model Explorer as we provide simplified versions of these menu entries
* [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus-informationmodeling.git/tree/plugins/org.eclipse.papyrus.information.modeling.simplifiedui/src/org/eclipse/papyrus/information/modeling/simplifiedui/internal/ContextConfigurator.java Disable the UML context in Papyrus] since we provide our own simplified UML context