Drupal Tips, Best Practices and Gotcha’s

It’s been a long time since I wrote my first blog post for CTI and I have been meaning to write more posts so thought it about time I add a new blog entry. I plan on doing a series of blog posts based on experience working on Drupal sites from 5 pages to large scale public sector sites and intranets. My first post of many on Drupal is something I see quite often on Drupal sites we have taken over from Developers who are not experienced in Drupal and is a bug bare of myne as it’s quite simple and makes life so much easier. I will often find myself re-organising the directory structure when first taken on new projects.

Drupal directory structure

This is one of the things at the top of my list when it comes to using Drupal, a well organised Drupal installation makes it easy to manage and maintain a Drupal site, this is especially the case when many people are working on the same project.

Drupal is a modular based framework and downloading modules and themes allows you to ‘bolt’ on functionality. This is great but following the following pattern will make management far easier.

A standard drupal installation will follow the below directory structure:

- Drupal
  -includes
  -misc
  -modules
  -profiles
  -scripts
  -sites
  -themes

Many newcomers to Drupal will download / create themes within the root themes folder and the same for modules copying them to the modules folder. This works, however it then becomes harder to manage updating the Drupal installation as you don’t know what are core Drupal modules / themes and which are downloaded ones.

A better approach is as below

- Drupal
  -includes
  -misc
  -modules
  -profiles
  -scripts
  -sites
    -all
      -modules
        |_contrib
        |_custom
      -themes
    -default
  -themes

Based on the above example you would place all downloaded modules from Drupal.org under ‘sites/all/modules/contrib’ , any custom modules under ‘sites/all/modules/custom’ and any downloaded / custom themes under ‘sites/all/themes’.

Using the above file structure you can easily spot the downloaded modules in use and update them, you just go to ‘sites/all/modules/contrib’, and similarly it is clearly visible where all your custom project specific modules are if you are using any.

I’ve only created one directory for themes ‘sites/all/themes’ . In general on all the sites we have worked on we only use one theme for the frontend and maybe a second admin theme (RootCandy is our favourite where CTI committed the icon patch for menu items which significantly improves the usability of the drupal admin pages) . As we only use 2 themes at most there isn’t so much of a issue of manageability issue for themes so placing all themes under ‘sites/all/themes’ should not prove problamatic.

Another important aspect of using the above directory setup is that when a new re-lease of Drupal comes out you only need to take a backup of the ‘sites’ folder and copy it across to the new Drupal installation (or extract the new version of drupal to the website root directory). This essentially means updating Drupal fixing security patches is under a minutes work.

For those of you who are using a VCS (Version Control System) such as git / svn etc it also means you only need to check the ‘sites’ directory into your repository, this is if you haven’t made changes to Drupal core in which case it may be wise committing everything to the VCS or creating patch files and committing them to the VCS.

White Screen off Death

We’ve all been there at some point when first getting started in Drupal. We’ve gone to Drupal.org spotted a set of modules which look useful, download them, install them and then get a blank (white) screen after enabling them or mainly visiting the admin pages.

Memory

This ‘white screen off death’ as it has been called can be explained in how Drupal implements it’s modular functionality. When you load a page in Drupal, Drupal goes through what is known as a bootstrap loads the enabled Drupal modules into memory to execute the end points in the module (drupal hooks). Outside of the admin pages some of these hooks are cached such as the menu callbacks, within the admin section no data is cached and this is where memory overhead is at it’s most as everything loaded. A modest Drupal installation can be using around 30-40Mb of memory per request (web page view), this will be more if you have a large number of modules installed.

This large memory usage is generally what causes a ‘white screen of death’. Generally php comes with a maximum of 12Mb memory it is allowed to use by default, this is far to small for Drupal. To fix this you need to update the ‘memory_limit’ option in your php.ini file . The location of the php.ini file will depend on the operating installed and if you are using something such as WAMP / XAMP on a development machine. When you find where your php.ini file I generally set the ‘memory_limit’ to the below:

memory_limit = 128M

This is quite alot of memory, on a Development server it’s not a problem as you often enable lots of modules and disable them, on a production server it may be appropriate for you to lower the memory limit until you get a maximum limit where the site still works. This will help stop PHP eating all available memory and causing disk thrashing (that’s another post on tweaking apache webserver for Drupal :)) .

Mod Rewrite

You often see this problem when developing a site locally and then move it on to the live servers. You have mod-rewrite enabled on your development machine for the creation of SEO friendly urls and when you move the site on to the live server non of the links work and you get shown a blank page or a ‘Server 500’ error. Generally this is because your hosts as prevented the Drupal ‘.htaccess’ file from overriding the hosts default settings, this is particularly the case on shared hosts. If you are seeing this on a local development machine it is useful adding the below to your vhosts or httpd.conf depending on your setup, if this is a problem with a shared hosts it is worth contacting the host to enable mod-rewrite for you.

# A windows example of httpd.conf overide
<Directory "c:/wamp/www/">
    Options All
    AllowOverride All
    Order Allow,Deny
    Allow from all
</Directory>
 
#A Linux example
<Directory "/var/www">
    Options All
    AllowOverride All
    Order Allow,Deny
    Allow from all
</Directory>

Note: The above examples are based on a development server, on a production machine hosting many sites the above would not be advisable and you would want to configure each vhost specifically.

The misuse of Drupal

Drupal is often thought of as a Framework, and it is. It provides a ‘Front controller’, a database api, access control functionality, a modular plugin system, it’s great. Drupal is based around the notion of nodes, content which is stored in a database (repository). I’ve seen some instances of Drupal used for it’s Framework functionality and not 1 single node, in one instance the MVC pattern was tried to be used within Drupal and parts of core where ripped out, and i’ll be honest it was horrible and I’ve no idea what possessed the original developers to do this. If you want a framework for a content based application (Open Atrium is a good example) Drupal makes sense. If you want something else and end up fighting Drupal more than working with it you may be better looking at one of the other bare bones MVC frameworks out their such as Cake, Symphony for php, Ruby on Rails or my favourite Grails built on enterprise technology (Spring, Hibernate, Sitemesh) taking full advantage of the dynamic Goovy programming language which runs on the JVM allowing full use of existing Java libraries and api’s.

There’s a module for that

This sort of relates to the above. One of the nice things about Drupal is that there is a active community and there are lots of modules available, you’ll even find they may be different modules essentially doing the same thing but in a different way. This is good, however be careful!

When you see a module, ask yourself do you really need it, can you achieve the same functionality following a ‘recipe’ so to speak which achieves the same outcome. One thing which alot of people say about Drupal is that it is slow, this often comes down to a user has found a module and slowly they then find they have a awful lot of modules installed. I’ve seen 100+ modules used on one Drupal site, when you reach 100+ modules you really need to ask yourself do you really need each and every module as this adds substantial overhead and although this may be a bit broad a generalisation each additional module is slowing you’re site down, eating up more memory doing more processing.

Again, this is something we see in a lot of sites developed by people new to Drupal, they take full use of the available modules and slowly end up with a huge amount of modules with alot which could be removed.

Another consideration with modules you have to consider is how they work with one and other. You may find a module interferes with another module. This sometimes becomes problematic when someone says ‘I found a module on drupal.org, can you install it’ and you find it doesn’t work as advertised or it introduces it’s own set of issues.

I’ve updated my theme but the changes are not showing

Another quite common one in Drupal. You are editing a theme, you make some changes and you end up hitting your head against a wall wondering why the changes are not showing. This generally comes down to that Drupal does caching in the background of certain elements even if you have caching disabled from within the admin section. This isn’t a bug in that we want theme elements and menu’s to be cached as in simple terms these are code and not content.

One way to overcome this is while developing you theme place the below in your template.php

<?php     drupal_rebuild_theme_registry(); ?>

It is important to remove this when your site goes into production otherwise each time a page is loaded it will be clearing and then re-building the theme which will slow your site down.

Another way is to install the admin menu module which provides a ‘flush all caches’ option when you hover over the drupal icon on the top left. This means if you think something should be working and it isn’t first try flushing all the caches in drupal by clicking the menu option

It looks like every other Drupal site!

Drupal and all it’s modules allow you to create a highly functional site very quickly. As Drupal becomes more popular you find more people installing the same modules / themes you have and alot of sites end up looking the same, you can even spot it being a drupal site without viewing the source code or doing any other digging such as checking for the favicon under ‘http://example.com/misc/favicon.ico’ .

Theming for Drupal is a topic which generates alot of interest and debate. As developers at CTI we like to follow the DRY principle (don’t repeat yourself), there have been many theme’s introduced and downloadable from drupal.org such as the Zen theme which attempts to give a base theme with the minimum to help reduce some of the repetition.

Using a base theme with minimal styling makes sence. However I find in practice the best looking Drupal sites are designed by a designer not knowing about Drupal, then passing this design on to a Drupal themer who converts this into a theme. This gives the best results if you want a site without knowing it’s Drupal, as a developer I think of nothing is impossible within Drupal or any other framework / language I have used so why constrain a designer to design for Drupal? There is one thing this approach fall’s down for, time. You can make Drupal look how you want and Drupal goes someway of helping you achieving this with it’s theming layer but deviate to much from a modules theme implementation the gains you got by having a rapid written site in Drupal is lost to the time needed to provide the fine grain customisation you required, at no fault to Drupal this is the case in any product.