ToScript

Description

Creates a JavaScript or ActionScript expression that assigns the value of a ColdFusion variable to a JavaScript or ActionScript variable. This function can convert ColdFusion strings, numbers, arrays, structures, and queries to JavaScript or ActionScript syntax that defines equivalent variables and values.

Returns

A string that contains a JavaScript or ActionScript variable definition corresponding to the specified ColdFusion variable value.

Category

Conversion functions, Extensibility functions

Function syntax

ToScript(cfvar, javascriptvar, outputformat, ASFormat)

See also

cfwddx; WDDX JavaScript Objects

History

ColdFusion MX 7: Added this function.

Parameters

Parameter

Description

cfvar

A ColdFusion variable. This can contain one of the following:

  • String

  • Number

  • Array

  • Structure

  • Query

javascriptvar

A string that specifies the name of the JavaScript variable that the ToScript function creates.

outputformat

Optional. A Boolean value that determines whether to create WDDX (JavaScript) or ActionScript style output for structures and queries:

  • True: creates WDDX-style output (default).

  • False: creates ActionScript-style output.

ASFormat

Optional. A Boolean value that specifies whether to use ActionScript shortcuts in the script:

  • True: creates new Objects and Arrays with ActionScript shortcuts: [] for New Array(), and {} for New Object. Using ActionScript shortcuts allows you to pass ActionScript into cfform attributes without triggering ActionScript validation.

  • False: does not use ActionScript shortcuts to create new Objects and new Arrays when generating the script. Instead, generates New Object() and New Array() in the script (default).

Usage

To use a ColdFusion variable in JavaScript or ActionScript, the ToScript function must be in a cfoutput region and be surrounded by number signs (#). For example, the following code uses the ToScript function to convert a ColdFusion variable to a JavaScript variable:

<cfset thisString="hello world"> 
<script type="text/javascript" language="JavaScript"> 
    <cfoutput> 
        var #toScript(thisString, "jsVar")#; 
    </cfoutput> 
</script>

When ColdFusion runs this code, it sends the following to the client:

<script type="text/javascript" language="JavaScript"> 
    var jsVar = "hello world"; 
</script>

An HTML script tag must enclose the JavaScript code. The cfoutput tag does not need to be inside the script block; it can also surround the block.

WDDX-style output generates JavaScript code that creates a WDDXRecordset object, where the key of each record set entry is a column name, and the value of the recordlist entry is an array of the corresponding query column entries, as follows: 

WDDXQuery = new WddxRecordset(); 
col0 = new Array(); 
col0[0] = "John"; 
col0[1] = "John"; 
WDDXQuery["firstname"] = col0; 
col0 = null; 
col1 = new Array(); 
col1[0] = "Lund"; 
col1[1] = "Allen"; 
WDDXQuery["lastname"] = col1; 
col1 = null;

To use WDDX-style output, first load the cf_webroot/CFIDE/scripts/wddx.js script, which defines JavaScript WDDX objects, as in the following line:

<script type="text/javascript" src="/CFIDE/scripts/wddx.js"> </script>

For more information on WDDX in JavaScript, see WDDX JavaScript Objects.

ActionScript-style output generates code that creates an array of objects, where the array is indexed by row number, and the objects consist of column name - column value pairs, as follows: 

    ActionScriptQuery = new Array(); 
ActionScriptQuery[0] = new Object(); 
ActionScriptQuery[0]['firstname'] = "John"; 
ActionScriptQuery[0]['lastname'] = "Lund"; 
ActionScriptQuery[1] = new Object(); 
ActionScriptQuery[1]['firstname'] = "John"; 
ActionScriptQuery[1]['lastname'] = "Allen";

An ActionScript-style array does not require you to include the wddx.js file, and creates a variable that you can use in ActionScript on a Flash format form, for example, in an onChange attribute.

If the outputformat parameter is False, setting ASFormat to True causes ToScript to use the ActionScript shortcut [] in place of NewArray() and the shortcut {} in place of NewObject(). Using these shortcuts allows you to pass ActionScript into cfform attributes without triggering ActionScript validation. If ASFormat is False, ToScript generates NewArray() and NewObject() in the script.

Example

The following example shows the results of converting a ColdFusion string, array, and query object to JavaScript variables. It also uses the string and array in JavaScript code.

<h2>ToScript</h2> 
 
<h3>Converting a string variable</h3> 
<cfset thisString = "This is a string"> 
<cfoutput> 
    <b>The thisString variable in ColdFusion</b><br> 
    #thisString#<br> 
    <br> 
    <strong>The output of ToScript(thisString, "jsVar")</strong><br> 
    #ToScript(thisString, "jsVar")#<br> 
    <br> 
    <strong>In a JavaScript script, convert thisString Variable to JavaScript 
     and output the resulting variable:</strong><br> 
    <script type="text/javascript" language="JavaScript"> 
        var #ToScript(thisString, "jsVar")#; 
        document.write("jsVar in JavaScript is: " + jsVar); 
    </script> 
</cfoutput> 
 
<h3>Converting an array</h3> 
<!--- Create and populate a one-dimensional array ---> 
<cfset myArray=ArrayNew(1)> 
<cfloop index="i" from="1" to="4"> 
            <cfset myArray[i]="This is array element" & i> 
</cfloop> 
 
<cfoutput> 
<b>The ColdFusion myArray Array</b><br> 
<!--- Write the contents of the myArray variable in ColdFusion ---> 
    <cfloop index="i" from="1" to="#arrayLen(myArray)#"> 
        myArry[#i#]: #myArray[i]#<br> 
    </cfloop> 
    <br> 
    <strong>The output of ToScript(myArray, "jsArray")</strong><br> 
    #toScript(myArray, "jsArray")#<br> 
    <br> 
    <strong>In JavaScript, convert myArray to a JavaScript variable and write it's contents</strong><br> 
    <script type="text/javascript" language="JavaScript"> 
        var #ToScript(myArray, "jsArray")#; 
        for (i in jsArray) 
        { 
            document.write("myArray[" + i + "]: " + jsArray[i] + "<br>"); 
        } 
    </script> 
<br> 
<h3>Converting a query</h3> 
This section converts the following query object to both WDDX format  
and ActionScript type JavaScript objects.<br> 
 
<!--- Query a database ---> 
<cfquery name="thisQuery" datasource="cfdocexamples"> 
    SELECT FirstName,LastName 
    FROM employee 
    WHERE FirstName = 'John' 
</cfquery> 
<br> 
The Query in ColdFusion 
<cftable query="thisQuery" headerlines="1" colheaders> 
    <cfcol align="left" width="9" header="<b>FirstName</b>" text="#FirstName#"> 
    <cfcol align="left" width="9" header="<b>LastName</b>" text="#LastName#"> 
</cftable> 
 
<strong>JavaScript generated by ToScript(thisQuery, "WDDXQuery"):</strong><br>  
    #toScript(thisQuery, "WDDXQuery")#;<br> 
    <br> 
<strong>JavaScript generated by ToScript(thisQuery, "ActionScriptQuery", 
            False):</strong><br>  
    #toScript(thisQuery, "ActionScriptQuery", False)#<br> 
    <br> 
<!--- Convert to both WDDX format and ActionScript format ---> 
<script type="text/javascript" language="JavaScript">  
    #ToScript(thisQuery, "WDDXQuery")#; 
    #ToScript(thisQuery, "ActionScriptQuery", False)#;  
</script> 
<!--- For brevity, this example does not use JavaScript query variables ---> 
</cfoutput>