Three new user interface controls in ColdFusion 9

In this article I will explore some of the user interface additions in ColdFusion 9, specifically the new file upload, maps, and media player controls. The multiple file upload control enables you to create an interactive file uploader in seconds. With the maps control, you can drop an interactive map on a template using the Google maps API. The new media player component enables you to point to a local or remote FLV file and play it through a nice user interface. These controls not only add some flare to applications, they also add real value.

The web has been trying to solve the file upload problem for years. After selecting a file from the operating system’s browse dialog box and clicking Upload, the user is expected to have the patience to wait it out with no idea when the operation will be completed. This is just not good practice. Imagine a vending machine that behaved the same way. You put your money into the machine and select an item. You are fairly certain that you will get your item but you’re just not sure when. It could take one second or three minutes. Worse yet, the whole process could get stuck, causing you to wait indefinitely with no way of knowing that something went wrong.

This is not a very friendly user experience, yet it is similar to the stateless adventure of uploading a file in most web applications today. ColdFusion 9 introduces a new control for uploading files that provides real-time feedback. The new cffileupload tag enables you to easily create a rich interactive file upload control that runs in Flash Player. If any of your end users are not among the 97% of web users who have Flash Player installed (or if they are using an older version) they will be prompted to download the latest version. The file upload control allows users to add multiple files at one time and provides feedback on the size of the file. When all the files to upload have been selected, the user clicks Upload and the files are sent to a control-supplied URL on the server where ColdFusion will handle the actual upload. Flash Player will show the real-time progress of each file as well as the total upload operation.

The only required attribute of the cffileupload tag is url, which specifies the URL of the server where the files are to be uploaded. In the following example (see Figure 1), I have added a bgcolor attribute to help make it look pretty:

That is only half the battle. This is the presentation layer of the control and it is used to add, delete, and send these files to the URL that you provide. Once the file gets to the URL you need to actually handle the upload. In the uploader folder included in this article’s sample files I have the upload.cfm template in the same directory as a folder called myuploads. I can use the cffille tag to upload the file to that directory automatically. If you have uploaded files with ColdFusion before you might be thinking to yourself that the code below is not going to work because it is missing the fileField attribute. In the past, the fileField attribute was required, and it specified the name of the form field used to select the file. This ColdFusion 9 example does not use the traditional upload procedure, so it can be omitted:

At this point you might be wondering how that works for multiple files. For each file selected, a new call is made to the URL you provide.

Customizing the functionality

Now that you know how to use the cffileupload tag, take a look at some of the attributes that help you customize the way it works. The maxfileselect and maxuploadsize attributes enable you to restrict users from simply uploading anything they want. The maxfileselect attribute will limit the user to selecting only the specified number of files at one time. The maxuploadsize restricts the maximum upload size (as a total of all files) measured in megabytes.

The following example allows five files and a total of 10,000 megabytes:

Another nice feature of the file upload control is the ability to limit the types of files that can be uploaded. You can use the extensionfilter attribute to specify the type of file that you will allow to be uploaded. For example, to restrict uploads to image files you can specify the file extensions .jpg, .gif, and .png. When your users select files for upload, they will only be allowed to select the types of files you provide using the extensionfilter attribute (see Figure 2). For example:

Uploader events

In some cases, you may need to extend the functionality and interact with the uploader. The upload control comes with two events for you to listen to. The oncomplete event will run after the file uploads. By default, ColdFusion passes a JavaScript object as a parameter to this event handler with the following properties:

• status – A numeric value that is based on the HTTP status code
• message - Passed or Failed
• filename - Name of the file selected for upload

You can use this event to display more information to the user after all of the files are done uploading. You could, for example, collect each file name that was uploaded and then display a list to the user:

You may also want to listen for the onerror event, which will be thrown in the case of network or server-side errors. By default, ColdFusion passes a JavaScript object as a parameter to the event handler with the same properties as the oncomplete event object. This is a useful mechanism for trapping network errors when working with larger files. You can listen for errors and display a more helpful message to the end user when an upload fails.

Customizing the look and feel

Right out of the box, the file upload control is ready to go. You may, however, need to style it to match your application, or you may want to change some labels so that it just fits better. For example, you can change the button labels for the Add, Clear, Delete, and Upload buttons:

You can also control the appearance of the uploader control itself. In most of the examples above, I have changed the look using the bgcolor attribute, but you can also change many of the UI items using the style attribute.

Here is a list of style attributes that you can set:

