The new model wizard is an extensible wizard framework used to provide a centralized means of creating models. There are two workflows within the wizard. The first page of the new model wizard provides the user with the choice to either create a new model from a standard template or from an existing model.
If the user selects to create a new model from a standard template the following page is shown. This page displays a list of templates alongside their corresponding categories. Templates and categories are contributed by the developer to provide the user with a model to start modeling with their application. The user must select a template, input the necessary data, and continue on to finish the wizard which will result in the creation of a new model based on the selected template.
If the user selects to create a model from an existing model the following page is shown. This page lets the user browse the workspace to find a model to find an existing model. Upon completion of the wizard, a new model based on the existing model will be created.
The new model project wizard wraps the new model wizard to provide a means to additionally create a project to contain the model. All contributions to the new model wizard will also be contributed to the new model project wizard.
Templates can either be contributed statically through template directories or dynamically by template factories. Contributing static templates is the easier of the two methods as custom handlers are required when working with dynamic templates.
A static templates resides in the file system as a model file and is defined by a template definition file.
Static templates are contributed by specifying the directory containing the template file.
To contribute a template directory extend the
com.ibm.xtools.common.ui.wizards.newModelWizard extension-point and set the templateDirectory path
to be the path to the directory located within the same plugin which contains the template files.
<extension
point="com.ibm.xtools.common.ui.wizards.newModelWizard">
<templateDirectory
path="templates/"/>
</extension>
When contributing template directories, the directory should contain the template definition file whose file extension is .templatedef.ve, the model template and the template icon:
Example directory containing template files:
The template definition file can either be a properties file or XML. The XML format supports the definition of multiple templates, while there can only be one properties file for each template.
There are 6 required properties when defining a template:
name: This is the name of the template to be displayed in the new model wizard.description: This is the description of the template to be displayed in the new model wizard.modelName: This is the default name of the model to be created from this template and is displayed in the new model wizard.id: A unique identifier used to reference the template.templateFile: The template file name, including the file extension, located within the same directory as the template definition file.icon: The icon file name, including the file extension, located within the same directory as the template definition file.
The icon is displayed along side the name within the new model wizard.Example properties template definition file:
name=Main Template description=Create main model. modelName=mainModel id=com.ibm.examples.templates.mainTemplate templateFile=mainTemplate.foo icon=mainTemplate.gif
Example XML template definition file with multiple template definitions:
<templates>
<template
name="Support Template1"
description="Create support model."
modelName="supportModel"
id="com.ibm.examples.templates.supportTemplate.template1"
templateFile="supportTemplate1.foo"
icon="supportTemplate1.gif">
</template>
<template
name="Support Template2"
description="Create support model."
modelName="supportModel"
id="com.ibm.examples.templates.supportTemplate.template2"
templateFile="supportTemplate2.foo"
icon="supportTemplate2.gif">
</template>
</templates>
The template model handler is used to create the final model from the template upon finishing
the wizard. By default, any template file contributed through a template directory will utilize the
com.ibm.xtools.common.ui.wizards.handlers.FileTemplateModelHandler. This handler creates a working copy of the template model
in the workspace and opens the new model using its default editor.
If the default template model handler is not sufficient
then a custom template model handler is required. To contribute a custom template model handler for all
templates provided within a template directory, when defining the templateDirectory, additionally
set the handler to be a class which extends
com.ibm.xtools.common.ui.wizards.handlers.ITemplateModelHandler.
<extension
point="com.ibm.xtools.common.ui.wizards.newModelWizard">
<templateDirectory
path="templates/"
handler="com.ibm.examples.MyTemplateModelHandler"/>
</extension>
For the template model handler choose to either extend
com.ibm.xtools.common.ui.wizards.handlers.FileTemplateModelHandler or
com.ibm.xtools.common.ui.wizards.handlers.AbstractTemplateModelHandler or implement
com.ibm.xtools.common.ui.wizards.handlers.ITemplateModelHandler and write a handler
from scratch.
Implementing
ITemplateModelHandler requires providing implementation
for two methods:
createTemplateConfiguration(ITemplate template)
and
createFiles(IProgressMonitor progressMonitor, TemplateConfiguration config)
The
createTemplateConfiguration(ITemplate template) method should return a
TemplateConfiguration for the given template.
The template configuration is populated by the wizard with information such as the location to create
the new model, the new model file name, etc...
The wizard calls the
createFiles(IProgressMonitor progressMonitor, TemplateConfiguration config)
method when the wizard finishes. This method performs the actions necessary to create a new model using
the data from the template configuration. If the operation is successful, this method should return
true. If the operation cannot successfully complete, returning
false will abort the wizard finish operation.
A template factory is used to programmatically contribute templates that may not relate to a physical
file in the system. To contribute a template factory extend the
com.ibm.xtools.common.ui.wizards.newModelWizard extension-point and set the templateFactory class
to be a class which extends
com.ibm.xtools.common.ui.wizards.templates.ITemplateFactory.
<extension
point="com.ibm.xtools.common.ui.wizards.newModelWizard">
<templateFactory
class="com.ibm.examples.MyTemplateFactory"/>
</extension>
Only a single method is required when implementing
ITemplateFactory.
getTemplates() which returns an array of
ITemplates.
The factory must populate the following template data for a template to be valid:
id: A unique identifier used to reference the template.name: This is the name of the template to be displayed in the new model wizard.description: This is the description of the template to be displayed in the new model wizard.model name: This is the default name of the model to be created from this template and is displayed in the new model wizard.model file extension: The file extension of the model file to be create from this template.icon URL: The URL for the icon that is to be displayed along side the name within the new model wizard.template model handler: Unlike contributing template directories, the templates contributed through a template factory
must have a custom template model handler.public class MyTemplateFactory implements ITemplateFactory {
public ITemplate[] getTemplates() {
BasicTemplate template = new BasicTemplate();
// populate template information
template.setId("com.ibm.examples.templates.supportTemplate.dynamicTemplate");
template.setName("Dynamic Support Template");
template.setDescription("Create support model.");
template.setModelName("supportModel");
template.setModelFileExtension("foo");
try {
newTemplate.setIconURL(new URL("file", null, "/icons/supportTemplate.gif"));
} catch (MalformedURLException mue) {
// log error
}
// set the template model handler
newTemplate.setTemplateModelHandler(new MyTemplateModelHandler());
return new ITemplate[] { template };
}
}
Categories are used to categorize templates in the new model wizard. To contribute
a category extend the
com.ibm.xtools.common.ui.wizards.newModelWizard extension-point and create a
category element with a unique id and a label to be displayed in the wizard.
Optionally a category may specify the ID of its parent category.
<extension
point="com.ibm.xtools.common.ui.wizards.newModelWizard">
<category
id="com.ibm.examples.category1"
label="My Category"/>
<category
id="com.ibm.examples.category1_1"
label="My Sub Category"
parent="com.ibm.examples.category1"/>
</extension>
The next step is to bind a template to the new category. Binding templates (whether they are contributed through a template directory or by a template factory) to categories is necessary, otherwise neither will show up in the new model wizard.
To bind templates to a category extend the
com.ibm.xtools.common.ui.wizards.newModelWizard extension-point and create a
templateCategoryBinding element. Set the categoryRef to be the ID of the
category for which the templates will be bound to. The templates are specified by adding
template elements.
Templates can be referenced in two different ways. To reference a single
template by ID, set match to "equals" and set ref
to be the ID of the template. To reference multiple templates using a pattern match against the template ID,
set match to "pattern" and set ref
to be a regular expression pattern.
<extension
point="com.ibm.xtools.common.ui.wizards.newModelWizard">
<templateCategoryBinding
categoryRef="com.ibm.examples.category1">
<template
ref="com.ibm.examples.template.mainTemplate"
match="equals"/>
</templateCategoryBinding>
<templateCategoryBinding
categoryRef="com.ibm.examples.category1_1">
<template
ref="com\.ibm\.xtools\.example\.templates.supportTemplate\..*"
match="pattern"/>
</templateCategoryBinding>
</extension>
To allow the user to configure template parameters, additional wizard pages may be contributed to
the new model wizard for a specific template. This can be done using template configuration page groups.
A group consists of one or more wizard pages which implement
com.ibm.xtools.common.ui.wizards.pagegroups.ITemplateConfigurationPage.
The group has the ability to create a workflow between
each page it contributes. When the wizard finishes, the group is given the opportunity to modify the
newly created model.
To contribute template configuration page groups extend the
com.ibm.xtools.common.ui.wizards.newModelWizard extension-point and create a
templateConfigurationPageGroup element. Set class
to be a class which extends
com.ibm.xtools.common.ui.wizards.pagegroups.ITemplateConfigurationPageGroup and
provide a unique id. The template configuration page group must be bound to templates
by adding template references
similar to when creating category template bindings.
Additionally, template configuration page groups may be ordered by specifying the afterRef
attribute which ensures that this group will be displayed after the referenced group. Similar to template referencing,
there are two ways to reference the group. To reference a single
group by ID, set match to "equals" and set afterRef
to be the ID of the group which this group will come after. To reference multiple groups using a pattern match against the group ID,
set match to "pattern" and set afterRef
to be a regular expression pattern. Note that specifying afterRef does not ensure this group will be
displayed immediately after the specified group; there may be additional groups displayed in between depending on other contributions.
Clients that wish to contribute a linear list of configuration pages may utilize the
LinearTemplateConfigurationPageGroup which is an abstract implementation of
ITemplateConfigurationPageGroup. This group will navigate one or more pages in linear order.
<extension
point="com.ibm.xtools.common.ui.wizards.newModelWizard">
<templateConfigurationPageGroup
class="com.ibm.examples.MyMainTemplateConfigurationPageGroup"
id="com.ibm.examples.MyMainTemplateConfigurationPageGroup">
<template
ref="com.ibm.examples.templates.mainTemplate"
match="equals"/>
</templateConfigurationPageGroup>
<templateConfigurationPageGroup
afterMatch="pattern"
afterRef="com.ibm.examples.MyMainTemplateConfigurationPageGroup"
class="com.ibm.examples.MyTemplateConfigurationPageGroup"
id="com.ibm.examples.MyTemplateConfigurationPageGroup">
<template
ref="com\.ibm\.example\.templates\..*"
match="pattern"/>
</templateConfigurationPageGroup>
</extension>
If a template is contributed by use of a
templateDirectory and no custom
template model handler is specified,
to propagate the user input data from the wizard pages contributed by the group, create an instance of
com.ibm.xtools.common.ui.wizards.handlers.IContentCreator and add it to the
TemplateConfiguration set by the wizard on the group.
The content creator has a single method to implement which can be used to customized the newly created model(s).
Otherwise, if a template is contributed along with a custom template model handler,
either the handler must be made to support content creators, or the handler must provide a custom
TemplateConfiguration which can be populated with the user input data. For extensibility
purposes, all handlers should be made to support content creators.
To have the new model, created from a template, participate in UI Reduction, activity template bindings are used. These bindings allow the template owner to dictate which UI components should be visible when working with the template model. For more information on UI reduction click here.
To create an activity template binding extend the
com.ibm.xtools.common.ui.wizards.newModelWizard extension-point and create an
activityTemplateBinding element. The activityTemplateBinding must contain
one template reference and one more more activity references.
Activities can be referenced in two different ways. To reference a single
activity by ID, set match to "equals" and set ref
to be the ID of the activity. To reference multiple activities using a pattern match against the activity ID,
set match to "pattern" and set ref
to be a regular expression pattern.
The activities must be bound to templates
by adding a template reference
similar to when creating category template bindings.
<extension
point="com.ibm.xtools.common.ui.wizards.newModelWizard">
<activityTemplateBinding
required="true">
<activity
ref="com.ibm.examples.mainUIReductionActivity"
match="equals"/>
<template
ref="com.ibm.example.templates.mainTemplate"
match="equals"/>
</activityTemplateBinding>
<activityTemplateBinding
required="false">
<activity
ref="com.ibm.examples.supportUIReductionActivity"
match="equals"/>
<template
ref="com\.ibm\.example\.templates\.supportTemplates\..*"
match="pattern"/>
</activityTemplateBinding>
</extension>
The activities configuration page works in conjunction with activity template bindings and allows the user to customize these activities prior to writing them to the newly created model.
The activities configuration page can be contributed by
contributing a template configuration page group, and setting the
class attribute to be
com.ibm.xtools.common.ui.wizards.pagegroups.ActivitiesTemplateConfigurationPageGroup. The id
attribute must be set to a unique identifier.
<extension
point="com.ibm.xtools.common.ui.wizards.newModelWizard">
<templateConfigurationPageGroup
afterMatch="pattern"
afterRef=".*"
class="com.ibm.xtools.common.ui.wizards.pagegroups.ActivitiesTemplateConfigurationPageGroup"
id="com.ibm.xtools.examples">
<template
ref=".*"
match="pattern"/>
</templateConfigurationPageGroup>
</extension>
The existing model handler is used to create the final model from an existing model upon finishing the wizard. Its function is similar to the template model handler in that it creates a model from a configuration.
To contribute an existing model handler extend the
com.ibm.xtools.common.ui.wizards.newModelWizard extension-point and create a
templateConfigurationPageGroup element. Set class to be a class which extends
com.ibm.xtools.common.ui.wizards.handlers.IExistingModelHandler and set
extensions to be a comma separated list of supported model file extensions.
<extension
point="com.ibm.xtools.common.ui.wizards.newModelWizard">
<existingModelHandler
class="com.ibm.examples.MyExistingModelHandler"
extensions="foo, bar"/>
</extension>
For the existing model handler choose to either extend
com.ibm.xtools.common.ui.wizards.handlers.AbstractExistingModelHandler or implement
com.ibm.xtools.common.ui.wizards.handlers.IExistingModelHandler and write a handler
from scratch.
Implementing
IExistingModelHandler requires providing implementation
for two methods:
createExistingModelConfiguration(IFile sourceModel)
and
createFiles(IProgressMonitor progressMonitor, ExistingModelConfiguration config)
The
createExistingModelConfiguration(IFile sourceModel) method should return an
ExistingModelConfiguration for the given source model.
The existing model configuration is populated by the wizard with information such as the location to create
the new model, the new model file name, etc...
The wizard calls the
createFiles(IProgressMonitor progressMonitor, ExistingModelConfiguration config)
method when the wizard finishes. This method performs the actions necessary to create a new model using
the data from the existing model configuration. If the operation is successful, this method should return
true. If the operation cannot successfully complete, returning
false will abort the wizard finish operation.
