Illustration by Lia Avant

Converting the State of Hawaii Governor’s Website to Plone

If you’ve been looking for Content Management Systems (CMS) recently, most likely you’ve run into an Open Source CMS called Plone. The fact that Plone is free and offers features that rival existing commercial content management solutions makes it a strong CMS contender for any Website project.

Plone is probably one of the most sophisticated systems developed for Zope, powerful yet flexible enough to be customized to look like any other Website. Prior to the switch to Plone, the State of Hawaii Office of the Governor’s Website required a Macromedia Dreamweaver Web developer to update its Website content. After adopting the Plone CMS, several non-technical staff members from the Governor’s Office are able to keep the site updated using a simple Web browser. The switch to Plone was completed by the Department of Accounting and General Services/Information and Communication Services Division (DAGS/ICSD) in April 2003 and since then the Governor’s staff members have benefited from the multi-user and through-the-web content creation features of Plone.

Implementing the Governor’s Website as a Plone content-managed Website was relatively easy compared to the amount of work it would have taken to build a CMS from scratch. With a zero budget, a one-month time frame and only 2 developers on the project, the choice to use Plone was a relatively easy one to make. As Plone already provides content management functionality out-of-the-box, the challenge for the project was to replace the existing skin of Plone to adopt the look and feel of the State of Hawaii Governor’s Office Website.

This article will explain some prerequisites for customizing Plone and outline the major steps of how this conversion was undertaken. The article will cover the following topics :

• Zope Page Templates required
• Plone skins
• Preparing the existing Website HTML as a custom skin in Plone
• Modifying the Plone main_template for the Website sub-pages
• Creating a separate template for the Website front page
• Aggregating dynamic content on the Website front page
• Installing additional Plone products

Besides requiring some knowledge of Dynamic HTML, CSS, and Javascript, aspiring Plone Web developers need to have a good grasp of Zope Page Templates (ZPT).

ZPT uses Template Attribute Language (TAL) to render dynamic content on a Web page, and Macro Expression TAL (METAL) to define macros, or blocks of code, that can be used in different ZPT pages. Explaining TAL and METAL goes beyond the scope of this article, so if you need to find out more, please refer to the Page Template and Advanced Page Templates sections of the Zope Book

Knowledge of DTML is not as important as it once was since almost all current Plone work is now done in ZPT.

Finally, knowledge of the Python scripting language is important for customizing all the Python scripts used by Plone.

Separation of form and content is achieved in Plone by its extensive use of TAL and METAL. Because of this separation, it becomes possible for Plone sites to dynamically render Plone user content using different UIs, called “skins”. Out of the box, Plone comes with several variations of the Default Plone skin. These skins are listed in the “Properties” tab of the Plone portal_skins folder.

Figure 1: Plone skins listing

The portal_skins folder contains several locked (uneditable) subfolders and a regular (unlocked) subfolder, named “custom”. The locked subfolders group all the default templates, stylesheets, scripts and images that come with Plone.

Figure 2: Default portal_skins subfolders

Customizations to the Plone skins are stored in the aptly-named “custom” subfolder. This folder supersedes all other portal_skins subfolders (as seen in the layer precedence order in Figure 1), so templates, stylesheets, images and scripts placed here override the Plone originals. Further, by copying files from the locked subfolders to the custom subfolder, the UI and behavior of Plone can be modified and enhanced further.

Of all the files in portal_skins, the main_template file in portal_skins/plone_templates holds the key to the structure and layout of all Plone pages.

The main_template file contains the Master macro, which is called by all other Plone templates for rendering layout. This Master macro uses other macros such as the portal_header and portal_footer macros, which are stored in the /portal_skins/plone_templates/header and /portal_skins/plone_templates/footer templates, respectively.

The Master macro also contains a handful of METAL “slots”, which specify areas within the macro where content from the calling template is placed. The left_slots and right_slots respectively specify where content for the left and right columns are placed. The macro’s main slot specifies the area where the main content of the page is rendered.

Figure 3: Layout of main_template’s Master macro

