Creating radio button group extensions in WebSphere Portlet Factory Designer

IBM® WebSphere® Portlet Factory Designer’s radio button group builder allows users to create radio button groups with corresponding labels. The groups can be rendered in one column or in one row. Three custom builders extend this base functionality by allowing any member of a radio button group to be associated with a text box or drop-down list, and by providing the ability to render the radio button group in a grid format, both horizontally and vertically. The three custom builders are the subject of this article.

Shannon N. Irvine (spixley@us.ibm.com), IT Specialist, IBM

Shannon N. Irvine is an IT Specialist in IBM Software Services for Lotus. She specializes in portlet application development. She has a Master’s Degree in Computer Science from Rensselaer Polytechnic Institute. She lives in Raleigh, NC. You can reach her at spixley@us.ibm.com.



29 June 2009 (First published 09 June 2009)

Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.

Introduction

This article discusses a set of custom builders developed for WebSphere Portlet Factory that extend the base functionality of the Radio Button Group builder provided in WebSphere Portlet Factory. The radio button group builder, which is ready to use without modification, allows each radio button to be associated with a label and a value. This base builder allows the layout of the group to be either horizontal or vertical. The builder, however, does not allow for more complex data input within radio button groups, such as displaying a text input box for a specific radio button within the group or a drop-down list for a specific radio button within the group.

The builder extensions, Radio Button Group Grid, Text Input Plus, and Select Plus, provide the ability to render radio button groups in a grid format and allow any member of a radio button group to be associated with a text box or drop-down list. For larger groups, it can be preferred to display the radio buttons in a grid layout.

The custom builders and a sample model demonstrating the usage of the custom builders are available for download with this article. This article assumes that you have hands-on experience with WebSphere Portlet Factory Designer and that you are comfortable creating models and using builders. At the time of this writing, the most current version of WebSphere Portlet Factory Designer is version 6.1.2. The custom builders and sample model accompanying this article run on WebSphere Portlet Factory 6.0 and later.


Overview of the sample model

The sample model contains eight radio button groups. These examples are referred to in later sections of the article. All eight examples are displayed on a page, with a single submit button beneath. Upon submission, the selected values are saved and text is written to the bottom of the page to verify the selection. The examples are independent of one another. Each example is added to the page using a single span tag, referencing the radio button group name, for example, <span name=”rbg1”></span>. The example radio button groups are named rbg1, rbg2, rbgg3, and so on, up to rbgg8.

The first two examples, shown in figure 1, are simple radio button groups built with the radio button group builder. In this article, the elements that we call "ready to use" are those that are included in the product and can be used immediately, without modification.

Figure 1. rbg1 and rbg2
rbg1 and rbg2

The third and fourth examples, shown in figure 2, demonstrate the grid feature of the radio button group Grid builder. Example 3 uses vertical wrapping, and example 4 uses horizontal wrapping. The radio button group grid builder and its features are discussed later in this article.

Figure 2. rbgg3 and rbgg4
rbgg3 and rbgg4

Examples 5 through 8, shown in figure 3, demonstrate radio button groups with incorporated text input plus builders and/or select plus builders. The text input plus and select plus builders are discussed later in this article.

Figure 3. rbgg5, rbgg6, rbgg7, rbgg8
rbgg5, rbgg6, rbgg7, rbgg8

JavaScript™ is incorporated into examples 5, 6, and 7 using the HTML Event Action builder. The JavaScript is used to automatically change the radio button selection when a change occurs in a drop-down list or when focus is given to a text input. The HTML builder is used in the same examples to slightly modify the alignment of the text inputs and select fields.

A portion of the model outline is shown in figure 4. The components of each example are grouped together. See the outlined rounded rectangle that highlights the components of example one, rbg1. The builders for examples 2 through 8 follow the same grouping.

Figure 4. Sample model outline
Sample model outline

Ready-to-use radio button groups

Radio button groups created with the radio button group builder consist of sets of radio buttons matched up with labels. The groups can be rendered in one column (vertically) or in one row (horizontally). Examples of radio button groups built with the radio button group builder included in WebSphere Portlet Factory are shown in the figures 5 and 6.

