Adobe ColdFusion 8

cflayoutarea

Description

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

Category

Display management tags

Syntax

In a border layout
<cflayoutarea
    required 
    position="bottom|center|left|right|top"
    optional
    align="left|center|justify|right"
    closable="false|true"
    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|scroll|visble"
    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
    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"
    title="string">

    area elements 

</layoutarea>

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.

See also

cfdiv, cflayout, cfpod, cfwindow, "AJAX JavaScript Functions", "Using layouts" in the ColdFusion Developer's Guide

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

closable

Optional

false

border, 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.

You cannot use this attribute for border layout areas with a position attribute value of center.

collapsible

Optional

false

border

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.

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.

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

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 maximum 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

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.

refreshOnActivate

Optional

false

tab

  • true: Refresh the contents of the tab by running the source bind expression whenever the tab display region shows (for example, when the user selects the tab), in addition to when bind events occur.
  • false: Refresh the tab display region only when the bind expression is triggered by its bind event.

To use this attribute, you must also specify a source attribute.

selected

Optional

first tab is selected

tab

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, you must 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, you must 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.

title

Optional; required for tab layouts

 

border, tab

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.

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 ColdFusion Developer's Guide.

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 center position 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, you must 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.

Note: When you use the style attribute to specify the background color of a border layout area, you must 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>