The Robertson Team


  Programmers' Tools >  The Free Stuff >  Free ColdFusion Tutorials >  How can I enable Unicode-aware storage and display in ColdFusion MX?

How can I enable Unicode-aware storage and display in ColdFusion MX?

I have yet to see a truly complete tutorial on this subject, although Armin Danesh's 3-part Unicode article on CommunityMX comes pretty close.  He covers stuff I don't here (like mySQL data connections), and you'll find it worth spending US$6 to buy his articles; especially since he takes the time to explain things, and this is only a quick list of do's and don'ts.

So since nobody else gives start-to-finish instructions, I'll give it a shot:

  1. Your browser has to be able to display the characters your web application is going to output. In Windows this may mean installing some character sets. In Win2k, go to Settings/Control Panel/Regional Options. At the bottom of the dialog is a list of the character sets your system can display. If your desired language isn't on this list, install it (this will let you display the language; but not necessarily enter its characters).
  2. Your ColdFusion JDBC database connection has to support Unicode. I will only describe how to do it in MS Access: Set up your Access DSN in the ColdFusion administrator using the ''Access With Unicode Support'' option.  There's nothing more to it than that with Access db's.
  3. in Application.cfm, plug in the following code:
    This will make sure that variables in these two scopes, which both originate from the client side, will stay in Unicode format.
  4. While you've got the file open, put this into Application.cfm:
    <cfcontent type="text/html; charset=utf-8">
  5. Put this statement into every template that touches the database, processes user inputs or outputs data to the browser (which is just about everything):
    <cfprocessingdirective pageEncoding="utf-8">
    No, you cannot put it into Application.cfm, and you can't cfinclude it from some other template. It has to go into everything manually and individually.  Further, if a parent file calls an include, BOTH must have the statement.  Calling it in just the parent doesn't count.  The same goes for module (i.e. custom tag) calls.  
  6. Make sure that this goes into the HEAD area of any HTML documents that get output to the browser. You may opt to use CFHEADER somewhere convenient or this manual statement directly in the output area of your template:
    <META http-equiv="Content-Type" content="text/html; charset=utf-8">
    While the above is not strictly necessary since CF already outputs Unicode by default it is helpful to 3rd parties hitting your pages, such as search engine bots.
  7. If you are pulling data from text files via CFFILE, (like maybe language files that will be used to display an English, Korean or Chinese version of a site depending on what was requested) make sure those files are saved in Unicode format. Windows Notepad can do this, although you probably never noticed the Unicode option nestled at the bottom of its Save dialog.

Thats pretty much it, in terms of getting the ball rolling.  Do the above and you will be able to input and output data in Unicode format.  Depending on your database, you'll have to address issues like sorting and search (its my understanding mySQL 4.0x has issues with this). 

If you are looking for an easy way to test your display of foreign characters, as well as a readily available source for inputting same ({"What... you mean you don't have a PinYin device for inputting Chinese characters laying around?") you may find's What Is Unicode? page an invaluable resource.

If I forgot something, please drop me a line and let me know so I can update this page.

Hope this helps,

Matt Robertson

The Robertson Team,
1.559.360.1717 is a leader in ColdFusion web hosting and managed dedicated servers.