Controlling Ajax user interface layout

The following layout tags let you dynamically control the display:

• cfdiv
• cflayout
• cfpod
• cfwindow
  For information about how you can use these tags to submit form contents asynchronously, see Using Ajax containers for form submission in Using Ajax form controls and features.

Using the cfdiv tag

The cfdiv tag is a general-purpose container that lets you use a bind expression to specify its contents. It therefore lets you dynamically refresh any arbitrary region on the page based on bind events. By default, the tag creates an HTML div region, but it can create any HTML tag with body contents. Unlike other ColdFusion Ajax container tags, you can use any type of bind expression to populate contents: CFC or JavaScript function, URL, or a string with bind parameters. As a result, the cfdiv tag provides substantial flexibility in dynamically populating the page contents. 
The cfdiv tag is also useful if you want a form to submit asynchronously. That is, whether or not you use a bind expression to populate the tag. If you submit a form that is inside a cfdiv tag (including in HTML returned by a bind expression), the form submits asynchronously. The response from the form submission populates the cfdiv region. (The cflayoutarea, cfwindow, and cfpod tags have the same behavior.) For example, you could have a page with a form that includes a list of artists, and lets you add artists. If the form is in a cfdiv tag, when the user submits the form, the entire page is not refreshed, only the region inside the cfdiv tag. For an example of using container controls for asynchronous forms, see Using Ajax containers for form submission in Using Ajax form controls and features.
One use case for a cfdiv tag is an application where a cfgrid tag displays an employee list. Details of the selected row in the grid are displayed inside a cfdiv tag with a bind expression that specifies the cfgrid in a bind parameter. As users click through different employees on the grid, they get the employee details in the cfdiv region.
The following simple example shows how you can use the cfdiv tag to get data using a bind expression. It uses binding to display the contents of a text input field in an HTML div region. When a user enters text in the input box and tabs out of it, or clicks another region of the application, the div region displays the entered text.
The cfdiv tag.cfm file, the main application file, has the following contents.

The divsource.cfm file that defines the contents of the div region has the following code:

Using layouts

The cflayout tag controls the appearance and arrangement of one or more child cflayoutarea regions. The cflayoutarea regions contain display elements and can be arranged in one of the following ways:

• Horizontally or vertically.
• In a free-form bordered grid (panel layout) with up to five regions: top, bottom, left. right, and center. You can optionally configure the layout so that users can resize or collapse any or all of the regions, except the center region. The center region grows or shrinks to take up any space that other regions do not use. You can also dynamically show or hide individual regions, or let users collapse, expand, or close regions.
• As a tabbed display, where selecting a tab changes the display region to show the contents of the tab's layout area. You can dynamically show and hide, and enable and disable tabs, and optionally let users close tabs.
  You can configure a layout area to have scroll bars all the time, only when the area content exceeds the available screen size, or never. You can let layout area contents extend beyond the layout area. You can also nest layouts inside layout areas to create complex displays. 
  You can define the layout area content in the cflayoutarea tag body. But, you can also use a bind expression to dynamically get the content by calling a CFC function, requesting a CFML page, or calling a JavaScript function.
  ColdFusion provides many JavaScript functions for managing layouts, including functions to collapse, expand, show, and hide border areas; and to create, enable, disable, select, show, and hide tabs. For a complete list of functions, see Ajax JavaScript Functions in the CFML Reference.
  The following example shows the use of a tabbed layout, including the use of JavaScript functions to enable and disable a tab, and to show and hide a tab.

For an example that uses a bordered layout with cfpod children, see the next section. For another example of a tab layout, see the cflayoutarea tag in the CFML Reference. For an example of a bordered layout nested inside a layout area of a vertical layout, see cflayout in the CFML Reference.

Styling layouts

The cflayout and cflayoutarea tags have style attributes. The cflayout tag style attribute controls the style of the layout container, and sets default values for many, but not all, styles for the layout areas. For example, the color and background color styles of the cflayout tag set the default text and background colors in the layout areas. But the cflayout tag border style sets only the color of the border around the entire layout, not the layout area borders. The cflayoutarea tag style attribute controls the style of the individual layout area and overrides any corresponding settings in the cflayout tag. 
As is often the case with complex controls, the effects of layout and layout area styles can vary. For example, do not often specify the height style in the cflayout tag; instead, specify height styles on each of the cflayoutarea tags.
The following simple example shows a tab layout with two layout areas. The layout has a light pink background color, and the layout areas have three pixel-wide red borders.:

Using pods