Figure 5. Radio button group rbg1 rendered vertically
Radio button group rbg1 rendered vertically
Figure 6. Radio button group rbg2 rendered horizontally
Radio button group rbg2 rendered horizontally

Figure 7 shows the ready-to-use Radio Button Group available in WebSphere Portlet Factory. In addition to selecting the page and tag and the source of the radio button group data, users also specify vertical or horizontal orientation.

Figure 7. Radio button group builder
Radio Button Group builder

The builder inputs for rbg1 are shown in figure 8. Enter the following:

  • In the Page field, select main.
  • In the tag field, select rbg1.
  • In the Lookup Table Used field, select None.
  • In the Radio Group Data field, enter A,B,C,D,E.
  • In the Selected Value field, select ${Variables/group1SelectedVar}.
  • In the Orientation field, select vertical.

Click OK.

Figure 8. rbg1 builder inputs
rbg1 builder inputs

The builder inputs for radio button group rgb2 are shown in figure 9. Enter the following:

  • In the Page field, select main.
  • In the tag field, select rbg2.
  • In the Lookup Table Used field, select None.
  • In the Radio Group Data field, enter One,Two,Three,Four.
  • In the Selected Value field, select ${Variables/group2SelectedVar}.
  • In the Orientation field, select horizontal.

Click OK.

Figure 9. rbg2 builder inputs
rbg2 builder inputs

Extensions

The custom extensions to the radio button group builder provide the following functionality:

  • The ability to render the radio button group in a grid format, both horizontally and vertically, rendered in one of two ways:

    • Render the buttons horizontally, and then wrap at a specified index and lay out another row of buttons
    • Render the buttons vertically, and then wrap at a specified index and lay out another column of buttons
  • The ability to associate any member of a radio button group with a text box or drop-down list. The radio button can optionally provide a label. The radio button group can be built with the ready-to-use builder or with the extended builder providing the grid layout.

Figures 10 and 11 are examples of radio button groups with the extended functionality of grid rendering. The examples can be found in the sample model. The builders are named rbgg3 and rbgg4.

Figure 10. Radio button group rbgg3 rendered as a grid, vertical layout, wrapping at an index of 3
Radio button group rbgg3 rendered as a grid, vertical layout, wrapping at an index of 3
Figure 11. Radio button group rbgg4 rendered as a grid, horizontal layout, wrapping at an index of 5
Radio button group rbgg4 rendered as a grid, horizontal layout, wrapping at an index of 5

Figures 12, 13, 14, and 15 are examples of text input and drop-down components used in conjunction with radio button groups. Notice how radio button groups can contain a mixture of labels, text inputs, and drop-down components.

Figure 12. Radio button group rbgg5 rendered vertically, with the first three options associated with labels and drop-down components
Radio button group rbgg5 rendered vertically, with the first three options associated with labels and drop-down components
Figure 13. Radio button group rbgg6 with vertical orientation, plus a text input associated with each radio button
Radio button group rbgg6 with vertical orientation, plus a text input associated with each radio button
Figure 14. Radio button group rbgg7 with vertical orientation, a text input associated with the first radio button, and a drop-down list associated with the second radio button
Radio button group rbgg7 with vertical orientation, a text input associated with the first radio button, and a drop-down list associated with the second radio button
Figure 15. Radio button group rbgg8, vertical layout, wrapping at an index of 5, second radio button associated with a text input, and eighth radio button associated with a drop-down list
Radio button group rbgg8, vertical layout, wrapping at an index of 5, second radio button associated with a text input, and eighth radio button associated with a drop-down list

The extensions described previously are implemented by three custom builders:

  • radio button group grid builder
  • text input plus builder
  • select plus builder

Radio button group grid builder

This new builder extends the functionality of the radio button group builder in WebSphere Portlet Factory, with the additional feature of allowing users the choice of rending the group into a grid. In figure 16, the option to Create Grid, shown in a rectangle, is an extension of the base Radio Button Group builder.

