Working with Pages

Working with Pages
This document covers the following topics:
About Pages
Pages and their with Actions (Actions) are the building blocks of ActiveGrid applications. Each ActiveGrid Page represents a displayable chunk of content in your application. The Pages that you define in your application are not necessarily the “web application pages” displayed in the client browser. Each Page that the user sees is typically composed of several independently rendered ActiveGrid Pages. Think of Pages as components or pieces of a web page as it is displayed in a browser.
Pages display in AJAX-enabled areas, called AJAXFrames, that can be refreshed independently. ActiveGrid Applications all have one Page “container” called the Page Frame. All the other Pages in the application are displayed in the main AJAXFrame within the Page Frame. Individual Pages can themselves contain AJAXFrames, in which they can display other Pages.
Because the ActiveGrid Server can refresh the content of each AJAXFrame independently, only the relevant portion of the application Page has to be reloaded when the user takes an action. Each Page is defined in its own file. Page files are XForm files and they end in the .xform suffix. ActiveGrid Applications all have one Page “container” called the Page Frame. All the other Pages in the application are displayed in the main AJAXFrame within the Page Frame.
Individual Pages can also contain AJAXFrames, in which they can display other Pages. An ActiveGrid “web application page” is typically composed of several independently rendered ActiveGrid Pages. It can be helpful to think of Pages as components or snippets of web pages. The following figure illustrates how Pages might be displayed in AJAXFrames “nested” within other Pages.
Actions
Each button or link on the Page is tied to one or more Actions. The Actions tell the Server what operations to perform, what Page to load next, and so on. They orchestrate the flow between the different Pages. Actions are defined in the Page Flow for the project (“About Page Flows” on page 69).
Each Page in the application is displayed in an AJAXFrame, either in the main AJAXFrame on the Page Frame, or in an AJAXFrame in another Page. The location in which the Page is loaded is a property of the Action. Each Action has a target that specifies how and where to display the results of that Action. For example, the target might specify the ID of a particular AJAXFrame, or it might specify that the results display in a pop-up.
The preceding illustration shows a Page that contains two AJAXFrames. The top AJAXFrame contains a Page called OnePage.xform. When a user clicks the button on that Page, the Action associated with that button loads a different Page into the bottom AJAXFrame.
The Target property of the Action specifies where the Page is rendered. In the above illustration, the Target property is set to the ID of the lower AJAXFrame (BottomAJAXFrameID). Each AJAXFrame has a unique ID that Actions can target. In addition, ActiveGrid provides three other targets: popup, hover popup, and MainAJAXFrame (the AJAXFrame built into the Page Frame).
About Page Structure
In the Page Editor (Working with the Page Editor) each Page is presented as a hierarchical tree with three top-level nodes, which you can expand to view their contents:
Page Message: This node provides access to the Page Message, which defines the structure of the data that gets passed to the Page. In the Page Editor you can add and delete Message Parts to the Page Message, add default values and so on. See “Page Message” for more information.
Page Variables: This node provides access to the Page Variable, which allows you to define and populate variables for use on the Page itself. See “Page Variables” for more information.
Page: This node is where you add all the elements of the Page, such as tables, lists, text fields, buttons, links, images, and so on. For more about Page elements, see Page Elements and Page Properties.
Page Message
Each Page has an associated Page Message that defines the structure of the data for the Page. The Page Message is actually a Message Type, that specifies the structure of the data expected by the Page.
Each Page Message consists of one or more Message Parts. Message Parts have a data type, which can be a simple type (such as string or integer) or a complex type.
Each Page that you generate in the ActiveGrid Studio has at least one Message Part. The Message Part provides the backing data for that Page. You can add Message Parts to the Page Message and you can delete existing parts. You can also set up default values for Message Parts.
How the Page Message is Populated
Typically, a Page is loaded when a users clicks a button or link on another Page, triggering an Action that performs some piece of logic and then invokes the Page. Actions are discussed in “About Actions” on page 70. For now, what you need to know is that some Actions send specific data to the Page and some simply call the Page without sending any data.
1.
When the Page is first invoked, the ActiveGrid Server looks at the message generated by the Action that called the Page, if any. The Server uses any data in this incoming message to populate the data in the Page Message for this Page.
2.
If the incoming data does not contain a value for a particular element, the Server looks to see if a default value is defined for that element in the Page Message. If it is, the Server populates that element with the default value.
3.
The Server then populates Page Variables. Dependent Page Variables are populated after the variables on which they depend.
4.
Page Variables
In addition to the Page Message, each Page also has a Page Variable section. While Page Message gets passed back and forth between the server and client as part of the application flow, the Page Variable is used only to render the Page.
For example, you can use a Page Variable to perform a calculation on the values of Message Part elements. You could also use a Page Variable to do a database query or invoke a web service.
You cannot, however, use Page Variables in the Actions invoked from the Page. If you want to access data in an Action, then you must include that data in the Page Message. In particular, you cannot use Page Variables to implement scrollable data sets.
Use Page Variables rather than Message Parts in the Page Message where possible.
Accessing Session Information on the Page
The ActiveGrid Server maintains session information. The specific session persistence model that the ActiveGrid Server uses does not matter to the web application itself.
The session contains an instance of all active objects at the time the last response was sent. The ActiveGrid sys variable provides access to system and user created session information.
 
