Image Button Builder

Image Button Builder

In this topic ...

Quick Tips
Specifying Inputs

Related Topics ...

Overview: Creating Forms
HTML Guidelines
Passing Arguments to Actions

Sometimes you want more pizazz in an application than is available with run-of-the-mill button controls. When this is the case, consider using an image button. The image button builder creates a clickable image that functions and behaves exactly like a text-based button. In addition, this single control can display three different images based on mouse events. The three image states are:

Image - Displayed by default when pointer is not located over image
Hover image - Displayed on mouse-over event
Pressed image - Displayed on a mouse-down event

The builder dialog for the image button is similar to that of the button builder, but contains additional input fields to specify the file names for the three images the image button can display.
When specifying images to the image button, be sure that the paths you provide to images are relative to any <base url="" /> value specified on the HTML page. In addition, be sure to provide a unique name for each image button builder call on a page.

Quick tips

Target values relative to form -- If you specify a Target, keep in mind that the setting is relative to the form being processed and not the button.

Specifying inputs

This 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 tool displays this name in the builder call list.
Page Location Use the Page Location input to specify the page or pages on which this builder call will act.
See Locating control builders on pages for detailed documentation about the Page Location input and page location syntax.
Image URL to the default image you want added to the page(s) in the model. An image can be specified in three ways:

Absolute

http://www.example.com/~jdoe/mypics/image1.jpg

Relative

/files/images/mypics/image1.gif

Indirect Reference

${Variables/ImageName}

where ImageName references a variable containing a string value such as: /Images/myimages/image3.gif
The indirect reference can also be used to call a method. For example, if you have a getImage() method in your model, we can select it using the MethodCall picker ${MethodCall/getImage}. This method must return a String that contains the image file name relative to the servable content directory, for example, /Images/myimages/image3.gif. If you are displaying rows of data using the data page builder and want to vary the image based on some criteria related to the row, we can use the "xxxxLoopVar" variable in your method to fetch data related to the current row. The LoopVar variable name is based on the variable data that the data page builder is operating on.
Hover Image URL to the image displayed during mouse-over. See the Image input for more information.
Pressed Image URL to the image displayed when button is clicked. See the Image input for more information.
Action Type Defines the behavior of the of the action. Choose an action type based on the action that will process the onClick event and if you want to process any form inputs as part of that action.
Submit form and invoke action - Choose this option if the specified action is a method in the model or linked Java object and that method processes the inputs to the form on which the button resides.
Submit form to URL - Choose this option if the specified action is a URL outside of the factory runtime that will process the inputs to a form. The specified URL receives the form input values as name/value pairs appended to the URL.
Link to an action - Choose this option if the specified action is a method in the model or linked Java object (including service calls). This option acts as a simple link, transferring control directly to the specified URL. The specified action cannot process any form inputs.
Link to a URL - Choose this option if you want to navigate to a non-Factory URL. The URL cannot process any form inputs.
Run a script - Choose this option of you want to run some client-side JavaScript when the user clicks on the button. The script cannot process any form inputs.
Action model action to execute when the user clicks the image button.
Script to Execute Applies only if you selected Run a script as the value for Action Type. Specify the JavaScript to execute when the user clicks on the image button. Form inputs, if any, are not submitted to a script.
Note that Do not use comments in the script you specify. The script you specify is added as one line, so any code following comments is ignored.
Form Name If the image button is in one form and the inputs to be submitted are in another, enter the name of the form whose inputs you want to submit.
Arguments
Input Mappings We can pass arguments to the specified action by adding argument names and the value to be passed to it. Use the Reference Chooser to specify input values or values returned by methods or service calls as the value to be passed to an argument for the specified action. See Passing arguments to actions for more information.
Post-Action Behavior
Post-Action Behavior Select what should happen after the action launched by the image button has completed.

Default

In most cases this displays the output generated by the action. One exception to this is when the action is run from inside a container that specifies that the outermost page gets rendered after the action runs. In the exception case, default would not display the output, but refresh the outermost page.

Refresh specified page location after running action