Figure 16. Radio button group grid builder inputs without grid
Radio button group grid builder inputs without grid

To render the group into a grid, select the box next to the Create Grid option. When this box is selected, another input field becomes visible, allowing users to specify the number of radio buttons to be rendered before the column or row wraps to the next. The input field # Options Before Wrap, shown in a rectangle in figure 17, is an extension to the base functionality of the radio button group builder.

Figure 17. Radio button group grid builder inputs with grid
Radio button group grid builder inputs with grid

If the orientation selected is vertical, then the radio button group places the elements vertically, wrapping at the specified index. Additional columns are added as needed to render the entire group. If the orientation is horizontal, then the radio button group places the elements horizontally, wrapping at the specified index. Additional rows are added as needed. When rendering vertically, the maximum number of rows in the grid is the number specified in the # Options Before Wrap option; when rendering horizontally, the maximum number of columns in the grid is the number specified in the # Options Before Wrap option.

Figure 18 shows the builder inputs of rbgg3. Enter these values:

  • In the Page field, select main.
  • In the Tag field, select rbgg3.
  • In the Radio Group Data field, enter 1,2,3,4,5.
  • In the Selected Value field, select ${Variables/group3SelectedVar}.
  • In the Orientation field, select vertical.
  • Select the Create Grid option.
  • In the # Options Before Wrap field, enter 3.

Click OK.

Figure 18. rbgg3 builder inputs
rbgg3 builder inputs

Figure 19 shows radio button group rbgg4 builder inputs. Enter these values:

  • In the Page field, select main.
  • In the Tag field, select rbgg4.
  • In the Radio Group Data field, select ${Variables/data4Var/choices}.
  • In the Value Element field, enter value.
  • In the Label element field, enter value.
  • In the Selected Value field, select ${Variables/group4SelectedVar}.
  • In the Orientation field, select horizontal.
  • Select the Create Grid option.
  • In the # Options Before Wrap field, enter 5.

Click OK.

Figure 19. rbgg4 builder inputs
rbgg4 builder inputs

If the Create Grid option is selected, but the # Options Before Wrap field is cleared, then the radio button group renders the group without wrapping. If the Create Grid option is not selected, then the radio button group grid builder functions just as the ready-to-use WebSphere Portlet Factory radio button group builder functions.


Select plus builder

The Select plus builder extends the functionality of the Select Input builder in WebSphere Portlet Factory by allowing the select (or drop-down) field to be associated with a specific member of a radio button group. The select plus builder can be associated with radio button groups built by the radio button group builder or the radio button group grid builder.

Figure 20. A drop-down field associated with a radio button group
A drop-down field associated with a radio button group

With the select plus builder, users can create user interface (UI) components consisting of a radio button, an optional label, and a select input (see figure 20). In comparison with the ready-to-use select builder, the select plus builder provides the same input fields, with additional input options that allow the drop-down list to be rendered as an element of a radio button group. The additional builder input fields are Target Group, Targeted Data Value, and Target Group Name. The Targeted Data Value and Target Group Name are not visible unless the Target Group field is selected as shown in figure 21.

The select plus builder extends the select builder by adding the fields surrounded by the rounded rectangle: Target Group, Targeted Data Value, and Target Group Name.

Figure 21. The select plus builder extends the select builder by adding the fields surrounded by the rounded rectangle
The select plus builder extends the select builder by adding the fields surrounded by the rounded rectangle

If the Target Group field is not selected, the select plus builder provides the same functionality as the select builder.

Radio button group rbgg5 consists of a set of four radio buttons. The first three have select boxes next to their labels, each with different choices. The radio button group rbgg5 and the select plus builder for the select box beside the child radio button are shown in figure 22.

In the Select Plus Properties window, enter the following:

  • In the Page field, select main.
  • In the Tag field, select rbgg5.
  • Select the Target Group option.
  • In the Targeted Data Value field, enter child.
  • In the Target Group Name field, enter rbgg4.
  • In the Lookup Table Used field, select none.
  • In the Select Date field, select ${MethodCall/getAgeGroupData(child)}.
  • In the Selected Values field, select${Variables/group5SelectPlus1Var}.
  • In the Value Element field, enter GroupRange.
  • In the Label Element field, enter GroupRange.
  • Select the option Retain original options.

