Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "JWT Extensions"

(Adding NotificationChangeListener when a value is changed in EMF Model)
(Use cases)
Line 318: Line 318:
  
 
==== Use cases ====
 
==== Use cases ====
* Set application parameters when method is set on an application (org.eclipse.jwt.we.changeListener.applicationMethod)
+
* Set application parameters when method is set on an application (plugin: org.eclipse.jwt.we.changeListener.applicationMethod)
  
 
----
 
----

Revision as of 07:09, 23 September 2008

This page provides information on how to extend the JWT Workflow Editor (JWT-WE) through plugins.

Overview

The JWT Workflow Editor defines several extension points and mechanisms that allow users to customize and extend the abilities and properties of JWT-WE without changing the editor itself. However, there may be cases in which it becomes necessary to alter the Workflow Editor code itself, notably when the new features need to be implemented by committers of the JWT project. This page is intended to describe how third party suppliers can extend JWT-WE (e.g. with custom views on the model elements) through external plugins using the defined extension points (if you're instead looking for tutorials on how to modify the Workflow Editor or how to directly implement new features, please take a look at JWT_Modifications).

Extending JWT-WE through Plugins

The JWT-WE Platform

The Workflow Editor can be extended using standard Eclipse extension points and it also defines several new extension points.

The plugin interfaces of the JWT Workflow Editor

Adding Actions to Menu/Toolbar

New actions can be added to the Workflow Editor using the org.eclipse.jwt.we.menu extension point. It is then added to the WE toolbar as a selectable option in the External Functions dropdown menu. If the editor is run in RCP mode, an additional entry in the main menu bar is created. The action itself has access to several resources of the editor and the loaded model.

Some sample actions which are displayed in the toolbar of the Workflow Editor
Menu entries for the external actions (only in RCP mode)


An action which is hooked into the Workflow Editor must extend the abstract class org.eclipse.jwt.we.editors.actions.external.WEExternalAction:

  • Overwriting the method getImage() allows to provide an ImageDescriptor, which contributes an icon for the action (or null)
  • The run() method is called, when the user selects the action in the toolbar or main menu

Help methods available in WEExternalAction are:

  • getActiveWEEditor(): returns the active WEEditor, which allows to access many parts of JWT-WE
  • getActiveActivitySheet(): returns the active graphical editor (WEEditorSheet)
  • getActiveResource(): returns the XMIResource, that contains the currently loaded model file
  • getActiveShell(): returns the active shell

Additional interesting points for plugin developers:

  • org.eclipse.jwt.we.editors.preferences.PreferenceReader: allows easy access to the preference store
  • org.eclipse.jwt.we.figures.FigureFactory: creates the Draw2D figures used by GEF to display the diagram
  • org.eclipse.jwt.we.misc.logging.Logger: the logger
  • org.eclipse.jwt.we.misc.util.*: several help classes
  • org.eclipse.jwt.we.misc.views.Views: access the views subsystem
  • org.eclipse.jwt.we.model.*: The EMF meta model and edit code
  • org.eclipse.jwt.we.PluginProperties: access the localized strings used in the editor
  • org.eclipse.jwt.we.Plugin: the main plugin

The required steps to register one ore more actions with JWT-WE are:

  • Create a new plugin project
  • Add jwt-we to your project dependencies
  • Add an extension for the point org.eclipse.jwt.we.menu
  • Create a new action child element for this extension point
    • class must be set to the Java class which contains the action (must subclass org.eclipse.jwt.we.editors.actions.external.WEExternalAction)
    • name and description refer to the displayed name and tooltip description. They can be set directly or read from plugin.properties using the %-prefix
    • showInToolbar and showInMenu define whether the action is shown in the Toolbar and/or the Menu bar (menu is only available in RCP mode)
    • forceText forces the name of the action to be shown in the toolbar, even if an icon is provided in the action.
    • If requiresOpenEditor is set to true, the action is hidden/disabled if no Workflow Editor is active in Eclipse (this only affects RCP mode)

To register the external actions shown above, you will need to add the following code to your plugin.xml:

   <extension
         id="org.eclipse.jwt.we.menu"
         name="org.eclipse.jwt.we.menu"
         point="org.eclipse.jwt.we.menu">
      <action
            class="org.eclipse.jwt.we.ExternSample.actions.SampleAction1"
            description="Sample1 Description"
            forceText="false"
            name="Sample1"
            requiresOpenEditor="true"
            showInMenu="true"
            showInToolbar="true"/>
      <action
            class="org.eclipse.jwt.we.ExternSample.actions.SampleAction2"
            description="Sample2Description"
            forceText="true"
            name="Sample2"
            requiresOpenEditor="true"
            showInMenu="true"
            showInToolbar="false"/>
      <action
            class="org.eclipse.jwt.we.ExternSample.actions.SampleAction3"
            description="Sample3 Description"
            forceText="true"
            name="Sample3"
            requiresOpenEditor="true"
            showInMenu="false"
            showInToolbar="true"/>
      <action
            class="org.eclipse.jwt.we.ExternSample.actions.SampleAction4"
            description="Sample4 Description"
            forceText="true"
            name="Sample4"
            requiresOpenEditor="false"
            showInMenu="true"
            showInToolbar="true"/>
   </extension>

Example plugin for defining external actions (org.eclipse.jwt.we.ExternSample):

Zip File: Media:jwt-we-external-action-sample.zip
CVS: [1]

Adding Views

text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text

The two standard views that come with JWT-WE

How to create external views:

  • ifigurefactory erweitern, auf modellklassen entsprechende ifigure zurückgeben, sonst null
  • factory im extension point angeben
  • iwefigure erweitern
  • für schatten modelelementfigure erweitern und border erstellen (wird neu gezeichnet)
  • plugin mit jwt-we starten (run configuration)
  • dependencies für plugin (draw2d, jwt-we)
  • screenshots einbauen
  • beispiel als startpunkt

text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text

Additional views provided by the example plugin (toolbar)
Additional views provided by the example plugin (RCP menubar)


text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text


The example plugin for defining external views (org.eclipse.jwt.we.view.extension):

Zip File: Media:jwt-we-external-view-sample.zip
CVS:

A view that changes the look of the model to that of an UML activity diagram (org.eclipse.jwt.we.view.uml):

Zip File: Media:jwt-we-external-uml-view.zip
CVS:

Adding Editor sheets

The Workflow Editor is of the type MultiEditorPart and thus may contain multiple editors which are represented as independet sheets. JWT-WE already contains two built-in editor sheets:

  • The Overview Sheet, which is a SWT Control. It is automatically opened for each loaded workflow and cannot be closed.
  • The Activity Editor, a graphical GEF EditorPart. Multiple activity editors can be opened for activities contained in one workflow. The ActivityEditor sheet is closable.

Through the extension point for external editor sheets, it is possible to integrate your own editors into JWT-WE.

The two types of editor sheets that come with JWT-WE

The sheet must be provided to the Workflow Editor through an IWEExternalSheetProvider, i.e. a class must be created that implements org.eclipse.jwt.we.editors.pages.externalSheet.IWEExternalSheetProvider. This interface contains two methods:

  • init(WEEditor editor) is called before the new editor sheet should be displayed. This method offers the possiblity to initialize the custom editor and to save a reference to the parent MultiEditorPart of the type WEEditor.
  • getExternalSheet() is called to obtain the editor sheet. The editor sheet may be provided as an IEditorPart or a SWT Control.

The required steps to register one ore more sheets with JWT-WE are:

  • Create a new plugin project
  • Add jwt-we to your project dependencies
  • Add an extension for the point org.eclipse.jwt.we.sheet
  • Create a new sheet child element for this extension point
    • title is the name of the editor sheet displayed in its tab in the MultiPartEditor
    • class must be set to the Java class which provides an IEditorPart or SWT Control as editor sheet (must implement org.eclipse.jwt.we.editors.pages.externalSheet.IWEExternalSheetProvider)
    • If closable is set to true, the editor sheet can be closed
    • If autoshow is set to true, an instance of the editor sheet is automatically created when a workflow is loaded
    • If multiple is set to true, multiple instances of the editor sheet can be created


The example plugin for defining external views (org.eclipse.jwt.we.view.extension):

Zip File: Media:jwt-we-external-view-sample.zip
CVS:

A view that changes the look of the model to that of an UML activity diagram (org.eclipse.jwt.we.view.uml):

Zip File: Media:jwt-we-external-uml-view.zip
CVS:

Adding Property Sheet Pages

The workflow editor contains support for a multi-tab property sheet (TabbedPropertiesView) which is only activated if additional tabs are provided by plugins. If this is not the case, the classical property sheet is used which does not display any tabs. If the multi-tab sheet is used, a single tab Standard is always shown, which contains the model element properties as would be normally shown in the classical property sheet.

The classical property sheet without tabs that shows the model element properties
The multi-tab sheet with the Standard tab that shows the model element properties

To add a new property sheet page to the editor, it is necessary to define a new property tab in the plugin.xml and fill it with one or more property sections. The implementation of property sections is described in this Eclipse article. Once the property section have been implemented, they can be registered with the property tab.

The required steps to create one ore more new property tab(s) are:

  • Create a new plugin project
  • Add jwt-we to your project dependencies
  • Add an extension for the point org.eclipse.ui.views.properties.tabbed.propertyTabs
  • Create a new propertyTabs child element for this extension point and set its contributorID to org.eclipse.jwt.we.editors.WEEditor
  • Create a new propertyTab child element for each property tab that you wish to add to the property sheet. The label corresponds to the displayed name of the tab (use % as prefix to load a language specific caption from plugin.properties). The category should be set to WEStandardCategory. The id should be a unique identifier (use org.eclipse.jwt.we.propertytabs. as prefix) and setting afterTab to org.eclipse.jwt.we.PropertyTabStandard will ensure that the standard tab remains the topmost tab entry.

The required steps to register property sections with the newly defined tab(s) are:

  • Add an extension for the point org.eclipse.ui.views.properties.tabbed.propertySections
  • Create a new propertySections child element for this extension point and set its contributorID to org.eclipse.jwt.we.editors.WEEditor
  • Create a new propertySection child element for each property section that you wish to add to one of your property tabs. The tab must be set to the id of the property tab which should contain this section. The id should be a unique identifier (use org.eclipse.jwt.we.propertysections. as prefix). The class attribute connects this entry to the actual implementation of the section, which should be a subclass of org.eclipse.ui.views.properties.tabbed.AbstractPropertySection. Setting enablesFor to 1 ensures, that the section is only available if a single element is selected. afterSection can be used to specify the arrangement of multiple sections in one tab.
  • Create an input child for each section and assign its type a Java class type like org.eclipse.emf.ecore.EObject. The property section/tab is only shown if an element of this type (or a subtype) is selected.

The following excerpt from plugin.xml shows the definition of a new property tab (Advanced) that contains only one section (implemented in org.eclipse.jwt.we.propertiesexample.sections.AdvancedPropertySection). The new property tab is only activated if a model element of the type org.eclipse.jwt.we.model.processes.ActivityNode is selected.

   <extension
         point="org.eclipse.ui.views.properties.tabbed.propertyTabs">
      <propertyTabs
            contributorId="org.eclipse.jwt.we.editors.WEEditor">
         <propertyTab
               afterTab="org.eclipse.jwt.we.propertytabs.Standard"
               category="WEStandardCategory"
               id="org.eclipse.jwt.we.propertytabs.Advanced"
               label="%properties_Advanced_label">
         </propertyTab>
      </propertyTabs>
   </extension>
   <extension
         point="org.eclipse.ui.views.properties.tabbed.propertySections">
      <propertySections
            contributorId="org.eclipse.jwt.we.editors.WEEditor">
         <propertySection
               class="org.eclipse.jwt.we.propertiesexample.sections.AdvancedPropertySection"
               enablesFor="1"
               id="org.eclipse.jwt.we.propertysections.Advanced"
               tab="org.eclipse.jwt.we.propertytabs.Advanced">
            <input
                  type="org.eclipse.jwt.we.model.processes.ActivityNode">
            </input>
         </propertySection>
      </propertySections>
   </extension>
An additional tab named Advanced was added to the multi-tab property sheet



Adding an import or export transformation

See JWT Transformations


Adding Custom PropertyDescriptor (and editors) in property sheets

Description

The aim of this extension is to provide the ability to use a different Property Editor than the default one provided by EMF. This can be used for example to facilitate the input of data by proposing choices instead of letting user type something (reduce error risks).

The extension point is named org.eclipse.jwt.we.propertyDescriptor, it is made of:

  • The description of the EMF feature whom editor we want to change in property sheet
    • The EMF packageName (eg org.eclipse.jwt/application
    • The EMF className (eg WebServiceApplication)
    • The EMF featureNane (eg method)
  • The PropertyDescriptorFactory (defined in JWT-WE) that is responsible of creating an instance of PropertyDescriptor for the specified feature

Behavior

  • If there are several propertyDescriptors on this extension point for the same feature, then we can't guess which one will be used.
  • Override when Subclass: If there is a propertyDescriptor PropInClazzPropertyDescriptor for property Prop of EMF class Clazz, and a propertyDescriptor PropInSubClazzPropertyDescriptor for property Prop of EMF class SubClazz, then it will use PropInSubClazzPropertyDescriptor for SubClazz and children, and PropInClazzPropertyDescriptor for Clazz and chhildren, except for SubClazz and children.

Utils

  • Since several propertyDescriptor may share common and useful classes, generic PropertyDescriptors can be found in the "library" plug-in org.eclipse.jwt.we.editors.properties.widgets

Example / Code

TODO when commited

HowTo / Wink

TODO


Adding NotificationChangeListener when a value is changed in EMF Model

Description

The aim of this extension is to provide the ability to listen to changes of EMF values of EMF Model and then to run a piece of code according to the notification. For example, automatically generate an alert when a value does not fit a constraint, or automatically set a property value according to the one that just changed (eg set parameters of an application according to the choosen method signature)

The extension point org.eclipse.jwt.we.changeListener is defined by:

  • The EMF feature that we want to listen changes
    • EMF packageName
    • EMF className
    • EMF featureName
  • An implementation for INotifyChangedListener

Behavior

A notification listener on a feature is applied to feature of specified class and subclasses. When several extensions associates a change listener to the same feature, then all listeners will run their notifyChanged method when notified in an order that can not be previwed.

Code / Example

TODO when commited

Demo / Howto / Wink

TODO

Use cases

  • Set application parameters when method is set on an application (plugin: org.eclipse.jwt.we.changeListener.applicationMethod)

Adding Meta Model Extensions

See also

Back to the top