Component which implements the ZaphodsMap configuration system.

Design Overview

• cross-platform: Windows (win32 and Dot Net), Linux, etc.
• cross-language: Object Pascal, C#, C++, etc.
• dependent only upon a single environment variable
• flexible enough for real-world applications
• easy enough for most programmers to learn

Licensing

The web site for this system is http://www.ZaphodsMap.com and all source code and documentation is published under a Creative Commons license. You may use TZaphodsMap in any type of Delphi project as long as you include a mention of the web site in your source code and documentation. Details are on www.ZaphodsMap.com.

Requirements

In order to use ZaphodsMap, you must have an environment variable named ZaphodsMap pointing to a folder on your computer, e.g. c:\Data\ZaphodsMap\. Use a folder which you know will be backed up.

Use a Branch for each Software Project

In terms of the Object Pascal components, the TZaphodsMap component loads data from files starting at the map's folder.

Under the map's folder are so-called branches (sub-directories). You should use a unique name for your branch -- perhaps your company name or project name. You can have as many sub-branches as you need, and you can include a configuration version in your branch as well.

Example Branches

Usage

When you create a TZapohdsMap component in Delphi, you can either Create it in general, or Create it specific to a branch. It is better to create it specific to a branch, using CreateForBranch.

var
  ZM: TZaphodsMap;

begin
  ZM := nil;
  try
    ZM := TZaphodsMap.CreateForBranch('ACompany' + PathDelim + 'AProduct');
    // use the map
  finally
    FreeAndNil(ZM);
  end;

Once you have the component created, you can use the map to find keyboxes (ZMKeybox.xml) which contain keys. A key can point to a folder, a file, or a string value. If you are writing a simple application which requires only a small amount of customization, you can put all your configuration settings directly into the ZMKeybox. Alternatively, you can set up one more level of pointers, and make a Key2File point to an XML file containing your configuration values.

Creating and maintaining the XML files can be done with any ascii file editor, or with the ZMAdmin utility (available as a binary for Windows from www.ZaphodsMap.com).

In memory, the keys are represented by TZaphodKey. If the key is a Key2File, then that pointed-to file is represented by TZaphodXmlDoc.

Once you have the TZaphodXmlDoc loaded, you have extraordinary powers for retrieving values from your custom XML configuration file. In particular:

• you can use simple xpath syntax to identify the node you want to retrieve instead of climbing through the tree yourself;
• you can take advantage of the context feature, which is designed for applications whose configuration might change based on deployment computer, for example, a web application;
• you can retrieve settings based on the current user;

Shortcuts

If you like the idea of ZaphodsMap but do not want to get involved with the intricacies of the classes, just use the static methods available for retrieving configuration settings: ZaphodKeyedFileZNodeAttr, ZaphodKeyedValue, ZaphodKeyedFolder, and ZaphodKeyedFileName.