The Ciel Web Page Editing System


Or, "How to let a whole bunch of people with mixed levels of HTML knowledge edit their own web pages, maintain a consistent look and feel, and provide good performance without the liabilities of a frames-based website"

Copyright 1998, 1999, Boutell.Com, Inc.

Permission granted to use this information free of charge, under the terms of the GNU Public License, version 2 or later.

Rationale

Like most organizations nowadays, our cohousing community has a website. The community is made up of many individuals, with varying levels of skill and interest in Internet matters.

Ordinary websites are typically maintained by a single skilled webmaster. This is often a good approach, and it helps to ensure a consistent look and feel, which users appreciate. However, this approach is not ideal for a consensus-based community administered by very busy volunteers. I therefore decided to create an easy-to-use system that allows individuals to update their own web pages.

Ease of Use

The Ciel web page editing system was created to allow a group of individuals to maintain their own contributions to a shared web space describing a cohousing community. I wanted to provide everyone with the ability to edit their own personal page. I also wanted to allow several individuals to edit all of the pages as needed, acting as "administrators." I didn't want to require a great deal of HTML knowledge on the part of all users, but I also wanted to allow the use of HTML by knowledgeable contributors.

Implementing Ease of Use

The ease of use problem is solved by allowing users to edit their HTML right on the web, using a forms-based interface. For the convenience of inexperienced users, blank lines are interpreted as paragraph breaks, inserting a <P> tag in the actual page. This translation is performed in both directions so the page continues to look simple when the user opens it for additional editing.

More experienced users are free to enter as much or as little HTML as they desire.

In addition, in order to make the interface less annoying for beginners and experienced users alike, the HTML code is word-wrapped in a consistent fashion. (Many HTML editors place entire paragraphs with dozens of tags on a single line.) Line breaks from different types of systems (such as Macintoshes, Windows PCs, and Unix systems) are converted to a consistent form.

Performance

It is very important that the web server not be forced to carry out extra work in order to deliver every web page. Systems that rely on CGI programs to deliver every page are much more likely to slow down and begin refusing connections.

Implementing Performance

The performance issue was resolved by assembling entire, complete web pages each time the editing system is used. As a result, no CGI programs are required for actual browsing of the resulting pages. They are normal, complete HTML documents. The editing system uses simple HTML "comments" to keep track of structural details. These comments are not shown to the user as part of the rendered page.

Consistent Look and Feel

Providing a consistent appearance and a standard navigation bar was the second goal of the system. This could have been accomplished by placing the user's content in a frame, and the navigational tools in another frame. However, the use of frames has several significant disadvantages:

Why Frames Are A Problem

1. Older web browsers do not support frames at all

2. Web browsers for handheld devices usually ignore frames, using the "<noframes>" content instead, if any is provided

3. Text-based browsers offer, at best, a menu of the available frames

4. Frames are individual documents which must be retrieved individually from the web server, slowing down the user. You might expect them to be reused, but you'd be surprised; read on to see why unique <frameset> pages for almost everything are necessary.

5. Frames don't work well, even in browsers that do support them:

5a. In Netscape 2.0, the "BACK" button takes you all the way out of the entire frameset; it does NOT reverse your most recent navigation in an individual frame, contrary to the user's expectations

5b. In all frames-capable browsers, users cannot bookmark "what you see now" if frames are being used, unless the pages were created using a tedious workaround; see 5c. below. The latest browsers try to help, by allowing the browser to bookmark "this frame" using the right-button menu. But when the user returns to that bookmark, they only see that one frame -- completely missing the other frames you lovingly designed to provide navigational tools ... and to sell stuff. You don't want that to happen, do you?

5c. Designers can work around 5a. and 5b. by creating a unique top-level <frameset> web page "wrapper" for absolutely EVERY document, writing every single link in every single page with a target="_top" attribute. This does provide something to bookmark and to "BACK" up from; however this is extremely inconvenient and difficult to maintain consistently, with no exceptions, across your entire website.

5d. It is possible to automate 5c. using Perl scripts, but if you're going to do that, why not write scripts that build lovely tables instead of bothersome frames? They will load faster, render better, crash browsers less, and provide the same services.

5e. Frequently the browser will not set the "focus" to the right frame. This means the user must first use the mouse to select the desired frame before using the keyboard to scroll that frame, or to interact with forms in that frame.

5f. Frames typically take up a great deal of real estate. Compare this to table cells, the sizes and borders and layout of which can be specified more precisely.

How It Works

Templates: An Alternative to Frames

The Ciel web page authoring system relies on "templates." Templates are web pages in which the HTML content common to all pages is present, and the location at which the content for an individual page should be inserted has been clearly marked. This allows the editpage.cgi script to find the correct position from which to extract the current HTML in order to present it to authorized users for editing purposes. The script then recreates the page, inserting the HTML back into the page at the same location.

An Example Template

The following HTML makes up the template currently used on Ciel Cohousing's website. Note that the HTML for each unique page will be inserted by the editpage.cgi script at the location where the words BODY GOES HERE appear.
<html>
<head>
<title>Ciel Cohousing</title>
<meta http-equiv="Content-Type" 
content="text/html; charset=iso-8859-1"></head>