The outermost page is not refreshed. Instead, new HTML for the specified region is re-calculated after the action runs, and this HTML is sent to the client where it replaces the existing HTML. If the Replace "id" Matches is checked, then the HTML produced by the action is examined for elements that have ID attribute values. If ID attribute values are found, then the corresponding elements in the page will have their HTML replaced.
Note that If Ajax is disabled, the default post-action behavior is used without loss of functionality. Ajax enablement is controlled through the Global Ajax Enablement builder and profiling rather than changing inputs in a large number of builders.

Replace specified location with action results

This is good for tooltips, incremental validation, and other simple information calculated on the server.
Note that If Ajax is disabled, the default post-action behavior is used without loss of functionality. Ajax enablement is controlled through the Global Ajax Enablement builder and profiling rather than changing inputs in a large number of builders.

Evaluate action results as JavaScript

Run the main action, and evaluate what it returns as JavaScript.

Always reload top-most page after running action

This is very similar to default, but overrides behavior that prevents the top-most page from refreshing (such as those behaviors introduced by the asynchronous client loader builder). This option would be necessary in cases where portal event and render phases need to be carried out to enable portlet-to-portlet communication to function properly.

Show action results "stand-alone": display no containing pages

This option is similar to default, but it ensures that even if the model is running in a portal or model container, the action only returns the results of the specified action, not the containing portal or other surrounding pages. This option is ideal for lower-level Ajax or related functionality such as pop-ups, computed images, or Excel export.

Advanced
Target The window or frame which will display the results of the action. If you do not set this value, the current window/frame will be the target. Valid entries for the Target value include...

_self - Display results in the frame containing the form. If target is not specified, _self is the default.
_blank - Display results in a new browser window.
_parent - Display results in the frameset above the frame containing the form.
_top - Display results the topmost frameset.
We can also specify the name of a frame in the current frameset.

Note that All of these targets are relative to the form being processed, not the button image itself.
Rendering mode If you know that the specified action returns a specific page, set Rendering Mode to Normal. If you do not know the specific page that gets returned, set Rendering Mode to Return Outermost page after running action. For example, use this setting when creating a builder.
Break Containment Enable this check box if you want to replace the contents of the target window with the contents of the URL returned by the action.
HTML Attributes We can manage the display of this control by setting the following attributes:

Alternate text

Enter alternative text for the image to assist users with vision impairment.

Width

Enter the width of the button image in pixels.

Height

Enter the height of the button image in pixels.

Border

Enter the width of the button image border in pixels.

