ColdFusion.Window.create

Description

Creates a ColdFusion pop-up window. This function is equivalent to the cfwindow tag.

Function syntax

ColdFusion.Window.create(name, title, URL [, configuration])

History

ColdFusion 8: Added this function

Parameters

Parameter

Description

name

The name of the window. This attribute is required to interact with the window, including to dynamically show or hide it. If a window with the specified name exists, the function shows that window, and ignores the remaining parameters; otherwise, the name must be unique on the page.

title

The text to display on the window title bar. You can use HTML mark-up to control the title appearance.

URL

The URL from which to get the window body contents. This attribute can use URL parameters to pass data to the page. ColdFusion uses standard page path resolution rules to locate the page.

Note: If the page specified in this attribute contains tags that use ColdFusion Ajax features, such as the cfform, cfgrid, and cfpod tags, identify the tags in a cfajaximport tag on the page that includes this function. For more information, see cfajaximport.

configuration

An object containing window configuration parameters. For details, see “Usage”.

Returns

This function does not return a value.

Usage

This function is equivalent to the cfwindow tag.

If you do not also use a cfwindow tag on a page that calls this function, specify a cfajaximport tag on the page and specify cfwindow in the tags attribute. Doing so ensures that the page includes the necessary JavaScript to create the window. For example, use the following line if you do not have to import the JavaScript for any other ColdFusion Ajax features.:

<cfajaximport tags="cfwindow">

The configuration parameter defines the window characteristics; it can have any or all the following entries:

Entry

Default

Description

callbackhandler

 

A function that is called when the window body loads. This function must not take any arguments.

center

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

true

A Boolean value that specifies whether the user can close the window. If true, the window has an X close icon.

draggable

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.

errorHandler

 

A function that is called if an error occurs in loading the window body. This function must take two arguments:

  • The HTTP status code, or -1 if the error is not an HTTP error

  • An error message

height

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

false

A Boolean value that specifies whether to display the window when the containing page first displays. If this value is false, use the ColdFusion.Window.show JavaScript function to display the window.

minheight

0

The minimum height, in pixels, to which users can resize the window.

Specifying this parameter and a resizable="false" parameter causes an error.

minwidth

0

The minimum width, in pixels, to which users can resize the window.

Specifying this parameter and a resizable="false" parameter causes an error.

modal

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 displaying. If true, the user cannot interact with the main window.

resizable

true

A Boolean value that specifies whether the user can resize the window.

width

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

 

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

 

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.

Note: Entry names in the configuration object must be all-lowercase.

Example

The following minimal CFML application creates a window and gets the window contents from the hello1.cfm file.

<cfajaximport tags="cfwindow"> 
 
<cfform name="test"> 
    <cfinput type="button" name="x" value="Create Window"  
        onClick="ColdFusion.Window.create('Window1', 'This is a CF window', 
        'http://localhost:8500/My_stuff/AjaxUI/Book/hello1.cfm', 
        {x:100,y:100,height:300,width:400,modal:false,closable:false, 
        draggable:true,resizable:true,center:true,initshow:true, 
        minheight:200,minwidth:200 })"> 
</cfform>

The hello1.cfm file can be as simple as the following line:

Hello from hello1.cfm