CityDesk Replacer - A Post-Process, Pre-Copy String Replacement Tool for Fog Creek CityDesk

Overview

This is the home page for a utility called "CityDesk Replacer." The purpose of this tool is to augment the functionality of Fog Creek Software's CityDesk web publishing tool, specifically the 2.0 version (even though CityDesk Replacer will presumably support future versions of CityDesk, my hope is that the need for CityDesk Replacer will go away with a future version of CityDesk). In short, this script allows for generic string replacement functionality at a specific point in the CityDesk publishing process: after a CityDesk "Location" has been processed using the "Publish" feature, but before the files for that Location have been copied.

I created this script when I hit a wall with the "extra fields" feature. Each CityDesk article can have a limited number of "extra fields" associated with it. I use these extra fields often in my CityDesk teplates in cases where I need a standard kind of information to appear within a template, but with a different value for each article. Because the value needs to be different per article, CityDesk variables are not a solution. When I ran out of extra fields, I had to devise my own solution. Luckily, a nice CityDesk feature that allows you to shell out to an external program during the publish process makes CityDesk Replacer possible.

I can think of two features for future versions of CityDesk that will eliminate the need for CityDesk Replacer: more extra fields for each article and/or a more full featured scripting capability within CityDesk. In the meantime, CityDesk Replacer does the trick.

One quick example might help: let's say I've maxed out the "extra fields" for my CityDesk articles--they're all filled with data already. I want to add a new feature to my article template, which will be link to a PDF version of an article. Using an extra field is a natural for this purpose, since I can refer to {$.extraX$} in my template and assign a unique value per article, but I've used up all of my extra fields. CityDesk Replacer provides a solution to this problem.

How to Use

(Note: the best source for usage information is the large block of comments at the top of the script file itself, from which the following is excerpted).

This script processes a list of files, performing a series of string replacement operations on each file. An XML configuration file provides the input for which files need to be processed and which strings need to be replaced in each file. The location of the files is expected to be relative to a path passed in as the first command line argument.

You have to prepare three things in order to use this script:

• First, create a token that you want to replace in one of your CityDesk (CD) articles. The token could go into an article, variable, or template--as long as it ultimately ends up in a file outputted by the CD processor. For example, say in the file \Articles\ArticleOne.html you wanted to replace the token "[{NAME}]" with the value "Tom Jones". You would put the token value [{NAME}] in the CD article, variable, or template where you want it replaced.
• Second, add the file \Articles\ArticleOne.html to the CDReplacerConfig.xml file, which should be in the same location as this script. Use the correct pathname for the output file, and put the value you want to replace the token with into a CDATA section inside the Replacement node. TIP: The optional second command line argument is the name of the configuration file to use. This allows you to create different config files for different Locations.
• Third, configure one or more Locations in CD to call this script file. You have to configure it for the "Before Copy" field. Here is an example:
  
      WScript C:\CityDeskReplacer\CDReplacer.vbs %1 CDReplacerConfig.xml
  
  As explained in the CityDesk user interface, %1 is automatically replaced at runtime with the path to the temporary folder that is the root of the site about to be copied to the server. Notice that you must use either the WScript or CScript host executables to launch the script. Be aware that the CScript host will route errors to the Windows error log instead of displaying them. Use CScript if you want to supress message boxes during the publish process. It is recommended that you use WScript at least at first so you can make see any error messages right away.

You can think of adding the Replacement nodes to the configuration file as adding new "extra fields" to the article. This example use a token-based scheme (that is, [{NAME}] gets replaced with Tom Jones), but any string can be replaced by any other string. And since the "search for" and "replace with" values are within CDATA sections in the configuration file, you can use special characters, white space, line breaks, etc.

Download

Click here to download the latest release of CityDesk Replacer.

Note: you will also need to have the Microsoft's MSXML 4 XML parser component installed on your machine. This component comes with several Microsoft products, such as Visual Studio, so you may have it already. Try running CityDesk Replacer first and see if you get an error that it could not create the XML object.

License

CityDesk Replacer is licensed under the GNU General Public License. This script may be used freely, as specified in the license. You can modify and redistribute the script as long as derivative works are also released under the same license. No warranty of this script is offered or implied.

Support
If you have any suggestions or comments, feel free to post them below or

. If you fix any bugs or make any improvements, please let me know.

--Daniel Read

(Note: the site you are viewing now is not a CityDesk site. This developer.* Cooperative Digest site is powered Drupal. However, the companion developer.* Magazine site is published using CityDesk.)