1 files changed, 0 insertions, 6 deletions
diff --git a/plugins/doc/org.eclipse.papyrus.uml.profile.assistants.doc/resource/profile-assistants.html b/plugins/doc/org.eclipse.papyrus.uml.profile.assistants.doc/resource/profile-assistants.html
deleted file mode 100644
index e5b0ba6b08b..00000000000
--- a/plugins/doc/org.eclipse.papyrus.uml.profile.assistants.doc/resource/profile-assistants.html
+++ /dev/null
@@ -1,6 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/></head><body><h1 id="About_Diagram_Assistants_for_UML_Profiles">About Diagram Assistants for UML Profiles</h1><p>Papyrus UML diagrams provide a feature called <i>Diagram Assistants</i> that offer context-sensitive tools directly in the diagram.  These are manifest in two forms:</p><ul><li>pop-up bar:  an orange rounded rectangle containing a variety of tools for creation of new model elements</li><li>connection handles:  a pair of arrows handles, one incoming and outgoing, appearing at the border of a shape from which new connections can be dragged to other shapes in the diagram</li></ul><p>The diagram assistants provided out-of-the-box by Papyrus support creation of the basic UML elements.  However, you can extend the capabilities of the diagram assistants to create elements from your profile-based DSL, by creating new UML elements having your stereotypes applied.</p><h1 id="Diagram_Assistant_Models">Diagram Assistant Models</h1><p>Papyrus uses EMF-based models to describe the diagram assistants that can be presented in UML diagrams.  The core UML assistants are described by these models, and so are the assistants for your DSLs.</p><p>Consider a trivial example of a profile for design of use cases in a J2EE-based system: </p><p><img border="0" src="images/usecase-stereotypes.png"/> </p><p>This profile has several stereotypes:</p><ul><li>«webScenario» extending UseCase</li><li>«branchPoint» extending ExtensionPoint</li><li>«user» and «browser» extending Actor</li><li>«web» extending Association</li></ul><p>Diagram assistants that might be provided for such a profile should offer to create «branchPoint» ExtensionPoints in «webScenario» use cases:</p><p><img border="0" src="images/popup-bar.png"/></p><p>and «web» Associations between «webScenario» UseCases and «user» or «browser» Actors, thus:</p><p><img border="0" src="images/connection-assistant.png"/></p><p>The model is described by a <b>ModelingAssistantProvider</b> in a <code>*.assistants</code> resource.  The ModelingAssistantProvider captures essentially the same information as is provided by implementations of the <code>org.eclipse.gmf.runtime.emf.ui.services.modelingassistant.IModelingAssistantProvider</code> interface, with the exception of "show related elements" queries.  In particular, it provides:</p><ul><li>a list of element types (by ID) for which the provider offers diagram assistants</li><li>a list of <b>PopupAssistant</b>s describing creation tools presented in the pop-up bar. Each of these specifies:<ul><li>the element type (by ID) of the model element that the tool creates</li><li>a <b>Filter</b> matching model elements on which the popup assistant should be shown</li></ul></li><li>a list of <b>ConnectionAssistant</b>s describing relationships (elements and references) that should be presented by the connection handles. Each of these specifies:<ul><li>the element type (by ID) of the model element or reference that the tool creates</li><li>a <b>Filter</b> matching source model elements on which the popup assistant should be shown</li><li>a <b>Filter</b> matching target model elements on which the popup assistant should be shown</li></ul></li></ul><p>The filters specified by the different kinds of assistants may be owned by the assistants that require them (private one-offs) or may be shared for re-use by any number of assistants.  The latter are commonly stored in the root <b>ModelingAssistantProvider</b> element, which just serves as a container.  Several different kinds of filter are provided by Papyrus:</p><ul><li><b>ElementTypeFilter</b>:  matches the element type of any <code>EObject</code> or <code>IAdaptable</code> (such as a diagram <code>EditPart</code>) by ID.  The match is a subtype match:  any object that matches the given element type or any specialization of that element type is accepted by the filter.  This is particularly useful with the visual-ID hinted types that distinguish different visualizations of UML elements in the different diagrams.</li><li><b>Equals</b>:  matches an element that is equal to (the same as) the element referenced by the filter</li><li><b>ProfileApplied</b>:  matches an element that is in the context of a UML Package that has a particular profile applied.  The profile may be specified by URI (preferred) or by qualified name (which is susceptible to shadowing by name conflicts)</li><li><b>AssistedElementTypeFilter</b>: a special filter that matches any object of an element type that is referenced as one of the element types for which the containing ModelAssistantProvider provides assistants</li><li><b>CompoundFilter</b>:  groups filters with boolean expressions.  Filters in an expression may be owned or referenced by the compound.  Supported operators are:<ul><li><b>and</b>: matches objects for which all filters matches. An empty compound matches no objects</li><li><b>or</b>:  matches objects for which at least one filter matches. An empty compound matches no objects</li><li><b>xor</b>: matches objects for which exactly one filter matches. An empty compound matches no objects</li><li><b>not</b>: matches objects for which none of the filters match (more than one filter may be referenced). An empty compound matches any object</li></ul></li></ul><p>Extenders can define custom filters by extending the filter model defined in the <code>org.eclipse.papyrus.infra.filters</code> plug-in.  The editor makes use of EMF's "child creation extenders" facility to integrate your custom filters with the core set.</p><p><img border="0" src="images/assistant-filter.png"/></p><p>The image above shows a detail of the filter generated by Papyrus for a «branchPoint» ExtensionPoint pop-up tool in the example J2EE profile in Use Case diagrams.  The filter is an <b>and</b> combination of</p><ul><li>the "pertains to Profile1" filter (which is based on a ProfileApplied filter referencing the J2EE profile)</li><li>an <b>or</b> combination of the various visualizations of UseCase supported by the diagram, including UseCases visualized as ellipse or as classifier shapes.  To restrict the pop-up assistant to only «webScenario» UseCases from this DSL, one would replace the generic UseCase element type filters with filters selecting the more specific <code>org.eclipse.papyrus.example.j2ee.WebScenario</code> element type that specializes UseCase for the stereotype extension</li></ul><h1 id="Generating_Diagram_Assistants">Generating Diagram Assistants</h1><p>Building a diagram assistant model by hand is a tedious undertaking.  To ease this process, Papyrus provides a wizard that generates an assistants model from a Profile selected in the <b>Model Explorer</b> view:</p><p><img border="0" src="images/generate-assistants-menu.png"/></p><p>Because the diagram assistants model specifies the element types that are created by the assistant tools, the wizard also generates the element types for your DSL as an <code>*.elementtypesconfigurations</code> model.  If you only need to generate this latter model, that option is also available in the menu.</p><p>The diagram assistants wizard dialog requires several pieces of information as inputs (as identified in the image below):</p><ol><li>An unique identifier for the assistants model. This is used as a prefix for element types that are generated for your DSL</li><li>The element types set model on which to base the element types generated for your DSL.  This has important consequences discussed below</li><li>Whether to suppress the reference to a semantic supertype distinct from the diagram-specific ("visual") element type in the list of specialized types for generated element types.  This option is only applicable when generating a diagram-specific diagram assistants model</li><li>The workspace folder or project in which to create the model</li><li>The name of the <code>*.assistants</code> model file to create.  The element types model will use the same name, except with the <code>*.elementtypesconfigurations</code> extension</li></ol><p><img border="0" src="images/generate-assistants-wizard.png"/></p><p>Upon completion of the wizard, element types and modeling assistants are generated as follows:</p><ul><li>for each metaclass extension of a stereotype in the profile, <b>SpecializationTypeConfiguration</b>s are generated that specialize each of the element types in the base element types set that are based on the same UML metaclass.  So, in our trivial J2EE profile example, the «branchPoint» stereotype generates two element types: one for each of the 3007 and 3008 visualizations of the ExtensionPoint metaclass in the Use Case diagram<ul><li>if your assistants model is based on a diagram-specific element types model, then the visualization-specific element types that are generated will specialize the visual UML element types of the diagram and also semantic element types representing the stereotyped element in the model (unless the option to suppress the semantic supertype was selected)</li><li>if your stereotypes include Image specifications that reference an icon by a <code>profile:/plugin/...</code> URI, then that is used to generate an equivalent <b>IconEntry</b> in the element type configuration</li></ul></li><li>for each profile-specific element type, a diagram assistant is generated, either<ul><li>a <b>ConnectionAssistant</b> if the element type is not a relationship or reference type, or</li><li>a <b>PopupAssistant</b> otherwise</li></ul></li><li>for each pop-up assistant, a filter is generated that is an <b>or</b> combination of <b>ElementTypeFilter</b>s for each of the element types in the base set that can contain an instance of the profile element type</li><li>for each connection assistant, filters are generated that are <b>or</b> combinations of <b>ElementTypeFilter</b>s for each of the element types in the base set that can be sources and targets, respectively, of the profile element type</li><li>a few common filters are generated for use by all of the assistants, including:<ul><li>an <b>AssistedElementTypeFilter</b> matching objects of an element type that is provided by the model as an assistant</li><li>a <b>ProfileApplied</b> filter that matches objects in the context of some package that has the source profile applied</li><li>a "pertains to <i>profile name</i>" filter that is an <b>or</b> combination of the previous two</li></ul></li><li>the generated <b>ModelingAssistantProvider</b> lists the element types generated in the accompanying <code>*.elementtypesconfigurations</code> model as the element types that it provides as assistants.  This restricts the sources and targets of connections from/to new elements to only element types specific to your profile.  You can edit this list as necessary to further restrict or widen the end types created by the connection assistants</li></ul><h2 id="Choosing_a_Base_Element_Types_Set">Choosing a Base Element Types Set</h2><p>As mentioned above, the decision of which element types set model to base the generated assistants on is crucial in determining the shape of the result.  There are essentially two choices to be made:</p><ul><li>generate assistants based on the core UML element types, describing the unprofiled UML metamodel without reference to any particular visualizations of elements in any diagram</li><li>generate assistants based on the visual-ID hinted element types of a specific UML diagram</li></ul><h3 id="Generating_Generic_UML-based_Assistants">Generating Generic UML-based Assistants</h3><p>To generate modeling assistants that will be applicable to any diagram in which the elements of your DSL can be visualized, choose the <b>uml</b> element types set from the <code>org.eclipse.papyrus.uml.service.types</code> plug-in.  This option has the advantage that if your profile has stereotypes extending metaclasses in several different diagrams, you will need only the one assistants model to cover all of those diagrams.</p><p>However, there are some drawbacks that you will have to account for.  The most important of these is that, as generated, the assistants model has to infer on-the-fly specializations of your profile element types for the various visual ID hinted types supported by the different specific diagrams.  This inference is automatic and can result in</p><ul><li>repetition of the same element type (for different visual IDs) on some selections</li><li>presentation of element types in contexts that actually are inappropriate (such as N-ary association branch in a use case diagram) if the diagram's view provider is not sufficiently specific about the visualizations that it supports</li></ul><p>These problems can usually be remedied by careful crafting of filters to restrict the applicability of each assistant.  It may be necessary in some cases to resort to custom filters.</p><h3 id="Generating_Diagram-specific_Assistants">Generating Diagram-specific Assistants</h3><p>To generate modeling assistants that are applicable only to a particular diagram in which the elements of your DSL can be visualized, choose that diagram's element types set from the list (the example screen shot above shows the Use Case Diagram selected).  This option has the advantage of giving the most accurate/appropriate assistants out of the box but it does require a separate model for each diagram that your DSL covers.</p><p>In this case, the element types generated for your assistants are specializations of the particular visual-ID hinted types supported by the diagram for the different visualizations, in that diagram context, of the base UML metaclass.  The most significant customization that you would do after generating the assistants model is to delete assistants that are not required.</p><p>By default, the wizard will also reference a second supertype in each generated specialization element type:  an element type representing the
-stereotyped element in the model, irrespective of any visualization in the diagram.  This is effectively referencing the element type that would be
-generated in the "Generic UML-based Assistants" case, asdescribed above.  At run-time, these "semantic element types" will be expected to be
-available, so it is necessary to generate them using the <b>Generate Tooling Model &rarr; Element Types...</b> action in the context menu and
-selecting the generic UML element types as the base model.  However, the reference to the semantic super-types may be ommitted, if desired, by
-checking the <b>Suppress semantic parent in diagram-specific element types</b> box in the wizard.</p><h2 id="Considerations_for_Designing_Assistants_Models">Considerations for Designing Assistants Models</h2><p>The most important considerations in designing assistant models are appropriateness of the element types suggested to the user and the number of element types suggested to the user.</p><p>As discussed above, the generation of the assistants model just provides a starting point that needs to be fine-tuned.  The generator outputs every combination that seems to be valid; these need to be culled in practice.  Some assistants are not valid in every context where they may be shown (which requires customization of their filters) whereas many assistants just may not be necessary because they are element types that are rarely used, or only in advanced use cases.</p><p>Of particular concern is the scaling of the diagram assistants user interface:  it is important not to overwhelm users with too many options.  There is a practical limit to how large the pop-up bar can be before its usability degrades; likewise the menus that are popped up for completion of connections.  When designing the assistants model for your profile, keep in mind that the diagram assistants will include proposals from five sources:</p><ul><li>the base UML assistants models deployed by Papyrus for each of the diagrams</li><li>the assistant models deployed by Papyrus for first-party profiles such as SysML and UML-RT</li><li>assistant models deployed from the workspace or in third-party plug-ins for other profiles</li><li>the assistant model that you are designing for your profile</li><li>the pop-up bar shows hyperlinks created by the user, in addition to the green "plus" button for creation of new hyperlinks</li></ul><p>The number of assistants presented on any given selection in a diagram can add up rather quickly.  Precise filtering of assistants is critical and restricting the overall number of assistants that are defined to only the most commonly used elements is highly recommended.</p><h1 id="Deploying_a_Diagram_Assistants_Model">Deploying a Diagram Assistants Model</h1><p>There are two ways to deploy diagram assistants. The assistants in a <code>*.assistants</code> resource can be hot-deployed directly from the workspace or they may be statically deployed in a plug-in installed in the Papyrus workbench.</p><h2 id="Deploying_Models_in_the_Host_Workbench">Deploying Models in the Host Workbench</h2><p>The simplest method, which is best for testing during development of the assistants model, is to deploy the assistants model in your workspace directly into the running Papyrus workbench.  In the <b>Project Explorer</b>, select your assistants model and choose the <b>Deploy Modeling Assistants</b> action in the context menu:</p><p><img border="0" src="images/deploy.png"/></p><p>Note that you may first need to deploy the element types configuration model if you have not already done so.</p><p>From this point, the assistants described in your model are active in the system.  Whenever you save changes, the model is "hot re-deployed" to update the diagrams in real time.  Papyrus remembers which assistant models in the workspace are deployed so that you don't have to deploy them again the next time you open that workspace.</p><p>To remove the assistants in a model from the Papyrus run-time, just select the <b>Deactivate Modeling Assistants</b> action in the context menu:</p><p><img border="0" src="images/undeploy.png"/></p><h2 id="Deploying_Models_in_Plug-ins">Deploying Models in Plug-ins</h2><p>When your assistants model is ready to ship, together with your profile and other DSL tooling, you should deploy it statically in the plug-in that installs your profile into your users' Papyrus workbenches.  Simply bundle the <code>*.assistants</code> resource in your plug-in and register it on the <code>org.eclipse.papyrus.infra.gmfdiag.assistants.modelProviders</code> extension point just as Papyrus, itself, does for the core UML diagram assistants:</p><p><img border="0" src="images/providers-extpt.png"/></p></body></html>
-\ No newline at end of file