Returns the object that was implicitly selected by the user when they clicked on an action (Accessing Session Information on the Page).
Page Elements and Page Properties
In the Page Editor, the final top-level node is the Page node. The Page node is where you add and arrange all the elements of your Page, such as buttons and links, inputs and outputs, navigation, banners, footers and so on.
Each element on the Page has a set of associated properties that you can view and edit in the Property Editor. For each Page element, the most important properties are:
About Page Layouts
Each element on a Page has an associated layout. The layout defines the look and feel for the associated element. Most layouts have parameters that you can set to specify how you want the layout to look or where you want it placed.
ActiveGrid uses CSS for all layouts, but the CSS is not separated out into a generated file. Instead, each individual layout contains its own CSS. Layouts are the chunks of HTML/JS/CSS that are used to render elements of your Page, based on what is selected in the Appearance property for that element.
Layouts are defined in a file called LayoutRenderer.lyt. You can also create your own layout file (.lyt) in the Layout Editor and add the new layout to your project. The new layouts you defined will then be available to your application, along with the layouts provided in the LayoutRenderer.lyt file.
About Skins
Skins are used as application-wide style guidelines. They include font families to use, navigation styles, colors, and table styles. You can override these elements for an individual layout, but generally you set the style for your application by using the Skin Chooser to apply a skin. Skins are defined in the LayoutRenderer.skn file.
About AJAXFrames
AJAXFrames are similar to iFrames in that they define regions on the screen as areas that can display content. You can display any Page within an AJAXFrame. Each AJAXFrame has a unique ID. These IDs are used by Submits to target AJAXFrames in which to display results.
Each Submit on the Page has at least one associated Action that tells the Server what to do when a user clicks that button, link or tab. Each Action has a target property that specifies the ID of an AJAXFrame in which to display the results of that Action. If the Action does not have the target property set, then that submission’s response will take up the entire Page.
In an ActiveGrid Application, each Page has only one form that the user can submit. The form can’t span multiple AJAXFrame. You can’t submit something that’s on a different AJAXFrame.
AJAXFrames are refreshed independently from each other and the Page Frame does not get refreshed at all. A big part of the application design is deciding how you’re going to lay out your AJAXFrames and what content displays in which AJAXFrame. Group together Pages that are likely to update at the same time.
About the Page Frame
ActiveGrid Applications use a Page called the Page Frame (PageFrame.xform) which acts as a frame for each individual Page in your application as it is displayed. The Page Frame specifies all the content that is common to all the Pages in the application, such as a banner, main navigational links, and so on.
Note: The Page Frame content is not refreshed. If you want dynamic content in the Page Frame, put the dynamic content in a separate Page and then include that Page in an AJAXFrame the Page Frame.
The Page Frame contains one special element, called the MainAJAXFrame element, that you use as a placeholder for the individual Pages. You place the MainAJAXFrame element in the location where you want the individual Page to display within the Page Frame. Each ActiveGrid Application contains one and only one PageFrame.xform file.
Working with the Page Editor
The Page Editor typically displays Pages in two side-by-side panels. On the right, the Preview Panel shows you how the Page is rendered in a browser. On the left, the Page Editor allows you to edit, arrange and configure all the items that make up your Page layout (groups, links, images, text blocks, and so on). The far right panel contains the Property Editor, which allows you to edit the properties for the selected item.
The Page Editor
The Page Editor shows the Page as a hierarchical collection of elements. At the top of the hierarchy is the Page Message. Below the Page Message is the Page Variables element, followed by the root element for the Page. The Page element contains elements representing the content of the Page.
The Preview Panel
The Preview Panel shows you how the Page looks when rendered in a browser. You cannot make changes to a Page from within the Preview Panel. Its purpose is to show you the result of the changes you make in the Page Editor and the Property Editor Panels.
If you prefer, you can set the ActiveGrid Studio options to display previews in a separate browser window instead of a Preview Panel. You can alternatively choose to display previews both in the Preview Panel and also in a separate browser window. To set your browser preferences, select the Options... item in the Tools menu, then click the Browser tab.
The Property Editor
The Property Editor allows you to edit properties for the selected Page element. To edit a property, click in the field and begin typing. Different properties are available for different items in the Page.
Page Properties
This section discusses properties for Page elements. Properties appear in the Property Editor. Most are straightforward, such as “Name” or “Label”. Others, such as LabelRef or Role Visibility, require a little more explanation:
Complete List of Page Properties
The following table provides a list of all the properties that might appear in the Property Editor. For a more detailed discussion of important properties, see Working with Important Page Properties
 
Optional. Name that appears in the Page Editor. Select a descriptive name, such as BannerGroup, OuterGroup, and so on.
Alternate means of supplying a label for the field. This is an XPath expression of a data item to use as the label for the field. The XPath is relative to the point in the current document at which this field appears. A LabelRef overrides anything specified in the Label property. See Labels and LabelRefs.
Specifies the layout to use to render this field. When you double-click on the Appearance value, the Pick a Layout dialog appears. See The Layout Property.
Icon to use for buttons. The image must be under the static folder in the directory for the application. The image can be in a subdirectory, called images for example, within the static folder.
A property for Page Actions only. Specifies where the page invoked by the Action should be displayed (in a popup, or in a specific AJAXFrame for example)
When the Image is an image map, this specifies what rectangle within the image map is associated with this field.
Working with Important Page Properties
This section explains the most important Page element properties in detail:
Labels and LabelRefs
The Label property specifies the text label for items such as input fields, output fields, submission buttons, links and so on. For example, the Label property specifies the text that appears on a button.
The LabelRef, on the other hand, labels each button or link in an iterative list. You use the LabelRef to tie the text of the label/button to some selected data, typically an element in a complex type. Each value for the specified element becomes a label for a link or button in that list.
For example, the standard List Page presents a table that is tied to a complex type, so that it can display a list of values for each element.
The Message Ref Property
The Message Ref property ties the selected item in the Page to a data object. The Application Wizard sets up these references for you, but if you create your own Pages you’ll need to set up the references yourself.
For example, look at the Page in the following figure. The LayoutTable Group contains a table that references the product Message Part from the Page Message. This Message Ref tells the application where to get the data for this Page.
Items in the Page can inherit the Message Ref property from a parent item. The default is the root of the backing message for the Page itself. For more information on the Message Ref property, and on relative and absolute references, see the The ActiveGrid Application Model Overview.
The Layout Property
Layouts have parameters that let you override default CSS attributes. To access the layout for an element, double-click on the Layout property for the element. The Pick a Layout screen appears. Here you can set parameters for the current layout or change to a different layout.
Different Layouts allow you to set different parameters, so the dialog looks different depending on what layout is selected. Basically, the dialog allows you to set the following things:
Layout: The Layout pull-down menu allows you to choose the type of layout you want to use for the selected element (see System Layouts).
Parameters: Some layouts have parameters that you can use to set appearance and behavior of the layout. For example, a table layout might have parameters for specifying cell spacing and padding.
Override Skin Parameters: For some layouts, display parameters are determined by the skin you selected for the application. In many cases you can override these skin settings for a particular element. The Override Skin Parameters section lists all the skin parameters that you can override for the selected element. Typical examples include font family and color.
CSS Selectors: You can access custom layouts for an element using CSS selectors. Here you can specify the name of any valid CSS class in the layout or in an external stylesheet linked from the layout (“The ag:css Tag” on page 193).
If you need more control over layout than the Layout property provides, you can edit and create layouts yourself (“Creating Custom Layouts” on page 191).
The Condition Property
The condition property allows you to make the display of a particular element conditional. When the condition expression is true, the element displays. Conversely, when the condition expression is not true, the element does not display.
Syntax for condition expressions is based on a subset of XPath. Your condition expression can include:
Note: Greater than and less than comparators work for simple types, for numeric types (like xs:int) and for xs:string. However, these comparators are not guaranteed to work for date/time types, and they will not work for complex types.
 
