cfajaximport

Description

Controls the JavaScript files that are imported for use on pages that use ColdFusion AJAX tags and features.

Category

Internet protocol tags

Syntax

<cfajaximport 
    cssSrc = "local URL path" 
    params = "parameters" 
    scriptSrc = "local URL path" 
    tags = "comma-delimited list">
Note: You can specify this tag’s attributes in an attributeCollection whose value is a structure. Specify the structure name in the attributeCollection and use the tag’s attribute names as structure keys.

See also

cfform, cfgrid, cfinput, cflayout, cfmenu, cfpod, cfsprydataset, cftextarea, cftooltip, cftree, cfwindow, Specifying client-side support files in the Developing ColdFusion Applications

History

ColdFusion 8: Added this tag.

Attributes

Attribute

Req/Opt

Default

Description

cssSrc

Optional

scriptsrc/ajax

Specifies the URL, relative to the web root, of the directory that contains the CSS files used by ColdFusion AJAX features, with the exception of the rich text editor. This directory must have the same directory structure, and contain the same CSS files, and image files required by the CSS files, as the web_root/CFIDE/scripts/ajax/resources directory.

This attribute lets you create different custom styles for ColdFusion AJAX controls in different applications.

params

Optional

  

This attribute allows you to specify parameters for the CFM page.

Currently, the only parameter that you can specify is googlemapkey. You can specify the googlemapkey as follows:

<cfajaximport params=#{googlemapkey="Map API Key"}#>

scriptSrc

Optional

scriptsrc setting in the Administrator;

default path is /CFIDE/scripts/

Specifies the URL, relative to the web root, of the directory that contains the client-side script files used by ColdFusion. This directory includes the JavaScript files and the default location of the CSS files used for all AJAX features.

If you use this attribute, the cfajaximport tag must precede all other ColdFusion AJAX tags on the page; that is, all tags that rely on the scripts.

You can have only one scriptsrc attribute on a page, in a cfajaximport tag or a cfform tag. You can use a scriptsrc attribute in a cfajaximport tag to apply its value to all forms on a page.

tags

Optional

A comma-delimited list of tags or tag-attribute combinations for which to import the supporting JavaScript files on this page.

If you use this attribute, it must specify all ColdFusion AJAX tags that you use on the page and on any pages specified in tag source attributes.

For a list of valid attribute values and their purposes, see Usage.

Usage

Using the scriptsrc and cssSrc attributes

The scriptsrc attribute is useful if the JavaScript files are not in the default location. This attribute is required in some hosting environments and configurations that block access to the /CFIDE directory.

The default scriptsrc value is determined by the Default CFFORM ScriptSrc Directory setting on the Server Settings > Settings page of the ColdFusion Administrator. For cfform tags, the tag’s scriptsrc attribute takes precedence over this attribute.

You can use this attribute only if the cfajaximport tag is on a top-level page; that is, a page that the client directly requests. You cannot use it, for example, on a page that is specified in a cfwindow tag source attribute.

When you use the cfajaximport tag with a scriptsrc attribute, the specified directory must have the same structure as the /CFIDE/scripts directory. For example, if you specify scriptsrc="/resources/myScripts", the JavaScript files used by AJAX must be in the /resources/myScripts/ajax directory.

This attribute specifies the folder that contains the ColdFusion client-side files for all subsequent tags on the current page, not just for AJAX-based tags. Therefore, the directory tree must include all ColdFusion client-side files used by those tags. For example, if a cfform tag on the page is in Flash or applet format, include the CF_RunActiveContent.js file in the directory specified by the scriptsrc attribute.

You use the cssSrc attribute to specify the location of the CSS files required by ColdFusion AJAX features. This attribute overrides the scriptsrc/ajax/resources directory for the current page. Therefore, if all pages that use a custom scriptsrc directory also use a custom cssSrc directory, you do not have to include the ColdFusion AJAX CSS files in the scriptsrc directory tree.

Using the tags attribute or no attribute

If you do not use the cfajaximport tag on a page that contains ColdFusion tags with AJAX UI features, ColdFusion correctly imports the required JavaScript files in most cases. Use this tag to explicitly import JavaScript files in these cases:

  • If you use a ColdFusion AJAX JavaScript function, such as ColdFusion.navigate, ColdFusion.Ajax.submitForm, or ColdFusion.Log.info on a page that does not otherwise import any AJAX JavaScript functions, use the cfajaximport tag with no attribute to import the base JavaScript functions only. For example, use this tag on a page that does not include any ColdFusion AJAX-based tags,

  • If the following conditions are true:

    • You use any source attributes in cflayoutarea, cfpod or cfwindow tags, or bind attribute in cfdiv tag.

    • The file that the source or bind attribute specifies has any of the tags listed in the following table.

    • You do not use each of the listed tags on the top-level page.

    If these conditions are true, the top-level page must use the cfajaximport tag with a tags attribute that specifies the tags that only the other pages use. Otherwise, ColdFusion cannot identify that it will be using the tags and does not import the necessary JavaScript files.

You can specify any or all the following tag attribute values:

Attribute value

Used for

cfdiv

cfdiv tags

cfform

Forms that are in cfpod, cfwindow, or cflayoutarea tag bodies

cfgrid

AJAX format cfgrid tags

cfinput-autosuggest

cfinput tags that use the autosuggest attribute

cfinput-datefield

HTML format cfinput tags that use the datefield attribute

cflayout-border

cflayout tags with a type attribute value of border

cflayout-tab

cflayout tags with a type attribute value of tab

cfmenu

cfmenu tags

cfpod

cfpod tags

cfsprydataset-JSON

cfsprydataset tags that generate Spry JSON data sets

cfsprydataset-XML

cfsprydataset tags that generate Spry XML data sets

cftextarea

HTML format cftextarea tags

cftooltip

cftooltip tags

cftree

HTML format cftree tags

cfwindow

cfwindow tags

Example

The following cfajaximport tag example specifies separate custom locations for the scripts used for AJAX features and for the AJAX CSS files. It also imports all JavaScript files used for cftree, and cftooltip.

<cfajaximport cssSrc="/collegeApp/application/cssFiles" 
    scriptsrc="/collegeApp/ajaxScripts" 
    tags="cftooltip, cfwindow">