Setting up CFEclipse

From BriansWiki

Contents 1 Overview 2 Setup 2.1 Get Eclipse 2.1.1 Install location 2.2 Get CFEclipse 2.3 Select the CFEclipse Perspective 2.4 Get a Source Control Plugin 2.5 Get JSEclipse Plugin 2.6 Get FTP Plugin 3 Configuration 3.1 Turn on Label Decorations 3.2 Save CF files as Ascii 3.3 Random Associations 3.4 Turn on Line Numbers 3.5 Configure RDS 4 Eclipse Project Management 4.1 Create a Project 4.2 Share the Project 4.3 Checkout a file 4.4 Export a File 4.4.1 via Filesystem 4.4.2 via FTP 4.5 Preview in a Browser

[edit] Overview

Eclipse is an open source IDE that allows the use of plugins to support many different programming languages. There is one for ColdFusion called "CFEclipse" that lets you edit cfm and cfc files. There are also plug-ins that lets you integrate with Source Control Servers, like CVS, SubVersion or Perforce. Checkout the amazing list of other plugins available here for an idea about how flexible this IDE is.

On the down side, Eclipse takes some time to configure and you may be overwhelmed by the number of options. Some of the plugins are beta quality and there are dependency issues that can be hard to resolve. As far as CFEclipse goes, it doesn‘t have a visual development mode, but you can always use Dreamweaver if you need that.

IMPORTANT NOTE: If you are going to use FlexBuilder as an Eclipse Plugin, you should wait to install it until after you have CFEclipse installed. In my experience, the ColdFusion Extension plugin (CF_FB_Extensions.zip) that they ask you to install after the main FlexBuilder setup is also named 'CFEclipse'. This causes a conflict in the 'Sites to include in Search' list of the 'Install - Sites to visit' dialog. The net effect is you can't install CFEclipse if you have the ColdFusion extensions already installed. The work-around is to disable this plugin by going to the Help > Software Updates > Manage Configuration dialog and select the 'disable' link in the description dialog. After you install CFEclipse you can go back and enable this plugin and it should work fine.

On the plus side, this plugin handles the RDC protocol, which is pretty cool. I still have issues with directly editing files on a server, but for quick fixes, this can save a lot of time. Checkout this page: Coldfusion Extension Plugin for more details.

[edit] Setup

[edit] Get Eclipse

You can download the latest Eclipse sdk from here.

[edit] Install location

I usually install my Java applications to "C\Java\" so create a sub directory beneath called "elipse" and unzip the file contents into that. The nice part about java applications is that they do not need a complicated installation; as long as there is a Java Virtual machine already installed, you should be good to go. Navigate to the root of the eclipse folder and run the eclipse.exe to test your installation.

When Eclipse starts up you will be prompted for a default workspace; use the root of the folder that contains your source code repository.

[edit] Get CFEclipse

Note: The 1.3.1.4 build of CFEclipse fixes the bug that crashed Eclipse when using single quotes in a javascript block in a CFM file. If you are still using version 1.3.1.3 you definitely want to upgrade.

The best way to get CFEclipse is to use the built-in installation and update management tools that come with Eclipse. Here‘s how:

1. Select the "Help > Software Updates > Find and install" menu option
2. On the screen that is displayed, select ‘Search for new features to install‘ and click the ‘Next‘ button
3. Now click the ‘New Remote Site‘ button
4. Enter a name for the update site, for example "CFEclipse". In the URL box, enter http://www.cfeclipse.org/update and click the OK button
5. You should now have a ‘CFEclipse‘ node in the ‘Sites to include in search‘ box. Select "Finish".
6. Yo should now see the versions of CFEclipse Expand the CFEclipse node and you will see two child nodes: ‘Stable CFEclipse‘ and ‘Bleeding Edge CFEclipse‘
7. Tick the ‘Stable CFEclipse‘ box and click ‘Next‘
8. Eclipse will contact the CFEclipse site and retrieve the list of available plugins. Tick the plugin with the highest version number and click ‘Next‘
9. The next instructions are self-explanatory, agree to the license, install the software and restart Eclipse
10. Once Eclipse has restarted CFEclipse should have been successfully installed

