This section of the documentation covers tips for working with CFX_ImageCR from Coldfusion. The items documented here are not part of ImageCR, but are often used with it. They are probably documented elsewhere.

ExpandPath is a Coldfusion function which returns an absolute system path when passed a relative url path.

Relative url paths begin with a file or directory name -or- a period. A single period in a relative url path represents the current directory, two periods represent the parent of the current directory.

For example, from D:\Web\docs\reference\advanced\tips.cfm :

This is very useful in dynamically creating absolute paths to images and directories used in some CFX_ImageCR attributes. The alternatives are to type the absolute path every time, or to set a variable representing the absolute system path root of your site and append to that in your code.

Since the calls will most often be made within CFX_ImageCR attributes, our convention is to use ' to delimit string literals as the first parameter. The following example shows ExpandPath being used with CFX_ImageCR. Note the values of the IMG tag's SRC attribute are the same as those passed to ExpandPath.

<cfx_imagecr3 load="#expandpath('../examples/example.jpg')#" 
              save="#expandpath('savedInCurrentDirectory.jpg')#" >

<img src="../examples/example.jpg">
<img src="savedInCurrentDirectory.jpg">
expandpath.cfm 

It is often useful to perform some operations in a web application just once. This is a primarily a matter of convenience and dynamic functionality, but it can also provide performance benefits.

Setting the CFX_ImageCR DefaultSave is one operation meant to be executed once. The default save is often implemented to point to a generic cache directory for use in creating cached autonamed images more easily.

Our convention is to implement the cached global section in the top level application.cfm, which might just be one of many cascading application/onrequestend cfm files in the application. However, the top level application.cfm, always located at the root of our sites, will be included in all pages we consider part of the application, in all subdirectories. In this way, our applications are given a skeleton which suits our development style.

The following is an example of a cached global section. The top half would be the code in our top level application.cfm. The bottom half exists only in this example to demonstrate and prove the top half.

This specific example sets a variable to store the hold the root directory and sets the ImageCR DefaultSave.

<cfapplication name="example">

<cfparam name="application.started" default="0">

<cfif not application.started>
  <cfset application.started="1">  
  <cfset application.laststart="#Now()#">
  <cfset application.root="D:\Web\docs\">  
  <cfx_imagecr3 setdefaultsave="D:\Web\_cache\" >
</cfif>

<!--- the rest shows it works --->

<cfx_imagecr3 getdefaultsave >
<cfoutput>
<pre>
  Application last started : #application.laststart#
  CFX_ImageCR default save : #imagecr.defaultsave#
</pre>
</cfoutput>
cached.cfm 

This code will run the first time someone visits any page in your application after a Coldfusion Server restart.

This code will also run if you set application.started to 0. This convention allows a soft refresh. Simply set application.started to 0 and the cached global section will be reloaded. The server would not need to be restarted. This is usually as done as part of an administrative page which allows configuration of these type variables.

Cached global sections are a matter of convenience, and often performance, for all types of Coldfusion programming. They are not at all required for ImageCR operation.

If for some reason you can not implement a cached global section using application scoped variables, you can implement a traditionally non-cached global section; include a designated "global" cfm file anywhere you need it.

To aid in debugging and quality control we like to be notified of all exceptions Coldfusion throws.

In the "Settings" section of the Coldfusion Administrator there is a field for a "Site-wide Error Handler". In this you can specify the absolute path to a Coldfusion template which will be used instead of the default exception handling.

When you define this, you can implement custom error handling which sends all exceptions to you via email.

This convention uses cfmail and thus requires proper configuration of the "Mail Server" setting in the Coldfusion Administrator. Additionally, errors in the error handling template itself are not handled well.

Finally, if you ever have problems with specific image files, etc, you might have a hard time figuring out which one is causing the trouble, especially if you have tens of thousands. Something similar to this is a good way to debug and detect them. Catch the exception and include the problematic image's filename and other details in a mail to yourself. For more information, lookup <cftry> and <cfcatch> in your Coldfusion documentation.

ImageCR can process uploaded images exactly as it would any other. Coldfusion handles uploading images, or any file, similar to most web development platforms. The file is part of a form field submission. The HTML form field and form itself use special attributes to denote a file is being represented and will be sent with the form.

Once uploaded, simply operate on the image with ImageCR as you would any other.

If you need to delete the original upload, use cffile in "delete" mode.

<cffile action="delete" file="d:\web\uploads\file.jpg">

  -or perhaps-

<cffile action="delete" file="#serverDirectory##serverFile#">