By default, ColdFusion does the following:
- Gets all the client-side JavaScript, CSS, and other files required for Ajax-based features from the web_root/CFIDE/scripts/ajax directory.
- For each application page, imports only the JavaScript files required for the tags that are explicitly included on the page.
In some cases, override these default behaviors.
Specifying a custom script or CSS location
In some situations, you cannot use the default location for the CFIDE directory, because a hosting site blocks access to it to prevent access to the ColdFusion Administrator. Then, move the CFIDE/scripts directory, or the subdirectories that you use in your applications, to a different location.
In other situations, you have custom versions of some of the client-side files, such as the CSS files that specify form control appearance, that apply only to certain applications.
In both situations, inform ColdFusion of the new location. Specify the location of either or both directories containing the following files:
- All client-side resources required by the ColdFusion Ajax features
- Only the CSS files required by the ColdFusion Ajax features
Specify the client-side resource location
Use any of the following techniques to control the location of the directory that contains the client-side resources required by the ColdFusion Ajax features:
- If the ColdFusion client-side files required by all applications, including the files used by cfform tags are in a single location, you specify the directory in the ColdFusion Administrator > Server Settings > Settings page, Default CFFORM ScriptSrc Directory field. The directory you specify and its subdirectories must have the same structure and contents as the CFIDE/scripts directory tree.
- If the client-side files required for Ajax features on a specific page are in one location, you use the cfajaximport tag scriptsrc attribute to specify the source directory. This tag overrides the setting in the administrator, and does not affect the files used for standard cfform features. The directory you specify must have an ajax subdirectory with the same structure and contents as the CFIDE/scripts/ajax directory tree.
- You specify the client-side source directory for a specific form in the cfform tag scriptsrc attribute. This setting overrides any cfajaximport tag setting for the form and its child controls. The directory you specify and its subdirectories must have the same structure and contents as the CFIDE/scripts directory tree.
If you require multiple resource locations for a single page, make sure that each JavaScript file is imported only once on a page, the first time it is required. Therefore, you cannot use different copies of one JavaScript file on the same page.
To prevent problems, ColdFusion generates an error if you specify more than one scriptsrc attribute on a page. Therefore, if multiple forms require custom client-side resource files, specify their location in a single cfajaximport tag, not in scriptsrc attributes in the cfform tags.
Specify the CSS file location
Use the cfajaximport tag cssSrc attribute to specify the location of a directory that contains only the CSS files that control the style of ColdFusion Ajax-based controls. This attribute overrides any scriptsrc value in determining the CSS file location. Therefore, you could use the CSS files in the scriptsrc directory tree for most pages, and specify a cssSrc attribute on selected application pages that require a custom look.
For detailed information on how to use the scriptsrc and cssSrc attributes, and requirements for the contents of the specified directory, see the cfajaximport tag in the CFML Reference.
Importing tag-specific JavaScript files
In the following situations, ColdFusion does not automatically import the JavaScript files that are required for Ajax-based tags:
- If you use a ColdFusion Ajax-based tag on a page that you specify by using a source or bind attribute in a container tag, such as cfdiv, cflayoutarea, cfpod, or cfwindow. Place a cfajaximport tag on the page that has the container tag and use the tags attribute to specify the Ajax feature tags that are on the other pages. (You do not have to do this for any tags that are also used on the page with the source attribute.)
If you use a ColdFusion Ajax JavaScript function, such as ColdFusion.Window.create or ColdFusion.navigate, on a page that does not otherwise import the required ColdFusion Ajax JavaScript functions, use the cfajaximport tag to import the required JavaScript functions. If you are using a function, such as coldFuson.navigate, that is not used for a specific control, you can omit any attributes; the default behavior is to import the base functions that are not control-specific. If you are using a function such as ColdFusion.Window.create, use the tags attribute and identify the associated control, for example, cfwindowin the following line:
<cfajaximport tags="cfwindow">
For detailed information on importing tag-specific JavaScript files, see the cfajaximport tag in the CFML Reference.