Click OK.

Figure 22. rbgg5 builder inputs
rbgg5 builder inputs

The select plus builders for the adult radio button and the senior radio button are similar to the select plus builder for the child radio button. The only differences are that the Targeted Data Value options are replaced with the values adult and senior, the Select Data passes the argument adult and senior (respectively), and they have different variables for the Selected Values fields.


Text input plus builder

The text input plus builder extends the functionality of the text input builder in WebSphere Portlet Factory by allowing the text input to be associated with a specific member of a radio button group. The text input plus builder can be associated with radio button groups built by the radio button group builder or the radio button group grid builder.

Figure 23. A text input associated with a radio button group
A text input associated with a radio button group

With the text input plus builder, users can create UI components consisting of a radio button, an optional label, and a text input as shown in figure 23. In comparison with the ready-to-use text input builder, the text input plus builder provides the same input fields, with additional fields that allow the text input to be rendered as an element of a radio button group. These additional fields are Target Group, Targeted Data Value, and Target Group Name. The fields Targeted Data Value and Target Group Name are not visible unless the Target Group fields is selected as shown in figure 24.

The text input plus builder extends the text input builder by adding the fields surrounded with the rounded rectangle: Target Group, Targeted Data Value, and Target Group Name.

Figure 24. The text input plus builder extends the text input builder by adding the fields surrounded with the rounded rectangle
The text input plus builder extends the text input builder by adding the fields surrounded with the rounded rectangle

To associate a text input plus builder to a radio button group, do the following:

  • Specify the Page Location field entries that identify the page and tag name of the radio button group for which this text input is associated.
  • Select the option Target Group.
  • Enter the value for the Targeted Data Value field. Targeted Data Value is the value of the specific radio button in the group. If this field is cleared, then the Text Input builder does not render with an element of the radio button group.
  • Review the value that you use in the Target Group Name field. Target Group Name is the name of the radio button group, if one was provided. This field must be cleared if the radio button group was not given a name. If the name is not correct, then this mistake can cause errors and the builders cannot work together correctly.

If the Target Group field is not selected, then the text input plus builder provides the same functionality as the text input builder.

In the sample model, the radio button group rbgg6 contains text input plus builders to add text entries beside the radio buttons. The builder for the first text input plus is shown in figure 25.

In this window, enter the following:

  • In the Name field, enter group6Text InputPlus1.
  • In the Page field, select main.
  • In the Tag field, select rbgg6.
  • Select the Target Group option.
  • In the Targeted Data Value field, enter child.
  • In the Text field, enter ${Variables/group6TextVar1}.
  • In the Display Type field, select Normal.

Click OK.

Figure 25. rbgg6 builder inputs
rbgg6 builder inputs

Similarly, another text input plus builder is used to add the text input box next to the Spouse radio button. Its inputs are the same, except the Targeted Data Value is spouse, and the Text field points to a different variable.


Installing custom builders in WebSphere Portlet Factory Designer

Download the RBG_extensions.zip file, included in Downloads section this article. Use a compression utility to extract all files from RBG_extensions.zip onto your hard disk, for example, into the directory C:\temp. This step creates a folder called rbg_extensions in the C:\temp folder. The file structure is shown in figure 26.

Figure 26. RBG_extensions.zip file structure
RBG_extensions.zip file structure

The rbg_extensions directory contains two folders. The first folder is install_files. In the install_files folder, there are three archive files:

  • custom_rbgg.jar contains the custom builder classes.
  • custom_rbgg_builders.zip contains the custom builder definitions.
  • custom_rbgg_doc.zip contains the model editor help for the custom builders.

The second folder, sample_model, contains the file RadioButtonGroupPlus.model.

There are two options for installing the custom builders:

  • Install into a project in the workspace.
  • Install into WebSphere Portlet Factory Designer so that the custom builders are available to all models.

