cfimport

Description

You can use the cfimport tag to import custom tags from a directory as a tag library, or to import a Java Server Page (JSP) tag library. A JSP tag library is a packaged set of tag handlers that conform to the JSP 1.1 tag extension API.

Category

Application framework tags

Syntax

<cfimport 
  taglib = "taglib-location"
  prefix = "custom"
  webservice = "URL"> 

See also

cfapplication

History

New in ColdFusion MX: This tag is new.

Attributes

Attribute Req/Opt Default Description
taglib
Required
 
Tag library URI:
  • A directory in which customer tags are stored
  • A URL path to a JAR in a web-application; for example, "/WEB-INF/lib/sometags.jar"
  • A path to a tag library descriptor; for example,
    "/sometags.tld"
prefix
 
 
Prefix by which to access imported JSP tags on a CFML page.
To import tags directly, specify an empty value, "". Use this to create server-side versions of common HTML tags.
webservice
Optional


URL of a WSDL file.

Usage

The following example imports the tags from the directory myCustomTags:

<cfimport 
  prefix="mytags" 
  taglib="myCustomTags">

You can import multiple tag libraries using one prefix. If there are duplicate tags in a library, the first one takes precedence.

JSP tags have fixed attributes; however, if the tag supports runtime attribute expressions, most tag libraries support the use of the syntax #expressions#.

To reference a JSP tag in a CFML page, use the syntax <prefix:tagname>. Set the prefix value in the prefix attribute.

To use JSP custom tags in a ColdFusion page, follow these steps:

  1. Put a JSP tag library JAR file (for example, myjsptags.jar) into the ColdFusion server directory wwwroot/WEB-INF/lib.
  2. At the top of a CFML page, insert code such as the following:
  <cfimport
    prefix="mytags" 
    taglib="/WEB-INF/lib/myjsptags.jar">

To reference a JSP tag from a JAR file, use the following syntax:

<cfoutput>
  <mytags:helloTag message="#mymessage#" />
<cfoutput>

The cfimport tag does not work within a cfinclude call. ColdFusion does not throw an error in this situation. To include tags from a JSP tag library, you must put the cfimport tag at the top of every page that is called by the cfinclude tag. (Putting the cfimport tag into an application.cfm file does not propagate the import.) For example, put a statement such as the following in each page that is called by the cfinclude tag:

<cfimport taglib="/WEB-INF/webcomponent" prefix="c"> 

You cannot use this tag to suppress output from a tag library.

For more information, see the Java Server Page 1.1 specification.

Example

<h3>cfimport example - view only</h3>
<cftry>
  <!--- Import the JRun Custom Tag Libraries --->
  <cfimport 
taglib="jruntags.jar" 
prefix="customtag">
    
  <customtag:sql datasrc="#regdatasource#" id="x">
    SELECT employee_id, firstname, lastname, email, phone, department
    FROM employees
    WHERE employee_id < 3
  </customtag:sql>
    
  <customtag:param id="x" type="allaire.taglib.querytable"/>
  <table>
    <customtag:foreach group="#x#">
    <tr>
      <cfoutput>
        <TD>#x.get("employee_id")#</TD>
        <TD>#x.get("firstname")#</TD>
        <TD>#x.get("lastname")#</TD>
        <TD>#x.get("email")#</TD>
        <TD>#x.get("phone")#</TD>
        <TD>#x.get("department")#</TD>
      </cfoutput>
    </tr>
    
    </customtag:foreach>
  </table>
  <cfcatch>
    <cfoutput>#CFCATCH.message# - #CFCATCH.DETAIL# </cfoutput>
  </cfcatch>
</cftry>  

<h3>id= cfimport-jruntags-sql-pos-1-t1</h3>
<table>
  <tr>
    <td>1</td>
    <td>carolynn</td>
    <td>peterson</td>
    <td>cpeterson</td>
    <td>(612) 832-7654</td>
    <td>sales</td>
  </tr>
  <tr>
    <td>2</td>
    <td>dave</td>
    <td> heartsdale</td>
    <td>fheartsdale</td>
    <td>(612) 832-7201</td>
    <td>accounting</td>
  </tr>
</table>

Comments