As indicated above, the Governor’s Website was originally developed using Macromedia Dreamweaver. The original Website provided the images, HTML and Javascript code that had to be integrated into the Plone main_template file. It would have been better to redo the templates from scratch but the Dreamweaver template had already been approved by the Website committee. The creation and approval of new templates would not have been possible within the deadline set.

Therefore, the Dreamweaver template was cut up into separate pieces of HTML and Javascript that could be strategically inserted into Plone’s Master macro to render the original Webpage in Plone. HTML snippets for header Javascript code, the page header section, the left column section, the right column section and the page footer section were stored as separate DTML Documents in the Plone skins custom subfolder. The actual content from the Dreamweaver page was not included in the HTML snippets since it is provided as users of the Plone CMS create content. Figure 4 shows an approximation of how the Dreamweaver template was split up.

Figure 4: Approximation of the Dreamweaver Template’s division into separate files

Since the right column area was not used in the original Dreamweaver page, it was the ideal area to put Plone content management navigation and controls.

While a default Plone site uses the same layout throughout the site, the Governor’s Website uses 2 different HTML layouts, one for the front page and another for all subpages.

This required the creation of 2 main_template files – one for the front page and a second one for the subpages. Each template contained its own Master macro which was modified to fit the corresponding layout. Since Plone uses the main_template Master macro by default, we used main_template for the subpages as it required the least amount of changes to Plone. Only for the front page, therefore, was a completely new main_template created, which we named main_template_front. Both main_template files were stored in the custom portal_skins folder.

A new image portal_skins subfolder was added to contain all the image files used to render the Macromedia Dreamweaver pages. The actual image files were easily uploaded to this folder using Zope’s built in FTP service (port 8021).

Except for the Plone Default listing, all the other Plone skin listings in portal_skins were removed. The newly created images folder was then added as an additional layer of the Plone Default skin (see Figure 5).

Figure 5: Adding an images subfolder to the Plone Default skin.

The separated HTML and Javascript templates were stored in the custom portal_skins folder as separate DTML Documents, since DTML Documents are better than Zope Page Templates for storing non XML-compliant HTML code. Because DTML Documents are not strict about properly-formed HTML markup, it will not generate errors when the HTML fragments are saved. Figure 6 shows the content of the custom portal_skins folder.

Figure 6: The portal_skins custom subfolder containing HTML code fragments (stored as DTML Documents), and customized main_template and main_template_front files.

In addition to main_template, the header and footer files were also customized and stripped of unneeded Plone content. Commenting out of blocks of code is easily done using the tal:replace function:

<tal:commentout tal:replace=”nothing”>
(block of code to comment out)
</tal:commentout>

The DTML Document code snippets were then included in the Plone templates using the tal:replace function:

<span tal:replace=”structure here/filename” />

where filename is the name of the DTML Document to include.

The following macros were modified to integrate the Dreamweaver code into Plone’s main_template skins:

The portal_header macro in /portal_skins/custom/header:

• The Plone logo, the search box, the horizontal bars, the portal_tabs, the personal tabs and the path bars were commented out using

  tal:replace=”nothing”

• The Javascript rollover code contained in gov_javascript_code was inserted between HTML <head></head> tags using
• The Governor’s Page header code was inserted at the top of the portal_header macro using

  <span tal:replace=”structure here/gov_header” />

The portal_footer macro in /portal_skins/custom/footer

• The Governor’s Page footer code is inserted at the top of the portal_footer macro using

  <span tal:replace="structure here/gov_footer" />

The master macro in /portal_skins/custom/main_template:

• The subpage left column code was inserted at the top of the left_column macro using

  <span tal:replace="structure here/gov_leftbar" />

• The background images, margin settings, text and link colors and onLoad Javascript code from the original subpage <body> tag were added to the <body> tag of the Master macro.
• Additional minor HTML tweaks were performed on the master macro to make the Governor’s subpages render properly.

