Locating control builder calls on pages

The Page Location input provides you with three different ways to locate a control builder call with one or more locations on one or more pages in your model . Each page location technique results in the generation of a Page Location string that determines on what pages, and where on those pages, the control builder calls are added.

This help topic includes information about these techniques for locating builder calls on pages:

  • On Named Tag -- Allows you to specify one named location (<input /> or <span /> element) on the page on which to place the builder call. For more information see, "Using the On Named Tag Location Technique."

  • Relative to Named Tag -- Allows you to specify one location on a page that either replaces the named element or uses that named element to orient the placement of a new named element on which the builder call gets placed. For more information see, "Using the Relative to Named Tag Technique."

  • Advanced -- Allows you to enter the Page Location syntax that specifies one or more locations on one or more pages on (or by which) to place the builder call. For more information see, "Using the Advanced Technique."

  • Profiling Builder Location Inputs -- Allows you to customize the location of controls on a page based on user profiles and roles.

 

Using the On Named Tag Technique

The On Named Tag technique is the simplest of the three page location methods and is meant to replace a named element on the page with the JSP code that implements the builder control.

To place a control builder call on a page using the On Named Tag technique:

  1. Select the page on which you want to place the builder call from the Page select box.

The Page select box displays the names of all the Imported Page and Page builder calls in the model as well as the Imported Page and Page builder calls in any linked models ( provided that their Expose to linked model input is enabled).

  1. Select the named element on which you want to place the builder call from the Find Tag select box.

The Find Tag select box displays all the named <input /> and <span /> tags on the selected page.

 

Using the Relative to Named Tag Technique

The Relative to Named Tag technique is a little more complex than the On Named Tag method in that we can choose to replace the contents of a named tag, insert a new tag inside the specified tag, or insert a new tag oriented in some way near the named tag.

To place a control builder call on a page using the Relative to Named Tag technique:

  1. Enable the Relative to Named Tag radio button.

  2. Select the page on which you want to place the builder call from the Page select box.

The Page select box displays the names of all the Imported Page and Page builder calls in the model as well as the Imported Page and Page builder calls in any linked models ( provided that their Expose to linked model input is enabled).

  1. Select the named element on which you want to place the builder call from the Find Tag select box.

The Find Tag select box displays all the named <input /> and <span /> tags on the selected page.

  1. Select one of the following insertion modes for placing the builder call on the page:

  2. Replace Node -- Builder call output replaces the element specified in the Tag select box.

In the profile, this choice will be represented by the profile value "Rename." As a result, in the Profile Dialog, the value you see in the values table representing "Replace Node" behavior will be "Rename."

  • Before -- Builder call output gets inserted before the element specified in the Find Tag select box with the name set to the value you specify in the New Tag Name text input.

  • After -- Builder call output gets inserted after the element specified in the Find Tag select box with the name set to the value you specify in the New Tag Name text input.

  • Inside Top -- Builder call output gets inserted as the first "child" element of the named element specified in the Find Tag select box with the element name set to the value you specify in the New Tag Name text input.

  • Inside Bottom -- Builder call output gets inserted as the last "child" element of the named element specified in the Find Tag select box with the element name set to the value you specify in the New Tag Name text input.

  • TableWrapAbove -- Builder call output gets added as a new table row, duplicating the table row in which the element named in the Find Tag select box appears. For example, where #old# and #new# specify the element specified in the Find Tag select box and the new element, respectively:

<table>

   <tr><td>#new#</td></tr>

   <tr><td>#old#</td></tr>

</table>

Note: If the named element is inside a <tr> node, then the TableWrapAbove will only make a new <tr> node above it.

  • TableWrapBelow -- Builder call output gets added as a new table row, duplicating the table row in which the element named in the Find Tag select box appears. For example, where #old# and #new# specify the element specified in the Find Tag select box and the new element, respectively:

<table>

   <tr><td>#old#</td></tr>

   <tr><td>#new#</td></tr>

</table>

Note: If the named element is inside a <tr> node, then the TableWrapBelow will only make a new <tr> node below it.

  • TableWrapLeft -- Builder call output gets added as a new <td> element to the left of the <td> element named in the Find Tag select box. For example, where #old# and #new# specify the old node and the new node, respectively

<table>

   <tr>

      <td>#new#</td>

      <td>#old#</td>

   </tr>

</table>

Note: If the node is inside a <td> node and the containing <tr> node has no siblings, then the TableWrapLeft will only make a new <td> node before the selected <td>.

  • TableWrapRight -- Builder call output gets added as a new <td> element to the left of the <td> element named in the Find Tag select box. For example, where #old# and #new# specify the old node and the new node, respectively

<table>

   <tr>

      <td>#old#</td>

      <td>#new#</td>

   </tr>

</table>

Note: If the node is inside a <td> node and the containing <tr> node has no siblings, then the TableWrapLeft will only make a new <td> node after the selected <td>.

  1. If you selected an insertion mode other than Replace Node, enter a name for the element to be inserted in the New Tag Name text input.

 

Using the Advanced Technique

The Advanced page location technique allows you to create complex page location strings to locate control builder calls on multiple pages in multiple ways. We can use the Advanced technique after using the On Tag or Relative to Named Tag techniques to build up a page location expression and then build on that expression using the Advanced technique.

The following page location examples are meant to show the flexibility of the page location syntax:

  • Page StartingPage NameSearch firstBuilder

The firstBuilder tag on the StartingPage page.

  • AllPages NameSearch firstBuilder

All locations named firstBuilder on all (non-generated) Pages

  • Page StartingPage NameSearch firstBuilder else XPath HTML/BODY InsertInsideBottom firstBuilder

In StartingPage, search for an element named "firstBuilder." If it is found, that is the node. If not found, search for the XPath "HTML/BODY" and InsertInsideBottom a new node and name it "firstBuilder."

  • (Page StartingPage NameSearch theBody else XPath HTML/BODY) InsertInsideBottom firstBuilder

In StartingPage, search for an element named "theBody." If it is not found, search for the XPath "HTML/BODY." From whichever point, InsertInsideBottom a new node and name it "firstBuilder."

  • AllPages XPath HTML/BODY InsertInsideBottom Foo

In all pages, just inside the BODY tag insert a new node at the bottom and name it Foo

  • (Pages where (Public = true), Page Extra) XPath HTML//FORM InsertInsideTop Header

In all public pages and in Page named Extra, use XPath to search for a FORM tag, then insert a new node inside it at the top. Name the new node "Header."

  • ((Page A, Page B) NameSearch OKButton, Page C NameSearch OK) TableWrapRight Cancel

At the three elements named (the element named OKButton on Pages A and B, and the element named OK on Page C), create a new element to the right, and name it Cancel.

  • PagesWhere (true & TopLevel = true) NameSearch AdvancedButton

For all pages with the property TopLevel set to true, search for a node with the name "AdvnacedButton."

  • PagesWhere (TopLevel = true | AddAdvanced = true) NameSearch AdvancedButton

For all pages with the property TopLevel set to true, or the property AddAdvanced set to true, search for a node with the name "AdvancedButton."

 

Profiling Builder Location Inputs

We can profile the Page Location widget's individual fields as well as the entire widget. You might want to do this to customize the look and feel of the controls on a page based on the users profile. You have two profiling approaches we can use:

  • Profile entire location widget -- Use this approach to provide a level a generalized customization of the page

  • Profile individual settings within the location widget -- Use this approach to provide more granular customization of the page

Note that it makes little sense to use both approaches. If both the entire widget and individual widget tags are profiled, the profile assigned to the entire widget will be used.