Portlet Customizer Builder

Portlet Customizer Builder

In this topic ...

Quick Tips
Specifying Inputs
Related Topics ...

Implementing Configure and Edit Modes in Factory Portlets

The Configure mode in a portal server generally refers to a mode in which the Portal Administrator can apply settings to a portlet. These settings apply to all users of the portlet. The Edit mode generally refers to a mode in which individual end users can set personal preferences for how a portal will behave for them. Each portal server provides a User Interface (UI) for these modes. The Portlet Customizer Builder makes it possible to replace the UI for these modes with a Factory model that performs similar functions.
Use the Portlet Customizer Builder to create a configure or edit model for an existing portlet. When the user clicks on the configuration or edit icon in your portlet's title bar, this model runs and allows the user to determine what Factory profile to apply or specify values for specific profile values.
We can use a Portlet Customizer to provide the following functionality over the default configuration mode behavior:

Limit profile entries displayed -- We can prevent profile entries from being exposed in the configuration or edit model by removing the entries from the list displayed in the Portlet Customizer Builder call. Right-click on the profile entry and choose Delete Row from the popup menu.
Specify UI controls for setting profile values -- The Portlet Customizer Builder utilizes the Data Page Builder. As a result, we can use Data Field Modifier Builder calls to specify the controls to use for different profile entries as well as the behavior of those controls.

Quick Tips

The portlet and customizer models reference each other -- The Configure or Edit Model input value in the Portlet Adapter must be the name of the model that contains the Portlet Customizer Builder call. In turn, the Portlet input value for the Portlet Customizer Builder call must be the name of the portlet model.
Localizing Button Labels - The text of the buttons generated by the Portlet Customizer Builder can be changed by using a Localized Resource builder. In the Localized Resource Builder refer the keys "OK", "Update", "Cancel" and "Clear_Portlet_Data" when swapping in translated strings. Note that tab label text can also be localized in a similar way, with keys equal to the tab labels with spaces replaced with underscores ( "Tab One" would result in a key of "Tab_One".)

Specifying Inputs

The Portlet Customizer 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."

Input Name Description
Name Enter a name for this Builder call. The Designer displays this name in the Builder Call List.
Portlet Enter the name of the model for which this model will be the configure or edit model. In the Portlet Adapter Builder call in this model, make sure that the Custom Configure or Custom Edit Model input names this model as its value.
Profile sets applied to the model will be listed in the Profile Sets input below.
Profile Sets Determines how profile sets and profile entries get exposed in the Edit or Configure mode of the portlet. Choose:

Profiles - Allows the user to specify a profile to apply to the portlet. Use this setting to allow the user to apply all the values determined by the selected profile to the portlet. For example, a profile set could contain profiles oriented towards the user s region. Using this setting on such a profile set allows the user to determine the regional profile to use, while the developer retains control over the individual values in that profile.
Input Prefix - Allows models to use a prefix instead of the traditional naming convention of profileSetName_entryname which can become lengthy. This prefix allows you to create shorter variable names. Note that changing prefixes in existing models can cause issues if other Builders (such as Data Page) rely on the variable names created by the Portlet Customizer Builder. This feature is recommended when creating new models. A naming clash can occur depending on two or more profile sets if you have the same named entry names and use the same name prefixes.
Handling - Allows the user to specify values, or a profile, for each entry in the profile set when customizing the portlet. Use this setting to allow the user to set portlet parameters. For example, a stock-symbol list, zip-code for weather, background color, etc. All entries in the profile associated with the request are exposed.

