ColdFusion 9.0 Resources

cflayoutarea

Description

Defines a region within a cflayout tag body, such as an individual tab of a tabbed layout.

Syntax

In a border layout 
<cflayoutarea 
    required 
    position="bottom|center|left|right|top" 
    optional 
    align="left|center|justify|right" 
    collapsible="false|true" 
    initcollapsed="false|true" 
    inithide="false|true" 
    maxSize="number of pixels" 
    minSize="number of pixels" 
    name="string" 
    onBindError = "JavaScript function name" 
    overflow = "auto|hidden" 
    size="number of pixels" 
    source="URL" 
    splitter="false|true"  
    style="CSS style specification" 
    title="string"> 
 
    area elements 
 
</cflayoutarea> 
 
In a hbox or vbox layout 
<cflayoutarea 
    optional 
    name="string" 
    onBindError = "JavaScript function name" 
    overflow = "auto|hidden|scroll|visble" 
    size="number of pixels" 
    source="URL" 
    style="CSS style specification"> 
 
    area elements 
 
</layoutarea> 
 
In a tab layout 
<cflayoutarea 
    optional 
    bindonload="false|true" 
    closable="false|true" 
    disabled="false|true" 
    inithide="false|true" 
    name="string" 
    onBindError = "JavaScript function name" 
    overflow = "auto|hidden|scroll|visble" 
    refreshOnActivate = "false|true" 
    selected="false|true" 
    source="URL" 
    style="CSS style specification" 
    tabTip="text" 
    title="string"> 
 
    area elements 
 
</layoutarea>  
 
In an accordion layout 
<cflayoutarea 
    optional 
    bindonload="false|true" 
    closable="false|true" 
    name="string" 
    onBindError = "JavaScript function name" 
    overflow = "auto|hidden|scroll|visble" 
    refreshOnActivate = "false|true" 
    selected="false|true" 
    source="URL" 
    style="CSS style specification" 
    title="string" 
    titleicon="icon location"> 
 
    area elements

If you specify a source attribute, all child tags are ignored. If you do not have child tags, close the tag with />.

Note: You can specify this tag’s attribute in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag’s attribute name as structure key.

History

ColdFusion 8: Added this tag

Attributes