The Input Pattern Property
The Input Pattern property sets up server-side field validation for a particular input field. (The Input Pattern property appears only on input fields.) This property allows you to validate the user input against a regular expression. You would typically set this property for input fields where the input must be of a specific form.
For example, to require a 5-digit number, you would type in the following regular expression for the Input Pattern property:
^\d{5}$
To require either a 5-digit or a 9-digit number, you would use the following regular expression:
^\d{5}(?:[- ]?\d{4})?$
To set up client-side validation for an input field, use the Validation Regular Expression parameter field on the text input layout. The following figure shows an example.
The Role Visibility Property
The Role Config property allows you to hide individual Page elements from some users, based on user role. You can set this property only in applications that have one or more defined roles. By default, each Page element is visible to all users. If you want to hide specific Page elements from a user role, double-click on the Role Config property and select the roles for which you want to hide the selected Page element.
For example:
1.
2.
In the Project Panel, double-click on the RestrictedEdit.xform file. The file opens in the Page Editor.
3.
Now in the Form Container on the Page, select the check box element referencing emptradingrestricted.
4.
5.
By default, each Page element is visible to all users. In this example, we want the users with the manager role to see this Page element. First, click to uncheck the All Roles check box.
6.
7.
Now, in the Preview Panel, preview the Page for the trader role. The check box element does not appear for users with this role.
For more information on setting up user roles in ActiveGrid applications, see “Role-Based Access Control” on page 143.
The Target Property
The Target property is associated with Actions on the Page. The Target property specifies where the Page invoked by the Action is rendered. When you double-click on the Target property for a particular Page Action, the Set the Target screen appears.
The Set the Target screen offers three main options:
Clear the Target: When you choose the Clear the Target option, the Page invoked by the Action replaces the current Page in its AJAXFrame.
PopupWindow: Displays the invoked Page in a separate popup window (Pop-up Windows).
MainAJAXFrame: Displays the invoked Page in the Main AJAXFrame built into the Page Frame (About AJAXFrames).
Target an AJAXFrame in another Page: You can choose to display the invoked Page in an AJAXFrame defined in another Page in the application (About AJAXFrames).
Working with Layouts
You can rearrange different elements within the Page by dragging and dropping them in the Page Editor. Use the group layouts to group individual elements on the Page. You can move items into different groups or to a different place within a particular group.
ActiveGrid provides several different layouts to choose from for each basic type of Page element. The types of Page elements are as follows:
Group: Groups things on the Page. Some group layouts actually display on the Page, such as a bordered group layout, while others are intended for placement only. See “Groups”.
Input Field: Fields in which users can type input or controls in which users can select input (such as check boxes or drop-down menus). You tie these to incoming Page data by setting the Message Ref property. See “Input Fields”.
Output Field: Fields that display output from the data source. You tie a field to specific Page data by setting the Message Ref property. See “Output Fields”.
AJAXFrame: AJAX-enabled frames that can display a Page. Similar to iFrames. Each AJAXFrame has an ID that identifies it. See “AJAXFrames”.
Submit: Buttons, links, or tabs that perform a submit. Each submit needs an associated Action that tells the Server what to do on the submit. See “Submits”.
 
