Builder Skeleton Builder

Builder Skeleton Builder

In this topic ...

How do I...
Specifying Inputs
Objects Builder Creates

Related Topics...

Builder Architecture Overview

The Builder Skeleton Builder provides a quick, automated starting point for making new builders. It generates a lot of the basic code we need when creating Builders, presents a simple user interface for specifying the information about a builder, and generates all the necessary files required by the builder.
Note that If you've installed the "Tutorials and Samples - Builders" Feature Set, a tutorial is available to help you learn how to use the Builder Skeleton. To access this tutorial install the Feature Set and in the WebSphere Portlet Factory Designer Help system Table of Contents select: Tutorials | Builder Tutorials | Creating a Custom Builder.
Review Builder Architecture Overview for detailed information about Builders, their architecture, components, and regeneration behavior.

How do I...

Create a Builder Definition File

Create a Coordinator

Create a New Model Wizard

Specifying Inputs

The Builder Skeleton builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see "Using the Builder Call Editor" Depending on the Builder Type you choose, some or all of the following inputs might be available.

Input Name Description
Reset all inputs to defaults Click to clear all the Builder call editor input fields and restore their default contents.
This allows you to start creating a new builder with a clean slate.
Builder Type Select the type of Builder to create by choosing:

Basic Builder - This is the basic WebApp Builder interface. The generated Builder class has a 'doBuilderCall' method you can edit to implement your desired functionality.
Page Control Builder - This is used for Builders that put JSP or HTML on a page at a specified location. The page location is passed as an argument to the 'doBuilderCall' method.
Model-Based Builder - This is used to create a Builder from a model. To do this, you have to first make a model and profile all the inputs that you want to expose in your new Builder.
Model-Based Wizard Builder - Creates the code necessary to add a wizard that implements the "New Factory Model" functionality.

Model Name
This input is available when Builder Type is "Model-Based Builder" or "Model-Based Wizard."
Specify the name of a model that contains the functionality you want encapsulate into a Builder.
Builder ID Specify the unique ID of the Builder. The format of this ID should be that of a fully-qualified Java class name.
For example: com.acme.builder.MyCustomBuilder
Readable Name
Specify the user-visible name of the Builder. The name you enter here will be displayed in the Designer's Builder Palette.
The WebSphere Portlet Factory does not support the use of bi-directional 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.
Description Specify a Builder description.
Text you enter here will be displayed at the top of the Builder's editor page and should describe the Builder's functionality.
Builder Class Specify the full classname for the Builder's regen class to be generated
This input defaults to the value of the Builder ID input.
Update Builder Input names from model For model-based Builders, press this button to incorporate changes made in the Builder's underlying model into the builder itself.
You might need to update input names if you add, delete or change an input in the model that represents your builder.
Generate Coordinator Enable to generate a coordinator class for implementing dynamic Builder call editor behavior.
For example, we can use this feature to make input values drive the layout of the Builder's user interface. For example, when a user selects a particular input, additional inputs can be displayed dynamically as required.
Coordinator Class Specify the full classname for the coordinator to be generated, or the existing coordinator to be used.
Generate Helper Enable to generate a Builder helper LJO class.
This class can be used to implement methods that can be called during execution.
Helper Class Available when Generate Helper is checked. Specify the full class name for the helper LJO class to be generated.
For example: com.mycompany.runtime.DataRetrievalHelper
Category Specify the category, if any, under which you want this Builder to appear in the Builder palette.
If no category is specified, an error will be generated and the builder will be unavailable.
Help File Specify the name and path of the HTML help file for this Builder. This file will be displayed when a user presses the Help button in the Builder Call editor.
If no help file is specified, no help will be available for the builder.
Required Version Specify the minimum version of Designer required for use with this Builder.
If no required version is specified, all Designer versions will attempt to load and use this builder without warning.
Generate Builder API Enable to generate a Builder API class for your Builder.
This will allow other Builders to programmatically invoke this Builder.
The Builder can be accessed by model-based builders whether or not an API class is generated, but this class simplifies the development of Java-based builders that may want to invoke this builder.
Builder Pages
This input is available when Builder type is Model-Based Wizard.
Use this input to identify the various pages in the wizard. For each page in your wizard, we can specify the internal ID, the user-visible name, and a description for the page
Builder Inputs Use the Builder Inputs section to identify the inputs you want to make available in your Builder. Inputs you create here will be displayed in your Builder's UI.
To delete an input you have created, right-click on the input name and select "Delete Row."
For each input, we can provide some or all of the following information:

Name - A name identifying the input.
Input Type - The type of input widget used to represent the input. For example, you might choose a text box, list table, model picker or indirect reference. The appropriate widget will be used based on your choice.
Prompt - Text displayed adjacent to the input identifying it.
Help Text - Text string displayed when a user hovers over the input with the cursor.
Profile Type -
Is Required - Enable to make input a required value. This will force the user to provide this input.
Visible Input - Enable to display this input in the Builder's editor page. Disable to hide the input. You might want to hide an input if it's value is taken from another source, such as a when an underlying input is computed from two or more visible inputs. Inputs may also be hidden initially and then later made visible by the coordinator when the value of some other input changes.
Callable Input - If you are generating a Builder API, enable to make this input public in the Builder's API. Disable to make the input private and thus unavailable.
Extra Data - If the builder input s editor presents a list of choices (Combo box or Radio button, etc.), then the values to display can be specified here in a comma-separated list. For other input types this can be left blank.

Objects this Builder Creates

Builder Skeleton generates these files that are used when creating a Builder:

BuilderDef (under the WEB-INF/Builders folder) -- XML file that defines the Builder. Specifies the name and description of the Builder, the Builder s Java class name, the Builder help filename, and more. It also describes all of the Builder inputs, so that a rich, consistent user interface can be automatically generated when the Builder is used.
Builder Java class -- This is the Builder s regen class, with a "doBuilderCall" method that is called whenever a model containing your Builder is regenerated. The "doBuilderCall" method must be implemented to modify the WebApp object that is passed as an argument. To do this, the Builder can call methods on the WebApp directly, or it can invoke any other Builders in the system.

The generated Builder class has an inner "Constants" class containing definitions of all the Builder input names. These constants are available in all of the other generated Java classes. The generated code for doBuilderRegen also generates variables, which are initialized to the values of each of the Builder inputs.

Coordinator Java Class (Optional) -- Java class that can be used to implement custom dynamic user interface for the Builder. For example, we can create a Coordinator when you want a selectable list of choices obtained by calling into some library. Or, you might have one checkbox input which controls showing and hiding other inputs. The generated coordinator class automatically creates a structure with variables for each of your Builder inputs. See the generated sample code for examples.
Helper LJO Java Class (Optional) -- Many Builders make use of a Java class that can be called during execution of the model (this is quite different from the Builder s regen class, which is called during regen but never during application execution). For example, the Service Call Builder has a helper class with an "invoke" method and other useful execution-time methods. When you generate a helper class, the helper extends the Factory s BuilderHelper class, which makes it easy to access properties and indirect values from Builder inputs.

All the Java files are generated under the WEB-INF/work/source folder, for easy editing within the project.

Input Name	Description
Reset all inputs to defaults	Click to clear all the Builder call editor input fields and restore their default contents. This allows you to start creating a new builder with a clean slate.
Builder Type	Select the type of Builder to create by choosing: Basic Builder - This is the basic WebApp Builder interface. The generated Builder class has a 'doBuilderCall' method you can edit to implement your desired functionality. Page Control Builder - This is used for Builders that put JSP or HTML on a page at a specified location. The page location is passed as an argument to the 'doBuilderCall' method. Model-Based Builder - This is used to create a Builder from a model. To do this, you have to first make a model and profile all the inputs that you want to expose in your new Builder. Model-Based Wizard Builder - Creates the code necessary to add a wizard that implements the "New Factory Model" functionality.
Model Name	This input is available when Builder Type is "Model-Based Builder" or "Model-Based Wizard." Specify the name of a model that contains the functionality you want encapsulate into a Builder.
Builder ID	Specify the unique ID of the Builder. The format of this ID should be that of a fully-qualified Java class name. For example: com.acme.builder.MyCustomBuilder
Readable Name	Specify the user-visible name of the Builder. The name you enter here will be displayed in the Designer's Builder Palette. The WebSphere Portlet Factory does not support the use of bi-directional 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.
Description	Specify a Builder description. Text you enter here will be displayed at the top of the Builder's editor page and should describe the Builder's functionality.
Builder Class	Specify the full classname for the Builder's regen class to be generated This input defaults to the value of the Builder ID input.
Update Builder Input names from model	For model-based Builders, press this button to incorporate changes made in the Builder's underlying model into the builder itself. You might need to update input names if you add, delete or change an input in the model that represents your builder.
Generate Coordinator	Enable to generate a coordinator class for implementing dynamic Builder call editor behavior. For example, we can use this feature to make input values drive the layout of the Builder's user interface. For example, when a user selects a particular input, additional inputs can be displayed dynamically as required.
Coordinator Class	Specify the full classname for the coordinator to be generated, or the existing coordinator to be used.
Generate Helper	Enable to generate a Builder helper LJO class. This class can be used to implement methods that can be called during execution.
Helper Class	Available when Generate Helper is checked. Specify the full class name for the helper LJO class to be generated. For example: com.mycompany.runtime.DataRetrievalHelper
Category	Specify the category, if any, under which you want this Builder to appear in the Builder palette. If no category is specified, an error will be generated and the builder will be unavailable.
Help File	Specify the name and path of the HTML help file for this Builder. This file will be displayed when a user presses the Help button in the Builder Call editor. If no help file is specified, no help will be available for the builder.
Required Version	Specify the minimum version of Designer required for use with this Builder. If no required version is specified, all Designer versions will attempt to load and use this builder without warning.
Generate Builder API	Enable to generate a Builder API class for your Builder. This will allow other Builders to programmatically invoke this Builder. The Builder can be accessed by model-based builders whether or not an API class is generated, but this class simplifies the development of Java-based builders that may want to invoke this builder.
Builder Pages	This input is available when Builder type is Model-Based Wizard. Use this input to identify the various pages in the wizard. For each page in your wizard, we can specify the internal ID, the user-visible name, and a description for the page
Builder Inputs	Use the Builder Inputs section to identify the inputs you want to make available in your Builder. Inputs you create here will be displayed in your Builder's UI. To delete an input you have created, right-click on the input name and select "Delete Row." For each input, we can provide some or all of the following information: Name - A name identifying the input. Input Type - The type of input widget used to represent the input. For example, you might choose a text box, list table, model picker or indirect reference. The appropriate widget will be used based on your choice. Prompt - Text displayed adjacent to the input identifying it. Help Text - Text string displayed when a user hovers over the input with the cursor. Profile Type - Is Required - Enable to make input a required value. This will force the user to provide this input. Visible Input - Enable to display this input in the Builder's editor page. Disable to hide the input. You might want to hide an input if it's value is taken from another source, such as a when an underlying input is computed from two or more visible inputs. Inputs may also be hidden initially and then later made visible by the coordinator when the value of some other input changes. Callable Input - If you are generating a Builder API, enable to make this input public in the Builder's API. Disable to make the input private and thus unavailable. Extra Data - If the builder input s editor presents a list of choices (Combo box or Radio button, etc.), then the values to display can be specified here in a comma-separated list. For other input types this can be left blank.