Create builder definitions

Create builder definitions

The builder definition is an XML file that defines the builder's characteristics such as the builder's generation class help file, domain type, and Builder Palette category. The builder definition also defines the inputs to the builder and the editors with which users can specify the builder inputs.
The following code sample shows the builder definition file for a Hello World builder:

<?xml version="1.0"?> <BuilderDef id="com.bowstreet.examples.builders.webapp.HelloWorldBuilder" xmlns="http://www.bowstreet.com/2001/Schemas"> <ReadableName>Hello World</ReadableName> <GenHandlerClassName> com.bowstreet.builders.webapp.foundation.WebAppControlGenHandler </GenHandlerClassName> <HelpFile>help/fileName.html</HelpFile> <RequiredFactoryVersion>5.8.2</RequiredFactoryVersion> <Description>Hello World Builder</Description> <Domains> <Domain>WebApp</Domain> </Domains> <!-- Add the Hello World builder to the Pages Category in the Builder Palette -| <Category>Page and Layout</Category> <BuilderData> <BuilderDataEntry name="BuilderClassName"> com.bowstreet.examples.builders.webapp.HelloWorldBuilder </BuilderDataEntry> </BuilderData> <InputDefinitions> <InputDefinition name="Name" base="com.bowstreet.core.Base.BuilderName" /> <!-- Add a page location widget to the Builder Call Editor -| <InputDefinition name="PageLocation" base="com.bowstreet.core.WebAppBase.PageLocation" /> <!-- Add a text input box that can also use the Reference Chooser to populate the value -| <InputDefinition name="DisplayText" base="com.bowstreet.core.Base.IndirectValue"> <Prompt>Hello World Text</Prompt> <HelpText>Enter a String value or Indirect Reference to a String that you want to display as the "Hello, world" text.</HelpText> </InputDefinition> </InputDefinitions> </BuilderDef>

To learn more about builder definitions, install the "Tutorials and Samples - Builders" Feature Set.
The rest of this topic describes how to define the inputs to your builder. For information on setting the top-level elements in the builder definition, see the description of the builder definition elements in the Creating Builders Overview.

Defining Inputs for Your Builder

An input definition is a structure in the builder definition that describes the input for a builder in terms of its type, editor widget (text input, select box, etc.), the input group to which it belongs and other similar information. The input definitions you create only need to specify values for the elements not defined by a base builder definition or those elements that you want to override.
The table below lists and describes each of the elements used to to define an input to a builder:

Input Definition Element Description
<Prompt /> The user-readable description for this input. The Builder Call Editor displays this value to the left of the input's editor widget.
<HelpText /> The text that appears as a tool tip when the user hovers over the input in the Builder Call Editor.
<ProfileType /> The type of value set when the user profiles the input. Possible values for the ProfileType are:

None -- The input value cannot be profiled.
Value -- The entire input value can be profiled.
XmlElements -- (Valid for XML type input only) Individual String values within the XML can be profiled.

<Callable /> Determines whether accessor methods should be generated for this input in the "callable" version of this builder. Possible values are true or false.
<Editor /> Determines the input widget displayed in the Builder Call Editor that allows the user to specify a value to this input. If you are extending a base input definition, the editor is already specified by the base definition.
<Visible /> Determines whether the Builder Call Editor displays the input widget for this input by default. We can set the Visible value for one or more input defintions as false, and use a Coordinator to set the Visible value for those inputs to true, based on some condition.

Inheriting Input Definitions from the Base Builder Definition

The following table describes each of the input types defined in the Base builder definition. Using the resources contained here is the preferred way to create invoke input types. (If you do not find a type here. see the next table for advanced types.)
The Base.bdef file is in the WEB-INF/builders/com/bowstreet/core directory and contains the following types:

Input Value Editor Widget Arguments
A long String BigString

linewrap -- Specify whether lines are clipped or wrapped (default false)
data text to display
isEditable -- Specify if the user can directly type in data (default is true)
Action event is triggered on focus loss (mouse)