Groups
Groups are layouts that help you place content on the Page. There are four general categories of group layouts:
“Placement Groups”: Some group layouts, such as HTML Table are designed mainly to place other elements on the Page. These layouts typically offer a variety of parameters for positioning and spacing child elements. When you need a finer granularity in placing your content on the Page, choose a placement group.
“Presentation Groups”: These layouts are designed to be visible to the user. They offer more presentation parameters (colors, fonts, heading bars, and so on) than do the placement groups. When you want more options for look and feel, choose a presentation group.
“Navigation Groups”: These layouts display their children as menu items. They are designed for Page navigation, but you can use them for any group of submits you choose. They all have mouse-over effects and when clicked, preserve what the user has clicked on. (Tabs stay clicked, menu items highlighted).
Note: Although the grid layouts are specifically designed to display lists, any group layout will unpack a list. To cause a group layout to iterate over the contents of a list, set the Message Ref for the group layout to the list and then make the Message Refs for the child elements relative to the parent’s Message Ref.
For a list of all available group layouts, see “Group Layouts”.
Placement Groups
ActiveGrid provides some group layouts to help you place items on the Page. These layouts are not intended to be visible to the user. The most commonly-used of these placement group layouts are:
Single Cell Layout Table: This layout is a single table cell for placing elements on the Page. It provides a multitude of parameters allowing you to set cell padding, border, alignment, height, width and so on.
HTML Table: This layout creates a standard HTML table, with parameters for setting table height, width, alignment and so on. It has two child layouts: HTML Table Cell and HTML Table Row. Use these child layouts to add rows and columns to the table.
Horizontal Layout Group and Vertical Layout Group: These simple group layouts display their children in rows or columns, respectively. Each has parameters for customizing padding, alignment, height, width and font. You can nest these groups to create more complex layouts.
Presentation Groups
These layouts are designed to be visible containers for other Page elements. For example, the Form Container layout is a parent group layout for the elements of a form.
The Form Container layout is a two-column layout. The Label Column displays the labels for the form elements and the Value Column contains the form elements themselves. The layout has parameters that allow you to set the widths of the Label and Value columns as percentages of the total width of the form. You can also set the alignment of the Label Column (values are left, right or center). The Form Container layout also has parameters that you can set to customize the form’s fonts and colors.
The Bordered Group layout is a parent group that displays its child Page elements in a single-cell table with a single-pixel border surrounding it. The Bordered Group layout has two special child layouts that work with it: Bordered Group Header provides a title bar for the group and Bordered Group Footer provides a footer.
Navigation Groups
ActiveGrid provides some standard navigation groups to help you provide cohesive navigation in your application. The most commonly-used navigation groups are:
Vertical Tabbed Navigation Group: A group designed to contain a column of tabs. Provides a variety of parameters for customizing colors and fonts. The tabs should use the Vertical Tabbed Navigation Links layout. Nest the entire Vertical Tabbed Navigation Group inside a Vertical Navigation Page Container layout.
Horizontal Bar Navigation Group: A group that presents a bar of tabs across the screen. Provides a variety of parameters for customizing colors and fonts. The tabs should use the Horizontal Bar Navigation Link layout.
Group Layouts
The following table lists the available group layouts.
 
Bordered groups, that when you click on their header bar, alternate between normal and minimized.
A footer layout. This can be used as a footer for another element, or as the layout of a page. It displays its children left-justified in a table.
This layout displays its children in a single-cell table with a single-pixel border surrounding it. It has two child layouts designed to work with it: Bordered Group Footer and Bordered Group Header.
This layout is designed to create a header for a Bordered Group. Use it as a child of the Bordered Group layout. It can display child elements or a label.
This layout creates a footer for a bordered group. Use it as a child of the Bordered Group layout. It can display child elements or a label.
This layout is designed to display a form. Use it as a parent layout to the input, output and submit layouts for a form.
This menu shows its children in a horizontal bar. Its child elements must be of layout Horizontal Bar Navigation Link.
This layout creates a single-row table where each child element is created in a separate column. This can be used with a Vertical layout to create complex nested tables.
Use these groups, nested together, to form complex table structures. Border, Colspan, Rowspan, Width, Height, etc - are all exposed on all relevant elements so that you can create a completely custom table. This should eliminate the need for custom pageframe layouts, as well as add greater flexibility in laying out a page.
This is a special page footer that displays its contents always at the bottom of the page. The layout is displayed in front of all of the other elements, and hugs the bottom of the browser viewport, even when scrolling.
This layout is used at the top of your application, and displays the application title.
This layout is the same as the Page Title Bar layout, but it shows a logo on the right margin of the title bar.
This menu, which can be used for any menu and not just navigation despite the name, creates a drop-down menu in DHTML that appears and disappears at the press of a button. Its child elements must be of type Popup Navigation Link.
This layout displays its children in a single-cell colored table with rounded corners.
This layout creates a single-cell table and displays its children within that cell. Single Cell Layout Table is especially useful for page layout because it exposes many of the properties of a table (cellspacing, cellpadding, align, valign, width, height) as parameters that can be accessed by double-clicking on the appearance attribute of a Page element with appearance = LayoutTable.
This is the parent element of a set of Toolbar Button layouts. It displays as a horizontal bar that can contain any number of buttons or links, to be displayed as a standard application tool bar.
This layout creates a transparent gif on a page, that can be used by a designer to restrict the size of tables or provide padding. The height and width of the gif can be manipulated using its appearance attributes.
This layout forms a DHTML tree control, with children that are folders or menu items. Its children must be of type Tree Control Item. To construct a tree, create the tree structure in the Page using PagesGroups (folders) and PagesSubmits (links), and set them all to layout = Tree Control Item.
This layout creates a single-column table where each child element is created in a separate row. This can be used with a Horizontal layout to create complex nested tables.
The parent layout of a list of links that are displayed vertically within a containing table. All child elements must be of layout Vertical Link List Link.
This creates a two-columned table, one the width of the vertical nav group, the other *.
This menu displays vertically on the page, typically down the left margin. Clicking on an item leaves the item set to the background color of the site, so it appears to be a tab connected to the page contents. Its child elements must be of type Vertical Tabbed Navigation Link.
 
 
This group creates a standard HTML Image Map. The group takes one or more submits elements as child elements. These submits must be in the Image Map Area layout.
 
 
 
