The builder definition file is generally divided into the following sections.
|BuilderDef||Contains all the elements in the builder definition and the id attribute. For example, <BuilderDef id="com.bowstreet.builders.webapp.ButtonBuilder"> The id attribute includes the file path and name of the builder definition file. The path is relative from the IBM® WebSphere® Portlet Factory WEB-INF/builders directory. Directory names are separated using dots (.) as in Java™ package names. The id is referenced in BuilderCalls in models. |
|ReadableName||Set the value of this element to be the name of the builder. This name appears in the WebSphere Portlet Factory Designer builder picker.|
For example: <ReadableName>Button</ReadableName> This value gets Internationalized if builder definition resource bundles are being used. If more than one (visible) builder in a project has the same ReadableName, an error is displayed and any duplicate name after the first has additional text appended to make it unique.
Note: WebSphere Portlet Factory does not support the use of bidirectional characters in builder names. This might cause problems in languages in which these types of characters are commonly used, such as traditional Chinese, simplified Chinese, Korean, and Japanese.
|GenHandlerClassName||Enter com.bowstreet.builders.webapp.foundation.WebAppGenHandler for builders that do not use a Page Location input.|
Enter com.bowstreet.builders.webapp.foundation.WebAppControlGenHandler for builders that do use a Page Location input.
|HelpFile||Enable WebSphere Portlet Factory Designer to launch a help file for this builder by setting this element value to the path and file name for the help file. Paths are relative from the WebSphere Portlet Factory servable content root directory. For example, <HelpFile>factory/product_documentation/builders/button.htm</HelpFile> |
Store the help files for builders that you create somewhere under the WebSphere Portlet Factory servable content root. The HelpFile value for a builder is similar to:
where acme/builders is the directory in which the help file, automated_site.htm resides.
| RequiredFactoryVersion ||Minimum version of the WebSphere Portlet Factory that supports this builder. Set this element value to correspond to the core engine and runtime version as displayed in the server startup message (to the console of the server or stdout). For example, <RequiredFactoryVersion>x.y.z</RequiredFactoryVersion> |
If the builder is placed in a lower version of the WebSphere Portlet Factory, it has the functionality of the Comment builder (none) but retains its builder inputs.
Note: Do not set this value to the displayable product version as shown in WebSphere Portlet Factory Designer. In some cases, version value represents versions of the plugins, not of WebSphere Portlet Factory.
|Description||Set this element value to the text to be displayed in the builder call editor for this builder. For example:|
Add a button to one or more pages in the model.
|Domains||Contains Domain elements.|
|Domain||All builders specify at least one domain:|
This element adds the builder name to the builder picker. Builders without this value can still be used; some builders are only intended to be called from other builders and do not have this value.
|Category||For each builder, you can define categories that display in the builder picker. Each builder can be defined in multiple categories by specifying a comma-separated list.|
The builder definition declares the types of things that it can create and can modify. With each declaration is a category and a description. This data is used by the WebSphere Portlet Factory Designer to offer the list of builders that make sense to create in different contexts. For example, the user can right-click on a button and he is offered only those builders that can modify a button. This information is not meant to be exhaustive, just to be usable.
|CanCreate||From an element in the Application tree or the graphical view, if the user has selected a category, for example, Page, a list of objects that the selected builder can create is displayed. |
|CanModify||From an element in the Application tree or the graphical view, a list of objects that the selected builder can modify is displayed. That list is made from the builder definitions that have declared with CanCreate or CanModify elements in the Category element a particular type of element.|
Once you declare that your builder can modify elements of a particular type, initialize some of the values within a new instance of the builder so that it starts off pointing to the currently selected element. The initialization process is executed not only if the user picks your builder from the context menu, but also if the user chooses your builder in the builder picker while anything is selected in the Application Tree.
In this initialization process, the Application Tree is really the tree of GenElements. Each GenElement has a name, a type (that might be hidden) and a pointer to a Domain Object (an object in the WebApp itself). This information can be used to set up the value in the BuilderCall so that the new BuilderCall references the current Domain Object.
|CreateModifyList||From the WebApp node, a complete list of objects that can be created displays, with sub-menus for each object.|
|Keywords||For each builder, you can define searchable keywords that display in the builder picker. Every builder automatically has its name and all of its categories in its keyword list. You can also specify additional keywords. Here is a sample from the button builder. |
<Category>Page Elements,Navigation and Page Actions</Category>
<Keywords>Form Submit, Data Entry, Flow Control, Action, HTML</Keywords>
This element declares the button builder to belong to two categories, and defines five additional keywords.
|ModifierInitializerTranslations ||When the fields of a new BuilderCall are initialized, the type of the currently selected GenElement is compared to the names of the BuilderInputs, using the ModifierInitializerTranslations table. The type of the GenElement is compared to the type specified by the genelement attribute of each translation. If that matches, then the BuilderInput specified by the builderinput attribute is initialized to the name of the GenElement. |
For example, if the GenElement Page: page1 is selected in the Application Tree, and an instance of the builder with the example above is created, the field PageName is populated with the value page1. For example:
<Translation genelement="Page" builderinput="PageName" />
<Translation genelement="Control" builderinput="CreateTagsLocation" />
<Translation genelement=" [Unassigned Elements]" builderinput="CreateTagsLocation" />
|BuilderData||Contains BuilderDataEntry elements.|
|BuilderDataEntry||Set the value of the name attribute for this element to BuilderClassName and the value for this element to the builder generation class fully-qualified name. For example: |
|CoordinatorClassName||Optional. If you create a coordinator class to add logic to the builder call editor for the builder, set this element value to the coordinator class fully-qualified class name. For example:|
|AddFromPaletteListenerClassName||Specify one of the following elements.|
In the element, specify the descriptor for the class that implements IModelEditorAddFromPaletteListener or Extends BaseAddFromPaletteListener.
The default class indicates that the builder supports the ability to be dropped onto a WebSphere Portlet Factory Designer page. The item is displayed in the palette under its default category. When the item is dropped onto the WebSphere Portlet Factory Designer, the default palette listener class opens the related builder in a dialog and uses a default page location, if it is available. The dialog allows the user to enter any needed data. After the user accepts the dialog, the model is regenerated and any visible changes are displayed.
If the builder does more than the default implementation, you can identify a class that implements the IModelEditorAddFromPaletteListener class. This class allows you to add multiple items to the palette or do something more than use the builder dialog. You can identify a class that extends BaseAddFromPaletteListener which handles getting icons and tooltips and supports having a single item added from the builder.
Palette support has the following BuilderDataEntry elements.
Specifies the name that the base palette handler uses to get the icon. The base palette handler assumes that the icons are in the visualdesigner plugin in the icons\palette
directory and that the large and small icons names end in 24.png
The IDesigner interface has support for the palette.
- One of the following elements.
Specifies the value that is used by the base palette listener to change the default values for the page location. By default, the page location is after or below the tag on which it was dropped. If you set this value to Implicit and the builder has an implicit setting for the page (for example, style sheets being in the HEAD section), the builder editor uses that default as the page location. If you set this to onNamedTag, the item replaces the current tag. (This value is used for a builder like HTML Event Action. )
- One of the following elements.
<BuilderDataEntry name="ExtraWarning">Deleting/disabling this builder will cause
all dragging of design items to be lost from this page?</BuilderDataEntry>
This message is used for both disabling and deleting the builder. If you have a builder that creates multiple design items and the user is deleting or disabling the builder, the WebSphere Portlet Factory Designer provides an extra level of warning. Specify a message that can be translated and the builder can display a message that it is not generic.