A boolean value BooleanData n/a
The name of the builder BuilderName n/a
The name of the builder as a required input. RequiredBuilderName n/a
The name of the builder must fit parameters you define. RestrictedBuilderName n/a
A button to execute some action from the Builder Call Editor. Button

Label the text to show on the button
Event: Action event triggers on a button press (mouse click, return key).
Default size to that required of text.

An editable combo box that allows the user to select a value from a pre-determined list. ComboBox

isEditable -- Specify if the user can directly type in data (default is false)
listData -- Set pick list using data encoded in a comma-delimited string
listLabels -- Set pick list displayable labels using names encoded in a comma-delimited string
listDataObject -- Set pick list at runtime using a java.util.List object
listLabelsObject -- Set pick list displayable labels using a java.util.List object
selectItem -- Set selection
Action event triggers on a selection change.

A file on the development machine. FileChoose

Action event triggers on selection change.

A file name determined by a variable or method in the WebApp. IndirectFileChoose n/a
The name of a file to be used as an HTML resource such as an image or HTML page. Only files that reside in the Factory's servable content root directory. ServableContent n/a
The name of a servable file determined by a variable or method in the WebApp. IndirectServableContent n/a
The name of an item in a pre-determined list or a value from an object (method, page, variable, input) in the WebApp. IndirectComboBox n/a
The output of an object in the WebApp. IndirectValue

Action event triggers on a selection change.

The body of a Method builder call.
Not commonly used.
MethodBody

keywordColor -- Syntax highlighting color for Java key words
commentColor ---Syntax highlighting color for code comments
stringColor -- Syntax highlighting color for literal strings
Change event is triggered on focus loss (mouse)

The name of a model . Model

Filter used when generating list of models to display
Action event triggers on selection change.

The name of a model determined by the value of a variable or method in the WebApp. IndirectModel n/a
The content of an HTML or JSP page.
Not commonly used.
PageData n/a
The name of a page in the WebApp. PageName n/a
A read-only String value. ReadOnlyStringData

label -- text to display for the input label
No action is triggered for this widget.

A read-only XML structure. ReadOnlyXMLData n/a
A String value chosen from a pre-determined list of options in a select box. Select n/a
A String value. StringData

data -- Text to display as the input value
Action event is triggered on focus loss (mouse or tab key or return key)

The name of a variable in the WebApp. VariableName n/a
The value of a variable in the WebApp. VariableValue n/a
A name/value listing of arguments to a method.
Not commonly used.
Arguments n/a
A determination that evaluates argument values at generation time or at execution time.
Not commonly used.
EarlyArgumentEvaluation n/a
A name/value list of argument names and values for a specified action.
Not commonly used.
InputMappings n/a
Expose element to a linked model. Public n/a
Enable/disable a builder call. BuilderCallEnabled n/a
Specify a category for the builder call. BuilderCallCategory n/a
Add a comment to the builder call. BuilderCallComment n/a
Advanced Group n/a
Arguments Group n/a
Properties Group n/a

Advanced Widget Usage

This section provides details on all widget names and arguments provided by the Designer for use by builder authors.
Note IBM recommends that you use the input definitions provided in the com.bowstreet.core.Base.bdef and com.bowstreet.core.WebAppBase.bdef. However, in cases where this does not provide the needed functionality, the widgets described in this section can be used directly.
Abstract Widget Classes

Note that the arguments defined in these abstract classes will be available to all subclasses.
1. com.bowstreet.designer.builders.widgets.AbstractBuilderWidget
      Description: Base class for generic builder widgets. All other abstract widget classes extend this class.
      Arguments:

Name Type Description
enabled true/false (true) Whether or not the underlying SWT widget is enabled.

2. com.bowstreet.designer.builders.widgets.AbstractButtonWidget
      Description: Abstract base class for button type widgets.
      Arguments: None
3. com.bowstreet.designer.builders.widgets.AbstractChooserWidget
      Description: Abstract base class for "chooser" type widgets, i.e. a text field with an attached button which will display a picker allowing the user to choose an appropriate value.
      Arguments:

Name Type Description
append true/false (true) If set to true, the value selected in the chooser will be inserted into the text field at the cursor location- if false, any value in the text field will be replaced.

  4. com.bowstreet.designer.builders.widgets.AbstractComboListWidget
      Description: Abstract base class for select or combo type widgets which are populated by the widget class itself (for example, by values from the WebApp).
      Arguments:

Name Type Description
isEditable true/false (false) Whether or not the select list can be edited directly by user.

5. com.bowstreet.designer.builders.widgets.AbstractStyledTextWidget
      Description: Abstract base class for text type widgets which have text formatting capabilities.
      Arguments:

Name Type Description
inewrap true/false (false) Whether or not line wrapping is enabled for the text widget.

6. com.bowstreet.designer.builders.widgets.AbstractTextWidget
      Description: Abstract base class for text widgets.
      Arguments:

Name Type Description
data string Initial value for widget
filter **Alphabetic
**AlpahNumeric
**ObjectName (none) Filter for values entered into text widget.

7. com.bowstreet.designer.builders.widgets.AbstractUpdateableBuilderWidget
      Description: Abstract base class for widgets which will be notified when the open is generated, and given a chance to update themselves.
      Arguments:

Name Type Description
label string label for button

Concrete Widget Classes

There are many concrete widget classes we can use. Click here to view a list of these classes and their related arguments.

Inheriting Input Definitions from the WebAppBase Builder Definition

The following table describes some of the input types defined in the WebAppBase builder definition. Refer to the WebAppBase.bdef file in the WEB-INF/builders/com/bowstreet/core directory:

Input Value Editor Widget
PageLocation Page Location chooser that allows the user to choose one or more locations on a page on which the builder operates.
WebAppAction WebAppActionList chooser that allows the user to select a Page or Method in the model.

Suppressing the Display of an Input

We can designate an input definition to be hidden from the Builder Call Editor by adding (or setting) the input definition's <Visible /> value to "false." For example,
<InputDefinition name="CustomerName" base="com.bowstreet.core.Base.IndirectValue">
   <Prompt>Customer Name</Prompt>
   <Visible>false</Visible>
</InputDefinition>

Grouping Inputs

We can organize inputs by including the common groups such as "Advanced", "HTML Attributes," or "Arguments," shown in the Factory's builder call editors or by creating your own input groups.
To include an Arguments input group in your builder call editor:

Include one or more input definitions whose base is in the "Advanced" group in the Base.bdef file. For example:

      <!-- Adds an Arguments list control to the builder call editor -|
      <InputDefinition name="ArgumentsInput" base="com.bowstreet.core.Base.Arguments" />

      <!-- Adds an Evaluate Arguments checkbox control to the builder call editor -|
      <InputDefinition name="EvalArgsInput" base="com.bowstreet.core.Base.EarlyArgumentEvaluations" />

Include the "Arguments" group definition in your builder definition file:

      <GroupDefinitions>
         <GroupDefinition id="Arguments" base="com.bowstreet.core.Base.Arguments" />
      </GroupDefinitions>
To include an Advanced input group in your builder call editor:
The Advanced inputs are builder-specific and the Base.bdef does not include any common Advanced input definitions. We can declare inputs to be in the Advanced group by performing the following steps below.

Set the <Group/> value in your input definition to "Advanced" for any inputs you want included in the Advanced group. For example,

      <InputDefinition name="AdvancedInput1" base="com.bowstreet.core.Base.IndirectValue">
         <Prompt>Advanced Input 1</Prompt>
         <Group>Advanced</Group>
      </InputDefinition>

      <!-- Adds a String input to the Advanced group -|
      <InputDefinition name="AdvancedInput2" base="com.bowstreet.core.Base.StringData">
         <Prompt>Advanced Input 2</Prompt>
         <Group>Advanced</Group>
      </InputDefinition>


Include the "Advanced" group definition in your builder definition file:

      <GroupDefinitions>
         <GroupDefinition id="Arguments" base="com.bowstreet.core.Base.Arguments" />
         <GroupDefinition id="Advanced" base="com.bowstreet.core.Base.Advanced" />
      </GroupDefinitions>

Create Your Own Builder Input Groups