Grid Data Display
Grids are layouts that are meant to display data in a grid, or table. Typically you use grid layouts to “unpack” lists of data. The layout iterates over each row of data in the list, displaying it as a row in the grid.
There are three main grid layouts: “Paginating Grid”, “AJAX Scrolling Grid” and “Scrolling Grid”. You can use these layouts interchangeably. They differ mainly in how they handle multiple “pages” of data.The size of a “page” of data in a list is determined by the Page Size setting in the query that populates the list.
To use a grid layout to unpack a list, you set the Message Ref of the group to point to the appropriate complex type in the Page Message. The Message Refs of the child elements in the group should point to the relevant piece of that complex type. These Message Refs should use paths relative to the Message Ref of the group itself.
If you include buttons or links in the list, set the Label Ref to the relevant piece of the complex type. Again, the path should be relative to the parent group.
AJAX Scrolling Grid
This layout displays its data in an AJAX-enabled scrolling grid. This layout initially loads only the first page's worth of data. When a user scrolls the table, the layout makes an asynchronous call to the server to retrieve the next set of rows, and then appends them to the bottom of the table.
As the user scrolls down the page, the application retrieves the next rows and places them in the grid as the user scrolls to them. Column headers on this table are clickable to sort, however multiple-column sorting (stable sort) is not supported at this time.
For this table to function properly, you need to set the paging size large enough that the number of rows returned is always more than the viewable area of the Page. If the paging size is too small, or the size of the layout too big, scrollbars do not appear, making scrolling impossible
Scrolling Grid
Similar to the AJAX Scrolling Grid, this layout displays its data in a scrolling grid. However, unlike the AJAX-enabled grid, this layout treats all the data in the grid as a single Page, that it loads when the application initially renders the grid. If there is more data on the Page than can display in the size of the layout, then scrollbars appear.
Because the scrolling grid layout gets only one “page” of data, you need to make sure that the Page size is large enough to contain all the data in the list. Otherwise, the grid will not contain all the data.
Paginating Grid
This layout displays its data in a paged grid that includes Next and Previous buttons at the bottom of the Page for navigation. Column headers are clickable to sort in alternating ascending or descending order. Multiple-column sort (stable sort) is not supported at this time.
Input Fields
Input fields allow users to type in or select data. Each input field must reference a field from the Page Message so that the Server knows what to do with the input from that field. To tie the input field to the appropriate piece of the Page Message, you use the Message Ref property (“The Message Ref Property”).
ActiveGrid provides several basic input field layouts including Text Input, Text Area, Password Input and Popup Calendar.
There are also a variety of “select” inputs, in which users can make a selection from a list. Select input layouts include Check Box, Drop Down List, Multiple Select List, and Radio Button Group.
Selects
Selects, such as pull-down menus, allow users to select an item from a set of possible values. You can add items to the list individually, or you can a set of items, or both. To add a set of items, you need to add a reference to a complex type.
There is a detailed example on using selects in the ActiveGrid Studio Tutorial, in the section on customizing an application.
Lookup Fields
The following figure shows a lookup fieldand lookup button.
When a user clicks the button, the list of available choices for the lookup field appears in a pop-up window.
When the user selects an item in the list, the application automatically populates the lookup field with the users’s selection.
In order to get the lookup field to work properly, make sure you do the following:
Add a GoTo Action to the Page containing the lookup field and Button. This Action should invoke the target Page for the lookup button--the Page that contains the list of items the user chooses from.
Insert the lookup field and lookup button. The Action for the lookup button is the Action you created in the previous step. The target for this Action must be the built-in Target, called PopUp Window (The Target Property).
The lookup button layout has a parameter that contains the ID of the corresponding Lookup Field. Similarly, the Lookup Field layout has a parameter that holds the ID of the Lookup Field. These IDs need to match.
On the “target” Page, the Page that pops up when the user clicks the button, create a Grid layout. Within the grid, add a Lookup Value Link. It’s very important to correctly select the Message Ref for the Lookup Value link. Rather than selecting the referenced element relative to the container, (the Paginating Grid), select it from the Page Message.
The Lookup Value Links all look the same (by default, they just say “Select”) so add at least one Text Output Field to the grid, so that users can see what they’re selecting.
Cascading AJAX Drop Downs
Cascading AJAX Drop Downs take a user selection from a drop down menu and populate another drop down menu based on that selection. In the following example, we create a drop down menu showing product categories. When the user selects a category, the drop down menu showing product IDs is populated with all the products in the specified category.
To make this work, you need to create a Cascading AJAX Drop Down Source menu to select the category and then create a Cascading AJAX Drop Down Destination menu to select the product. The following example shows you how to create Cascading AJAX Drop Downs for a simple application based on the Pet Store SQLite database that ships with the ActiveGrid Studio:
1.
Generate an application (File > New...) from a data source based on the SQLite database, db, that is included with the Pet Store demo application:
In the Choose Tables dialog, click the Deselect All button and then select the Category table and the Product table.
2.
Before we create the drop downs, we need to create a custom Action to populate the second drop-down based on the results from the first. To write the custom Action, first open the Page Flow file for the project (ProductMaint.bpel).
3.
In the ProductInsert Page, right-click and select Insert Action > Custom... from the resulting pop-up menu. The Custom Action Details screen appears.
4.
Select a Page to go to when the Action completes. Pick any Page you want, because we are going to delete this invoke when we customize the Action.
5.
In the Action Name: field type:
DropDownAction
6.
Click Next. The Presentation screen appears. Click to deselect the checkbox labled, Add Button and Submission to Source Page.
7.
Click Finish. The new Action appears in the ProductInsert Page in the Page Flow Editor. Double-click on the new Action to open it in the Custom Action Editor.
The Action has no variables and one invoke. The invoke corresponds to whatever Page you selected to go to when the Action completes.
8.
9.
Right-click on the Variables box and select Add Variable... from the resulting pop-up menu. The Variable Details screen appears.
10.
In the Name field, type:
ReplyVariable
11.
From the Type menu, select ProductMaint:ProductInsertMsg.
12.
Right-click on the Variables box again, and this time select Add Set... from the resulting pop-up menu. The BPEL Set screen appears.
13.
Click the XPathRef... button next to the Set: field. The Select an XPath dialog appears. Select ReplyVariable/product and click OK.
14.
Click the Database Query radio button.
15.
In the Filter field, click on the Column button. The Select a Column dialog appears.
16.
17.
From the Operator drop down, select the equals sign (=).
18.
19.
Click OK. The BPEL Set screen should look like the following.
20.
Click OK. The Set appears in the Custom Action Editor.
21.
Right-click on the Set you just created and select Add Reply... from the resulting pop-up menu. The Reply Variable screen appears.
22.
In the Variable field, select ReplyVariable from the pull-down menu.
23.
Click Finish.
24.
Save the file. The custom Action is complete. Next we create the drop down select that displays a list of all the entries in the Category table from the Data Model.
25.
In the Project Panel, double-click on the ProductInsert.xform Page. The Product Insert Page appears in the Page Editor.
This Page contains fields for specifying the Product ID, the Product Category, and the product’s name, image and description. We need a Page Variable that references the Category table in the Data Model. Then we can do a database query on that table.
26.
Right-click on the Page Variables node on the Product Insert Page and select the Insert Page Variable... option from the resulting menu. The Insert Page Variable screen appears.
27.
In the Name field, type:
category
28.
Choose to populate from a Database Query. Then, from the Type menu, select ProdMaint.xsd:Category. Then click OK.
29.
30.
Right-click on the Form Container and select the Insert Input Field > Other > Cascading AJAX Drop Down Source option. The Insert Action screen appears.
31.
Select DropDownAction from the list, and click OK. The Pick a Reference dialog appears.
32.
 
