Content Management

Keep track of updates to your web site documents with this Mason application.

Mason-CM is now in place. However, we need Apache to load a number of Perl modules in order for it to work. In your Mason configuration file (which I call “”, but the Mason documentation calls it “”), insert the following block of Perl code:

   package HTML::Mason::Commands;
   use Fcntl;
   use MLDBM;<\n>
   use Image::Size;
   use URI::Escape;
   use File::PathConvert;
   use File::Copy;
   use File::Find;
   use IO::Handle;
   use IPC::Open2;

Now that we have told Apache and Mason where to find Mason-CM, it is time to configure Mason-CM itself. Nearly all of the configuration is performed by modifying the cmConfig component, located in the /cm directory. As of this writing, cmConfig is written using the old-style Mason interface, which may seem a bit foreign to those of us who started using Mason with version 0.80. For example, the initialization block is called <%perl_init> rather than simply <%init>, and one component invokes another with mc_comp rather than $m->comp. Nevertheless, the component should be relatively easy to recognize and understand by anyone with even a minimum amount of experience with Mason.

The two main variables that must be set at the top of cmConfig are $CM_HOME and $CM_DATA. (These are defined on line 25 of the default version of cmConfig, at the top of the <%perl_init> section.) The first refers to the directory in which Mason-CM is installed. The second refers to the directory in which Mason-CM can store information on the files it manages, such as locking and version control information. On my system, I defined them as follows:

my $CM_HOME = '/usr/local/apache/mason/cm';
my $CM_DATA = '/usr/local/apache/cmdata';

Both of these directories must exist in order for Mason-CM to work. While $CM_HOME should already be defined (since cmContent is supposed to be inside of $CM_HOME), you may need to create the $CM_DATA directory. Note that this directory is different from the Mason data directory, which I typically put in /usr/local/apache/masondata.

Following the definitions of $CM_HOME and $CM_DATA is a large hash, called %cm_config. The keys in %cm_config describe different configuration options, and the values are the settings for those options. In most cases, the default options are probably adequate; we will discuss only those options that you must or should change.

The “admin” key refers to the e-mail address of the Mason-CM administrator. The administrator is responsible for undeleting files, unlocking locked files and generally managing the content management system. By default, this is set to be cm-admin, but you can change the value to something else.

Defining Branches

The value associated with the “branches” key is an array reference describing the various “branches” on the version control system. While all of the branches must be under $CM_HOME, this makes it possible to differentiate between subsites. For example, a newspaper might have separate branches for the news, sports and business sections. Each branch is identified by a unique name, followed by a hash reference identifying different characteristics associated with the branch. For example, here is what the “branches” key looks like for a web site with a single branch, called “Primary”:

branches => [
      Primary => {
          path =>'/usr/local/apache/htdocs/staging/content',
          trg_from => 'staging',
          trg_to => 'production',
          components => 0

The above branch will be displayed in the Mason-CM “branch selector” as “Primary”, and controls all of the documents under /usr/local/apache/htdocs/staging/content. Make sure the named directory does not end with a “/”, or Mason-CM will fail with a security violation.

The “trg_from” and “trg_to” keys are used in a simple substitution, indicating that to move documents from the staging server to the production server, we replace the string “staging” with the string “production”. (Mason-CM calls the staging process “triggering”.) Thus content is initially placed in /usr/local/apache/htdocs/staging/content, and is staged to the directory /usr/local/apache/htdocs/production/content. Finally, we indicate that this branch contains static HTML (rather than Mason components) by setting the “components” key to 0.

A more complicated site might set branches to the following value:

branches => [
        News => {
            path => '/usr/local/apache/htdocs/staging/news,
            trg_from => 'staging',
            trg_to => 'production',
            components => 1,
            hidden => 1
        Business => {
            path => '/usr/local/apache/htdocs/staging/business,
            trg_from => 'staging',
            trg_to => 'production',
            components => 1,
            obj_dir => '/usr/local/apache/staging/obj',
            hidden => 1

The above Mason-CM configuration has two branches, known as “News” and “Business”. Because “branches” is an array reference rather than a hash reference, its elements are kept in their original order. This means the branch selector will display the branches in the order they are entered into branches above. Changing the order in which branches are displayed is as easy as modifying the order of elements in the branches array reference.

If we set up the branches using the above system, we can then modify our Apache configuration such that it takes any URL beginning with /news and rewrites it as /production/news:

Alias /news /usr/local/apache/htdocs/production/news

Now the staging server is hidden from view via a web browser. We can, however, configure our web server such that all requests to port 8080, or any other port we choose, are directed toward the staging server.

The “hidden” tag indicates whether the branch will be displayed by default in the branch selector. Normally, all branches are displayed by default, and are available to all users. And any user can customize the list of branches using the “my.CM” link in the upper right-hand corner of the Mason-CM index page, adding and removing branches from his or her menu. However, making a branch hidden by default gives new users a relatively clean view of the content management system.

Unlike the “Primary” branch, “News” and “Business” are defined to contain Mason components. Staging a component is different from staging a static page of HTML, in that Mason-CM will try to compile the component and test it for errors before actually allowing it on the production server. In this way, a broken component will not cause the production web site to fail, but rather only the staging server. If we want to store the compiled Mason components in a specific directory, we can specify that with the “obj_dir” key.

cmConfig can be modified in many other ways to customize your Mason-CM. However, once you have configured $CM_HOME, $CM_DATA and branches, you can begin to use Mason-CM.