December 17, 2007

Writing the User Guide for the Website Owner in Drupal

Every now and then I end up building a website for someone, and these days I'm tending to pick Drupal as the starting point. It's got a huge number of extensions and modules you can add, and an active developer community.

Part of the reason for going with a Content Management System (the fancy title for the category of website software that Drupal falls into) is that it makes adding and managing content easy for the non-web-developer website owner. That means that there's less work for me to do to keep it running, and more importantly means that whoever runs the website doesn't have to wait for me to find some time before they can change anything.

In order to make updating the website easier for the owner, I try to document some of the basic tasks - adding a page; putting a new product in the catalogue; etc. - in some help pages on the site itself, but obviously I don't want those pages to be visible to normal visitors to the site.

To save me reinventing the wheel next time I'm building a site, here are the details of how I add the 'Staff User Guide'.

A Different Class of User

In order to stop normal users from seeing the "Staff User Guide", we need some way to differentiate between them. I tend to create a new user role for "website staff" anyway, rather than give them the same privileges as "admin".

So, on the page /admin/user/roles add a new role "Staff user", and assign that role to any users who will be updating the website.

Restricting Access to the User Guide Content

With the out-of-the-box installation of Drupal you can't (to my knowledge) prevent anyone from seeing any of the nodes (Drupal-speak for a page, or chunk of content). We could just hide the links to the user guide from normal users, but it would be better to prevent them from accessing them at all.

That's where the Content Access module comes in. Install the module in your Drupal site and enable it on the modules page.

This module allows you to choose who can access (view, edit or delete) any type of content. When editing a content type you'll now have a new page of options entitled "Access Control". For each user role you can decide whether they can view, edit or delete nodes of that content type.

So, let's create a new content type called "User Guide Page", of type "userguide". Then set the access control so that only the "Staff User" role can see or edit the pages.

Optional: If you're using the Pathauto module, and want your user guide pages to have nice URLs then remember to update the setting on the Pathauto configuration page. For example, to have all user guide pages appear at "/userguide/name-of-page", set the pattern for all user guide page paths (in the Node path settings section) to userguide/[title-raw].

Creating the Index

Now you're free to start adding pages to your user guide, by creating new "User Guide Page" nodes. However, one last setup task is to provide a way for the staff users to find and browse through the guide. As I don't expect there to be too many pages in my user guides, I'm going to keep it simple and list them all in a new block in the sidebar.

Go to the Blocks admin menu (/admin/build/block) and add a new block. I called mine the "Staff User Guide" (in both block description and block title) and then chose the "Staff user" as the only role who can see the block. Then I added this snippet of PHP code as the block body, and chose "PHP Code" as the "Input format". It's fairly simple, all it does is find all the nodes of type 'userguide' and creates a simple bulleted list of links to those nodes. (If you chose a different name for the type of your content type, then replace 'userguide' with your name).

<p>Explanations of how to do common tasks on your website.</p>
  $results = db_query("SELECT nid FROM {node} WHERE type = '%s'", 'userguide');
  $output = '<ul class="menu">';
  while ( $data = db_fetch_object($results) ) {
    $node = node_load($data->nid);
    if ($node->status == '1') {
        $output .= '<li class="leaf">';
        $output .= l($node->title, 'node/'.$node->nid);
        $output .= '</li>';
  $output .= '</ul>';
  print $output;

There you go. Choose where you want the block to be displayed, and then get on with writing your user guide.


Posted by Adrian at December 17, 2007 07:37 PM | TrackBack

This blog post is on the personal blog of Adrian McEwen. If you want to explore the site a bit further, it might be worth having a look at the most recent entries or look through the archives or categories over on the left.

You can receive updates whenever a new post is written by subscribing to the recent posts RSS feed or

Post a comment

Remember personal info?

Note: I'm running the MT-Keystrokes plugin to filter out spam comments, which unfortunately means you have to have Javascript turned on to be able to comment.