Table of contents
3 March 2008
|Although this article does not get into coding, you should have at least a fundamental knowledge of hand coding with ColdFusion before using CFEclipse.
ColdFusion 8 (any edition will work, including the free DeveloperEdition)
- Note: To get started, you will need to have ColdFusion alreadyinstalled.
What program do you currently use to build your Adobe ColdFusion code and manage your applications? If you aren't using CFEclipse, it's definitely worth a look. This article will introduce and get you started with using Eclipse and the CFEclipse plug-in as an alternative IDE (Integrated Development Environment). In addition, I will briefly cover a few tools, such as the ColdFusion 8 Extensions for Eclipse. This is by no means a one-stop reference for the CFEclipse plug-in, but it should be a great starting point for anyone new to this environment.
Eclipse is an open-source IDE. By default, Eclipse is configured for coding in Java, but the CFEclipse plug-in for Eclipse provides an easy-to-use ColdFusion perspective with a feature-rich interface that can be customized with plug-ins and other tools. I will cover some of these features in this brief article and will also demonstrate how to set up this program so that you can start building with CFEclipse in just a few minutes—for free.
You may be asking yourself, why should I change my current IDE? Every developer has his or her preference, and Eclipse may not be for you; however, it provides a long list of features:
- It is free and open-source.
- It provides a dictionary view of functions, scopes and tags.
- It enables you to use snippets and use SnipEx servers to share snippets with coding team members.
- It enables you to create to-do lists that you can track within your code.
- It supports additional plug-ins such as the Frameworks Explorer.
In addition, you can change the perspective view (explained later) to switch from one coding environment to another. For example, you could be coding in ColdFusion, switch to a Flex Builder perspective, and then switch to a Java perspective, all within the same IDE with a click of a button.
Installing the CFEclipse plug-in
Download and install the Eclipse Classic version linked to in the Requirements section on page one. Unzip the download and place the output folder wherever you'd like. There is no install wizard, so it will be up to you where you'd like to put these files. Once you have this unzipped, open the Eclipse folder and run the Eclipse executable, eclipse.exe. You will be prompted to choose a workspace location. Again, it is up to you. In this tutorial, I chose to install it at the root of my C:/ drive, and that's how I will refer to the path throughout this tutorial.
The next step will be to add the CFEclipse plug-in to Eclipse. The easiest way to install CFEclipse is to use the built-in installation and update management tools that come with Eclipse. Unlike downloading an installer file and running it on your computer, using this updater tool will enable you to install and remove different plug-ins without leaving the Eclipse application.
To install CFEclipse, use the following steps:
- Select Help > Software Updates > Find and install.
- Select Search for new features to install and click Next.
- Click New Remote Site.
- Enter a name for the update site: for example, "CFEclipse." In the URL textbox, enter "http://www.cfeclipse.org/update" and click OK.
- You should now have a CFEclipse node in the "Sites to include in search" box.
- Select Stable CFEclipse and click Next.
- Eclipse will contact the CFEclipse site and retrieve the list of available plug-ins. Select the plug-in with the highest version number (the most recent update) and click Next.
- Agree to the license, install the software and restart Eclipse.
Click the perspective button (see Figure 1) and select Other from the dialog box. An Open Perspective window will open. Select CFEclipse from the list and click OK.
Figure 1. Changing the perspective to CFEclipse.
Assuming you already have ColdFusion 8 or earlier installed, be sure ColdFusion is running and you have a site folder in your ColdFusion wwwroot/ folder. This article assumes that you are running ColdFusion locally with the built-in JRun Server. However, if you are not, simply change the path in this tutorial to wherever your ColdFusion applications typically reside within your web root.
- In CFEclipse, click File > New > Project to open the New Project wizard.
- Click the plus symbol next to the CFEclipse Folder to expand the contents.
- Select CFML Project (see Figure 2) and click Next.
Figure 2. The New Project wizard
- Give your project a name (see Figure 3).
Figure 3. Naming a project.
- Deselect the "Use default location" option and browse to a location. Browse to the wwwroot/ folder of your ColdFusion 8 server (usually on your C:/ drive) and select your site folder. If you don't already have a folder in the wwwroot/ folder, you can create one now.
- Click Next to return to the CFEclipse perspective.
- Right-click your project and select Select Edit URL from the pop-up menu.
- Enter the local path of your ColdFusion server (see Figure 4). This is should be your localhost at port 8500, assuming you installed a ColdFusion developer server and used the built-in JRun server: http://localhost:8500/MyProject
- Click OK.
Figure 4. Entering the local path to your ColdFusion server
To test your configuration, create a CFML page with some sample code to test your set up.
- Create the page. Right-click your project and select New > CFML Page (see Figure 5).
Figure 5. Selecting CFML page option.
- Give your page a name; I named mine test.cfm. In the test.cfm page, type
.Notice how adding one hash(#) creates two. CFEclipse has code completion capabilities. Although this is a very simple example, you may find CFEclipse finishing your syntax for you. It has great coding tools and reference guides as well.
- Select the Dictionary view by clicking Window > Show View > Dictionary View (see Figure 6).
Figure 6. Selecting the Dictionary View
- In the Dictionary view, Select cf8 from the pop-up list and expand the Functions folder. Scroll down the list to select the
- Click between the two hash marks in your code and double-click the
Now()function in the Dictionary view. You will see that the code was added to the page. The hash marks (#) appear around the
Now()function so that your code looks like the following:
- Save your test.cfm page (Control + S).
- Select your Browser view tab below your test.cfm page. If it is not already visible, you can click the Show view button to select the Browser View (see Figure 7).
Figure 7. Opening up the Browser View
- In your Browser View tab, add the test.cfm URL to your site path. Click the Refresh button and a timestamp displays.
If you received an error, check to make sure you do not have any typos in your code, that the URL is correct, that you saved your page, and that ColdFusion is running.
Snippets are prewritten chunks of code that can be inserted into your .cfm files to save time. You can find snippets on the web or you can even create your own. The difference between these snippets and the snippets used in other programs is that CFEclipse snippets have contextual dialog boxes that enable you to specify attributes. Effectively, you can create custom wizards that are great productivity tools.
To view your snippets, Select Window > Snip Tree View. Your Snip Tree opens next to your Navigator panel. By default there will be no snippets, but you can easily add them.
To add snippets into CFEclipse, you must find (or build) snippets and then place them in the appropriate location of the CFEclipse plug-ins folder. This should be located within the workspace folder of your C: drive under the .plug-ins\org.cfeclipse.cfml\snippets folder (see Figure 8). This workspace folder is created when you run the Eclipse installer. If you put these snippets in the wrong location, they won't work.
Figure 8. Placing your Snippets in the workspace folder
I have added "snippets_aaron" from a number of snippets that I found at Aaron West's blog site. Simply download the snippets and place them in this folder.
Return to CFEclipse and refresh your Snip Tree View. If you still cannot see the new snippets, you may have to restart Eclipse.
To test your snippets, return to the test.cfm page. Double-click the HTML tree snippet (see Figure 9). You will see that a chunk of code was inserted onto your page. As you peruse the other snippets that came in this folder, you'll see that selecting some cause dialog boxes to appear, asking you to specify values for different variables.
Figure 9. Inserting an HTML Skeleton snippet
If you would like to have the ability to share snippets across your team, you may consider using a SnipEx server. You can specify the location of a SnipEx server by clicking the options menu of the Snip Tree View and selecting SnipEx Server (see Figure 10).
Figure 10. Editing SnipEx Servers
A SnipEx server is a MySQL database and application for storing snippets that can be shared either locally among developers or even over the web for developers that reside in different locations. This is a great way to standardize code practices and improve productivity within an organization.
You can download this application and documentation from the SnipEx site.
Creating Tasks list with the TODO snippet
Another handy feature of CFEclipse is that it offers a shortcut for creating to-do lists by simply prefixing a comment with "TODO." Adding this code to your CFML template will populate a Task tab next to your Browser View.
To add a to-do item, you can use your new snippets again. Select an insertion point at the top of your test.cfm page. From your Snip Tree View, double-click the TODO snippet and you will see some commented code added to your CFML template. Add some text, such as "Clean up page" next to the "TODO:" text so that your comment appears as follows:
<!--- TODO : Clean up page 1/7/2008 --->
To view this task, click Window > Show View > Tasks.
Your TODO task now appears in the Task panel with a check box (see Figure 11). This is an elegant way to keep track of the tasks you need to complete to finish developing your app.
Figure 11. Viewing your Tasks
Changing the default features of the CFEclipse plug-in is a snap. Select Window > Preferences to open a Preferences window (see Figure 12). Select the CFEclipse menu item and expand the tree to view and optionally change different preference settings.
Figure 12. Editing preferences
To install additional plug-ins, you can run a Software Update and download from the plug-in site, just as you did when you installed the CFEclipse plug-in. Other plug-ins require that you place the necessary files into the plug-ins folder of Eclipse. Most plug-ins usually come with some documentation and installation instructions.
Now you can build a robust ColdFusion IDE by installing the ColdFusion 8 Extensions for Eclipse. These extensions and CFEclipse can be used independently or in tandem. When you use them together, you incorporate two great tool sets that speak the same language.
To use the ColdFusion 8 Extensions for Eclipse, you will need to download them from the Adobe ColdFusion support site and install them as directed. These extensions include plug-ins that add a ColdFusion 8 code debugger, RDS capabilities, code wizards, and more.
I will very briefly give an overview of the RDS capabilities and the code wizards. I also recommend reading the following article that will give you an in-depth look at the code debugger in Eclipse: Using the ColdFusion 8 step-through debugger for Eclipse.
Remote Development Services, or RDS, enables applications such as Eclipse to browse available components and data structures of data sources on the ColdFusion server. You will be able to access your data sources to view your database tables and to build queries.
Once you have installed the ColdFusion 8 Extensions for Eclipse, you can access these new tools by clicking Window > Show View > Other from the main toolbar. From the window that appears, click the ColdFusion folder to see the options available. From the list, select RDS Dataview and click OK (see Figure 13).
Figure 13. Selecting the RDS Dataview
Now you will see a panel open at the left side of the Eclipse environment. A localhost data source should be visible. If you try to expand the localhost view, you will be prompted for an RDS password. If you configured your ColdFusion server on port 8500, enter your password, and the data sources that are configured in your ColdFusion Administrator will appear. If you have configured your server in another fashion, you will need to open the RDS configuration window by right-clicking the localhost item and Selecting "RDS Configuration."
From the RDS Configuration window, select your localhost and enter the relevant information to allow Eclipse to connect to your RDS Server that should have been installed and configured when you installed ColdFusion.
When you return to your Eclipse environment, open the tree under the localhost server in the RDS panel. You can expand your data sources to view the tables and columns for each database. You can also build queries off of these data sources.
To view the Query Builder, right-click the data source you want to work with and Select RDS Query Viewer. From here you can write your SQL code by hand or visually, by clicking the Visual Query Builder button on the top of this panel.
From the Visual Query Builder, you can click and click and click to create your SQL queries. There is even a nice visual table relations view to join fields and build WHERE statements (see Figure 14).
Figure 14. Visual Query Builder
Several wizards are available with the new ColdFusion 8 Extensions for Eclipse. This article will briefly introduce two of them.
The CFC component wizard builds complex CFCs fast and efficiently from your data sources. For example, you can click on a table in a data source from your RDS Dataview panel, then right-click and select ColdFusion Wizards > Create CFC. A CFC wizard opens with editable parameters (see Figure 15).
Figure 15. The CFC Wizard
Select your options and click Finish. Your CFC will be created and opened in Eclipse.
ColdFusion/AJAX Application wizard
The next wizard that I will introduce is the ColdFusion/AJAX Application wizard. There is also a ColdFusion/Flex Application wizard, but it requires the Flex Builder plug-in for Eclipse. This current version of Eclipse that we are using will not work with Flex Builder 2, and you may want to install Flex Builder 3 instead or install an older version of Eclipse that is compatible with Flex Builder 2. The CF/AJAX wizard will step you through building a complete data-driven AJAX application with a few clicks.
To begin, you will need to Select File > New > Project > Other. From the window that opens, select the ColdFusion Wizards folder and open its tree to select the ColdFusion/AJAX Application wizard. A window will appear welcoming you to the power of ColdFusion – yes, indeed…
Select Next a couple of times till you get to the RDS Server and Data Source Selection step. Since this is a new application, it is not necessary to edit any of the default settings in the steps that you skipped through. Refer to the documentation for more details. I have a link below to the relevant Live Docs.
Choose your localhost RDS server and your data source. Click Next again and you will be in the Page Layout and Design step. This section defines the pages that will be a part of your application. You can define Master Pages, Detail Pages, Master Detail Pages and ColdFusion/Flashpaper Report Documents.
In this step you will create a new page from the Available Pages section and add it to the Navigation tree. In the Page Information, name your page and select Master/Detail page (see Figure 16).
Figure 16. Page Layout and Design step
Click the Edit Master Section button and a Query Builder will open. As this is a master page, only select a few general details, since you will be able to add more columns to the Detail Section.
You will need to select an ID column from the table that you want to work with, even though it doesn't have to appear in your application. When you are finished building your query, Click OK to close the builder. Back in the Page Layout and Design window, Select the Detail Section tab to reopen the Query Builder.
After you have built your query, click Save and then enter a Project Name and the path to your local ColdFusion server. A folder will be created in your wwwroot folder with the project name that you specify. Do not add a folder name to the end of Web Root Folder. Click Finish and wait for the ColdFusion/AJAX wizard to finish.
That's it. To browse your new application, Edit the URL of your project to point to your new index.cfm page and click the refresh button in your Browser View tab in the Eclipse environment. Test your new data-driven AJAX application.
If your outcome was not what you desired, you can edit the code, or just create a new project and run the wizard again. For more information about additional wizards and details how to use them, check out the ColdFusion Live Docs documentation.
Where to go from here
This tutorial gets you started ColdFusion building applications with Eclipse. CFEclipse has many more features to offer. For more details about CFEclipse, including a brief history, you can read this overview on CFEclipse for ColdFusion Developers. I recommend browsing the CFEclipse.org website for updates, how-to videos, and other useful information. A ton of tweaks and add-ons are available for you to use to supercharge your Eclipse environment, but you will need to build the hotrod yourself with available plug-ins.
By leveraging the additional tools that are available for Eclipse and CFEclipse, you can customize your very own feature-rich development environment.