cfpod

Description

Creates a pod, an area of the browser window or layout area with an optional title bar and a body that contains display elements.

Syntax

<cfpod 
    source = "path" 
    bodyStyle = "CSS style specification" 
    headerStyle = "CSS style specification" 
    height = "number of pixels" 
    name = "string" 
    onBindError = "JavaScript function name" 
    title = "string" 
    width = "number of pixels"/> 
 
OR 
 
<cfpod 
    bodyStyle = "CSS style specification" 
    headerStyle = "CSS style specification" 
    height = "number of pixels" 
    name = "string" 
    onBindError = "JavaScript function name" 
    title = "string" 
    width = "number of pixels"> 
        pod contents 
</pod>

If the tag does not have a body and end tag, close it with /> character combination.

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

Description

bodyStyle

Optional

 

A CSS style specification for the pod body.

As a general rule, use this attribute to set color and font styles. Using this attribute to set the height and width, for example, can result in distorted output.

headerStyle

Optional

 

A CSS style specification for the pod header.

As a general rule, use this attribute to set color and font styles. Using this attribute to set the height and width, for example, can result in distorted output.

height

Optional

100

Height if the control, including the title bar and borders, in pixels

name

Optional

 

Name of the pod control.

onBindError

Optional

See Description

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

Specifies how to display child content whose size would cause the control to overflow the pod boundaries. The following values are valid:

  • auto: shows scrollbars when necessary.

  • hidden: does not allow access to overflowing content.

  • scroll: always shows horizontal and vertical scroll bars, even if they are not needed.

  • visible: content can display outside the bounds of the pod.

Note: In Internet Explorer, pods with the visible setting expand to fit the size of the contents, rather than having the contents extend beyond the layout area.

source

Required if the tag does not have a body

 

A URL that returns the pod contents. ColdFusion uses standard page path resolution rules.

If you specify this attribute and the cfpod tag has a body, ColdFusion ignores the body contents.

You can use a bind expression with dependencies in this attribute; for more information see Usage.

Note: If a CFML page specified in this attribute contains tags that use AJAX features, such as cfform, cfgrid, and cfwindow, you must use a cfajaximport tag on the page with the cfpod tag. For more information, see cfajaximport.

title

Optional

 

Text to display in the pod’s title bar. You can use HTML mark-up to control the title appearance, of example to show the text in red italic font. If you omit this attribute, the pod does not have a title bar.

width

Optional

500

Width if the control, including borders, in pixels.

Usage

You use a source attribute or a tag body to specify the pod 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.

To use a bind expression, specify a URL and pass one or more URL parameters the page, including bind parameters. In its most basic form, a bind parameter consists of the name or id attribute of the control to which you are binding in braces ({ }). To include the value of the city control as a bind parameter, for example, use the following format:

source="/myapplication/cityPod.cfm?cityname={city}"

For detailed information about using bind expressions, see Binding data to form fields in the Developing ColdFusion Applications.

Example

The following CFML page displays two pods in a vertical layout. Each pod gets its contents from a displayforpod.cfm page that uses the cffeed tag to get an Atom feed.

<html xmlns="http://www.w3.org/1999/xhtml"> 
<head> 
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> 
<title>Untitled Document</title> 
</head> 
 
<body> 
<cflayout type="hbox" style="background-color:##CCffFF; color:red;"> 
    <cflayoutarea> 
        <cfpod name="pod01" source="displayforpod.cfm?start=1" height="500" width="300" 
            title="Comment 1"/> 
    </cflayoutarea> 
    <cflayoutarea> 
        <cfpod name="pod02" source="displayforpod.cfm?start=2" height="500" width="450" 
            title="Comment 2"/> 
    </cflayoutarea> 
</cflayout> 
</body> 
</html>

The following code shows the contents of the displayforpod.cfm page:

<cffeed action="read" source="http://googleblog.blogspot.com/atom.xml" 
            query="feedQuery" properties="feedMetadata" > 
 
<cfloop query = "feedQuery"  
        startRow = "#url.start#" endRow = "#url.start#"> 
    <cfoutput>#feedQuery.content#<br /> 
    =========================================<br/> 
    </cfoutput> 
</cfloop>