Attribute	Req/Opt	Default	Applies to	Description
`align`	Optional	The `cflayout` tag `align` attribute value	all	Specifies how to align child controls within the layout area. The following values are valid: `center` `justify` `left` `right`
`bindLoad`	Optional	true	tab, accordion	A Boolean value that specifies whether to execute the source attribute expression when the layoutarea is first loaded.
`closable`	Optional	false	tab	A Boolean value that specifies whether the area can close. Specifying this attribute adds an x icon on the tab or title bar that a user can click to close the area.
`collapsible`	Optional	false	border, accordion	A Boolean value that specifies whether the area can collapse. Specifying this attribute adds a >> or << icon on the title bar that a user can click to collapse the area. You cannot use this attribute for border layout areas with a `position` attribute value of `center`.
`disabled`	Optional	`false`	tab	A Boolean value that specifies whether the tab is disabled, that is, whether a user can select the tab to display its contents. Disabled tabs are greyed out. Ignored if the `selected` attribute value is `true`.
`initCollapsed`	Optional	`false`	border	A Boolean value that specifies whether the area is initially collapsed. You cannot use this attribute for border layout areas with a `position` attribute value of `center`. Ignored if the `collapsible` attribute value is `false`.
`initHide`	Optional	`false`	border, tab, accordion	A Boolean value that specifies whether the area is initially hidden. To show an initially hidden area, use the `ColdFusion.Layout.showArea` or `ColdFusion.Layout.showTab` function. You cannot use this attribute for border layout areas with a `position` attribute value of `center`.
`maxSize`	Optional	-1 (no maximum size)	border	If the `position` attribute value is `top` or `bottom`, the maximum height of the area, in pixels, that you can set by dragging a splitter. If the `position` attribute value is `left` or `right`, the maximum width of the area. You cannot use this attribute for border layout areas with a `position` attribute value of `center`.
`minSize`	Optional	-1 (no minimum size)	border	If the `position` attribute value is `top` or `bottom`, the minimum height of the area, in pixels, that you can set by dragging a splitter. If the `position` attribute value is `left` or `right`, the minimum width of the area. You cannot use this attribute for border layout areas with a `position` attribute value of `center`.
`name`	Optional		all	The name of the layout area.
`onBindError`	Optional	See Description	all	The name of a JavaScript function to execute if evaluating a bind expression results in an error. The function must take two attributes: an HTTP status code and a message. If you omit this attribute, and have specified a global error handler (by using the `ColdFusion.setGlobalErrorHandler` function), it displays the error message; otherwise a default error pop-up displays.
`overflow`	Optional	`auto` For accordion, if `fillheight` attribute of the `cflayout` tag is false, default value is `hidden`.	all	Specifies how to display child content whose size would cause the control to overflow the window boundaries. The following values are valid: `auto`: show scroll bars when necessary. `hidden`: do not allow access to overflowing content. `scroll`: always show horizontal and vertical scroll bars, even if they are not needed. `visible`: content can display outside the bounds of the layout area. Notes: You cannot use `visible` or `scroll` for layout areas in border layouts. In Internet Explorer, layout areas with the `visible` setting expand to fit the size of the contents, rather than having the contents extend beyond the layout area.
`position`	Required if the `cflayout` type is `border`		border	The position of the area in the layout. Must be one of the following values: `top`: Position the area across the top of the full layout. `bottom`: Position the area across the bottom of the full layout. `left`: Position the area on the left side of the layout, between any visible top and bottom areas. `right`: Position the area on the right side of the layout, between any visible top and bottom areas. `center`: Position the area in the space not taken by the top, bottom, left, and right areas. Border style layouts can have at most one layout area of each type.
`refreshOnActivate`	Optional	`false`	tab, accordion	`true`: Refresh the contents of the tab/ accordion panel by running the `source` bind expression whenever the tab/panel display region shows (for example, when the user selects the tab), in addition to when bind events occur. `false`: Refresh the tab/accordion panel display region only when the bind expression is triggered by its bind event. To use this attribute, also specify a `source` attribute.
`selected`	Optional	first tab is selected	tab, accordion	A Boolean value that specifies whether this tab is initially selected so that its contents appears in the layout.
`size`	Optional	-1 calculate initial size dynamically	border, hbox, vbox	For hbox layouts and border layouts with `position` attribute values of `top` or `bottom`, the initial height of the area. For vbox layouts and border layouts with `position` attribute values of `left` or `right`, the initial width of the area. For hbox and vbox layouts, you can use any valid CSS length or percent format (such as 10, 10% 10px, or 10em) for this attribute. For `border` layouts, this attribute value must be an integer number of pixels. You cannot use this attribute for border layout areas with a `position` attribute value of `center`. ColdFusion automatically determines the center size based on the size of all other layout areas. Note: If a layout area in a border layout contains only AJAX controls such as HTML format `cftree` tags, specify a `size` attribute. Otherwise, the AJAX components may not be visible until the layout area is resized.
`source`	Optional		all	A URL that returns the layout area contents. ColdFusion uses standard page path resolution rules. You can use a bind expression with dependencies in this attribute. If a file specified in this attribute includes tags that use AJAX features, such as `cfform`, `cfgrid`, and `cfpod`, use the `cfajaximport` tag on the page that includes the `cflayoutarea` tag. For more information, see `cfajaximport`. For more information on the `source` attribute, see Usage.
`splitter`	Optional	false	border	A Boolean value that specifies whether the layout area has a divider between it and the adjacent `layoutarea` control. Users can drag the splitter to change the relative sizes of the areas. If this attribute is set to `true` on a `left` or `right` position layout area, the splitter resizes the area and its adjacent area horizontally. If this attribute is set to `true` on a `top` or `bottom` position layout area, the splitter resizes the layout vertically. You cannot use this attribute for border layout areas with a `position` attribute value of `center`.
`style`	Optional		all	A CSS style specification that controls the appearance of the area.
`tabTip`	Optional		tab	If defined, a tab tip is displayed.
`title`	Optional; required for tab layouts		border, tab, accordion	For tab layouts, the text to display on the tab. For border layouts, if you specify this attribute, ColdFusion creates a title bar for the layout area with the specified text as the title. By default, border layouts that are not closable or collapsible do not have a title bar. You cannot use this attribute for border layout areas with a `position` attribute value of `center`.
`title`icon	Optional		accordion	Specifies the location of the icon to display with the title.

Usage

All cflayoutarea tags must be children of cflayout tags and cannot have cflayoutarea tags as immediate children, but they can contain cflayout tags. However, the cflayoutarea tags do not have to be direct children of the cflayout tag; instead, the cflayout tag could have a tag such as cfloop or cfquery as a child, and the cflayoutarea tags could be in the body of the cfloop or cfquery tag. These rules let you create arbitrarily complex combinations of different layouts.

Note: You cannot put a layout of type border inside a layout of type tab.

If you do not specify a size attribute value, ColdFusion attempts to determine the required size for the layout area contents. However, in some cases, such as when the layout area contains AJAX controls, ColdFusion might not be able to determine the required size, and you must specify the size attribute to make the AJAX control appear. In these cases, a scroll bar appears for the layout area.

