ColdFusion 9.0 Resources

cfwindow

Description

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

Syntax

<cfwindow 
    bodyStyle = "CSS style specification" 
    center="true|false" 
    closable="true|false" 
    destroyOnClose ="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, 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.

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.
`destroyOnClose`	Optional	false	If `true`, destroys the window when it is closed.
`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.
`overflow`	Optional	auto	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 window. Note: In Internet Explorer, windows with the `visible` setting expand to fit the size of the contents, rather than having the contents extend beyond the layout area.
`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.

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 Developing ColdFusion Applications.

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>