Update Profile Sets for Portlet Press this button to update the list of profile sets.
You might need to do this if you change the profile set(s) a portlet model is associated with. You would continue to use the existing Update from Profile Set button if just the contents of the profile had changed and not the profile set name
Number of Pages Determines how many pages this Builder creates for the customizer UI.
Use Tabbed Pages Enable this check box to use Tabbed pages in place of page navigation buttons.
When this input is enabled, fill in the inputs in the "Tab Appearance" section of the Builder Call editor.
Input Values Determine the page number on which this input value appears in the customizer and specify the prompt and default value for the input field in the form.
Treat Text as XML Enable this input to force the Customizer to treat any profile value text that appears to be XML (begins with "<", and ends with ">"), as XML.
Setting this enables the Data Page Builder to operate on the profile data in a more meaningful way.
For example the XML text might be repeating data that Data Page can treat as a table. If this input is not checked, the profile value will be treated as text, which happens to look like XML.
Update Input Values from Profile Set Press this button to update the contents of an individual profile set.
You might need to do this if contents of the profile have changed and the profile set name has not changed.
Tab Appearance
Control Type Choose the radio button that represents the tab style you require. We can choose:

Text To make entire tab cell active and clickable. Tab label is a simple Text label.
Link To make tab label a Link. Only link text is active and clickable.
Image To make tab an Image Button. Entire image is active and clickable.

Each Control Types has additional inputs for specifying the appearance (see below).
Orientation Choose the tab orientation you require. We can choose:

Horizontal - To locate tabs across the top of a page.
Vertical - To locate tabs down the side of a page.

Style for background of tabs This input applies to Text and Link style tabs.
Select a Style to be used for the background of individual tabs in the tab control.
If you have specified a Selected Tab Variable, this style will not be applied to the selected tab.
Style for background of selected tabs This input applies to Text and Link style tabs.
If you have specified a Selected Tab Variable, select a Style that will be applied to the selected tab.
Style for text of tabs This input applies to Text and Link style tabs.
Select a Style that will be used for the label of individual cells in the tab control.
If you have specified a Selected Tab Variable, this style will not be applied to the selected tab.
Style for text of selected tabs This input applies to Text and Link style tabs.
If you have specified a Selected Tab Variable, select a Style that will be applied to the selected tab text label.
Alt text element This input applies to Image style tabs.
Select the name of the element that specifies the alt text for each tab. This may be the same as the ID element specified above.
Prefix for image name This input applies to Image style tabs.
Select a prefix used to construct the image name for each tab in the tab control.
Image filenames are constructed by concatenating the prefix + the tab ID + the image suffix to build a unique image name for each tab.
For example, consider the following code snippet of typical data:
<tabs>
<tab>
<id>editPage1</id>
<label>List</label>
</tab>
<tab>
<id>editPage2</id>
<label>Details</label>
</tab>
</tabs>
For this set of images:
editPage1.gif
editPage2.gif
The image prefix is editPage1, editPage2, as specified by the <id> element The <label> tags contain text that appears on each tab.
Suffix for image name This input applies to Image style tabs.
Select a suffix used to construct the image name for each tab in the tab control.
If you have specified a Selected tab variable, this suffix is used to construct the image name for unselected tabs.
Suffix for selected image name This input applies to Image style tabs.
Select a suffix for selected image name.
If you have specified a Selected Tab variable, this suffix is used to construct a selected image name.
If the selected images are:
editPage1_Selected.gif
editPage2_Selected.gif
The suffix for selected images is _Selected.gif
Suffix for hover image name This input applies to Image style tabs.
Select a suffix for hover image name.
Suffix used to construct a hover image for each tab in the tab control. This image is displayed when the user places the cursor over a tab.
If the set of hover images is:
editPage1_Hover.gif
editPage2_Hover.gif
The suffix for selected images is _Hover.gif
Custom HTML Base Page Specify the URL of a custom base page to use as the base HTML of the tab control. The HTML should contain control suitable for repeating with a Repeated Region Builder.
This Builder relies on three specific tag names that must be in your HTML:

TabItemRepeat this defines the region that is repeated
TabItemCell this defines the region that is the background for Text and Link style tabs. For Text style Builders, an onclick HTML Event Action is placed on this tag.
TabItemText this defines the tab label. A Text, Link, or Image Button control is placed on this tag.

