Adding Custom Properties	Top

Purpose

When creating your own custom Page Types, Elements, and Layouts, the Property Manager provides the "Property Definition Editor", opened by clicking "Property Definition". This editor lets you specify properties appearing in the <Root> node of the actual Property Tree (and thereby in all of its children), and how these properties will be displayed in the Property Tree, which the person configuring the page will use to set property values.

Property Types

Each property-value pair can be one of three "Property Types" (below):

Simple

A "Simple" Property Type defines a single property-value pair:

The following example shows how the editor might display three Simple Property Types:

Collection

A "Collection" Property Type defines a set of Property Lists:

Collections are used to create multiple items of the same kind, such as multiple columns or buttons. For example, the property "columns" is a "Collection" Property Type. It creates multiple table columns to display a list of Samples. In the Property Definition Editor, you define one set of properties. The resulting Property List then lets you add duplicate sets of properties (as shown below) and add the required values to each.

When dealing with Collections, you will notice that the <Root> node show only one set of properties, while its children show as many sets as you have added. This is because the purpose of the <Root> is to pass default values to its children, not to provide actual values for use in a specific Page Type, Element, or Layout. In the example below, the <Root> node provides the default width of a button. Three buttons have been added to the "SampleMaintPage" node, each inheriting its width from the <Root> node. One of the buttons has been changed to a width of "300". When the "MySampleMaintPage" node is added, it inherits the three buttons and their widths from the "SampleMaintPage" node. However, when two buttons are added to "MySampleMaintPage", they inherit their widths from the <Root> node.

Property List

A "Property List" Property Type consists of a group of "Simple" Property Types, e.g.,

colors
textcolor = black
bgcolor = white
buttoncolor = red

This Property Type is used solely to support internal functionality.

The following Display Options determine how each Property List is displayed:

String Editors provide more specialized attributes for entered strings:

Customizing Buttons

When working with List and Maint Elements, the "Add Button Method" option lets you customize the functionality of an"Add" button associated with a Collection Property Type. Provide a JavaScript function that will be called when the "Add" button is clicked, plus a semicolon-delimited list of properties to pass into the funtion. The property values are filled first from the top Property List, followed by the current Property List.

Examples:

Out-of-the-box, these Page Types and Elements define the specified JavaScript functions for the "Add Button Method":

You can also define your own button functionality. Here are some guidelines concerning how to do this:

Column Headings

To add or edit a property, specify information under the following column headings in the Property Definition Editor.

Declaring Advanced Properties

Adv

The checkbox at the left appears on properties. Checking this declares a property as "Advanced".

Use your own judgment to declare any property as "Advanced" when you want to hide it in certain situations.

Advanced can be applied to a simple property, property list or an entire collection. Marking a property list (or collection) as "Advanced" automatically propogates to properties (or properyt lists) within that parent property list (children will be hidden if the parent is hidden).

The Property Definition Editor displays Show Advanced Properties in the Root:

The Advanced Properties will be hidden in the Root's children unless you click Show Advanced Properties. In the example below, View Only is the Advanced Property.

Translatable Properties

Trans

The checkbox at the left appears on certain properties.

Checking this enables translation of the entire text string entered as the value for this property for all child nodes (descendents) of the <Root> node. This feature marks a Property in the PropertyManager as "translatable".

If this is not checked (), the person configuring your properties can still conduct translations in the Property Manager by enabling it in the <Root> node of the Property Tree, or conduct full or partial translations using double curly braces to control the translated portion of the string.

Deprecating Properties

Dep

The checkbox at the left appears on properties. Checking this deprecates a property.

Expression Properties

Expr

The checkbox at the left appears on properties. Checking this allows you to use "Expression-Based Properties". For more information, see Expression Based Properties in the Properties Overview section.

Resolution Properties

Res

The checkbox at the left appears on properties. Checking this indicates that the property can vary by display resolution.

When "Res" is checked, properties appear nominal by default until you click the "mobile" icon.

The value then expands to three editors. Each represents a different device: "Desktop", "Tablet", and "Phone". These devices and their corresponding resolutions are defined by the "GUI Modes" property collection in the GUI Policy. These demonstrations use generic example text to demonstrate the mechanics of the editors. Note that the original value is replicated for convenience.

Clicking the "X" reverts to a single value, preserving the "desktop" value for convenience.

Inherited values have this appearance:

Changing a single value overrides inheritance for the other two values as well.

Clicking the "X" collapses this down to a single value.

Deleting this value returns to the inherited triple value. 

Tooltips

Deprecating Pages, PageTypes, Elements, and Layouts

