cfwindow

Description

Creates a pop-up window in the browser. Does not create a separate browser pop-up instance.

Category

Syntax

<cfwindow
    bodyStyle = "CSS style specification"
    center="true|false"
    closable="true|false"
    draggable="true|false"
    headerStyle = "CSS style specification"
    height="number of pixels"
    initShow="false|true"
    minHeight="number of pixels"
    minWidth="number of pixels"
    modal="true|false"
    name="string"
    onBindError = "JavaScript function name"
    refreshOnShow = "false|true"
    resizable="true|false"
    source="path"
    title="string"
    width="number of pixels"
    x="numeric pixel coordinate"
    y="numeric pixel coordinate">

        window contents

</cfwindow>

If you use the source attribute, ColdFusion ignores any tag body contents. If you do not have a tag body and omit the </window> end tag, you must close the cfwindow tag with the /> 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.

See also

cfajaximport, cfdiv, cflayout, cfpod, ColdFusion.Window.create, "Using pop-up windows" in the ColdFusion Developer's Guide

History

ColdFusion 8: Added this tag.

Attributes

Attribute	Req/Opt	Default	Description
bodyStyle	Optional		A CSS style specification for the window 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.
center	Optional	false	A Boolean value that specifies whether to center the window over the browser window. If `true`, ColdFusion ignores the `x` and `y` attribute values. If `false`, and you do not specify `x` and `y` attributes, ColdFusion centers the window.
closable	Optional	true	A Boolean value that specifies whether the user can close the window. If `true`, the window has an X close icon.
draggable	Optional	true	A Boolean value that specifies whether the user can drag the window. To drag the window, click the mouse on the title bar and hold the button down while dragging. If the window does not have a title, users cannot drag it.
headerStyle	Optional		A CSS style specification for the window 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	300	Height of the window in pixels. If you specify a value greater than the available space, the window occupies the available space and the resize handles do not appear.
initShow	Optional	false	A Boolean value that specifies whether to display the window when the containing page first appears. If this value is `false`, use the ColdFusion.Window.show JavaScript function to display the window.
minHeight	Optional	0	The minimum height, in pixels, to which users can resize the window.
minWidth	Optional	0	The minimum width, in pixels, to which users can resize the window.
modal	Optional	false	A Boolean value that specifies whether the window is modal, that is, whether the user can interact with the main window while this window is displayed. If `true`, the user cannot interact with the main window.
name	Optional		The name of the window. Must be unique on the pages. This attribute is required to interact with the window, including to dynamically show or hide it.
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 specified a global error handler (by using the ColdFusion.setGlobalErrorHandler function), it displays the error message; otherwise a default error pop-up appears.
refreshOnShow	Optional	false	`true` Refresh the contents of the window by running the `source` bind expression whenever the window shows (for example, by calling the `ColdFusion.Window.show` JavaScript function), in addition to when bind events occur `false` Refresh the window only when the bind expression is triggered by its bind event. To use this attribute, you must also specify a `source` attribute.
resizable	Optional	true	A Boolean value specifying whether the user can resize the window.
source	Optional		A URL that returns the window contents. This attribute can use URL parameters to pass data to the page. ColdFusion uses standard page path resolution rules to locate the page. You can use a bind expressions 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 `cfpod`, you must use a `cfajaximport` tag on the page with the `cfwindow` tag. For more information, see cfajaximport.
title	Optional		The text to display in the window's title bar. You can use HTML mark-up to control the title appearance; for example, to show the text in red italic font.
width	Optional	500	Width of the window in pixels. If you specify a value greater than the available space, the window occupies the available space and the resize handles do not appear.
x	Optional		The X (horizontal) coordinate of the upper-left corner of the window, relative to the browser window. ColdFusion ignores this attribute if the `center` attribute value is `true` and if you do not set the `y` attribute value.
y	Optional		The Y (vertical) coordinate of the upper-left corner of the window, relative to the browser window. ColdFusion ignores this attribute if the `center` attribute value is `true` and if you do not set the `x` attribute value.

Usage

You cannot use this tag in a form or as a child of a cflayout, or cflayoutarea tag.