<body bgcolor="#9f9fcf">
<table border="0" width="100%" cellpadding=20>
<tr> 
    <td valign=top bgcolor="#60309f">
  <div align="center">
  <MAP name="indexPanel">
  <AREA shape="rect" 
  coords="1,1,126,163" href="index.html" 
  alt="Home Page">
  <AREA shape="rect" 
  coords="1,172,126,265" href="page2.html" alt="Who We Are">
  <AREA shape="rect" 
  coords="1,273,126,359" href="page3.html" alt="Our Land">
  <AREA shape="rect" 
  coords="1,369,126,456" href="page4.html" alt="Our Values">
  <AREA shape="rect" 
  coords="1,463,126,565" href="page5.html" alt="Interested?">
  <AREA shape="rect"   
  coords="1,566,126,674" href="page6.html" alt="Calendar">
  </MAP>
  
  <IMG SRC="img0.gif" BORDER=0 
  usemap="#indexPanel" alt="Menu" HEIGHT=696 WIDTH=129>
  </div>
  </td>
  
    <td valign="TOP" align="left">
BODY GOES HERE
    </td>
  </tr>
</table>
<p>  </p>
</body>
</html>

A Complete Page

The following HTML demonstrates the result of creating a page through the Ciel web page authoring system. Note that the text unique to the page appears between the BEGIN USER BODY and END USER BODY HTML comments. This allows the editpage.cgi script to extract this text again when the page is again edited.
<html>
<head>
<title>Ciel Cohousing</title>
<meta http-equiv="Content-Type" 
  content="text/html; charset=iso-8859-1"></head>

<body bgcolor="#9f9fcf">
<table border="0" width="100%" cellpadding=20>
<tr> 
    <td valign=top bgcolor="#60309f">
  <div align="center">
  <MAP name="indexPanel">
  <AREA shape="rect" 
  coords="1,1,126,163" href="index.html" alt="Home Page">
  <AREA shape="rect" 
  coords="1,172,126,265" href="page2.html" alt="Who We Are">
  <AREA shape="rect" 
  coords="1,273,126,359" href="page3.html" alt="Our Land">
  <AREA shape="rect" 
  coords="1,369,126,456" href="page4.html" alt="Our Values">
  <AREA shape="rect" 
  coords="1,463,126,565" href="page5.html" alt="Interested?">
  <AREA shape="rect" 
  coords="1,566,126,674" href="page6.html" alt="Calendar">
  </MAP>
  
  <IMG SRC="img0.gif" 
  BORDER=0 usemap="#indexPanel" alt="Menu" HEIGHT=696 WIDTH=129>
  </div>
  </td>
  
    <td valign="TOP" align="left">
<!-- BEGIN USER BODY -->
<div align="center">
<IMG SRC="logo.gif" ALT="Ciel Cohousing"
HEIGHT=239 WIDTH=248 ALIGN=bottom>
</div>
<strong>
A second cohousing community is planned for West
Seattle!
</strong>
<BR>
<H3>
Ciel Won the Mayoral and AIA Co-Sponsored Design
Demonstration Project Competition, September 10,
1998! <a href="pressrelease.html">
Click here for details </a>
</H3>
<UL>
<LI>
We own 2.7 acres of lightly forested land in West
Seattle, a ten minute drive from downtown. 
We will be directly across the street from South
Seattle Community College in a quiet area near
parks, an open green space, and within a few
blocks of the new six acre Chinese garden planned
for the area.
</LI>
<a href="neighborhood.html">
Click here to see information on neighborhood
amenities and transportation </a>
<LI>
We have eleven active household members so far and
several prospective future members.  We are
organized as a limited liability company.
</LI>
<LI>
We provide regular orientations for people
interested in the community, with a goal of
building a multi-cultural cohousing community as
diverse as the surrounding neighborhood
</LI>
<LI>
We value community, the environment, consensus
decision making, and diversity in its many
forms.
</LI>
<LI>
We meet every Sunday afternoon or evening, usually
on Phinney Ridge
</LI>
<LI>
We plan to finish construction and move in in 1999
</UL>
<a href="design.html">
Click here to see our site plan (updates available
at orientations) </a>
<p>
<img src="img3.gif" width="90" height="90"
align="left" alt="email">
<a href="mailto:sample@dummynameexample.com">
Email us!</a>

<!-- END USER BODY -->
    </td>
  </tr>
</table>
<p>  </p>
</body>
</html>

The editpage.cgi Script

editpage.cgi is a simple Perl CGI program that implements the design described above. When this script is placed in a password-protected directory of the website, it allows users to edit only their own personal web page, unless they appear on a list of administrators who are allowed to edit all pages in the directory. Note that this script was designed for a small site for which a single directory was a reasonable strategy. It would not be difficult to modify the script for larger sites with many subdirectories.

Downloading the Components

For your convenience, you can right-click the following links and choose "save link as" in order to pick up unaltered copies of editpage.cgi and template.html. In order to allow you to download it, the file editpage.cgi is renamed editpage-cgi.txt in this link. Just save it as editpage.cgi or rename it afterwards!

Installation Note

There are various references to directories, people and email addresses at the start of editpage.cgi. Of course, you must change them to suit your purpose. You must also put the script in a password protected directory and create a set of users in an Apache password file. In order for a user named bob to edit his own web page, to edit their own web page, you or another person on the list of administrators at the top of the script must first create a web page named bob.html for him. This is easy to do; try visiting the script's URL as an administrator.

If You Have Problems

Read this document. Then read it again. Then read the Apache manual, or the manual of your web browser. Then make sure you can use CGI programs at all before sending email. Don't email us asking why your web server doesn't want to allow any CGI programs to run. That is between you and your ISP. Finally, make sure you have Perl 5. If you are sure you have tried everything, you can contact us

Security Note

Considerable care has been taken to ensure that if the script is properly installed in a password protected directory, only individuals who appear in the password file will be able to use it to create and edit pages. In addition, care has been taken to prevent the entry of dangerous characters such as shell escapes and full paths that could provide access to other files on the system. The single-directory design greatly eases this process.

Credits

By Thomas Boutell. Thanks are due to Ciel Cohousing, and to Odysseus Levy.