See the default base pages at the location below for examples of appropriate HTML:
<servableContent>/factory/pages/tabBuilder_horizontal.html
<servableContent>/factory/pages/tabBuilder_vertical.html
Tab Labels Use this input to set the label text for each page tab.
Simply choose a page and assign a tab label to it.
If you specify a Localized Resource below, this Builder will look in the specified resource for the text (key) entered in the Tab Labels input table. If a localized version of the text exists in the resource variable, the Builder will use it as the tab label. If localized text is not available, the Builder will use plain text.
Display Options
Page Import Determine the page or pages to be imported for this customizer. We can choose to import:

Single Page - Same HTML page will be used for all pages in the customizer
Multiple Pages - Unique HTML pages can be used for each page of the customizer

Page URL(s) Enter the path (relative to the Factory's servable root directory) to the HTML page on which the Portlet Customizer adds a form for setting the profile values. We can create your own HTML page to alter or enhance the default display of the form. See "Implementing Configure and Edit Functionality," for more information.
If you elect to import multiple HTML pages, a table is displayed in which you can associate a specific imported HTML page with a page in the Customizer.
Default Page URL Enter the path (relative to the Factory's servable root directory) to the HTML page on which the Portlet Customizer adds a form for setting the profile values. We can create your own HTML page to alter or enhance the default display of the form. See "Implementing Configure and Edit Functionality," for more information.
Make URLs Absolute Recommended and enabled by default. Enable this checkbox to prompt the Factory to generate absolute URLs to the HTML resources (images, style sheets, etc.) that the page specified in the Page URL use.
Stylesheet URL Enter the path (relative to the Factory's servable root directory) to a CSS stylesheet to use for formatting the HTML display.
HTML Template File Select an HTML Page Automation template file that will be used to generate the Customizer HTML pages.
Label Translation Settings
Localized Resource Use this input to specify an existing localized resource in the model to use with this Builder.
Advanced
Post-Save Method Use this input to specify a method to invoke after the page input data has been saved to their corresponding variables.
You might want to invoke such a method when we need to manually process the customizer's values before updating the data store.
Post-Save Method Behavior Use this input to determine if the Post-Save Method is called when validation errors occur. We can choose:

Always call Post-Save method - To perform Post-Save operation regardless of validation error status.
Call Post-Save Method only if all fields were valid - To block Post-Save when validation errors occur

Generate Main By default, the Portlet Customizer Builder adds a main Action List to the model. This Action List displays "editPage1." To implement your own "main" action, disable this checkbox. Be sure to call the "editPage1" action, which displays the customization form generated by the Portlet Customizer Builder call.
Remain in Customizer on error Use this input to control portlet Edit/Config behavior.
Enable - To include in the generated "Update" method code to check for data page errors (such as missing required inputs). If there errors occur, a request property named bowstreet.remainInCustomizer (defined on com.bowstreet.adapters.Constants) will be set to "true", and the current page is then specified to be re-displayed.
Setting the bowstreet.remainInCustomizer request property to "true" causes the Portlet Adapter to skip the actual saving of the Profile data, and remain in the Edit/Config mode.
Add Clear Data Button Enable this input to add a button to the page to clear the profile information for the internal Edit/Configure storage. This feature is useful during development and testing, or when switching between Edit and Configure modes.
Clearing the portlet data will cause the model to regenerate using the defaults from the profile set.

Input Name	Description
Name	Enter a name for this Builder call. The Designer displays this name in the Builder Call List.
Portlet	Enter the name of the model for which this model will be the configure or edit model. In the Portlet Adapter Builder call in this model, make sure that the Custom Configure or Custom Edit Model input names this model as its value. Profile sets applied to the model will be listed in the Profile Sets input below.
Profile Sets	Determines how profile sets and profile entries get exposed in the Edit or Configure mode of the portlet. Choose: Profiles - Allows the user to specify a profile to apply to the portlet. Use this setting to allow the user to apply all the values determined by the selected profile to the portlet. For example, a profile set could contain profiles oriented towards the user s region. Using this setting on such a profile set allows the user to determine the regional profile to use, while the developer retains control over the individual values in that profile. Input Prefix - Allows models to use a prefix instead of the traditional naming convention of profileSetName_entryname which can become lengthy. This prefix allows you to create shorter variable names. Note that changing prefixes in existing models can cause issues if other Builders (such as Data Page) rely on the variable names created by the Portlet Customizer Builder. This feature is recommended when creating new models. A naming clash can occur depending on two or more profile sets if you have the same named entry names and use the same name prefixes. Handling - Allows the user to specify values, or a profile, for each entry in the profile set when customizing the portlet. Use this setting to allow the user to set portlet parameters. For example, a stock-symbol list, zip-code for weather, background color, etc. All entries in the profile associated with the request are exposed.
Update Profile Sets for Portlet	Press this button to update the list of profile sets. You might need to do this if you change the profile set(s) a portlet model is associated with. You would continue to use the existing Update from Profile Set button if just the contents of the profile had changed and not the profile set name
Number of Pages	Determines how many pages this Builder creates for the customizer UI.
Use Tabbed Pages	Enable this check box to use Tabbed pages in place of page navigation buttons. When this input is enabled, fill in the inputs in the "Tab Appearance" section of the Builder Call editor.
Input Values	Determine the page number on which this input value appears in the customizer and specify the prompt and default value for the input field in the form.
Treat Text as XML	Enable this input to force the Customizer to treat any profile value text that appears to be XML (begins with "<", and ends with ">"), as XML. Setting this enables the Data Page Builder to operate on the profile data in a more meaningful way. For example the XML text might be repeating data that Data Page can treat as a table. If this input is not checked, the profile value will be treated as text, which happens to look like XML.
Update Input Values from Profile Set	Press this button to update the contents of an individual profile set. You might need to do this if contents of the profile have changed and the profile set name has not changed.
Tab Appearance
Control Type	Choose the radio button that represents the tab style you require. We can choose: Text To make entire tab cell active and clickable. Tab label is a simple Text label. Link To make tab label a Link. Only link text is active and clickable. Image To make tab an Image Button. Entire image is active and clickable. Each Control Types has additional inputs for specifying the appearance (see below).
Orientation	Choose the tab orientation you require. We can choose: Horizontal - To locate tabs across the top of a page. Vertical - To locate tabs down the side of a page.
Style for background of tabs	This input applies to Text and Link style tabs. Select a Style to be used for the background of individual tabs in the tab control. If you have specified a Selected Tab Variable, this style will not be applied to the selected tab.
Style for background of selected tabs	This input applies to Text and Link style tabs. If you have specified a Selected Tab Variable, select a Style that will be applied to the selected tab.
Style for text of tabs	This input applies to Text and Link style tabs. Select a Style that will be used for the label of individual cells in the tab control. If you have specified a Selected Tab Variable, this style will not be applied to the selected tab.
Style for text of selected tabs	This input applies to Text and Link style tabs. If you have specified a Selected Tab Variable, select a Style that will be applied to the selected tab text label.
Alt text element	This input applies to Image style tabs. Select the name of the element that specifies the alt text for each tab. This may be the same as the ID element specified above.
Prefix for image name	This input applies to Image style tabs. Select a prefix used to construct the image name for each tab in the tab control. Image filenames are constructed by concatenating the prefix + the tab ID + the image suffix to build a unique image name for each tab. For example, consider the following code snippet of typical data: <tabs> <tab> <id>editPage1</id> <label>List</label> </tab> <tab> <id>editPage2</id> <label>Details</label> </tab> </tabs> For this set of images: editPage1.gif editPage2.gif The image prefix is editPage1, editPage2, as specified by the <id> element The <label> tags contain text that appears on each tab.
Suffix for image name	This input applies to Image style tabs. Select a suffix used to construct the image name for each tab in the tab control. If you have specified a Selected tab variable, this suffix is used to construct the image name for unselected tabs.
Suffix for selected image name	This input applies to Image style tabs. Select a suffix for selected image name. If you have specified a Selected Tab variable, this suffix is used to construct a selected image name. If the selected images are: editPage1_Selected.gif editPage2_Selected.gif The suffix for selected images is _Selected.gif
Suffix for hover image name	This input applies to Image style tabs. Select a suffix for hover image name. Suffix used to construct a hover image for each tab in the tab control. This image is displayed when the user places the cursor over a tab. If the set of hover images is: editPage1_Hover.gif editPage2_Hover.gif The suffix for selected images is _Hover.gif
Custom HTML Base Page	Specify the URL of a custom base page to use as the base HTML of the tab control. The HTML should contain control suitable for repeating with a Repeated Region Builder. This Builder relies on three specific tag names that must be in your HTML: TabItemRepeat this defines the region that is repeated TabItemCell this defines the region that is the background for Text and Link style tabs. For Text style Builders, an onclick HTML Event Action is placed on this tag. TabItemText this defines the tab label. A Text, Link, or Image Button control is placed on this tag. See the default base pages at the location below for examples of appropriate HTML: <servableContent>/factory/pages/tabBuilder_horizontal.html <servableContent>/factory/pages/tabBuilder_vertical.html
Tab Labels	Use this input to set the label text for each page tab. Simply choose a page and assign a tab label to it. If you specify a Localized Resource below, this Builder will look in the specified resource for the text (key) entered in the Tab Labels input table. If a localized version of the text exists in the resource variable, the Builder will use it as the tab label. If localized text is not available, the Builder will use plain text.
Display Options
Page Import	Determine the page or pages to be imported for this customizer. We can choose to import: Single Page - Same HTML page will be used for all pages in the customizer Multiple Pages - Unique HTML pages can be used for each page of the customizer
Page URL(s)	Enter the path (relative to the Factory's servable root directory) to the HTML page on which the Portlet Customizer adds a form for setting the profile values. We can create your own HTML page to alter or enhance the default display of the form. See "Implementing Configure and Edit Functionality," for more information. If you elect to import multiple HTML pages, a table is displayed in which you can associate a specific imported HTML page with a page in the Customizer.
Default Page URL	Enter the path (relative to the Factory's servable root directory) to the HTML page on which the Portlet Customizer adds a form for setting the profile values. We can create your own HTML page to alter or enhance the default display of the form. See "Implementing Configure and Edit Functionality," for more information.
Make URLs Absolute	Recommended and enabled by default. Enable this checkbox to prompt the Factory to generate absolute URLs to the HTML resources (images, style sheets, etc.) that the page specified in the Page URL use.
Stylesheet URL	Enter the path (relative to the Factory's servable root directory) to a CSS stylesheet to use for formatting the HTML display.
HTML Template File	Select an HTML Page Automation template file that will be used to generate the Customizer HTML pages.
Label Translation Settings
Localized Resource	Use this input to specify an existing localized resource in the model to use with this Builder.
Advanced
Post-Save Method	Use this input to specify a method to invoke after the page input data has been saved to their corresponding variables. You might want to invoke such a method when we need to manually process the customizer's values before updating the data store.
Post-Save Method Behavior	Use this input to determine if the Post-Save Method is called when validation errors occur. We can choose: Always call Post-Save method - To perform Post-Save operation regardless of validation error status. Call Post-Save Method only if all fields were valid - To block Post-Save when validation errors occur
Generate Main	By default, the Portlet Customizer Builder adds a main Action List to the model. This Action List displays "editPage1." To implement your own "main" action, disable this checkbox. Be sure to call the "editPage1" action, which displays the customization form generated by the Portlet Customizer Builder call.
Remain in Customizer on error	Use this input to control portlet Edit/Config behavior. Enable - To include in the generated "Update" method code to check for data page errors (such as missing required inputs). If there errors occur, a request property named bowstreet.remainInCustomizer (defined on com.bowstreet.adapters.Constants) will be set to "true", and the current page is then specified to be re-displayed. Setting the bowstreet.remainInCustomizer request property to "true" causes the Portlet Adapter to skip the actual saving of the Profile data, and remain in the Edit/Config mode.
Add Clear Data Button	Enable this input to add a button to the page to clear the profile information for the internal Edit/Configure storage. This feature is useful during development and testing, or when switching between Edit and Configure modes. Clearing the portlet data will cause the model to regenerate using the defaults from the profile set.