33.
The Add Choices screen appears. Click the radio button to Automatically render choices based on existing data and click Next. The Create a Set of Choices screen appears.
34.
For the Type field, click the XPath... button and select the category message part that you created in the Page Variables node.
35.
Click OK. Back in the Create a Set of Choices screen:
For the Labels Column, choose name.
For the Values column, choose catid.
36.
Click Finish. Then, on the Select Choices dialog, click OK.
The Cascading Drop Down Source element appears in the form container. Double-click on the layout in the Property Editor to see the parameters you need to set for this layout.
The first parameter in the list specifies the Action that the layout calls when a user selects an item from the source menu. This parameter is automatically populated with the name of the Action you selected when you created the drop down.
37.
/message/product
38.
productid
39.
name
40.
41.
Next, in the Page Editor, right-click on the Form Container and select Insert Input Field > Cascading AJAX Drop Down Destination. The Pick a Reference screen appears.
42.
43.
The Add Choices screen appears. Click the radio button to automatically render choices based on incoming data and then click Next. The Create a Set of Choices screen appears.
44.
Click the XPath... button and select product from the XPath picker.
45.
For the Labels column, select name.
For the Values Column, select productid.
46.
Click Finish.
47.
48.
49.
Run the application. In the running application, click on the Product tab, then on the Insert Product button. The Product Insert Page appears. Select a category from the category drop down.
50.
Input Layouts
The following table lists the available input layouts.
 
A combo-box layout that allows the user to select only one value. This is equivalent to the HTML element <select>
A multi-select layout that allows the users to select more than one element. This is equivalent to the HTML element <select multiple>
This layout displays as a text input with an ellipsis button following it. Clicking on the ellipsis causes a dynamic calendar to appear in front of the page, and a user can select a date or time using that calendar, and have the value appear in the text input. The format of this datetime string can be set in the appearance attributes of any PageInput with an appearance set to PopupCalendar.
The Lookup Field layout requires an adjacent Lookup Button. When you click the button, a popup list appears. You select an item from the list and that item automatically populates the Lookup Field. To set up a Lookup Field, refer to Cascading AJAX Drop Downs.
A drop-down select menu that is automatically populated based on the user’s selection in another drop down menu. Used in conjunction with one or more Cascading AJAX Drop Down Source layouts.
A drop-down select menu. When the user selects an item in this drop-down, the next drop down is automitically populated based on the user’s selection. You can chain any number of these drop downs together, but you must always end with a Cascading AJAX Drop Down Destination layout.
The Drop Down Form Submit layout creates a drop down menu. When a user selects an item from the menu, the form is submitted.
Output Fields
Output fields display data from the Page Message. Each output field must reference a field from the Page Message so that the Server knows what to display in that field. To tie the output field to the appropriate piece of the Page Message, you use the Message Ref property (“The Message Ref Property”).
ActiveGrid provides several basic output field layouts including Labeled Text Output, Plain Text Output, Text Area, and Image.
Output Layouts
The following table lists the available output layouts.
 
Using a layout parameter for the date/time string format, it outputs formatted date/time strings.
Boolean Image. Use this layout for a boolean value. Set the parameters to specify the path to two images:the image to display if the value is TRUE (1) and the image to display if the value is FALSE (0).
IFrame layout displays a web page in a scrollable IFrame. The IFrame layout takes a URL so the Message Ref needs to reference a URL.
Use the Lookup Value Link layout in conjunction with the Lookup Field and Lookup Button layouts. When a user clicks a Lookup Button, a popup list appears, containing a list of Lookup Value Links. When the user clicks on one of these links, that item automatically populates the Lookup Field. To set up a Lookup Field, refer to Cascading AJAX Drop Downs.
Similar to the IFrame layout, except that you specify the URL for the IFrame in the layout parameter called Content URL.
Takes a URL to an image and displays the image specified by that URL. You specify the URL in the layout parameter called Image URL.
Submits
Submits are Page elements (such as buttons or links) that trigger Actions defined in the Page Flow. Each Submit can have one or more associated Actions. If a submit has more than one Action, then the Server executes each Action in sequence.
In order to add a Submit, the Page must have at least one Action defined in the Page Flow (see “About Page Flows” on page 69). When you insert a Submit in the Page Editor, you are prompted to select an Action from the Page Flow:
Select the Action you want the Submit to trigger.
Set the Target property on the Action to specify where to display the results of the Action.
Set the Ref property to specify what Page data to send back to the Server when the Action is triggered.
Action Target Property
The Target property specifies where to display the results of the Action. Typically, you specify an AJAXFrame (“About AJAXFrames”) on the Page or the Main AJAXFrame in the Page Frame (“About the Page Frame”). You can also choose to display the results in a pop up menu.
Action Ref Property
The Ref property specifies which user-changed fields are actually sent back to the server when the form is submitted. If the Ref property is blank (no Ref) then the application sends back all the changed fields. Alternatively, you can use the Ref property to restrict what objects get sent back. If you do not want to send anything back, type in the following value for the Ref property:
null()
For example, a navigational link to another Page would have a Ref property value of null().
You can alternatively use the URL property to specify a URL to send when a submission-type field is activated. The URL property overrides the submission field.
Submit Layouts
The following table lists the available submit layouts.
.
This layout displays a button that can be clicked on. This replaces the FormSubmitButton and can be used to submit forms or for external links.
Displays the item's value as the src of a link, and the output value as the text of the link.
This layout defines an imagemap HTML element. It can have any number of children of layout Area that define a clickable area. Clicking on the area will cause the link to be fired.
This layout uses the href value of an item as its link, and its label as the text of the link.
This layout displays as a button. The button is flat, but upon mouseover appears raised, and upon mousedown appears pressed in. The button otherwise functions similar to LinkButton.
 