• headercolor - Format: color; colors of the band at the top of the control. Specify two values, separated by a comma. For a solid band, use the same color for both values. The default value is ##E6EEEE,##FFFFFF.
• textcolor - Color of text. Can be a hexadecimal value or a named color. For a hexadecimal value, use the form"##xxxxxx", where x = 0-9 or A-F; use two number signs or none.
• titletextalign - Aligns the title text. The recognized values are left, right, and center. The default value is right.
• titletextcolor -Color of the title text.
• bgcolor - The background color for the file upload control. A hexadecimal value without “#” prefixed.
• For example, to make the title stand out, you can set the title text color to red:

Like the file upload control, the new maps control enables better interaction with your users. You can use the new cfmap tag to create an interactive map using the Google Maps API. There is nothing in this control that couldn’t be done already using the API, but it is much easier to use. The ColdFusion team has a clear understanding of their developer base, and they realize that we don’t like to type; the less code the better!

There are many uses for maps in applications as well as on your corporate site. Long gone are the days when you could take a screen shot and post it in your Contact Us page. You are now providing rich feedback to your users along with a mapping system that they are already familiar with.

To get started using the new cfmap tag you first need to sign up for the Google Maps API. When you sign up, follow the instructions to the bottom of the page where you can agree to the terms and enter a website URL. This is the URL where you will be using the cfmap tag. In my case I was just doing a demo on my local machine so I entered http://locahost. When you click Generate API Key your key will be displayed at the top of the page. Copy the key and store it in safe place so you have it later.

You have three options for setting this key in your application.

• You can use the cfajaximport tag and specify the map API key in the params attribute as follows:

• You can use cfset in Application.cfc as follows:

• You can use the Settings page in the ColdFusion Administrator. Specify the map API key in the Google Map Key field.
• Each of these will accomplish the same result, but in different scenarios you will want to use different approaches. If you have one server for your one domain, you can set your key in the ColdFusion Administrator and never worry about again. For any other scenarios, you will want to use one of the other two options, and for me it makes most sense to set it at the application level if you can.

Show me the map

Now that you know how to get started using maps, you’re ready to see some examples. In all of the examples, I set up the API key in the Application.cfc file. To get started all you need to know is a street address or a longitude and latitude. Unless you happen to remember the longitude and latitude of your favorite places, you’ll probably want to use the street address. In the example below I am using the street address for Quicken Loans Arena, which is home to next year’s NBA Champions, the Cleveland Cavaliers. (In case you are wondering, yes I can see the future.) The following two lines of code will produce the same result (see Figure 4):

Controlling the map

There are many attributes of the map control that you can use to change how the maps are displayed. The zoomlevel and zoomcontrol attributes, as you can imagine, control the map’s initial zoom setting and whether the user can change it. In the examples shown in Figure 4, the address was found just fine but when you are looking at an overview of the United States it really doesn’t help you find the arena. Since I did not set a zoomlevel value, it used the default value 3. Next, I want to use a higher zoomlevel so that when the map loads the user can see exactly what I want them to see. The zoomcontrol attribute specifies if the user is allowed to interact with the map by controlling the zoom level. The following values are valid for the zoomcontrol attribute:

• none
• small
• large
• large3d
• small3d

The example code below produces a more detailed map of the Quicken Loans Arena; it uses zoom level 15 and provides the user with a small 3D zoom control (see Figure 5).

The type attribute controls the type of Google map to display. Valid values for type are map, satellite, hybrid, terrain, and earth. All of the examples so far have used the map type because it is the default. If you wanted your users to see the map using another view type, simply change the type attribute. When you use the earth attribute, users will be prompted to download the Google Earth 3D plug-in if they don’t already have it.

You can easily add an overview to the map with the overview attribute. When working with larger areas the overview provides more control for the user to move around. The user can interact with the map using a control in the lower right corner (see Figure 7). Here is an example:

With the title attribute, you can create a title panel for the map. This can be helpful, for example, if you have a directions page that includes maps to all of your facilities. To make each of these stand out you could place a title above each map or simply use the map’s built-in panel bar (see Figure 8). You create the panel bar by setting the title attribute and setting hideborder to false. If you also set collapsible to true then the user can collapse the entire map:

Customizing the markers

You can also use cfmap attributes to customize the points on your maps. As a first example, the code below changes the color of the marker. As you can probably already guess the default marker color is green. You can change that easily by passing a hex color to the markercolor attribute:

If you want your icons to be a little more distinctive, you can change the icon to any image you want using the markericon attribute. While it is possible to create your own icons, there are also some freely available to you. You can find some great, free icons on the google-maps-icons open source project hosted on Google code. In the following code, I mark the location of Cleveland Hopkins International airport with a custom airport marker:

Interacting with the markers

Now that you know how to place and customize markers on a map, the next step is to make them interactive. When a user clicks on the marker, you will generally want to display more information about the location. You can display this information statically using the markerwindowcontent attribute or dynamically using the markerbind attribute.

In the next example, I map a local restaurant chain. I want to give users more information about the location when they click on the marker (see Figure 11). To display the general contact information along with a link to the main website, I could use a string inline, but I choose instead to save the content into a variable using cfsavecontent and then use that variable as the content. I find this approach makes the code easier to read:

You can also use a dynamic source to display the same information. For example, you may have all of the contact information in a database or a CMS system that allows your users access to customize their own marker content. In this situation, you’ll want to get the content from a dynamic source. You can use the markerbind attribute to specify a CFC function, JavaScript function, or URL. Note that the markerbind and markerwindowcontent attributes are mutually exclusive; if you try to specify both an error will be thrown. In the past the name attribute was optional, but if you are going to use the markerbind attribute then name is required. For example:

Adding multiple markers

So far all of the map examples have used a single marker. There are many times, though, where you need to add multiple markers to a map. If you are mapping a chain of sports bars instead of just one, it may make more sense to show all of the locations for an area on a single map. This can make it easier for the user to quickly find the location they are looking for.

There are basically two ways to add multiple markers to a map. The first uses the cfmapitem tag, which is a child of the cfmap tag and can only be used under cfmap. The second way uses the ColdFusion JavaScript API, but I will not be covering that approach in this article. The following is the basic syntax of the cfmapitem tag:

The following code builds on the sports bar example above to present many locations on a single map (see Figure 12):

The cfmediaplayer tag creates a built-in media player that plays FLV files (see Figure 13). To use the media player just give the control a name and specify the URL of the FLV file you want to load using the source parameter. Note that the URL to the FLV can be relative to the template or it can point to another server. Here is an example:

By default the video will not start playing when the template loads. I dislike sites that automatically play video when the pages loads. With that said, there may be a scenario where you do want to automatically play a video. Simply set the autoplay attribute to true:

Controlling the look and feel

The cfmediaplayer tag supports several attributes that allow you to customize the look and feel of the media player. The bgcolor attribute allows you to set the background color by specifying a hexadecimal color value without the # sign:

You can also control the size of the player using height and width. If you do not specify a height the control will default to 480 x 360 pixels.

The title bar, the border, and the actual player controls are on by default when the player loads, but they can be hidden using the hidetitle, hideborder, and controlbar attributes:

Finally, you can use the style attribute to set a multitude of options:

• bgcolor - The background color of the media player.
• borderbottom - A numeric value. The default is 10.
• bordertop - A numeric value. The default is 10.
• borderleft - A numeric value. The default is 10.
• borderright - A numeric value. The default is 10.
• titletextcolor - Hexadecimal value of RGB color. For example, specify the color white as ##FFFFFF or FFFFFF. The default is black.
• titlebgcolor - Hexadecimal value of RGB color. The default is black.
• progresscolor - The foreground color for the progress bar. Hexadecimal value of RGB color. The default is black.
• progressbgcolor - The background color for the progress bar. Hexadecimal value of RGB color. The default is black.
• controlscolor - The foreground color of the controls in the Control panel. Hexadecimal value of RGB color. The default is black.
• controlbarbgcolor - The background color of the controls. Hexadecimal value of RGB color. The default is black.

Here is an example:

Watch the video below:

Listening for events

There are three media player events that you can listen for to add functionality to your application based on what is happening:

• onComplete – Runs when the FLV file has finished playing.
• onLoad – Runs on loading the player component.
• onStart - Runs when the FLV file starts playing.

The following example simply outputs the event name to the screen when it happens:

Where to go from here

ColdFusion 9 is introducing some great AJAX and UI control additions and this article has just scratched the surface.

Now that you’ve seen how some of these controls work, you’re probably already thinking about what they can add to your applications. Uploading a file, displaying a map, and playing a video are distinct functions, but in the end they all solve real-world problems. It is true that there are existing techniques for implementing the functionality provided by these controls. The controls’ real value lies in how easy they are to use. In the code examples used in this article, it’s likely that you intuitively knew how to use each tag just by glancing at the sample code. With these controls, ColdFusion continues to build on what it does better than any other application server around: deliver powerful functionality in a matter of seconds.