We can create your own input groups by creating a group definition and setting the <Group/> value for the input definitions you want to display as a group. The XML below shows the syntax for a group definition:
    <GroupDefinitions>
        <GroupDefinition id="MyInputsGroup">
            <Name>Inputs for Me</Name>
            <Description>Set these inputs to something</Description>
            <BorderStyle>Etched</BorderStyle>
            <IsCollapsible>true</IsCollapsible>
            <InitiallyCollapsed>true</InitiallyCollapsed>
        </GroupDefinition>
        <GroupDefinition id="Arguments" base="com.bowstreet.core.Base.Arguments" />
    </GroupDefinitions>
Any input definitions with the <Group/> value set to "MyInputsGroup" get included in the group:
<InputDefinition name="VariableValue" base="com.bowstreet.core.Base.VariableValue">
   <Prompt>Variable Value</Prompt>
   <Group>MyInputsGroup</Group>
</InputDefinition>

Inheriting Input and Coordinator Behavior

An Input Definition can inherit from any other Input Definition in the system, by setting the "base" attribute of the InputDefinition to the Builder ID followed by the input name. For example, the following input inherits from the ServableContent input defined in com/bowstreet/core/Base.bdef:
    <InputDefinition name="ImportedPage_URL" base="com.bowstreet.core.Base.ServableContent">
      <Prompt>URL</Prompt>
      <InitialValue />
      <HelpText />
      <Required>true</Required>
      <Visible>true</Visible>
      <ProfileType>Value</ProfileType>
      <Callable>true</Callable>
    </InputDefinition>
Input Definitions can inherit in this way from any Factory or custom Builders.
We can also inherit Coordinator behavior from another Builder. For example, if you have a Coordinator that initializes a Select input with a list of files from a particular folder, we can inherit that behavior in any other builders. To do this, first set the "base" attribute for the Input Definition as described above. Then, add an element called UseAssociatedCoordinator to the Input Definition with a value of "true." Here is an example from the Sample Input Types Builder in the "Tutorials and Samples - Builders" feature set:
        <InputDefinition name="SchemaFileName" base="com.bowstreet.samples.builders.SampleCoordinatorBuilder.SchemaFile">
            <Prompt>SchemaFileName</Prompt>
            <Required>false</Required>
            <Group>CustomPickers</Group>
            <HelpText>Example of inherited Coordinator behavior</HelpText>
            <UseAssociatedCoordinator>true</UseAssociatedCoordinator>
        </InputDefinition>
The "UseAssociatedCoordinator" element can be set in the derived input, as in the example above, or it can be set in the base input. If it is set in the base input, any inputs that inherit using the "base" attribute will automatically inherit the Coordinator behavior. This can provide a simple mechanism for creating your own set of pickers.
This Coordinator inheritance can be used for individual Input Definitions as in the example above, or it can be used for sets of cooperating inputs, such as when a choice in one input is used to populate a list of choices in another input.
There is a companion element to UseSharedCoordinator called "CoordinatorNamespace": this element allows you to give a name to one or more inputs to allow the coordinator sharing feature to distinguish these groups from each other. For example:
        <InputDefinition name="Shared1" base="TheBaseBuilder.TheBaseInput">
            <UseAssociatedCoordinator>true</UseAssociatedCoordinator>
            <CoordinatorNamespace>FirstSharedInput</CoordinatorNamespace>
        </InputDefinition>
        <InputDefinition name="Shared2" base="TheBaseBuilder.TheBaseInput">
            <UseAssociatedCoordinator>true</UseAssociatedCoordinator>
            <CoordinatorNamespace>SecondSharedInput</CoordinatorNamespace>
        </InputDefinition>

Input Definition Element	Description
<Prompt />	The user-readable description for this input. The Builder Call Editor displays this value to the left of the input's editor widget.
<HelpText />	The text that appears as a tool tip when the user hovers over the input in the Builder Call Editor.
<ProfileType />	The type of value set when the user profiles the input. Possible values for the ProfileType are: None -- The input value cannot be profiled. Value -- The entire input value can be profiled. XmlElements -- (Valid for XML type input only) Individual String values within the XML can be profiled.
<Callable />	Determines whether accessor methods should be generated for this input in the "callable" version of this builder. Possible values are true or false.
<Editor />	Determines the input widget displayed in the Builder Call Editor that allows the user to specify a value to this input. If you are extending a base input definition, the editor is already specified by the base definition.
<Visible />	Determines whether the Builder Call Editor displays the input widget for this input by default. We can set the Visible value for one or more input defintions as false, and use a Coordinator to set the Visible value for those inputs to true, based on some condition.