Input Name	Description
Name	Enter a name for this builder call. The designer tool displays this name in the builder call list.
Page Location	Use the Page Location input to specify the page or pages on which this builder call will act. See Locating control builders on pages for detailed documentation about the Page Location input and page location syntax.
Image	URL to the default image you want added to the page(s) in the model. An image can be specified in three ways: Absolute `http://www.example.com/~jdoe/mypics/image1.jpg` Relative `/files/images/mypics/image1.gif` Indirect Reference `${Variables/ImageName}` where ImageName references a variable containing a string value such as: `/Images/myimages/image3.gif` The indirect reference can also be used to call a method. For example, if you have a getImage() method in your model, we can select it using the MethodCall picker `${MethodCall/getImage}`. This method must return a String that contains the image file name relative to the servable content directory, for example, `/Images/myimages/image3.gif`. If you are displaying rows of data using the data page builder and want to vary the image based on some criteria related to the row, we can use the "xxxxLoopVar" variable in your method to fetch data related to the current row. The LoopVar variable name is based on the variable data that the data page builder is operating on.
Hover Image	URL to the image displayed during mouse-over. See the Image input for more information.
Pressed Image	URL to the image displayed when button is clicked. See the Image input for more information.
Action Type	Defines the behavior of the of the action. Choose an action type based on the action that will process the onClick event and if you want to process any form inputs as part of that action. Submit form and invoke action - Choose this option if the specified action is a method in the model or linked Java object and that method processes the inputs to the form on which the button resides. Submit form to URL - Choose this option if the specified action is a URL outside of the factory runtime that will process the inputs to a form. The specified URL receives the form input values as name/value pairs appended to the URL. Link to an action - Choose this option if the specified action is a method in the model or linked Java object (including service calls). This option acts as a simple link, transferring control directly to the specified URL. The specified action cannot process any form inputs. Link to a URL - Choose this option if you want to navigate to a non-Factory URL. The URL cannot process any form inputs. Run a script - Choose this option of you want to run some client-side JavaScript when the user clicks on the button. The script cannot process any form inputs.
Action	model action to execute when the user clicks the image button.
Script to Execute	Applies only if you selected `Run a script` as the value for Action Type. Specify the JavaScript to execute when the user clicks on the image button. Form inputs, if any, are not submitted to a script. Note that Do not use comments in the script you specify. The script you specify is added as one line, so any code following comments is ignored.
Form Name	If the image button is in one form and the inputs to be submitted are in another, enter the name of the form whose inputs you want to submit.
Arguments
Input Mappings	We can pass arguments to the specified action by adding argument names and the value to be passed to it. Use the Reference Chooser to specify input values or values returned by methods or service calls as the value to be passed to an argument for the specified action. See Passing arguments to actions for more information.
Post-Action Behavior
Post-Action Behavior	Select what should happen after the action launched by the image button has completed. Default In most cases this displays the output generated by the action. One exception to this is when the action is run from inside a container that specifies that the outermost page gets rendered after the action runs. In the exception case, default would not display the output, but refresh the outermost page. Refresh specified page location after running action The outermost page is not refreshed. Instead, new HTML for the specified region is re-calculated after the action runs, and this HTML is sent to the client where it replaces the existing HTML. If the Replace "id" Matches is checked, then the HTML produced by the action is examined for elements that have ID attribute values. If ID attribute values are found, then the corresponding elements in the page will have their HTML replaced. Note that If Ajax is disabled, the default post-action behavior is used without loss of functionality. Ajax enablement is controlled through the Global Ajax Enablement builder and profiling rather than changing inputs in a large number of builders. Replace specified location with action results This is good for tooltips, incremental validation, and other simple information calculated on the server. Note that If Ajax is disabled, the default post-action behavior is used without loss of functionality. Ajax enablement is controlled through the Global Ajax Enablement builder and profiling rather than changing inputs in a large number of builders. Evaluate action results as JavaScript Run the main action, and evaluate what it returns as JavaScript. Always reload top-most page after running action This is very similar to default, but overrides behavior that prevents the top-most page from refreshing (such as those behaviors introduced by the asynchronous client loader builder). This option would be necessary in cases where portal event and render phases need to be carried out to enable portlet-to-portlet communication to function properly. Show action results "stand-alone": display no containing pages This option is similar to default, but it ensures that even if the model is running in a portal or model container, the action only returns the results of the specified action, not the containing portal or other surrounding pages. This option is ideal for lower-level Ajax or related functionality such as pop-ups, computed images, or Excel export.
Advanced
Target	The window or frame which will display the results of the action. If you do not set this value, the current window/frame will be the target. Valid entries for the Target value include... _self - Display results in the frame containing the form. If target is not specified, _self is the default. _blank - Display results in a new browser window. _parent - Display results in the frameset above the frame containing the form. _top - Display results the topmost frameset. We can also specify the name of a frame in the current frameset. Note that All of these targets are relative to the form being processed, not the button image itself.
Rendering mode	If you know that the specified action returns a specific page, set Rendering Mode to Normal. If you do not know the specific page that gets returned, set Rendering Mode to Return Outermost page after running action. For example, use this setting when creating a builder.
Break Containment	Enable this check box if you want to replace the contents of the target window with the contents of the URL returned by the action.
HTML Attributes	We can manage the display of this control by setting the following attributes: Alternate text Enter alternative text for the image to assist users with vision impairment. Width Enter the width of the button image in pixels. Height Enter the height of the button image in pixels. Border Enter the width of the button image border in pixels.