Invoking CFC methods with forms and URLs

You can invoke CFC methods directly by specifying the CFC in a URL, or by using HTML and CFML form tags. Because all HTTP requests are transient, these methods only let you transiently invoke methods. They do not let you create persistent CFC instances.

Invoking component methods by using a URL

To invoke a component method by using a URL, append the method name to the URL in standard URL query-string, name-value syntax. You can invoke only one component method per URL request, for example:

http://localhost:8500/tellTime.cfc?method=getLocalTime
Note: To use URL invocation, set the access attribute of the cffunction tag to remote.

To pass parameters to component methods using a URL, append the parameters to the URL in standard URL query-string, name-value pair syntax; for example:

http://localhost:8500/corpQuery.cfc?method=getEmp&lastName=camden

To pass multiple parameters within a URL, use the ampersand character (&) to delimit the name-value pairs; for example:

http://localhost:8500/corpQuerySecure.cfc?method=getAuth&store=women&dept=shoes
Note: To ensure data security, Adobe strongly recommends that you not pass sensitive information over the web using URL strings. Potentially sensitive information includes all personal user information, including passwords, addresses, telephone numbers, and so on.

If a CFC method that you access using the URL displays output directly, the user’s browser shows the output. You can suppress output by specifying output="No" in the cffunction tag. If the CFC returns a result using the cfreturn tag, ColdFusion converts the text to HTML edit format (with special characters replaced by their HTML escape sequences), places the result in a WDDX packet, and includes the packet in the HTML that it returns to the client.

Invoking component methods by using a form

To invoke a method by using a ColdFusion or HTML form, do the following:

  • Specify the CFC filename or path in the form or cfform tag action attribute.

  • Specify the CFC method in a hidden form field, as follows:

    <form action="myComponent.cfc" method="POST">. 
        <input type="Hidden" name="method" value="myMethod">
  • Alternatively, if you use the POST method to submit the form, you can follow the filename with ?method=methodname, where methodname is the name of the CFC method, as shown in the following line. You cannot use this technique with the GET method.

    <form action="myComponent.cfc?method=myMethod" method="POST">.
  • Create an input tag for each component method parameter. The name attribute of the tag must be the method parameter name and the field value is the parameter value.

  • Specify the access="remote" attribute in the cffunction tag that defines the CFC method being invoked

If the CFC method that you invoke from the form displays output directly, the user’s browser shows the output. (You can use the cffunction tag output attribute to disable displaying output.) If the CFC returns a result using the cfreturn tag, ColdFusion converts the text to HTML edit format, places it in a WDDX packet, and includes the packet in the HTML that it returns to the client.

  1. Create a corpFind.cfm file with the following contents:

    <h2>Find People</h2> 
    <form action="components/corpQuery.cfc?method=getEmp" method="post"> 
        <p>Enter employee's last Name:</p> 
        <input type="Text" name="lastName"> 
        <input type="Hidden" name="method" value="getEmp"> 
        <input type="Submit" title="Submit Query"><br> 
    </form>

    In the example, the form tag’s action attribute points to the corpQuery component and invokes the getEmp method.

  2. Create a corpQuery.cfc file, specifying access="remote" for each cffunction tag, as the following example shows:

    <cfcomponent> 
        <cffunction name="getEmp" access="remote"> 
            <cfargument name="lastName" required="true"> 
            <cfset var empQuery=""> 
             <cfquery name="empQuery" datasource="cfdocexamples"> 
                 SELECT LASTNAME, FIRSTNAME, EMAIL 
                 FROM tblEmployees 
                WHERE LASTNAME LIKE '#arguments.lastName#' 
             </cfquery> 
             <cfoutput>Results filtered by #arguments.lastName#:</cfoutput><br> 
             <cfdump var=#empQuery#> 
        </cffunction> 
    </cfcomponent>
  3. Open a web browser and enter the following URL:

    http://localhost/corpFind.cfm

    ColdFusion displays the search form. After you enter values and click the Submit Query button, the browser displays the results.