You must define the cfwindow tag on the page that displays it (or a page that is included by using the cfinclude tag). So, you cannot use the cfwindow tag on a page that is specified by a cfmenuitem tag http attribute, cfdiv tag bind attribute, or cflayoutarea or cfpod tag source attribute. Instead, for example, you can display a window when a user clicks a menu item by defining the window on the same page as your menu and using a JavaScript function in the cfmenuitem tag http attribute to call the window's show function. The cfwindow tag uses its source attribute to get its contents from another page.

You can use a source attribute or a tag body to specify the window 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 by 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 "Binding data to form fields" in the ColdFusion Developer's Guide.

JavaScript functions

You can use the following JavaScript functions to manage an HTML format window:

Function	Description
`ColdFusion.Window.create`	Creates a window without using a `cfwindow` tag.
`ColdFusion.Window.getWindowObject`	Gets the underlying Ext JS - JavaScript Library object for the specified HTML format `cfwindow` control.
`ColdFusion.Window.hide`	Closes a window.
`ColdFusion.Window.onHide`	Specifies a function to run each time a specific window closes.
`ColdFusion.Window.onShow`	Specifies a function to run each time a specific window opens.
`ColdFusion.Window.show`	Opens a window.

Example

The following example shows several features of the cfwindow tag and dynamic binding of the cfwindow tag source attribute to form controls. It shows how you can use x and y attributes to position the windows and how several attributes, such as closable and resizable affect the window appearance. It also shows how you can use bind expressions to dynamically update window contents when form control values change, including different ways to trigger updating the window contents.

<html>
<head>
</head>

<body>
<cfform name="myform">
    <cfinput type="hidden" name="hiddentext" 
        value="This is hidden text from the main page">

    Click the mouse on the control to show its text in window 1.
    <cfinput name="text1"><br />
    
    Click the button to show the input control text in window 2.
    <cfinput name="text2">
    <cfinput type="button" name="mybutton" value="Show Text" 
        onclick="javascript:ColdFusion.Window.show('mywindow2')"><br />
        
    Click the Checkbox to change and show its status in window 3
    <cfinput name="check1" type="checkbox"><br />

    Click the button to open a window containing the page
        specified by the input control.
    <cfinput name="text3" value="windowsource.cfm">
    <cfinput type="button" name="mybutton3" value="Open Window" 
        onclick="javascript:ColdFusion.Window.show('mywindow4')">
</cfform>

<!--- This window shows initially and cannot be closed, dragged, or resized.
        The value of the text URL parameter, and therefore, the contents of the 
        text displayed in the window changes each time the user clicks the
        mouse over the text1 control. --->
<cfwindow x="0" y="100" width="200" height="150" 
        name="mywindow" title="My First Window" 
        closable="false" draggable="false" resizable="false" initshow="true"
        source="windowsource.cfm?text={myform:text1@mousedown}" />
        
<!--- This window shows initially and cannot be dragged, or resized, but can
        be closed.
        The text URL parameter represents the text2 input control value. --->
<cfwindow x="0" y="250" width="200" height="150" 
        name="mywindow2" title="My Second Window" 
        initshow="true" draggable="false" resizable="false" 
        source="windowsource.cfm?text={myform:text2}" />

<!--- This window shows initially and cannot be resized, but can be dragged
        or closed.
        The value of the text URL parameter, and therefore, Boolean value 
        displayed in the window changes each time the user clicks the mouse
        in the check1 control to change the check box status.
        The bind expression binds to the check box checked attribute;
        it specifies a click event because Internet Explorer does not 
        generate a change event when the user clicks the box.--->
<cfwindow x="0" y="400" width="200" height="150" 
        name="mywindow3" title="My Third Window" 
        initshow="true" resizable="false" 
        source="windowsource.cfm?text=<b>Checkbox: </b>{myform:check1.checked@click}" />

<!--- This window does not display initially.
        The Open Window button control opens it.
        It can be closed, dragged, and resized.
        The value text URL parameter represents the value of a hidden text
        field. --->
<cfwindow x="210" y="100" width="500" height="480" name="mywindow4"
        minHeight="400" minWidth="400" 
        title="My Fourth Window" initshow="false"
        source="{myform:text3}?text={myform:hiddentext}" />
</body>
</html>

The windowsource.cfm page that the cfwindow tag source attributes specify to display in the windows contains the following code:

<h3>Main page input:</h3>
<cfoutput>
    #url.text#
</cfoutput>

Adobe ColdFusion 8

cfwindow

Related Information

Help Resource Center