Upgrading Your Store with ExamDiff Pro

One of the things that is always challenging with online sites using a 3rd party software like CFWebstore is updating to new versions. Since the application is basically nothing more than a huge collection of text files, there's no real way to provide some kind of executable updater program. So performing an upgrade usually involves copying over all the changed text files, while attempting to preserve any changes you may have made to the code. Typically this involves at a minimum your layout files, but a large percentage of stores have changes in other pages as well that you want to be sure that you don't overwrite. By far the best way to do upgrades that keep all your changes is to use a file comparison tool. There are a number of good products out there, but one of the most popular ones is ExamDiff Pro. ExamDiff does come in a free version as well, but you'll want the Pro version for the full directory comparison and powerful customization options that it has. For the low registration price of $35, you'll find it well worth the time savings you will get when doing upgrades. This tutorial will help to show you how I do upgrades, you can certainly use a different process that best suits your own work flow, but this should at least get you started.

So a new version of CFWebstore has been released and you are ready to upgrade! Before you get out ExamDiff, there are a couple steps you need to take. First, make a working copy of your current version to do the upgrade on, so you have a backup copy of it (unless you use version control or have some other method of rolling back changes). This way if you make any mistakes you will be able to re-compare with your previous version. Download and extract the new CFWebstore version to another directory.

The first step is to update the headers on your current working version so that they match the copyright headers on the new version. Each CFWebstore version has headers on all the .cfm pages with the version number and dates. Here's what the headers would look like on version 6.02:

To replace these in all the webstore files, you need an editor that can do extended search and replace. There are many editors that will be able to do this. Dreamweaver, Homesite+, many other text editors like UltraEdit. I personally use CFEclipse. This is one of the more popular editors for ColdFusion, it runs on the open source Eclipse project, so is completely free to use and has many plugins you can use with it, works with the new step debugger in CF8, can do source control with CVS or SVN, etc. To do the search and replace in Eclipse, we just select the version header at the top of any page and click Ctrl-H to bring up the search dialog. Select the search within the entire project and then click Replace to do a search-and-replace function.

After Eclipse is done finding all the matches, it will bring up the replace dialog. Enter the new version number in and click Replace All to complete the replace function. Repeat for the copyright date header if needed (or just do both in the same step).

Now we're ready to start working on the upgrade. Open up ExamDiff and select the Directory comparison option. Select the directory with the new CFWebstore version and then the directory with your current working version. Before running the comparison though, let's set up some options (if this is the first time you are using ExamDiff). Just click on "Options" to bring up all the various settings you can adjust.

ExamDiff has a wide variety of options you can set. We're only going to look at the main two areas that will effect doing CFWebstore upgrades. The first is the Text Comparison options. Here's a screenshot of how I prefer to configure these options:

I prefer to have ExamDiff ignore all the differences in whitespace, blank lines and such. These are not going to really effect the store, so no point in including them in the comparison. You'll want to leave the Case comparison on as this may find adjustments to things like database tables and fields names for Unix compatibility. The second area that you will want to configure is the Directory Comparison options. Here's a screenshot of my settings:

The filters section allows you to tell ExamDiff to exclude specific files and directories. If you are doing a comparison to a CVS copy of the software, you'll want to exclude that so that none of the extra CVS directories that are created are included in the comparison. The rest of the settings basically determine how ExamDiff will run comparisons on the directories to determine which files are different and which have changes. These settings I find give the best balance of speed and accuracy, but you can tweak them to find what works best for you.

We're now ready to run our comparison. This will show you the list of differences from the top directory of your site, you can double-click on each sub-directory to compare it, or double-click a file to bring up the file comparison window. You can also configure ExamDiff to open sub-directories and files in new windows, or in the same window and can customize the toolbar to include additional buttons. I have mine set to use the same window and tweaked the toolbar to make it easier to go up the directory path. The files and directories with changes will be color-coded according to the types of differences to easily see where the changes are, which files are newer, etc. ExamDiff will flag all files that have differences, but keep in mind that all minor updates to CFWebstore come with a list of changed files (changes.txt) so to save yourself some time, you can always just go through that list and check only those files (particularly if you have a heavily-modified store that comes up with a lot of differences.) Here's a view of a comparison of the access admin directory:

You can see from the hints that the directory "membership" has some changes in it, and the files dsp_menu.cfm and index.cfm also have changes. The green highlighting on the left and the blue on the right tells us that the right side has the newer files, but usually after doing the search-and-replace on the headers, it will actually be the older files that you will be copying over as these will be the ones with the latest CFWebstore update. You generally will want to use a standard method of doing updates with the new version on the right or left according to what works best for you. I personally prefer to keep the newer version on the left and copy over to the right side. Let's now take a look at what the actual file comparison screen looks like:

The areas in the file that have changes will be highlighted in yellow to make them easy to find. Again, different colors are used to differentiate the actual changes (text added, removed, changed, etc.) You'll have arrows on the toolbar that will let you jump down the page from change to change, and to copy the changed sections from one file to the other. You can also copy-and-paste or directly edit each file after which you generally will need to save your changes and re-compare in order to use any of the ExamDiff auto-copy functions. Many times I will just review the changes on each page and then return to the directory and copy the entire file over rather than making line-by-line copies. The exception to this will be in files where I have made custom changes.

The CFWebstore documentation mentions how important it is to comment any changes you make in the code. Here's where these comments really can help you. Let's look at a file where I have made some custom changes:

Here I have added an additional section to the access/admin/index.cfm page. If I did not have a comment in there to remind me that this is code I added, I might think that this update is removing this code. Now, this is a fairly obvious change, but other code changes you make might not be quite so obvious. The comment will ensure that you save any such modifications and don't over-write them when performing updates. If you've previously made changes that you didn't comment, and still have a copy of the CFWebstore version that your store is running on, you can always run a comparison of the two copies to find your changes and go back and comment them to make future upgrades easier.

So that's basically it! Once you've completed the process, run through and check your store to make sure everything works as it should, particularly any areas where you have made customizations to the code (as occasionally changes to the code may break previously coded custom work). Then you're ready to upload your site with the latest, greatest CFWebstore version. Be sure not to overwrite your config.cfm file on the remote site (as this typically is different than your local development copy) and always run the Refresh Cache option in the admin after an update to be sure all the CFCs in memory are refreshed. You will typically also want to always copy over the new 'version.txt' file in the top store directory as this is used to display your current version on the Admin homepage.