Because Plone has default left_slot and right_slot entries that were not needed in the Governor’s Website, they had to be removed from the page. The content of the left_slots and right_slots columns of Plone are defined in the Properties tab of the Plone root folder and of the Plone Members folder. As the right column was the designated place for the content management navigation and control boxes, all the usable controls were moved to the right slot

Figure 7: Configuring the left and right columns

The personal_bar in the portal_header macro contains important CMS actions for the Plone user. Since it was removed from portal_header, this functionality needed to be made available elsewhere – the right_slots area was the natural candidate for it. Therefore, a new slot macro, portal_slot/macros/personal_slot, had to be created (in the custom portal_skins folder) and added to the site’s right_slots column.

Below is the code for portal_slot:

Listing 1: Code Listing for portal_slot

The personal_slot then had to be added to the right_slots listing to make this control box available.

Figure 8: Adding the personal_slot control box into right_slots

The image below shows a typical subpage of the Governor’s Website after all these changes were made. Plone’s content management features are now embedded in the Governor’s Website templates and visible only to Website content creators, reviewers and managers.

Figure 9: A typical subpage of the Governor's Webpage for content creators, post-Plone

As mentioned above, the front page of the Governor’s Website required a separate Master macro to be created. In addition, new header and footer files also had to be created as part of the customization of the front page layout. The customized template files for the front page were named main_template_front, header_front and footer_front. As in the subpage, code from the Dreamweaver-designed front page was integrated into this front page Master macro.

A copy of index_html file from /portal_skins/plone_template was placed in the Plone site’s root folder and modified to use the main_template_front/macros/master macro. This index_html file was then modified to collect content throughout the site that is published by the Portal managers and reviewers.

Two published portal_types were collected for display on the front page -- the newest published headline and the 3 most recently published news releases. While Plone has a built-in news release object, a new Headline object had to be created.

To learn how to create new portal_type objects, please refer to Chapter 8 of the Plone book, as this is beyond the scope of the current article.

The code listings shown below for dynamic insertion of the headline and the three news releases were inserted into index_html. Listing 2 shows the code that polls the Portal Catalog for the latest published headline and displays it on the front page:

Listing 2: Polling the Portal catalog for the latest headline on the front page

Similarly, Listing 3 was also inserted into index_html: it pulls the 3 most recently published News Items from the Portal Catalog and lists them on the front page.

Listing 3: Listing the 3 most recently published news items on the front page

Not enough praise can be given for the add-on products available in Plone. Several additional Plone products were installed in the Governor’s Office Website to enhance its CMS functionality.

CMFVisualEditor provides the end user with a WYSIWYG editor for editing HTML pages. Although it only works with Internet Explorer 5.5 and up, it is probably one of the most important add-ons that make Plone’s CMS features easy to use. Figure 10 shows CMFVisualEditor in action.

Figure 10: CMFVisualEditor in Internet Explorer 6.0

CMFPhoto and CMFPhotoAlbum were also installed on the Governor’s Website. The two Plone add-ons make it extremely easy to create photo galleries on the Website. Once Photos are uploaded as CMFPhoto, thumbnails and several pre-set image sizes are automatically generated, providing the most flexibility for viewing the Photos. Figure 11 shows a typical Photo listing on the Governor’s Website.

Figure 11: CMFPhoto in action

Finally, CMFQuickInstallerTool was also installed for facilitating the installation of additional products to a Plone site. The three Plone add-ons (and more) can be downloaded from Plone Collective’s Sourceforge Website.

The final step in the migration was the transfer of existing content. Although the content had to be recreated in the Plone site by hand, using the content management features in Plone made the process fairly easy to do. With the content creation workload now distributed among several staff members, moving all the content took no more than an hour and creation of new content now takes much less time than it used to.

With the implementation of Plone on the Governor’s Website, the Governor’s staff focuses on creating and publishing content instead of struggling with the technicalities of HTML. Those who are travelling no longer need to be at their desktops since they are able to update the Website using nothing more than a browser. In the end, the State of Hawaii not only saved money and time but also improved the timeliness of content publication on the Governor’s Website by its use of the Plone CMS.