[edit] Select the CFEclipse Perspective

When you first start Eclipse, it defaults to the "welcome" view which is really not that welcoming as there is no text to tell you what to do next. To switch to the CFEclipse perspective, select Window > Open Perspective and select "CFEclipse" from the dialog.

[edit] Get a Source Control Plugin

If you use a Source Control system, you can find a plugin for that in the Eclipse SCM plugin directory.

For example, the Subclipse Plugin is loaded via the Eclipse update manager. The steps are the same as those detailed above but name the update site "Subclipse" and point it to the following URL:

http://subclipse.tigris.org/update_1.2.x

[edit] Get JSEclipse Plugin

If you do any work with Ajax, you are going to want a good JavaScript Plugin. Adobe just aquired InterAKT, the company that developed JSEclipse, so it is now available through them, here. You have to register to download, but haven't we already sold them our souls, so who cares? This is installed from a zip which is annoying, here is the procedure:

1. In Flex Builder, select Help > Software Updates > Find and Install.
2. Select the Search For New Features To Install option, and then click Next.
3. Click New Archived Site.
4. Select the zip file you downloaded above, and then click Open.
5. When the Edit Local Site dialog box appears, click OK.
6. Ensure that the zip is selected, and then click Finish.
7. In the Search Results window, select the check box next to the zip, and then click Next.
8. Select the I Accept The Terms In This License Agreement option, and then click Next.
9. Click Finish.
10. Click Install All.
11. When the installation is complete, click Yes to restart Eclipse.

[edit] Get FTP Plugin

If you do not have file system access to your server you are probably going to need FTP support. The FTP plugin is different in that it is supplied as part of the core Eclipse distribution, but it is not installed by default (this plugin is no longer under development). To install it, go back to the Help > Software Updates > Find and Install dialog and select the "search for new features to install" radio button. In the now familiar dialog select the check box next to the "The Eclipse Project Updates" and select "Finish". In the Search Results Dialog, expand the tree to your current version of Eclipse. which should be 3.2.2 and expand that. You are looking for the feature called "FTP and WebDAV support", select the check box next to that item press the "Install Now" button.

[edit] Configuration

Once all the plugins are loaded, you need to configure them to your way of working. Your preferences may vary, but here is what I did to make Eclipse as much like Dreamweaver and Perforce as possible:

[edit] Turn on Label Decorations

Label Decorations are the little flags on a file‘s icon in the Project list that let you know if it is read-only, under source control, checked out, synced or not. This is used in the Perforce client and in Dreamweaver to a lesser extent. To get this same feature in Eclipse you need to set some preferences. The example here is for the Perforce client, if you use another plugin this may be different:

Select Window > Preferences from the Eclipse main menu and then select the General > Appearance > Label Decorations nodes in the configuration dialog tree control and then select the checkbox next to the "Perforce" item in the list.

Next select the "Team" node all the way on the bottom of the tree, expand it and you should see a "Perforce" child node; select that and then "Label Decorations" then in the dialog configure the dropdowns in the "File Decoration Icons" frame with the following values;

Top Left
Bottom Right
Top Right
- None -
- None -
Bottom Left

Now you should see the checkout status of the files in the CFEclipse Project just like in the Perforce standalone client.

[edit] Save CF files as Ascii

For some strange reason (I think has to do with the perforce plugin and the way files are saved in the Repository) Eclipse saves any file it doesn‘t understand as a binary file. This is going to confuse some external editors, so you need to add the .cfc and .cfm and .js extensions to the list of known files:

Go back to the Preferences dialog and select Team, File Content and select the "Add Extension" button and enter "*.cfc" in the resulting dialog. Repeat for the *.cfm, *.dbm and "*.js" extensions and then change the "Content" type in the grid for these new items to "ASCII Text".

[edit] Random Associations

I also added an association for "*.css" files to use TopStyle and "*.xml" files to use the JSEclipse html editor, its not great but at least the attributes are highlighted.

[edit] Turn on Line Numbers

In Preferences once again select the "CFEclipse" node and then the "Editor" child node and check the "Show Line Numbers" item in the list.

To turn on line numbers in JSEclipse, right click far left margin of the JS editor and select "line numbers" from the menu.