Use the Lookup Button layout in conjunction with the Lookup Field and Lookup Value Link layouts. When a user clicks a Lookup Button, a popup list appears, containing a list of Lookup Value Links. When the user clicks on one of these links, that item automatically populates the Lookup Field. To set up a Lookup Field, refer to Cascading AJAX Drop Downs.
 
A specialized link that displays the results of an RSS Feed request. Use this layout as the child of a grid layout.
This menu displays vertically on the page, typically down the left margin. Clicking on an item leaves the item set to the background color of the site, so it appears to be a tab connected to the page contents. Its child elements must be of type Vertical Tabbed Navigation Link.
AJAXFrames
When you create an AJAXFrame, you assign it a unique ID. Each Action launched by a Submit on the Page has a property called Target. The value of the Target property is the ID of the AJAXFrame in which you want to display the results of the Action.
When you create an AJAXFrame, you can specify a Page to load in it initially or you can choose for the AJAXFrame to be empty until the user triggers an Action that targets that AJAXFrame. If you choose the latter option, you can also choose to hide the AJAXFrame until a Page gets displayed in it.
The ActiveGrid Studio includes the following three “built-in” AJAXFrames:
MainAJAXFrame is the built-in AJAXFrame on the Page Frame (“About the Page Frame”).
Pop-up Window displays the Page in a separate pop-up window that can be closed independently from the client browser (“Pop-up Windows”).
Pop-up Windows
Pop-ups appear in front of all the other content on your Page. The pop-up has a title bar that the user can click and drag to reposition the pop-up on the Page. This is implemented using DHTML and <div> tags, and does not open a new browser window. The pop-up stays on the page until it is closed explicitly by clicking on a close button in the upper right corner of the pop-up. Pop-ups can be used as search boxes, or anything else, and interact with other portions of the page.
Hover Pop-ups
A hover pop-up is like a sophisticated tool-tip, or mouse-over. It displays its contents in an information bubble that appears in relation to the submit that calls it, and you can not drag or resize it. A click anywhere else on the page will cause the hover pop-up to close.
Hover pop-ups are useful for displaying small additional amounts of information, without any interactivity. While a standard pop-up can be an integral part of a user interface with rich interactivity, a hover pop-up is just meant to display a few lines of text or an image.
To use a hover pop-up:
1.
2.
3.
4.
A dialog box appears asking you to select a layout. Select Hover Submit. You want Hover Submit group to be the parent of whatever your trigger is.
5.
6.
In the Layout Parameters, type in the name of the submission that you would like to have called when the mouse hovers over this area for a period of time. This would be the submission you selected in step 1. Click OK to return to the Page Editor.
7.
Now you can add various outputs, text, inputs, whatever you want inside the HoverSubmit group. When your application is run and a user hovers over anything inside that group, your submission will be called and the results displayed in a Hover pop-up.
Static Images
To add an image to a Page, right-click on a group in the Page and choose Insert Image... from the resulting pop-up menu. A file chooser dialog appears listing all images files under the static directory for this project selected. Select the image you want and click OK. The image node appears in the Page Editor. The static image layout is called Image and has no parameters.
If the image is not in the static directory, or in a sub-folder under the static directory, you cannot add it to the Page. If the image you want does not appear in the file chooser list, exit the file chooser, copy the image to the static directory for the project, and then insert the image.
Static Text
To insert static text or HTML, right-click on a Page element and choose Insert Text... from the resulting pop-up menu. An Insert Text Component dialog box appears. Enter your text and click OK. The text element appears in the Page.
To enter HTML markup, double-click on the Layout property for the text node you just created. The Pick a Layout screen appears. Select the Markup layout from the drop down list. Type the HTML into the Markup Text fields in the layout parameters.
 
Use it to display HTML markup as text on a page. This layout provides four markup fields as layout parameters. Type your text, with HTML tags, into the Markup Text fields in the parameters section of the Markup layout.
This is the layout for plain (static) text. Enter or edit the displayed text in the Value property field. for the text node.
System Layouts
System Layouts are used by the ActiveGrid system. Editing these can result in unexpected consequences. These include error messages, and application-wide settings and methods.
 
The default layout used when no layout is specified, or a layout that has been specified can not be found. It does not display data, but rather an error message about the missing component.
This is the layout for all AJAXFrames. It specifies an area of the page for an included Page to be loaded in. The dimensions of this layout can be adjusted on an individual layout basis by double-clicking on the appearance parameter on the individual Page element for an AJAXFrame. Settings include width, height, and what to do with overflow. Overflow is a CSS property that can be set to 'auto' to enable scrolling on the data within the AJAXFrame. The contents of an AJAXFrame are set via asynchronous calls to the server side. Those calls are defined in the Master layout.
The Hidden Enter Submit layout is used by the system to set up text entry fields. When a user types something in a search field or another text-entry field, and then hits Enter, the client executes the submit. The system sets up forms to do this automatically, so you do not need to use the Hidden Enter Submit layout yourself.
This is the master layout that all other layouts are contained within when the page is constructed. This contains methods for constructing application pages, displaying errors, pop-ups, and AJAXFrames. User history and back button state saving are handled in the Master as well. This contains the starting head and body tags for the pages that will be generated in ActiveGrid. The master layout essentially provides the client-side framework for the application. It is the layout for the root node of the PageFrame page. Do not attempt to edit the master layout.
Layout Reference Table
The following table lists all the available layouts.
 