With the first option, only one project is affected. New projects, other projects in the workspace, and projects in other workspaces are not affected. If you are installing into WebSphere Portlet Factory Designer, then all projects created by WebSphere Portlet Factory Designer thereafter have the files copied into their workspaces.


Install custom builders into a project in the workspace

Place custom_rbgg.jar in the following location:

<workspace_home>\<project>\WebContent\WEB-INF\work\lib

Place custom_rbgg_builders.zip in the following location:

<workspace_home>\<project>\WebContent\WEB-INF\builders

Extract custom_rbgg_doc.zip into the following location:

<workspace_home>\<project>\WebContent\factory\product_documentation

After you restart WebSphere Portlet Factory Designer, the three custom builders are available in the builder call list.


Install custom builders into WebSphere Portlet Factory Designer

Installing the custom builders into WebSphere Portlet Factory Designer makes the custom builders available to all models created thereafter with that version of WebSphere Portlet Factory Designer. Close WebSphere Portlet Factory Designer (if it is open).

Place custom_rbgg.jar in the following location:

<Designer_home>\FeatureSets\Web-App_6.1.2\Templates\Project\wpf.war\WEB-INF\work\lib

Place custom_rbgg_builders.zip in the following location:

<Designer_home>\FeatureSets\Web-App_6.1.2\Templates\Project\wpf.war\WEB-INF\builders

Extract custom_rbgg_doc.zip into the following location:

<Designer_home>\FeatureSets\Web-App_6.1.2\Templates\Project\wpf.war\factory\ product_documentation\designer

Start WebSphere Portlet Factory Designer, and verify that the custom builders are present.


Verify custom builders

In your WebSphere Portlet Factory Designer workspace, create a WebSphere Portlet Factory project and a WebSphere Portlet Factory model within that project. Open the model. In the Outline view, click the icon to add a builder call to the current model. Select All for the category view, and verify the presence of these builders: radio button group grid, text input plus, and select plus.


Import the sample model

As mentioned previously, a sample model is included in the RBG_extensions.zip file in the folder rbg_extensions/sample_model. Import the model into the models folder of a WebSphere Portlet Factory project. Open the model, regenerate it, and save. If no errors are found in the Problems view, you can attempt to run the model.


Running the sample model

The sample model runs in a servlet container or Java™ Platform, Enterprise Edition (Java EE) application server. The model also runs on IBM WebSphere Portal.


Builder help

The help for the custom builders can be accessed from two places within WebSphere Portlet Factory Designer. In the builder picker, select a builder, and a link to builder-specific help displays in the Related Topics section of the window as shown in figure 27.

Figure 27. Builder help in Builder Picker
Builder help in Builder Picker

Help can also be accessed from the model editor. When a builder is open for editing, click the Help button in the bottom right corner of the builder editor, and a link displays in the Related Topics section of the window as shown in figure 28.

Figure 28. Builder help in builder editor
Builder help in builder editor

Troubleshooting

If the custom builders are not in the list of all builders when you verify the presence of the custom builders, go through the installation steps again to ensure that all the files are copied or extracted into the correct locations. Two of the archives are copied, and the third is an extraction.

If you find multiple errors in the Problems view after you import the sample model, such as BuilderDef not found, verify that all three custom builders are in the builder call list.

Some other troubleshooting tips include restarting WebSphere Portlet Factory Designer, creating a new workspace, and creating a new model.


Removing the custom builders

Remove the files that were copied or extracted during the installation.


Conclusion

The custom builders radio button group grid, text input plus, and select plus extend the base functionality of radio button groups in WebSphere Portlet Factory by allowing any member of a radio button group to be associated with a text box or drop-down list , and by providing the ability to render the radio button group in a grid format.


Disclaimer

The custom builders and sample model furnished with this article are provided as-is and are not supported by IBM. For this reason, IBM Technical Support is unable to answer questions about these custom builders.


Download

DescriptionNameSize
Code samplerbg_extensions.zip38.4KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=394973
ArticleTitle=Creating radio button group extensions in WebSphere Portlet Factory Designer
publish-date=06292009