[edit] Configure RDS

If you have the ColdFusion Extension plugin, you should see a RDS File View in one of your Eclipse windows. Mine was on the bottom with the "Tasks", "Problems" and "Bookmarks". To configure this view, you need to go to Window > Preferences and select the "RDS Configuration item in the tree on the left. This gets configured just like Homesite, where you need to know the Host name and port number; these are available in the ColdFusion Admin if you don't know what they are.

[edit] Eclipse Project Management

This section gives a brief overview of working with projects that are under source control. In my opinion, all projects should be under source control, our time is too valuable to lose work due to a crashed system or when the dog eats your code. Source Control also gets you off-site storage, which is handy in case of real disasters and it can save a lot of time if a project gets off-track.

I want to expand these ideas in another presentation, but the basic ideas are here.

Here's how to get started with projects:

[edit] Create a Project

Eclipse is different from Dreamweaver and Homesite in that you are supposed to create a project before you start working (unless you work from the file explorer which leads to un-managed code nightmares). From the Eclipse main menu select File > New > Other and in the resulting "Select Wizard" expand the CFEclipse node and then select the "CFML Project". Then select the "Next" button in the Wizard and name the project (it is a good idea to use the directory name as Eclipse expects this to be the case). Next uncheck the "use default location" checkbox and browse to your project, which should be under the Source Repository folder on your local drive.

[edit] Share the Project

You should now see all your files in the Eclipse "Navigator" on the left hand side of the IDE, but we still need to tell Eclipse that this project is under source control.

Select the Project root node and right-click to display the context menu, select "Team" and then "Share Project" and then select your Source Control client from the repository list. In the resulting dialog you need to set the connection settings, here‘s what I use for perforce:

Port: 192.168.254.143:1666 User: bcaufield Client Workspace BJC_INT1 Charset: <blank>

(Obviously you need to change these for your Source Control client)

Select the finish button on the wizard and after being prompted for your perforce password, you should now see the client specific label decorations in the Eclipse navigator tree.

[edit] Checkout a file

You can now checkout a file from the Eclipse navigator; select the file you want to work on and right-click on it to bring up the context menu and select "Team" and "Open for Edit". You should notice a red check box on the upper left side of the file icon.

NOTE: Depending on your Source Control client, you may not have a checkout option. CVS stands for "Concurrent Versions System" that means that you always have to merge; nobody gets dibs on a file. In my experience merging is not that bad - in particular you get to see more of what another developer is thinking which is a good thing and it forces you ti understand more of what is going on.

[edit] Export a File

To test your changes to a file you need to export it to the dev server. Eclipse is setup to use a number of different ways to export files, but it doesn‘t use RDS, which is generally thought to be a security risk.

NOTE: If you have the ColdFusion Extension Plugin You can use RDS, but it does not appear as part of the file system, which is how I would like it to work.

[edit] via Filesystem

The way I have worked around this is to map the dev drive using my admin user account and password so that I have read-write and modify privileges on the mapped drive. Once this is setup, select the file you want to export in the project navigator and then right-click and select the "Export" menu item. In the Export dialog, select the "General" and then "File System" tree nodes and then select the next button. The file system dialog allows you to select multiple files to export at a time, so select any extra files from the right hand file list and then confirm that the "To Directory" path is correct; this defaults to the Project‘s path so if you are saving a cfc or js file that is not in the root of the project you need to modify this path. Select "Finish" completing the export.

[edit] via FTP

If your server supports ftp, you can use the FTP plugin to post to the server. The procedure is like using the file system approach above, except that the plugin does a dif between your project and the server and presents you with a list of changed files to post, which is really helpful.

[edit] Preview in a Browser

To test your change in a browser, select the file you want to test in the editor and then press F12 (just like in Dreamweaver). The first time you do this you will receive an error since there is no "cfeclipse.properties" file to tell Eclipse how to load the browser and where the project is on the remote server. In the navigator pane, right click your project. On the subsequent context menu, click "Edit Url". Enter the url to the web root of the project, ie.... http://localhost/ (trailing slash is required). Now go back to your page and hit f12 again. The browser should launch the page.