Bordered groups, that when you click on their header bar, alternate between normal and minimized.
Grid Group
This is the layout for all AJAXFrames. It specifies an area of the page for an included Page to be loaded in. The dimensions of this layout can be adjusted on an individual layout basis by double-clicking on the appearance parameter on the individual Page element for an AJAXFrame. Settings include width, height, and what to do with overflow. Overflow is a CSS property that can be set to 'auto' to enable scrolling on the data within the AJAXFrame. The contents of an AJAXFrame are set via asynchronous calls to the server side. Those calls are defined in the Master layout.
A footer layout. This can be used as a footer for another element like a Bordered Group, or as the layout of a page. It displays its children left-justified in a table.
This layout displays its children in a single-cell table with a single-pixel border surrounding it. It has two child layouts designed to work with it: Bordered Group Footer and Bordered Group Header
This layout creates a footer for a bordered group. Use it as a child of the Bordered Group layout. It can display child elements or a label.
This layout is designed to create a header for a Bordered Group. Use it as a child of the Bordered Group layout. It can display child elements or a label.
This layout displays a button that can be clicked on. This replaces the FormSubmitButton and can be used to submit forms or for external links.
The default layout used when no layout is specified, or a layout that has been specified can not be found. It does not display data, but rather an error message about the missing component.
A combo-box layout that allows the user to select only one value. This is equivalent to the HTML element <select>
Displays the item's value as the src of a link, and the output value as the text of the link.
This layout is designed to display a form. Use it as a parent layout to the input, output and submit layouts for a form.
Using a layout parameter for the date/time string format, it outputs formatted date/time strings.
This menu shows its children in a horizontal bar. Its child elements must be of layout Horizontal Bar Navigation Link.
This layout creates a single-row table where each child element is created in a separate column. This can be used with a Vertical layout to create complex nested tables.
HTML Table, HTML Table Row, HTML Table Cell
Use these groups, nested together, to form complex table structures. Border, Colspan, Rowspan, Width, Height, etc - are all exposed on all relevant elements so that you can create a completely custom table. This should eliminate the need for custom pageframe layouts, as well as add greater flexibility in laying out a page.
This layout defines an imagemap HTML element. It can have any number of children of layout Area that define a clickable area. Clicking on the area will cause the link to be fired.
This layout uses the href value of an item as its link, and its label as the text of the link.
This is the master layout that all other layouts are contained within when the page is constructed. This contains methods for constructing application pages, displaying errors, pop-ups, and AJAXFrames. User history and back button state saving are handled in the Master as well. This contains the starting head and body tags for the pages that will be generated in ActiveGrid. The master layout essentially provides the client-side framework for the application. It is the layout for the root node of the PageFrame page. Do not attempt to edit the master layout.
A multi-select layout that allows the users to select more than one element. This is equivalent to the HTML element <select multiple>
This is a special page footer that displays its contents always at the bottom of the page. The layout is displayed in front of all of the other elements, and hugs the bottom of the browser viewport, even when scrolling.
This layout is the same as the Page Title Bar layout, but it shows a logo on the right margin of the title bar.
This is a single-line input that has been deprecated and its functionality included in BasicFormTextInput.
A text field input whose value is hidden by asterisks (*). This is used for password fields.
This layout displays as a text input with an ellipsis button following it. Clicking on the ellipsis causes a dynamic calendar to appear in front of the page, and a user can select a date or time using that calendar, and have the value appear in the text input. The format of this datetime string can be set in the appearance attributes of any PageInput with an appearance set to PopupCalendar.
This menu, which can be used for any menu and not just navigation despite the name, creates a drop-down menu in DHTML that appears and disappears at the press of a button. Its child elements must be of type Popup Navigation Link.
Works like a drop down (item set stuff) - but displays its results in a group of radio buttons.
This layout displays its children in a single-cell colored table with rounded corners.
This layout creates a single-cell table and displays its children within that cell. Single Cell Layout Table is especially useful for page layout because it exposes many of the properties of a table (cellspacing, cellpadding, align, valign, width, height) as parameters that can be accessed by double-clicking on the appearance attribute of a Page element with appearance = LayoutTable.
This is the parent element of a set of Toolbar Button layouts. It displays as a horizontal bar that can contain any number of buttons or links, to be displayed as a standard application tool bar.
This layout displays as a button. The button is flat, but upon mouseover appears raised, and upon mousedown appears pressed in. The button otherwise functions similar to LinkButton.
This layout creates a transparent gif on a page, that can be used by a designer to restrict the size of tables or provide padding. The height and width of the gif can be manipulated using its appearance attributes.
This layout forms a DHTML tree control, with children that are folders or menu items. Its children must be of type Tree Control Item. To construct a tree, create the tree structure in the Page using PagesGroups (folders) and PagesSubmits (links), and set them all to layout = Tree Control Item.
This layout creates a single-column table where each child element is created in a separate row. This can be used with a Horizontal layout to create complex nested tables.
The parent layout of a list of links that are displayed vertically within a containing table. All child elements must be of layout Vertical Link List Link.
This creates a two-columned table, one the width of the vertical nav group, the other *.
This menu displays vertically on the page, typically down the left margin. Clicking on an item leaves the item set to the background color of the site, so it appears to be a tab connected to the page contents. Its child elements must be of type Vertical Tabbed Navigation Link.
The top-level layout for a Page. This contains no HTML, but rather is a container for the Page elements that will be rendered as its children.
 

ActiveGrid
Application Developer's Guide
Version 2.0