Builder definition structure - Portlet Factory v6.1.2

Portlet Factory, Version 6.1.2

Builder definition structure

The builder definition file has a formal structure.
The following are sample tags in the builder definition file.
<BuilderDef> <ReadableName /> <GenHandlerClassName /> <GenerationPasses /> <HelpFile /> <RequiredFactoryVersion /> <Description /> <Domains> <Domain /> ... </Domains <CoordinatorClassName /> <BuilderData> <BuilderDataEntry /> ... </BuilderData> <InputDefinitions> <InputDefinition /> ... </InputDefinitions> <Editors> <Editor /> </Editors> </BuilderDef>

The following table describes each of the elements in the builder definition:

Element Name Description
CanCreate From an element in the Application tree or the graphical view, if the user has selected a category, such as "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 bdefs that have declared that they "CanCreate" or "CanModify" a particular type of element.
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 declares the Button Builder to belong to two categories, and defines five additional keywords.
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.
ModifierInitializerTranslations When initializing the fields of a new BuilderCall, 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, then the field "PageName" will be automatically populated with the value "page1." For example:
<BuilderDataEntry name="ModifierInitializerTranslations"> <Translation genelement="Page" builderinput="PageName" /> <Translation genelement="Control" builderinput="CreateTagsLocation" /> <Translation genelement="[Unassigned Elements]" builderinput="CreateTagsLocation" /> </BuilderDataEntry>

BuilderDef Besides containing the rest of the elements in the builder definition, the BuilderDef element has an id attribute that you set to the file path and name of the builder definition file. The path is relative from the IBM® WebSphere Portlet Factory WEB-INF/builders directory and directory names are separated using dots (.) as in Java™ package names. For example, <BuilderDef id="com.bowstreet.builders.webapp.ButtonBuilder">
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>
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 will be similiar to: <HelpFile>acme/builders/automated_site.htm</HelpFile>
where acme/builders is the directory in which the help file, automated_site.htm resides.
RequiredFactoryVersion Set this element value to correspond to the core WebSphere Portlet Factory 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>
Note: Do not set this value to the displayable product version as shown in WebSphere Portlet Factory Designer. In some cases, version value will represent versions of the plugins, not of WebSphere Portlet Factory.
Description Set this element value to the text that you want displayed in the builder call editor for this builder. For example:
<Description> Add a button to one or more pages in the model. </Description>

Domains Contains Domain elements.
Domain All builders specify at least one domain:
<Domain>WebApp</Domain>

CoordinatorClassName Optional. If you created 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:
<CoordinatorClassName> com.bowstreet.builders.webapp.ServiceCallBuilderCoordinator </CoordinatorClassName>

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:
<BuilderDataEntry name="BuilderClassName"> com.bowstreet.builders.webapp.ButtonBuilder </BuilderDataEntry>

InputDefinitions Contains InputDefinition elements.
InputDefinition Contains elements that define the input type, associated widgets to edit the input, the prompt to display for the input, and help text to display as a caption for the input. For example:
<InputDefinition name="ActionType" base="com.bowstreet.core.Base.Select"> <Editor> <Argument name="listData">form,link,script</Argument> </Editor> <Prompt>Action Type</Prompt> <HelpText>Determines whether clicking this button submits a form, links to another page, or executes a script. </HelpText> </InputDefinition>

Parent topic: About adding elements to pages in the web application

Library | Support |

Element Name	Description
CanCreate	From an element in the Application tree or the graphical view, if the user has selected a category, such as "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 bdefs that have declared that they "CanCreate" or "CanModify" a particular type of element.
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 declares the Button Builder to belong to two categories, and defines five additional keywords.
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.
ModifierInitializerTranslations	When initializing the fields of a new BuilderCall, 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, then the field "PageName" will be automatically populated with the value "page1." For example: <BuilderDataEntry name="ModifierInitializerTranslations"> <Translation genelement="Page" builderinput="PageName" /> <Translation genelement="Control" builderinput="CreateTagsLocation" /> <Translation genelement="[Unassigned Elements]" builderinput="CreateTagsLocation" /> </BuilderDataEntry>
BuilderDef	Besides containing the rest of the elements in the builder definition, the BuilderDef element has an id attribute that you set to the file path and name of the builder definition file. The path is relative from the IBM® WebSphere Portlet Factory WEB-INF/builders directory and directory names are separated using dots (.) as in Java™ package names. For example, <BuilderDef id="com.bowstreet.builders.webapp.ButtonBuilder">
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> 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 will be similiar to: <HelpFile>acme/builders/automated_site.htm</HelpFile> where acme/builders is the directory in which the help file, automated_site.htm resides.
RequiredFactoryVersion	Set this element value to correspond to the core WebSphere Portlet Factory 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> Note: Do not set this value to the displayable product version as shown in WebSphere Portlet Factory Designer. In some cases, version value will represent versions of the plugins, not of WebSphere Portlet Factory.
Description	Set this element value to the text that you want displayed in the builder call editor for this builder. For example: <Description> Add a button to one or more pages in the model. </Description>
Domains	Contains Domain elements.
Domain	All builders specify at least one domain: <Domain>WebApp</Domain>
CoordinatorClassName	Optional. If you created 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: <CoordinatorClassName> com.bowstreet.builders.webapp.ServiceCallBuilderCoordinator </CoordinatorClassName>
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: <BuilderDataEntry name="BuilderClassName"> com.bowstreet.builders.webapp.ButtonBuilder </BuilderDataEntry>
InputDefinitions	Contains InputDefinition elements.
InputDefinition	Contains elements that define the input type, associated widgets to edit the input, the prompt to display for the input, and help text to display as a caption for the input. For example: <InputDefinition name="ActionType" base="com.bowstreet.core.Base.Select"> <Editor> <Argument name="listData">form,link,script</Argument> </Editor> <Prompt>Action Type</Prompt> <HelpText>Determines whether clicking this button submits a form, links to another page, or executes a script. </HelpText> </InputDefinition>