The PropertyTree database table contains a deprecatedflag column. If you set the value of this column to Y, in the wizard for creating a DDP (described in the Basic Principles section), the list of Page Type and Layout pages shows deprecated ones at the end of the list with the page title striked-through. You must set this using a database update statement (you can not set this using the Web Page Designer interface).

Editor Attributes

You can choose from the following Editors, which let you specify what the Property List displays, as well as what it will accept as input.

Copy/Paste Across Collections

You can copy a property value and paste it across multiple collection items as follows:

Property Controls

Atop each set of properties are one or more symbols that let you control some aspects of the property, such as changing the order in which items are rendered on the Element or Page. For descriptions, see Property Controls in topic Properties Overview.

Required Elements

"Required Elements" are Elements available for use by a Page Type. You can also make a Required Element "mandatory", meaning each DDP created from the Page Type will always have the Element. The List Page Type is an example of a Page Type having Required Elements that are mandatory. A List Page Type requires a "List" Element (to show the SDIs) and a "Search" Element (to execute the query that retireves the SDIs).

Making a Required Element mandatory is a convenience and assurance feature. Each time someone adds a page based on this Page Type, the wizard will always add these Element nodes when creating the page.

The following controls let you define and maintain Required Elements:

Bypass

This is an editing area for the XML source files that define the Property Tree. This feature is currently intended for use only by LabVantage Solutions, Inc. developers.

The following controls provide a cursory interface for XML files in the editing area:

Working with JSPs	Top

This section contains information relevant to generating your own JSPs, whether you will use the JSP as the basis for a DDP, or simply register it as a custom JSP.

This section refers to some aspects of LabVantage Custom Tags. See the LabVantage Custom Tag Reference for more detail concerning their functionality and attributes.

JSTL objects play a key role in the contexts of both DDPs and custom JSPs:

• DDPs
  JSTL objects provide property-value pairs to the JSP that interprets properties and renders the HTML for a DDP.
• Custom JSPs
  You can use LabVantage Custom Tags and JSTL tags to call JSTL objects and retrieve property-value pairs without resorting to Java.

For each node in each Property Tree, the Request Controller makes an instance of a JSTL object available for use by a JSP. The diagram below shows the JSTL object instances created for one node in each of the example Property Trees shown in the Example Application near the beginning of the Basic Principles section of this document. Each object provides the reconciled Property List for the specified node.

The "Element Id" is the name of the JSTL object that provides property-value pairs. An Element Id uniquely identifies an Element on a page. In the example above, the JSTL objects build the DDP "MySampleListPage".

The WebPagePropertyTree table associates each Element Id to the node from which it inherits property values. If the page is a one of the DDPs supplied with the Web Page Designer, the records would look something like the following example:

Example WebPagePropertyTree Table for DDP

In this table:

"WebPageId" is the identifier of the page.

"ExtendNodeId" is the parent node of the "Element Id".

"ElementId" is the name of the JSTL object. Each Element in this column inherits from the node in the ExtendNodeId column.

In DDPs you create using the Page Types, Elements, and Layouts supplied with the Web Page Designer:

If the page is a custom JSP, the records would look a bit different:

Example WebPagePropertyTree Table for Custom JSP

In custom JSPs:

When working with a custom JSP, you can use a JSTL tag to retrieve a property value at a node. You need specify only the Element Id and the Property Id. You need not drill-down through the Property Tree as you would using methods called on an instance of the PageTagInfo class. Additionally, you can avoid Java breaks as you would when switching between Java and JSP/HTML. Using PageTagInfo to get a value defined by the ElementId "ListElement01", you would have to code:

pageinfo.getPropertyList( "ListElement01" ).getProperty( "title" );

Using a JSTL tag, you could display the information by simply coding:

<c:out value="${ListElement01.title}"/>

This information becomes helpful when you have to get property values from Elements (see Drilling Down Through Properties below).

The previous section showed how you can use JSTL to get the value of a first-level property provided by a JSTL object. Now consider the following excerpt, which shows properties for the Maint Element defined by the Element Id "SampleMaintElement" (the following information holds true for PageTypes, Elements, and Layouts).

You can retrieve values for first-level properties as noted in the previous section. For example:

SDC = <c:out value="${SampleMaintElement.sdcid}" />

gets the value and displays:

SDC = Sample

All column values are avialable from the JSTL Object as an array. To drill down to the second-level properties (the columns in each Collection), iterate through the array. For example:

Columns = <c:out value="${SampleMaintElement.columns}" />

gets the array values and displays:

Columns = [{title=Samples, columnid=s_sampleid, mode=lookup, link={}}, {title=Date Created, columnid=createdt, mode=readonly, link={}}]

To get individual values in the array, iterate through it. For example:

Column Ids:

<c:forEach items="${SampleMaintElement.columns}" var="col">

<c:out value="${col.columnid}" />

</c:forEach>

gets the columnids and displays:

ColumnIds: s_sampleid createdt

As shown in the previous section Concepts, the WebPagePropertyTree table holds records associating each WebPageId to a Property Tree, node, and ElementId. The PropertyTree table holds additional information, associating the "Property Tree Type" (Page Type, Element, or Layout), and the "Objectname". "Objectname" is a variable representing the thing that drives the JSTL object. For example, suppose you want to specify a JSP asosciated with a specific layout. If the page is a DDP, you would specify the layout JSP in the page tag as follows:

<sapphire:page layout="${layout.objectname}">

Using the Standard Layout as an example, the following record in the PropertyTree table associates the JSP used to interpret the Layout properties to the Property Tree (columns irrelevant to this discussion have been omitted):

You can use the following variables with JSTL objects.

For details and examples concerning the use of JSTL objects in your code, see the LabVantage Custom Tag Reference and Creating Page Types, Elements, and Layouts.

Creating Page Types, Elements, and Layouts	Top

Before proceeding, make certain you have read all information previously presented.

"Creating a Page Type" means "converting an existing custom JSP into a Page Type". You can then add multiple DDPs based on the Page Type.

The following example shows how to make the simplest possible Page Type, which we call "Message Page". The resulting DDP simply displays a message ("Hello"). The illustration accompanying the example shows only information relevant to explaining the Page Type creation process, eliminating irrelevant text on each screen.

A suggested order in which to create a Page Type:

If you want the Page Type to contain Elements:

• Your JSP must contain the LabVantage Custom Tags to render the Element. Each tag's attributes must point to the Element.
• When creating the Page Type in the Page Type wizard, specify the Element as a Required Element.

For simplicity, the next example uses two ready-to-use features of the LabVantage Java API: the (Core) List Element and the sdilist LabVantage Custom Tag. We use these to create a custom List Page.

You can create your own Element and add it to your JSP. This is basically a three-step process:

1. Create a Java class that defines the Element.
2. Create an Element in the Web Page Designer.
3. Call the Element from a LabVantage Custom Tag on your JSP.

The diagram below shows how everything works together using a simple Java class to generate the HTML "Hello" followed by the value of a property called "name" that is defined in the Element.

The code below shows the source file supporting our example class (MyElement.java) and the JSP (elements.JSP). To show a few more features, the code is slightly more complex than the previous example.

MyElement.java

elements.JSP

"Creating a Layout" means "using a custom JSP as the framework for a Layout". Typically, you would want the custom JSP to both specify the Layout and insert a page into the Layout. You will need to:

1. Create a custom JSP on which to base your Layout.
2. Create a Layout in the Web Page Designer.
3. Add properties to the Layout, with propertyids matching those in your custom JSP.
4. Add the Layout to a Page.

The file "customlayout.jsp" will be the object used for the Layout. This example goes something like this:

Create the JSP

When you add this layout to a page, the Layout inserts the body of that page's <sapphire:pagecontent> tag into the <sapphire:pagearea> tag in customlayout.jsp (see the description of pagearea and pagecontent tags in the LabVantage Custom Tag Reference for more details).

Lines 7 through 13 test to determine if the List Page contains a pagecontent tag with the identifier "content". If pageareadefined is false, the layout displays "No Content". If true, the contents of the List page are inserted within a scrollable div at lines 16 through 18.

customlayout.JSP

Create the Layout and Create Properties

Next, create a Layout in the Web Page Designer:

Add a Page

Next, add a page, then add this Layout to the page. We have added a List Page DDP, which contains the <sapphire:pagecontent> tag with the identifier "content". The result is shown above: an applied stylesheet, separate background colors for the top and bottom of the page, our List Page inserted into the Layout, and an image.

The previous example arranges a List Page (based on a core List Page Type) within a Layout to provide the basic concepts involved in creating your own Layouts. Extending this idea, you could nest multiple pages within a Layout by adding you own Page Type (previously described in Adding Page Types). Suppose you wanted two List Pages in your Layout... one to list Samples, the other to list Projects:

In the custom JSP on which you base the Page Type, insert two pagecontent tags (<sapphire:pagecontent>), each with a unique identifier. For example, the body of one pagecontent tag could have an element tag that renders a list of Samples (the "name" attribute of the tag could be "samples"). The body of the other pagecontent tag could have an element tag that renders a list of Projects (the "name" attribute of this tag could be "projects). Each element tag would point to an appropriate List Element.

In the JSP on which your Layout is based, you could insert each pagecontent body into a different pagearea by matching the "name" attributes (one pagearea tag would have the "name" attribute set to "samples", the other set to "projects".

When creating a New Page (as shown in Creating a DDPs and Registering a Custom JSP in the Basic Principles section (Part 1) of this document), you can make your custom Layout available for use by displaying an image in the Choose Layout Style page of the page wizard. To do this:

The image will appear in the Choose Layout Style page each time you create a new page.

Creating Custom Wizards	Top

You can create your own custom wizard that lets users step backward and forward through pages. We supply the following to help you do this:

Among the features provided by the controller and API (and described in this section), the following list summarizes what will probably be the most-used:

A page must contain two items in order to work within a wizard:

An XML file stores the series of pages that make up the wizard. Following is an example of a wizard that creates a new page.

<wizard title="Create a new page." >

<step id="content" src="rc?command=file&amp;file=webadmin/wiz_choosecontenttype.jsp" help="Choose one of the options:">

<return value="serverjsp" nextstepid="pagedetails"/>

<return value="existingpageptree" nextstepid="pageptreepolicy"/>

</step>

<step id="pageptreepolicy" src="rc?command=file&amp;file=webadmin/wiz_chooseptreenode.jsp&amp;prefix=page&amp;" help="Choose the page-type node that best matches your requirements."/>

<step id="pagedetails" src="rc?command=file&amp;file=webadmin/pagedetails.jsp&amp;mode=add" help="Enter the final details and then click Finish to create the page."/>

<step id="elementnodes" src="rc?command=file&amp;file=webadmin/wiz_chooseelementptreenodes.jsp" help="Choose the element nodes."/>

<step id="layout" cancel="false" src="rc?command=file&amp;file=webadmin/wiz_chooselayout.jsp&amp;prefix=layout" help="Choose a layout style for your page." />

<step id="layoutnode" src="rc?command=file&amp;file=webadmin/wiz_chooseptreenode.jsp&amp;prefix=layout&amp;" help="Choose the layout node that best matches your requirements." />

<step id="createpage" src="rc?command=file&amp;file=webadmin/wiz_createpage.jsp" help="Please wait. Generating page..."/>

</wizard>

The wizard has a primary title ("Create a new page") and a series of steps. Each step can have the following attributes:

When a user clicks the Next button, the wizard calls a next() JavaScript function in the current page. All pages in the wizard must include a next() function, except for the following two kinds of pages:

The return value from the next() function is important. You can use it to control the flow of the wizard. For example:

The next() function of the first page in the above example could look something like the following, which defines control logic based on the user's selection:

function next() {

var selectedoption = getSelectedOption();

if ( selectedoption == null ) {

alert( "Please choose one of the source options." );

return null;

}

parent.setProperty( "contenttype", selectedoption.id );

if ( selectedoption.id == "serverjsp" ) {

return "serverjsp";

}

else if ( selectedoption.id == "existingpageptree" ) {

var selectedptree = getSelectedPTree();

if ( selectedptree == null ) {

alert( "Please choose one of the page types." );

return null;

}

else {

parent.setProperty( "pageptreeid", selectedptree.id );

return "existingpageptree";

}

}

}

The <sapphire:wizard /> tag has two optional attributes:

The Request Controller delivers the wizard harness using the command parameter "wizard" (as described in Calling the Request Controller). The parameter-value pair for the wizard defines the URL of the wizard xml file. For example, to launch the wizard defined in mystuff/newpage.xml:

rc?command=wizard&wizard=mystuff/newpage.xml

You can pass additional attributes into the wizard to control where the wizard goes if the user clicks the Cancel button or when the wizard is finished. These attributes are typically posted to the Request Controller servlet. A way of doing this is to create a JSP containing a form to submit values of hidden fields into the wizard. For example, this page might contain:

<form id="wizard" action="rc?command=wizard&wizard=mystuff/newpage.xml" method="POST">

<input name="wizardcancel" type="hidden" value="rc?<%=request.getQueryString()%>">

<input name="wizardcanceltarget" type="hidden" value="top">

<input name="wizardcomplete" type="hidden" value="rc?<%=request.getQueryString()%>">

<input name="wizardcompletetarget" type="hidden" value="top">

<input name="debug" type="hidden" value="N">

<input type="submit" value="Zubmeet ze furm">

</form>

You would then load this page. When you submit the form, it starts the wizard and passes all of these values into it for use by the wizard pages.

Two noteworthy items:

Enabling the Wizard Progress Bar

You can enable the Wizard Progress Bar in the left frame of the wizard, as well as jump back to previous steps in the wizard. To enable the Wizard Progress Bar, add this tag to the wizard XML file:

<wizard title="Create a new page." progressbar="true" progressbarjumping="true" >

Setting the attribute progressbarjumping to "true" lets the user jump back to previous steps in the wizard by clicking on a link in the Wizard Progress Bar.

You can also reset the Wizard Progress Bar (that is, restore all text to black up to the page to which you have jumped) by executing the JavaScript function resetProgressBar(). For example, if you are on step 5 of a wizard and you execute resetProgressBar() when step 2 is clicked, steps 3 through 5 will reset to black. CHECK THIS.

Disabling the Cancel Button

In a step of the wizard XML file, the cancel attribute disables the Cancel button while the page is being rendered and displayed:

<step id="deletedatabase" src="/sapphireconsole/database/deletedatabase.jsp" help="Deleting database" cancel="false"/>

The JavaScript function setWizardCancel() lets you do things if the Cancel button is clicked. For example, you may want to navigate to a page if the wizard is cancelled:

<script>

parent.setWizardCancel('rc?command=file&file=nextpage.jsp');

</script>

Passing Startup Properties into the Wizard

Any additional parameters sent into the servlet are automatically added as properties before the first page is rendered.

Skipping a Step

Occasionally it may be necessary for a page not to display anything and automatically move to the next step. Use the following JavaScript to do this:

<script>

parent.skip()

</script>

When the skip() function is executed, the wizard automatically passes control to the next step and removes the step from the Back button history.

Dynamically Changing the Complete URL

You can determine the completed URL when the wizard is at the end, rather than specifying it to the Request Controller servlet. For example, you may use the wizard to create an item in the database and, when the wizard is complete, you may want it to navigate to a page that shows that item. Use the following JavaScript to do this:

<script>

parent.setWizardComplete('rc?command=file&file=nextpage.jsp&itemid=<%=itemid%>');

</script>

Setting Properties Back into Fields from the Request Object

Typically, your page will include form elements such as <input> and <select> tags. In your next() function, you can store these values in the wizard using something like:

parent.setProperty( "value1", document.getElementById( "field1" ).value );

Then, in the next page, you can retrieve this value in a script using:

var = parent.getProperty( "value1" );

You may encounter a problem if the user later clicks the Back button to navigate back to this page, and the information needs to filled in again. You can avoid this problem using something like:

<input type="text" id="field1" value="<%=request.getParameter( "field1" ) == null ? "" : request.getParameter( "field1" )%>">

Alternatively, you can use JSTL to deal with this problem:

<input type="text" id="field1" value="<c:out value="${param.field1}" />">

Demonstration Pages

For demonstrations of these features, as well as all new functionality added by our developers, examine the wizard test pages by loading them at the following URL:

/sapphireadmin/rc?command=file&file=WEB-CORE/testpages/wizard/testwizard.jsp

In WEB-CORE\testpages\wizard, you will find examples of a standardized wizard, as well as examples of branching, the progress bar, and suggestions for alternative endings.

The following table lists JavaScript functions you can use to control wizards. When the API builds a wizard, these functions are installed in the "wizard bar" (the iframe, located at the bottom of the window, containing the wizard control buttons). Call each function on the parent object as shown in the previous examples, e.g.,

parent.function()

You can pass additional request parameters to a wizard page, then access the request parameter from the page within the wizard.

To do this, modify the wzInvokeWizard Page Type (implemented by WEB-OPAL/wizards/invokewizard.jsp) to pass the parameters and include them as hidden form fields in the wizard form.

Pages based on wzInvokeWizard use the "invoke_wizard.jsp" page to function. This jsp has a "form" named "wizard". This form has hidden variables. Whenever the user invokes the wizard or navigates through it, this form is submitted into a target iframe, i.e., present in the same "invoke_wizard.jsp" named wiz_iframe.

On form submission, the pages specified in the XML file are executed one-by-one, and allparameters are passed into that page.

To send extra request parameters to the inner page, those parameters must be included in the "wizard" form in the "invoke_wizard.jsp" page, then submitted. This is the code that performs the inclusion:

This code passes all provided request parameters to the inner wizard frame. These parameters can be retrieved either by "request.getParameter()" or "pageinfo.getProperty()" methods.

Recall that the variables wizardcancel, wizardcomplete, wizardcanceltarget, wizardcompletetarget, popup, debug, myfield, and sdcid are also sent to the inner page.