January 19, 2008

From HTML mockup to a full Drupal site: a tutorial - Part I: Introduction and Installation

So you've mocked up your latest client's site design in Photoshop, polished it all up, and coded it in XHTML and CSS. Now what? How will your client manage all of the content on the site? You surely don't want them calling you every 5 minutes with changes, now, do you?

Well, fortunately, you don't have to be a programmer (any more) to implement a simple and easy-to-use content management system (CMS) for both your client, and yourself. It's actually quite easy, and I'll try and run you through the motions here.

Before I met Mr. Drupal a few months ago, I myself spent countless hours reinventing the proverbial wheel of content management systems many times over. My 'mantra' was that who better to decide what my clients need than myself? For that reason, I felt 'pre-built' content management systems were for those non-programming types, not me. I was wrong.

If you're still not convinced that Drupal can suit your needs, here are the main reasons that I generally choose Drupal over a custom-built CMS solution (in most cases):

User management
Security
Caching
Native error reporting and handling
Great search engine optimization (SEO) out of the box
Theming

So let's get to it. First let me start off by saying this tutorial will just cover a very basic Drupal integration for a simple site, such as a local business. Essentially, 80% of my clients just need this:

A few pages: 'Homepage', 'About Us', 'News', 'Contact' (usually a few company-specific pages, too, but they generally follow these same formats)
Excellent location-based SEO performance (ie. 'Rochester Seal Coating' [read: elitefinishes.com])
A visually appealing site that functions well
The ability to manage content as easily as possible without the consult of a technical individual

In my experience, if you've accomplished the above, you've been successful for the majority of small-businesses seeking a website.

Throughout this tutorial, I'm going to use a site that I just finished a few months ago. The site is BellaScena.com. The site as you see it there is a fully Drupal-powered site. I'll take you from the point at which the site was mocked up in XHTML / CSS and through the steps to full Drupal integration.

BeeEss has some basic features that you might see on a simple business site. These are the main components that make up the site:

Doctype declaration
Title
Some meta data
CSS stylesheets
External JavaScript files
Logo
Navigation
Content well
Footer
Google Analytics code

So that's the basic skeleton, nothing creepy in there. For our purposes here, you could think of a Drupal 'site' as two separate entities. The Drupal system itself, and a site 'theme'. Drupal themes should, in theory, be able to be used with any Drupal installation, and you should develop your theme with that in mind. That said, our XHTML / CSS mockup is done, so now we need to prep our Drupal installation before we can move forward with our theme development.

There's a couple different ways you can go about setting up a basic Drupal installation. You can use traditional means by downloading and uploading a copy of Drupal onto your server. You could also use CVS to checkout a copy of Drupal from Drupal.org onto your server. About a month ago, I wrote a blog post outlining steps to manage your Drupal installation with CVS and Subversion if you're feeling brave.

For simplicity's sake with this tutorial, I'm going to use the traditional method of downloading and uploading a copy of Drupal to the server. I'm making a few assumptions here, they are:

You've got a server somewhere where you can install your Drupal site, and it supports PHP and MySQL. If not, try 1and1, that's who I use.
You have FTP access to your server
You have a basic knowledge of XHTML and CSS
You have a basic knowledge of how PHP and MySQL databases work

Okay, so let's get started. Go to www.drupal.org and download the latest version of the Drupal software to your computer. The current version is located here, but be sure to check that there isn't a newer version available.

Now log into your server via FTP and create a folder where you'll want to extract Drupal into. Let's assume you want to install Drupal at the root of your server like so:

/drupal

Go find the Drupal copy that you just downloaded and extract it somewhere on your computer. It should extract a folder titled 'drupal-5.6' (or the version number of your copy). Within that folder lives the Drupal core codebase. Go ahead and upload the entire codeset to your '/drupal' folder that you've created on your server.

Now, I'm not sure how your host is setup, but you'll need to configure a domain or subdomain to point to your new installation. You can go ahead and do that now. 1and1 calls this a 'destination' for a domain.

Go ahead and navigate to the domain you've just setup to point to your Drupal installation. OK, real world problem. I just navigated to my directory and received the following error:

Incompatible Environment The following error must be resolved before you can continue the installation process: register_globals is enabled. Drupal requires this configuration directive to be disabled. Your site may not be secure when register_globals is enabled. The PHP manual has instructions for how to change configuration settings. (Currently using PHP 4.4.7)

I definitely wasn't expecting that, so we need to fix the error before we can proceed with installation. So a little googling reveals there's quite a few problems with 1and1's configuration setup. The normal solution to this problem would be to set 'register_globals' to 'off' with a .htaccess file. Unfortunately, 1and1 is not so forgiving with the following .htaccess file:

php_value register_globals 0

Since that doesn't work, the next best solution that I tried and was successful with on 1and1 is to set this directory and all subdirectories within it to use PHP 5 with any PHP files, rather than PHP 4. To do so, create a .htaccess file in the '/drupal' directory with the following contents:

AddType x-mapp-php5 .php