The cfpod control creates a content region with a title bar and surrounding border. You can define the pod content in the cfpod tag body, or you can use a bind expression to dynamically get the content from a URL. Pods are frequently used for portlets in a web portal interface and for similar displays that are divided into independent, possibly interactive, regions.
You control the pod header style and body style independently by specifying CSS style properties in the headerStyle and bodyStyle attributes. 
The following example uses multiple pods inside cflayoutarea tags to create a simple portal. The time pod gets the current time from a CFML page. The contents of the other pods is defined in the cfpod bodies for simplicity. Each pod uses the headerStyle and bodyStyle attributes to control the appearance.
The cfpodExample.cfm application has the following code:

In this example, the podweather.cfm page contains only the following line. A more complete example would dynamically get the weather from a feed and format it for display.

Using pop-up windows

ColdFusion HTML pop-up windows have the following characteristics:

• They have title bars
• They float over the browser window and can be placed at an arbitrary location over the window.
• They can be modal (users cannot interact with the main window when the pop-up window is displayed) or non-modal (users can interact with both windows).
• You can specify that the user can drag, close, or resize the window.
• You can create and show a window independently. After you create the window, you can use JavaScript functions to show and hide it multiple times without having to create it again.

Display and hide windows

You display a window in the following ways:

• By using a ColdFusion cfwindow tag with an initShow attribute value of to create and show the window.
• By using a ColdFusion cfwindow tag with an initShow attribute value of false and calling the ColdFusion.Window.show JavaScript function to display it.
• By using ColdFusion.Window.create and ColdFusion.Window.show JavaScript functions.
  You can hide a window that is currently showing by calling the ColdFusion.Window.hide function. You can use the ColdFusion.Window.onShow and ColdFusion.Window.onhide functions to specify JavaScript functions to run when a window shows or hides.
  The following example shows how you can create, display, and hide a window. It also shows several of the configuration options that you can set, including whether the user can close, drag, or resize the window. When you run the application, the cfwindow tag creates and shows Window 1. You can then hide it and reshow it. To show Window 2, click the Create Window 2 button, followed by the Show Window 2 button. You can then hide and show it.
  The following example shows the main application page:

The window2.cfm file with the contents of Window 2 has the following contents:

Use the window show and hide events

You can use the onShow and onHide events that are triggered each time a window shows and hides to control your application. To do so, call the ColdFusion.Window.onShow and ColdFusion.Window.onHide functions to specify the event handlers. Both functions take the window name and the handler function as parameters. The event handler functions can take a single parameter, the window name. 
The following example displays an alert message when a window hides or shows. The alert message includes the window name. The alert does not show when the window first appears, because the cfwindow tag uses the initShow attribute to initially display the window. An alert message does appear when the user hides the window by clicking the Toggle Window button or the close button on the window.

Control container contents

ColdFusion provides a variety of ways to set and change container tag contents:

• You can use bind expressions in the container tag source (or for cfdiv, bind) attribute. The container then dynamically updates any time a bound control changes.
• You can call the ColdFuson.navigate function to change the container body to be the contents returned by a specified URL. This function lets you specify a callback handler to do additional processing after the new content loads, and also lets you specify an error handler.The callback handler can be useful to provide information about a successful navigation operation. For example, you could make a pod's title bar italic to indicate loading (just before the navigate call), and use the callback handler to switch it back to normal once the navigate completes. Similarly, if a pod is showing pages from a book, the callback handler could update a page number in a separate field once a page loads
• You can use the special controlNamebody variable to access and change the body contents for cfpod and cfwindow controls. For example, you can use the _controlNamebody.innerHTML property to set the body HTML. For cfpod and cfwindow tags, you can also use the _controlName_title to get or set the title bar contents of the control.
  These different techniques provide you with flexibility in writing your code. For example, the ColdFuson.navigate function and the controlNamebody variable provide similar functionality. However, with the _controlNamebody technique, you make explicit Ajax requests to get markup for the body, and the JavaScript functions in the retrieved markup might not work properly. ColdFusion.navigate takes care of these issues. Therefore, limit use of the _controlName_body technique to simpler use cases.
  The following example shows how you can use various techniques to change container contents. It consists of a main page and a second windowsource.cfm page with text that appears in a main page window when you click a button. The main page has a cfpod control, two cfwindow controls, and the following buttons:

• The "Simple navigate" button calls a ColdFusion.navigate function to change the contents of the second window.
• The "Change w2 body & title" button replaces the second window's body and title innerHTML values directly to specific strings.
• The "Change pod body" button changes the pod body innerHTML to the value of the second window's title innerHTML.
  The following example shows the main page:

The following example shows the windowsource.cfm page: