Showing Lists of Events in Drupal 6

I wanted to have a page in Drupal that showed upcoming events for the Parent Advisory Council of my son's school, with a tab making it easy to show past events. The idea was to have one place to go to find out about upcoming events, or to find previous events so you could get materials from the event (e.g. handouts provided by speakers).

Drupal has a pretty good module for showing calendars, but it shows them on day, week or month views in a calendar. My users wanted to see a list of events. Our events are more spread out, so a list or table view is actually easier to work with.

So to summarize, we want:

• A menu in Drupal's primary menu for "Events"
• The menu takes the user to a page that shows upcoming (in the future) events
• There is a tab on the page for "All Events". Clicking the tab shows all events, paged with 20 events per page
• There is also a tab for "Upcoming Events". Clicking it takes you back to just the future events
• Events have to have a start and end time, and may have an additional description and attachments (e.g. agenda, minutes, hand-outs)
  

The high level overview of what I did is:

1. Install and enable some contributed modules
2. Create a "content type" for events. This defines what information you're going to store for each event
3. Define a "view" and two "displays" for the view. The view and its displays are partly a query of the information you want to appear, and partly the definition of the menus that get you to the information. The format of the information is defined by your theme, which I won't talk about in this post
4. Put the menu in the right place
5. Create some events and test it out. Testing is really important. It's almost impossible to get this right the first time

A small warning before you get started: The smallest error in anything can lead to very bizarre behaviour, or simply to some part of the page not showing up, with no apparent connection to the error. It took me days to get this working (with a lot of side-tracks into Drupal esoterica). Don't expect to get it right the first time, even with detailed instructions.

Here's what I did. I don't guarantee that I've covered every single thing, so please let me know by commenting on this story if I missed anything. (I assume you know how to do Drupal basics like install modules.)

1. Install the Content Creation Kit (CCK), Views, Date, and Advanced Help modules. Date module version 6.x.2.1 won't work for the use case we're trying to implement. The filter relative to a date (e.g. "now") is broken, which means you won't be able to show upcoming events. Use date-6.x-2.x-dev (see http://drupal.org/node/426990) until the fix gets rolled into the release version
   
2. Enable the "Content" part of CCK
3. Enable all parts of Date except "Date Locale" and "Date Tools", unless you want them for other reasons. Also, if you're running on PHP5 you don't need "Date PHP4"
4. Enable the "Views" and "Views UI" parts of Views

Now, create the content type for events:

1. Administration-> Content Management-> Content Types
2. Click on the "Add content type" link at the top of the "Content types" area
3. Enter the name "Event" and type "event". There are many options to set, and the help text is pretty self-explanatory. Under "Workflow settings", "Attachments", make sure they're enabled (since we said that was a goal of what we're doing). Most of the other options depend on your needs, although under "Workflow settings" it's likely you'll want to turn off "Promoted to front page" under "Default options"
4. Click the "Save content type" button at the bottom of the page
5. Click on "Manage fields" beside the Event content type
6. Under "Add", "Existing field", select "Datetime: field_event_datetime..." You may have to scroll down to see the existing fields. If you don't see an existing field called "field_event_datetime", then create one under "Add", "New field"
   
7. Click "Save"
8. You will be presented with another page allowing you to set a bunch of options. Set them according to your needs
9. Click "Save"

Now create the view. You really should read the Drupal Views documentation, which you have available because you installed the Advanced Help module. Read it now. Click on Administer-> Site building-> Views and you'll be given a link to the documentation near the top of the "Views" area

Now, here's my summary of what's important in the Views documentation:

• A view can have several displays. The display determines where the view is seen, and can also override some parts of the view's default settings. In the rest of this post, I use "view" and "display" in these specific meanings
  
• Set up the common aspects of the view first in the Default display. In our case, that means the output format (a table), the fields to be viewed, and some of the filters
• Be very careful when editing non-default displays to click "Override" before editing anything that you want to be unique to the display. If you don't explicitly click "Override", you'll change the default which will affect other displays that use the default value
  

So what we have to do is:

1. Create the view
2. Set up the default for the view the way we want it
3. Create a "Page" display for the "Upcoming Events" tab
4. Move the menu to the right place
5. Enter some test events
6. Check that the "Upcoming Events" tab works
   
7. Create another "Page" display for the "All Events" tab
8. Check that the "All Events" tab works
   

Here are the steps:

1. Administer-> Site building-> Views
2. Click the "Add" link at the top of the "Views" area
3. Put "event_list" in the "View name" field, and "Event List" in the "View tag"
4. Make sure the "View type" is node and click "Next"
5. This brings you to the Views UI page. I found this page to be extremely unintuitive. You have to be patient and always remember to scroll down after clicking on something, because many links simply change what's displayed below what's likely visible when you click on the link

Set the defaults for the view:

1. Under "Basic Settings", click "Unformatted" under "Style". Scroll down. You'll see some radio buttons. Click "Table" and click "Update". Ignore the error message that appears about no fields defined. We'll get to that later
   
2. Beside ""Use pager", click "No". Scroll down. Select the "Mini pager" radio button and click "Update"
3. Beside "More link", click "No". Scroll down. Select the "Create more link" check box and click "Update"
4. Under "Fields", click on the "+" beside "Fields"
5. Scroll down. Click on the check boxes for "Content: Event Dat and Time... From date". Don't check the box for the corresponding "To Date" field. Both are included in the "From date". Click on the check boxes for "Node: Body", "Node: Title", and "Upload: Attached files". Click "Add"
6. You'll now be presented with a number of pages to allow you to set options for each field. For "Event Date...", accept the defaults by clicking "Update"
7. For "Node: Body", accept the defaults by clicking "Update"
8. For "Node: Title", click the "Link this field to its node" checkbox and click "Update"
9. For "Upload: Attached file", click the "Link this field to download the file" checkbox and click "Update"
10. Now, put the fields in the order you want: Click the up and down arrows by "Fields". Scroll down. Drag "Title" up to the top and click "Update"
11. Set the sort order: By "Sort criteria", click the "+". Scroll down. Select "Content: Event date and time" and click "Add"
    
12. In the next page, select "Ascending", so the next event will appear at the top of the list. Click "Update"
13. Choose the nodes you want to display, specifically the published event nodes. Click the "+" beside "Filters". Scroll down. Select the checkbox for "Node: Published" and "Node: Type" and click "Add"
14. On the page for "Node: Published", click the "Yes" radio button and click "Update"
15. On the "Node: Type" page, click the "Event" checkbox under "Node type" and click "Update"
16. Click "Save". We have our default view set up.

Create the "Upcoming Events" page:

1. Click the "Add Display" button (the drop down box above it should read "Page" already)
2. Under "Basic settings", click on "Page" beside "Name". Scroll down. Type in "Upcoming Events" and click "Update"
3. Click on "None" beside Title. Scroll down. Click "Override". Enter "Upcoming Events" and click "Update"
4. Under "Page settings", click on "None" beside "Path". Scroll down. Enter "events/upcoming_events" and click "Update"
5. Click on "No menu" beside "Menu". Scroll down. Select the "Default menu tab" radio button. Enter "Upcoming Events" under "Title". Click "Update"
6. On the next page, click on the "Normal menu item" radio button, and enter "Events" under "Title". Click "Update"
7. Click on the work "Filters". Scroll down. Click on "Override" and then "Update". This overrides the filter selection but makes a copy of the two filters that we set as default
8. Click on the "+" beside "Filters". Scroll down. Click on the checkbox beside "Date: Date (node)". Make sure you get the right one. There are three fields that start with "Date:". Click "Add"
9. Scroll down until you see a heading that says "Date field(s)". Select the checkbox beside "Content: Event Date and Time... From date". Click "Update"
10. On the next page that appears, under "Operator", pick "Is greater than or equal to". Under "Date default", enter "now". Click "Update"
    
11. Click "Save". Note that after clicking "Save" you're again editing the default settings, not the upcoming events display. Be careful to select the display you mean to edit. I got that wrong lots of times

Set up the menus correctly:

1. The above puts the menu under the site navigation menu. We want it under the Primary Links menu. Click on Administer-> Site building-> Menus
2. Click on "edit" beside "Events"
3. Under the "Parent item" heading, select "" from the drop-down list
4. Click "Save". The "Events" menu will show up at the end of your primary menu. Drag it to the appropriate place in the list and click "Save configuration"

Create an event to test what you have so far:

1. Go to "Create Content"
2. Click on "Event"
3. Enter an event on the your current day or sometime in the future. It should be self-evident how. Watch that you end date is after the start date. The user interface doesn't automatically do it like some other programs do. Click "Save"
4. Enter another event with a date in the past. Again, make sure the end date is the same as the start date
   
5. Click on the "Events" menu on your primary menu. You should see the one future event you just entered, but not the past event
   

If the event doesn't show up, see the troubleshooting tips at the end of this post.

Create the "All Events" page:

1. Click on Administer-> Site building-> Views
2. Select "edit" for the "Event List"
3. Click the "Add Display" button (the drop down box above it should read "Page" already)
4. Under "Basic settings", click on "Page" beside "Name". Scroll down. Type in "All Events" and click "Update"
5. Click on "None" beside Title. Scroll down. Click "Override". Enter "All Events" and click "Update"
6. Under "Page settings", click on "None" beside "Path". Scroll down. Enter "events/all_events" and click "Update"
7. Click on "No menu" beside "Menu". Scroll down. Select the "Menu tab" radio button. Enter "All Events" under "Title". Click "Update"
8. Click "Save". Note that after clicking "Save" you're again editing the default settings, not the upcoming events display

Test again:

1. Click on the "Events" menu
2. You should see the table with the one future event. You should also see two tabs for "All Events" and "Upcoming Events"
3. Click on "All Events". You should see both events in the table
4. Click on "Upcoming Events". You should see just the future event again

Here are some troubleshooting tips:

• If the events aren't sorting the way you think they should according to the display's "Sort Criteria", click on the little gear beside "Style" under "Basic Settings". Scroll down. If the radio button under "Default Sort" is anything but "None", the sort here will override the sort in "Sort Criteria". Click on the radio button beside "None"
• With the Date module circa March-April 2009, you have to install a patch or you'll get error messages when creating events. Get the patch here and how to install it is here
  
• If the menu doesn't appear on the primary menu, or the tabs don't appear, make sure the paths for each display are below the same name as I showed above. In other words, the display paths should be of the form "x/y" and "x/z", even though the user will never navigate to "x"
• Recheck all your settings. This is tedious but essential. In my experience, any one being wrong can cause a mysterious and seemingly unrelated failure
• Be sure that you didn't accidentally change the defaults instead of overriding them, or didn't accidentally override something that should be taken from defaults. Values taken from the default display are in italics when looking at other displays

I hope this helps someone.

Building a Website for a Grassroots Group

As I've been blogging about recently, I've been building a Drupal-based website for my son's school's Parent Advisory Council (PAC). As a geek, the technical nature of putting together a content management system like Drupal for a site is interesting, and I learned a lot. However, what really interested me is the social aspect of it.

You can't have a business it seems without having a website. That must mean there's value for a business to have a website. But is there value for a grassroots group to have one? If technology truly is neutral, then grassroots groups must be able to benefit from websites. (I'm not sure technology is inherently neutral, but that's another topic.)

When we started, the PAC has a static HTML website updated infrequently by a parent who knew some HTML and how to FTP files to his server. It was out-of-date, since the parent's children had moved on to high school and he was obviously not so active in the PAC. Members of the PAC did want some place to post meeting dates and minutes, and to publicize their activities, so I offered to help out.

We set up a committee with four members. I built a test site under my company's site (jadesystems.ca) and we started to work.

Right from the start a few people really took to it and started to use it in ways that I couldn't keep up with. This included translation into Chinese, especially after I enabled the translation modules in Drupal.

I also set myself up to do screencasts, and posted a number of them. It's still early, but I've got some feedback from people that they find them very useful. For grassroots groups, where you don't site face to face with people every day, I think screencasts are going to prove to be an excellent tool.

I think the main lesson I've learned so far is this: I like Drupal and it's allowed me to do a lot. However, I can't help feeling that I'm writing in assembly language for content management. What I mean is that I've had to learn too much about how the system works to get it to do what I want. We're still a long way from grassroots groups being able to set up a website without someone with technical skills.

My dream would be something analagous to blogging. You simply go to a website and create your own community site. The task is inherently more complicated than setting up a blog, so it will never be as simple, but the skill set should be relatively similar. You should be able to pick and choose based on functions the user wants (e.g. a list of upcoming events), not functions based on how the programmer delivers them (e.g. a Views module with an obtuse and fragile configuration screen that lets you cobble together a list of upcoming events if you bang your head on it long enough).

More on this later.

Parent Advisory Council Website

The Parent Advisory Council (PAC) website is live at http://hastingspac.ca/ and is in a relatively stable form. Much work remains on the translations, but the bones of the site are there and it's up to everyone else to put up the content (muscle).

I think we've got a pretty good site for a volunteer group. Our goal is to increase participation in the PAC to benefit the education of our children.

I'll be posting more about the technology behind the site (Drupal and content management systems) this morning.

I'd love to hear comments and ideas you might have about the site.

Drupal Set-Up and Administration Tricks

I can't claim to be the world's Drupal expert yet, but I'm learning some interesting tricks that are worth documenting and sharing.

First, my Drupal installations typically include a lot of contributed modules. They're distributed as .tar.gz files, which you upload to your server and unpack in the appropriate place. This can get tedious and error prone (e.g. I forget to unpack one).

I built a template directory with a complete Drupal install on a Linux box (you could do something similar with Windows if you had cygwin or a similar set of Linux-like tools). I unpacked the Drupal version, then went into the modules directory and unpacked all the modules I typically use. That was easy to do with a script like this:

for f in module_directory/*.gz; do tar -xzf $f; done

Your mileage may vary with that script, depending on where you put the tar'd modules.

This allows a couple of nice things:

• One module I use, fckeditor, requires that you unpack the basic (non-Drupal) installation for FCKeditor in a subdirectory of the Drupal fckeditor module. With a little playing around, you can easily do this in the template directory once, and then you have the deployment set up correctly
• I need to set a higher PHP memory limit in Drupal's "settings.php" file. I can do it once in the template directory and deploy many sites reliably (read why here and here)
• You need to temporarily change the permission of the "settings.php" file for installation, and create the "sites/default/files" folder before navigating to the Drupal site for the first time. I create them both and make them writable in the template directories
  

Then, tar and gzip the resulting directory tree. There's one big trick to this step. You need to make sure you get the .htaccess file, so I include it explicitly:

tar -czf ../drupal-6.10-template.tar.gz * .htaccess

There's a reason I don't just tar the template directory. That would give me a tar file that would create a directory and expand into it. On my hosting service, it's more convenient for me to expand into the existing "public_html" directory.

The other "trick" isn't so much a trick yet, as it is thoughts on running several Drupal sites from one installation. It seems to be a Drupal pattern to create "multisite" configurations where you have sub-domains running from the same Drupal source code (PHP files), but with different databases, and different configurations and themes.

This sounds good, and you would only have to update the files once for all your sites. However, I think it also causes some problems:

• The technique for Drupal multisites that I found gives you a circular symbolic link in the sites directory hierarchy. I believe this causes problems when I try to copy the site prior to upgrading it (I copy to have a backup)
• The recommended Drupal upgrade procedure requires that you take the site offline, disable all modules, and then re-enable all modules after you upgrade. That means all your sites are offline for the entire upgrade, rather than being able to do each site quickly

With the template approach, the pain of uploading the files is gone. The rest of the work you have to do for each site anyway, so it becomes almost the same amount of work to just run each site as a completely independent Drupal installation.

I'm going to try my template based upgrade and will post about the experience then.

Cheap Hosting Part II

In an earlier post I described how I was running out of memory in PHP using a moderate set of Drupal contributed modules.

It turns out I was able to increase the PHP memory on my HostPapa hosted site. The method to use it to add the following line to Drupal's "settings.php" file in each site's "files" directory:

ini_set('memory_limit',             '48M');

Or if the line already exists, make sure the amount is '48M'.

One of the problems I think I had earlier is not changing the right settings.php file. I have multiple sites in multiple sub-domains, because the main purpose of this host is to do proofs-of-concept for clients. I probably thought changing the settings.php file didn't work because I changed the wrong one.

Suppose you installed Drupal under public_html. You have to change settings.php in public_html/sites/default to change the memory limit on your main domain (for example, "example.com"). For a sub-domain "test.example.com", you have to change settings.php in public_html/sites/test.example.com. And so on for any other sub-domains you have.

Cheap Hosting and PHP Memory

(For an update, read this post.)

I've been working on a few websites: One for my son's school's parent advisory council (PAC) and one for some community health centres. It gives me a chance to get to know what's out there in the open source world for content management, wikis, and other collaboration tools that we're supposed to be using to make ourselves more effective and productive.

The first step was to find a hosting provider that let me run PHP, as the free hosting I get from my ISP is for static pages only. I was pleasantly surprised to find very cheap hosting with PHP, MySQL and everything I needed, many for less than C$10 per month. I chose HostPapa -- despite the somewhat odd name, they seemed to have a good reputation.

There's a catch, it turns out. I'm using Drupal 6, a well-established and widely used content management system. When I build a site with a reasonable set of contributed modules (calendars, translations, FAQs), it needs more than 32MB of memory in PHP (I get a white page with a message saying "memory exhausted"). And I'd like to add a number of other modules.

My hosting provider doesn't let me change the amount of PHP memory, so the whole hosting arrangement is mostly useless. (There are good instructions for how to increase the PHP memory in Drupal here, but not surprisingly the cheap providers don't allow you to take too much memory.)

I also originally considered using Joomla!. Once I ran into the problem with Drupal I did some searching of the Internet and found that it seems to be an issue with Joomla! as well. Neither runs comfortably in 32MB if you have a reasonable selection of add-on modules. (Instructions to increase PHP memory exist with Joomla! with the same caveat that the provider can prevent you from doing it.)

It's rather unfortunate. My idea was to have this space to be able to do proofs of concept or show potential clients what could be done with modern collaboration tools. It would be likely that any serious customer would be able to host their own server, or at least pay for a slightly more expensive hosting provider. I don't need a high volume website, but I do need a space where I can show the capabilities of the tools. I hate to have to pay more money on pure speculation that this will lead to work, but it looks like that's the case.

I don't know whether to be annoyed with the content management systems for being memory hogs, or the hosting providers for setting unreasonably low limits on accounts on which they should fully expect people to use a modern content management system. By the way, I'm not really annoyed at either. I can see their point of view: HostPapa is really cheap and they need to control costs somehow, and serious Drupal users will find the difference of $10 per month for better hosting to be inconsequential, or will be paying for a dedicated server anyway because they get so much traffic.

The obvious lesson: One of the big things to look at when evaluating hosting services is how much PHP memory they give you. It's easy to offer unlimited database space, unlimited sub-domains, and other such goodies when you know that no one can use serious website management tools anyway.

Favicon in Drupal

I'm using Drupal to put together a site for my son's school's Parent Advisory Committee (PAC). I'm impressed at how quickly you can get something up on Drupal. Getting something the way you want it is a little harder, as is always the case with computers.

One stumbling block has been the favicon. First, it appears that the HTML that Drupal generates requires a Windows Icon file type (favicon.ico). I've used favicon.png in other sites, but in Drupal it has to be a .ico file.

Also, the directory where you put the favicon.ico is write protected, and the file manager I was using on my hosted service didn't tell me I was trying to upload a file to a write protected directory. That resulted in another 10 minutes of muttering and fooling around trying to figure out where the file was going.