That should take care of our problem. A quick reload confirms my findings. If you've had such luck, you'll be confronted with a 'Database Configuration' page. Now is where the MySQL database comes in. Drupal is happy with either MySQL 4, or MySQL 5. For the sake of this tutorial, it won't really matter which one you use. Since 1and1 allows me to choose which version to use with a new database, I'll choose MySQL 5. Go ahead and setup a new database with your host and note the following:

Database Name Database Username Database Password Database Host (if you're on a shared server, it probably won't be 'localhost')

Since I'm on a shared server, I need to specify the hostname for my database's location. At first glance, Drupal doesn't have that field, but if you click 'Advanced options', you'll see it there. Go ahead and enter the appropriate data for your newly created database. You can usually leave the 'Database port' alone. 'Table prefix' comes in handy when you're using a single database for more than one application. Essentially, if you enter 'test' into the 'Table prefix' field, all of your tables will be prefixed with 'test_'. Once you've entered your database connection information, click 'Save configuration'.

If you've entered everything correctly, you'll be taken to a page that says 'Drupal installation complete'. Your Drupal site is now completely installed!

The very first thing you need to do is create a user. This user will be the 'super user', and there can be no other 'super users'. Thus, it's important to do this directly after you install Drupal. The 'super user' has full administration rights to do absolutely everything. Go ahead and create your username by clicking 'create the first account' in the first list item. You are assigned a default password, which you should change immediately via the form.

Before I forget, you should always download the 'settings.php' file that Drupal just modified for you. The file is located in:

/drupal/sites/default

Among other things, that file houses your database connection string. It's important to download this so that you don't overwrite the file later on with settings.php changes if you need to make them locally. It's also worth noting that Drupal will set that file's permissions to 'read only'. Thus, if you really do need to change the file, you'll have to modify the permissions before you can do so.

So now you're in your Drupal site. What next? Well that's really up to you, but you should poke around the administration pages to get a feel for things. One of the first things I do is setup "Clean URLs". Enabling Clean URLs will make all of your Drupal powered URLs look like this:

http://site.com/admin/settings/admin

instead of this:

http://site.com/?q=admin/settings/admin

There are a few pre-requisites to safely using Clean URLs, which is why it's not enabled by default. To begin the process, visit the 'Administer' page via the left-hand navigation column, and select "Clean URLs" from the 'Site Configuration' section in the right hand column of the page. You'll notice that both of the options are disabled. Well that sucks. Not really, you just need to have Drupal run some tests on your system to ensure it is safe to enable Clean URLs. To do so, click the 'Run the clean URL test' at the end of the paragraph.

Ahh! 404 error for me. That's 1and1 for you. If you've received the 404 error when you clicked on that, it's most likely because you've installed Drupal into a sub-directory onto your server. You must've not been paying attention above. Tisk, tisk. Anywho, it's a quick fix. Go back to that .htaccess file that you may or may not have created above to handle the PHP 5 switch, and add the following lines to that file:

<IfModule mod_rewrite.c> RewriteEngine on RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.*)$ index.php?q=$1 [L,QSA] </IfModule>

Okay okay, backup a bit. Some seasoned Drupal developers may be scratching their head a bit right now. In fact, I am myself. I'm a little confused as to why our new Drupal copy didn't come with a default .htaccess file with some of the goodies above already written in for us. If anyone wants to chime in here, please do so. Long story short, the code above was pulled from my BeeEss site listed above. I'm calling it 'BeeEss' so I don't affect the SEO of the actual site, like I did when I originally posted this :). The main reason you were receiving the 404 error (if you were) is beacuse of this line:

RewriteBase /

Well, that's what the line needs to be if you've installed Drupal into a sub-directory. So for the sake of moving on, we'll assume this is all set. By all means, leave a comment if you're having trouble at this point.

K, now upload the updated .htaccess file to your Drupal root. You should be able to refresh that 'Clean URL' test page now, and it should no longer result in a 404 error. The options for enabling / disabling clean URLs should also now be usable. Go ahead and click 'Enabled', and select 'Save configuration'. Now your URLs are delicious.

Go back to the 'Administer' page. Oh snap, a big red box. Not looking good. It probably says this:

One or more problems were detected with your Drupal installation. Check the status report for more information.

Go ahead and open the status report. There are probably two 'problems' being reported. The first of which is 'Cron maintenance tasks', and the second 'File system'. For the 'Cron maintenance tasks', you can safely ignore that for now, but go ahead and click 'run cron manually' to make it disappear temporarily. It's not important at this point, but maybe I'll get into it a bit later.

The other error is because the directory '/drupal/files' doesn't exist. That directory is used for files created by the Drupal system, such as theme specific files, user uploaded files, etc. A quick click on 'file system settings page' will actually generate the directory for you. That was easy. I wish all error resolution was that easy.

So we've finished our installation and basic setup of our barebones Drupal site. The next part in this series is titled "Site Setup, Content and Modules" and will focus on building our actual site with content, content types, structure and modules. After that, I'll run you through the motions of theming the entire site with my BeeEss site mockup.

If there's anything else you'd like me to touch on in the next two parts of this series, shoot me an e-mail or leave a comment on this post. Thanks!

Continue on to the second part: Part II: Site Setup, Content and Modules.