Input Value	Editor Widget	Arguments
A long String	BigString	linewrap -- Specify whether lines are clipped or wrapped (default false) data text to display isEditable -- Specify if the user can directly type in data (default is true) Action event is triggered on focus loss (mouse)
A boolean value	BooleanData	n/a
The name of the builder	BuilderName	n/a
The name of the builder as a required input.	RequiredBuilderName	n/a
The name of the builder must fit parameters you define.	RestrictedBuilderName	n/a
A button to execute some action from the Builder Call Editor.	Button	Label the text to show on the button Event: Action event triggers on a button press (mouse click, return key). Default size to that required of text.
An editable combo box that allows the user to select a value from a pre-determined list.	ComboBox	isEditable -- Specify if the user can directly type in data (default is false) listData -- Set pick list using data encoded in a comma-delimited string listLabels -- Set pick list displayable labels using names encoded in a comma-delimited string listDataObject -- Set pick list at runtime using a java.util.List object listLabelsObject -- Set pick list displayable labels using a java.util.List object selectItem -- Set selection Action event triggers on a selection change.
A file on the development machine.	FileChoose	Action event triggers on selection change.
A file name determined by a variable or method in the WebApp.	IndirectFileChoose	n/a
The name of a file to be used as an HTML resource such as an image or HTML page. Only files that reside in the Factory's servable content root directory.	ServableContent	n/a
The name of a servable file determined by a variable or method in the WebApp.	IndirectServableContent	n/a
The name of an item in a pre-determined list or a value from an object (method, page, variable, input) in the WebApp.	IndirectComboBox	n/a
The output of an object in the WebApp.	IndirectValue	Action event triggers on a selection change.
The body of a Method builder call. Not commonly used.	MethodBody	keywordColor -- Syntax highlighting color for Java key words commentColor ---Syntax highlighting color for code comments stringColor -- Syntax highlighting color for literal strings Change event is triggered on focus loss (mouse)
The name of a model .	Model	Filter used when generating list of models to display Action event triggers on selection change.
The name of a model determined by the value of a variable or method in the WebApp.	IndirectModel	n/a
The content of an HTML or JSP page. Not commonly used.	PageData	n/a
The name of a page in the WebApp.	PageName	n/a
A read-only String value.	ReadOnlyStringData	label -- text to display for the input label No action is triggered for this widget.
A read-only XML structure.	ReadOnlyXMLData	n/a
A String value chosen from a pre-determined list of options in a select box.	Select	n/a
A String value.	StringData	data -- Text to display as the input value Action event is triggered on focus loss (mouse or tab key or return key)
The name of a variable in the WebApp.	VariableName	n/a
The value of a variable in the WebApp.	VariableValue	n/a
A name/value listing of arguments to a method. Not commonly used.	Arguments	n/a
A determination that evaluates argument values at generation time or at execution time. Not commonly used.	EarlyArgumentEvaluation	n/a
A name/value list of argument names and values for a specified action. Not commonly used.	InputMappings	n/a
Expose element to a linked model.	Public	n/a
Enable/disable a builder call.	BuilderCallEnabled	n/a
Specify a category for the builder call.	BuilderCallCategory	n/a
Add a comment to the builder call.	BuilderCallComment	n/a
	Advanced Group	n/a
	Arguments Group	n/a
	Properties Group	n/a

Name	Type	Description
enabled	true/false (true)	Whether or not the underlying SWT widget is enabled.

Input Value	Editor Widget
PageLocation	Page Location chooser that allows the user to choose one or more locations on a page on which the builder operates.
WebAppAction	WebAppActionList chooser that allows the user to select a Page or Method in the model.