You can use a source attribute or a tag body to specify the layout area contents; if you specify both, ColdFusion uses the contents specified by the source attribute and ignores the tag body. If you use a source attribute, an animated icon and the text "Loading..." appears while the contents is being fetched.

If the source attribute specifies a page that defines JavaScript functions, the function definitions on that page must have the following format:

functionName = function(arguments) {function body}

Function definitions that use the following format may not work:

function functionName (arguments) {function body}

However, Adobe recommends that you include all custom JavaScript in external JavaScript files and import them on the application’s main page, and not write them inline in code that you get using the source attribute. Imported pages do not have this function definition format restriction.

If you use the source attribute, you can use a bind expression to include form field values or other form control attributes as part of the source specification. You can bind to HTML format form controls only. For detailed information on using bind expressions see Using Ajax Data and Development Features in the Developing ColdFusion Applications.

In border type layouts, a center layout area always takes up any space that is not used by the other areas, even if you do not specify a cflayoutarea tag with a centerposition attribute. Therefore, if you want only two layout areas in either direction, one of the two must be the center area, or you must explicitly size the two areas to take up the full layout area.

When you nest layouts, set the inner layout area initial sizes appropriately to ensure that they appear.

Use the following JavaScript functions to enable, disable, show, hide, expand, collapse, and select layout areas:

Function	Description
ColdFusion.Layout.createTab	Creates a tab in an existing tabbed layout.
ColdFusion.Layout.disableTab	Disables the specified tab so it cannot be selected.
ColdFusion.Layout.enableTab	Enables the specified tab so users can select it and display the area contents.
ColdFusion.Layout.hideTab	Hides a tab.
ColdFusion.Layout.selectTab	Selects a tab and displays the layout area contents.
ColdFusion.Layout.showTab	Shows a tab that was hidden using the `inithide` attribute or the `hideTab()` function.
ColdFusion.Layout.collapseArea	Collapses an area of a border layout.
ColdFusion.Layout.expandArea	Expands a collapsed area of a border layout.
ColdFusion.Layout.getTabLayout	Hides an area of a border layout.
ColdFusion.Layout.hideArea	Hides an area of a border layout.
ColdFusion.Layout.showArea	Shows an area of a border layout that was hidden using the `inithide` attribute or the `hideArea()` function.
ColdFusion.Layout.hideAccordion	Hides an accordion.
ColdFusion.Layout.showAccordion	Shows an accordion that was hidden using the `inithide` attribute or the `hideArea()` function.
ColdFusion.Layout.selectAccordion	Selects an accordion and displays the layout area contents.
ColdFusion.Layout.collapseAccordion	Collapses an area of an accordion layout.
ColdFusion.Layout.expandAccordion	Expands a collapsed area of an accordion layout.

Note: When you use the style attribute to specify the background color of a border layout area, specify a height style of 100% to make the background color cover the entire layout area. This is because the style specification applies to an inner content area of the layout area, not the layout area itself, and the 100% specification ensures that the content area takes up all available space in the layout area.

Example

The following example creates a three-tabbed layout and lets you use buttons to dynamically control the second tab.

<html> 
<head> 
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> 
</head> 
<body> 
<h3>Atab</h3> 
<cflayout type="tab" name="thelayout" tabheight="175" style="background-color:##CCffFF; 
        color:red; height:200"> 
    <cflayoutarea title="Tab 1" style="background-color:##FFAAFF;" closable="true"> 
        This is text in layout area 1 
    </cflayoutarea> 
    <cflayoutarea name="area2" title="Tab 2" inithide="true"  
            style="background-color:##FFCCFF" > 
        This is text in layout area 2 
    </cflayoutarea> 
    <cflayoutarea title="Tab 3" style="background-color:##FF99FF;"> 
        This is text in layout area 3 
    </cflayoutarea> 
</cflayout> 
<br /> 
<cfform> 
    <cfinput name="show" width="40" value="show tab" type="button"  
        onClick="ColdFusion.Layout.showTab('thelayout', 'area2');"> 
    <cfinput name="hide" width="40" value="hide tab" type="button"  
        onClick="ColdFusion.Layout.hideTab('thelayout', 'area2');"> 
    <cfinput name="enable" width="40" value="enable tab" type="button"  
        onClick="ColdFusion.Layout.enableTab('thelayout', 'area2');"> 
    <cfinput name="disable" width="40" value="disable tab" type="button"  
        onClick="ColdFusion.Layout.disableTab('thelayout', 'area2');"> 
    <cfinput name="select" width="40" value="select tab" type="button"  
        onClick="ColdFusion.Layout.selectTab('thelayout', 'area2');"> 
</cfform> 
</body> 
</html>