You are on page 1of 459

3 Aug 2007 Drupal Handbook

Table of Contents
Installation and configuration . . . . . . . . . . . . . . . 1
System requirements . . . . . . . . . . . . . . . . . 2
Client System Requirements . . . . . . . . . . . . . . 3
Javascript . . . . . . . . . . . . . . . . . . 3
CSS . . . . . . . . . . . . . . . . . . . . 4
RSS . . . . . . . . . . . . . . . . . . . . 4
Browser Specifics . . . . . . . . . . . . . . . . 4
Browser Popularity . . . . . . . . . . . . . . . . 4
Known Problems . . . . . . . . . . . . . . . . 4
Validation . . . . . . . . . . . . . . . . . . 4
Caveats . . . . . . . . . . . . . . . . . . . 4
HOWTO: Server requirement recommendations for your consulting clients . . . 5
Message to the Client . . . . . . . . . . . . . . . 5
Benchmark . . . . . . . . . . . . . . . . . . 6
What Drupal.org runs on . . . . . . . . . . . . . . 6
Requirements - older versions . . . . . . . . . . . . . . 6
Installing Drupal, modules and themes . . . . . . . . . . . . 8
Installing Drupal . . . . . . . . . . . . . . . . . 8
Formatted Drupal 5.x Installation instructions for better readability . . . . 13
Installation . . . . . . . . . . . . . . . . . 13
Changes . . . . . . . . . . . . . . . . . . 14
Requirements . . . . . . . . . . . . . . . . . 14
Optional Requirements . . . . . . . . . . . . . . 14
Installation . . . . . . . . . . . . . . . . . 14
Drupal Administration . . . . . . . . . . . . . . 16
Customizing your theme(s) . . . . . . . . . . . . . 16
Multi-site configuration . . . . . . . . . . . . . . 16
More Information . . . . . . . . . . . . . . . . 17
Formatted Drupal 4.7.x Installation instructions for better readability . . . . 17
Installation . . . . . . . . . . . . . . . . . 17
REQUIREMENTS . . . . . . . . . . . . . . . . 18
SERVER CONFIGURATION . . . . . . . . . . . . . . 18
OPTIONAL COMPONENTS . . . . . . . . . . . . . . 18
INSTALLATION . . . . . . . . . . . . . . . . 19
1. DOWNLOAD DRUPAL . . . . . . . . . . . . . . 19
2. CREATE THE DRUPAL DATABASE . . . . . . . . . . 19
3. LOAD THE DRUPAL DATABASE SCHEME . . . . . . . . . 20
4. CONNECTING DRUPAL . . . . . . . . . . . . . 20
5. CONFIGURE DRUPAL . . . . . . . . . . . . . . 21
6. CRON TASKS . . . . . . . . . . . . . . . . 22
DRUPAL ADMINISTRATION . . . . . . . . . . . . . 22
CUSTOMIZING YOUR THEME(S) . . . . . . . . . . . . 22
UPGRADING . . . . . . . . . . . . . . . . . 23
MORE INFORMATION . . . . . . . . . . . . . . . 23

i
Drupal Handbook 3 Aug 2007

10 minute install using PuTTY SSH/Telnet client . . . . . . . . . 23
.
How I installed Drupal: The Eightfold Way . . . . . . . . . . 24
.
Installing virtual hosts for Drupal sites and subsites . . . . . . . . 25
.
Mac OS X-specific guidelines . . . . . . . . . . . . . . 26
.
Important notes for MySQL install: . . . . . . . . . . . . 27
.
HOWTO: Create a local server environment for drupal using MAMP . . . . 28
.
HOWTO: Installing PostgreSQL and MySQL on the same Mac OS X machine . . 29
.
Installing Drupal on Mac OS X 10.4 Tiger . . . . . . . . . . 30
.
Installing and Configuring MySQL . . . . . . . . . . . 30
.
Sending mail . . . . . . . . . . . . . . . . . 32
.
Creating the Drupal Database and Database User . . . . . . . . 32
.
Installing using CVS repository . . . . . . . . . . . . 33
.
Prefixed database.mysql for search and replace . . . . . . . . . . 36
.
Setup Drupal on Windows XP Pro using IIS . . . . . . . . . . 51
.
Basic /sites directory setup . . . . . . . . . . . . . . 52
.
Special cases . . . . . . . . . . . . . . . . . . 53
.
Compilation failed: this version of PCRE is not compiled with PCRE_UTF8 support 53
.
Configure .htaccess to allow awstats to work with clean URL’s . . . . . 54
.
Configuring .htaccess to ignore specific subfolders . . . . . . . . 55
.
Ignoring Subfolders that exist in the DocumentRoot . . . . . . . 55
.
Ignoring subfolders that are included via Apache Alias directives . . . . 55
.
Create a custom php.ini . . . . . . . . . . . . . . . 56
.
How to create a custom php.ini file when nothing else works . . . . . 60
.
1. Get and modify your custom php.ini file . . . . . . . . . 60
.
2. Creating your CGI script . . . . . . . . . . . . . 60
.
3. Modifying your .htaccess file . . . . . . . . . . . . 61
.
4. Test your site . . . . . . . . . . . . . . . . 61
.
Create Drupal database using Plesk . . . . . . . . . . . . 61
.
Drupal with safe mode enabled and open basedir . . . . . . . . 62
.
Generic Mass SQL Import into Drupal . . . . . . . . . . . 65
.
DrupalCon site . . . . . . . . . . . . . . . . 67
.
How to degrade your Drupal db from MySQL 4.1.X/5.0.X to MySQL 4.0.X . . 67
.
How-To: Virtual Hosting with Drupal . . . . . . . . . . . 68
.
Introduction . . . . . . . . . . . . . . . . . 68
.
Environment . . . . . . . . . . . . . . . . . 68
.
Requirements . . . . . . . . . . . . . . . . . 69
.
Next pages . . . . . . . . . . . . . . . . . 69
.
How-To: Virtual Hosting with Drupal :: Prepare environment . . . . . 69
.
Introduction . . . . . . . . . . . . . . . . . 69
.
The drupal group . . . . . . . . . . . . . . . . 70
.
The temp directory . . . . . . . . . . . . . . . 70
.
The reference location . . . . . . . . . . . . . . . 70
.
Navigation . . . . . . . . . . . . . . . . . 70
.
How-To: Virtual Hosting with Drupal :: Solution Overview . . . . . 71
.
Introduction . . . . . . . . . . . . . . . . . 71
.
Safe mode . . . . . . . . . . . . . . . . . 71
.
Open Basedir . . . . . . . . . . . . . . . . . 71
.

ii
3 Aug 2007 Drupal Handbook

Plesk integration . . . . . . . . . . . . . . . . 72
.
Managed application . . . . . . . . . . . . . . . 72
.
eAccelerator . . . . . . . . . . . . . . . . . 72
.
Each individual vhost requirements . . . . . . . . . . . 73
.
Navigation . . . . . . . . . . . . . . . . . 73
.
HOWTO: copy a site to a local computer using XAMPP . . . . . . . 73
.
HOWTO: Copy site to another directory for testing . . . . . . . . 74
.
HOWTO: Install Drupal 5.x using cPanel . . . . . . . . . . 75
.
HOWTO: Install Drupal using cPanel . . . . . . . . . . . 77
.
HOWTO: Site to site transfer with phpMyAdmin and a FTP Client . . . . 80
.
Import a MySQL data dump with BigDump . . . . . . . . . . 82
.
What is BigDump? . . . . . . . . . . . . . . . 82
.
Setting up BigDump . . . . . . . . . . . . . . . 83
.
Uploading the sql file and bigdump.php to the webserver . . . . . . 83
.
Running BigDump . . . . . . . . . . . . . . . 84
.
Installing Drupal behind an Actiontec GT701-WG router . . . . . . . 84
.
Installing Drupal in a subdirectory in 4.6 . . . . . . . . . . . 85
.
More than one Drupal site on one machine . . . . . . . . . . 85
.
General rules for multiple Drupal deployments . . . . . . . . 86
.
Moving your Drupal installation to a new directory . . . . . . . . 86
.
PCRE_UTF8 solution for VPS servers | FreeBSD . . . . . . . . . 87
.
Known causes of PCRE server errors . . . . . . . . . . . 88
.
Redirecting specific pages to new URLs (301 redirects in Drupal) . . . . . 88
.
How to create 301 redirects in Drupal Apache mod_rewrite . . . . . 89
.
The tolerant base URL . . . . . . . . . . . . . . . 89
.
Using .htaccess to stop page caching . . . . . . . . . . . . 90
.
Linux specific guidelines . . . . . . . . . . . . . . . 90
.
Installing PHP, MySQL and Apache under Linux . . . . . . . . 90
.
XAMPP for Linux Packages . . . . . . . . . . . . . . 91
.
Installing XAMPP in Debian . . . . . . . . . . . . . 91
.
Download XAMPP Latest version from the following link . . . . . . 91
.
Start XAMPP Server . . . . . . . . . . . . . . . 91
.
Windows-specific guidelines . . . . . . . . . . . . . . 94
.
How to install Drupal for newbies using FTP and phpMyAdmin . . . . . 95
.
Change "/tmp" on your drupal site. . . . . . . . . . . . 95
.
Get Drupal ready . . . . . . . . . . . . . . . . 95
.
Upload the database . . . . . . . . . . . . . . . 96
.
HOWTO: Create an apache sandbox using Windows and Apache2Triad . . . 96
.
Before you begin . . . . . . . . . . . . . . . . 97
.
Installing Apache2Triad . . . . . . . . . . . . . . 97
.
Installing Drupal . . . . . . . . . . . . . . . . 98
.
Importing and exporting Drupal databases updated with PHPMyAdmin . . 100
.
To export a database with PHPMyAdmin . . . . . . . . . . 100
.
To import a database with PHPMyAdmin . . . . . . . . . . 101
.
Using bigdump.php to deal with large databases . . . . . . . . 102
.
Installing Apache (with PHP) on Windows . . . . . . . . . . 102
.
Installing MySQL on Windows . . . . . . . . . . . . . 104
.

iii
Drupal Handbook 3 Aug 2007

Installing PHP4 on Windows . . . . . . . . . . . . . 105
.
Drupal 4.7 on Windows/IIS Requires PHP in ISAPI mode . . . . . . 105
.
Installing PostgreSQL on Windows . . . . . . . . . . . . 105
.
Multiple Drupal Sites under Windows . . . . . . . . . . . 106
.
Running multiple sites on a local PC (localhost) from a single codebase, using Windows
106
Untar . . . . . . . . . . . . . . . . . . . 108
.
Installing Drupal on Windows . . . . . . . . . . . . . 109
.
PostgreSQL specific guidelines . . . . . . . . . . . . . 109
.
ERROR: DB connect failed . . . . . . . . . . . . . . . 109
.
ERROR: language "plpgsql" does not exist . . . . . . . . . . 110
.
ERROR: null value in column "uid" violates not-null constraint . . . . . 110
.
PostgreSQL support in Drupal 4.7.x . . . . . . . . . . . . 110
.
Drupal 4.5 and PGSQL 8 configuration . . . . . . . . . . . 110
.
Installing contributed modules . . . . . . . . . . . . . . 111
.
HOWTO: Install glossary module . . . . . . . . . . . . . 113
.
Where is the Glossary? . . . . . . . . . . . . . . . 113
.
What is the purpose of the Glossary Module, and what does it do? . . . . 113
.
Installing the Glossary Module . . . . . . . . . . . . . 114
.
Configuring the Glossary . . . . . . . . . . . . . . 114
.
Adding Full Page Definitions . . . . . . . . . . . . . 115
.
Adding Glossary To Menus . . . . . . . . . . . . . . 115
.
Leech - automating content addition . . . . . . . . . . . . 116
.
Relationships between modules . . . . . . . . . . . . . 116
.
Installing new modules (Drupal 4.6 or older) . . . . . . . . . . 117
.
Multi-site installation and set-up . . . . . . . . . . . . . . 118
.
10 Minute Multisite Install & Configuration . . . . . . . . . . 119
.
Access all multisites with www. only [.htaccess] . . . . . . . . . 121
.
Drupal as a library . . . . . . . . . . . . . . . . 121
.
Multi-site setup in 5.x using CPanel . . . . . . . . . . . . 123
.
Multi-Site, Single Codebase, Shared Database, Shared Sign-on 4.6 . . . . . 124
.
Apache (http) Configuration . . . . . . . . . . . . . 124
.
Download and Placement . . . . . . . . . . . . . . 124
.
SQL Setup . . . . . . . . . . . . . . . . . . 125
.
Individual Site Configuration & Theming . . . . . . . . . . 126
.
Some things which can be improved: . . . . . . . . . . . 127
.
Multi-Site, Single Codebase, Shared Database, Shared Sign-on 5.x . . . . . 127
.
1. Prepare database and database user . . . . . . . . . . . 128
.
1.1. create a database and user . . . . . . . . . . . . . 128
.
2. create and modify site configuration . . . . . . . . . . . 128
.
2.1. duplicate settings folder . . . . . . . . . . . . . . 128
.
2.2. Modify config files . . . . . . . . . . . . . . . 128
.
2.2.1. provide DB connection detail . . . . . . . . . . . . 128
.
2.2.2. set prefixes for table names . . . . . . . . . . . . 128
.
3. create static links . . . . . . . . . . . . . . . . 129
.
4. install drupal . . . . . . . . . . . . . . . . . 130
.
Multiple domains or vhosts using different databases . . . . . . . . 130
.
Sharing Drupal tables between databases using MySQL5 Views . . . . . 131
.

iv
3 Aug 2007 Drupal Handbook

Multiple domains using the same database . . . . . . . . . . . 132
.
Same codebase, completely different content and users . . . . . . . . 132
.
Setup of /sites directory for multi-site . . . . . . . . . . . . 135
.
Installing new themes . . . . . . . . . . . . . . . . 137
.
Basic site configuration . . . . . . . . . . . . . . . . 139
.
Settings . . . . . . . . . . . . . . . . . . . . 139
.
General settings . . . . . . . . . . . . . . . . . 140
.
Default front page . . . . . . . . . . . . . . . . . 140
.
Examples . . . . . . . . . . . . . . . . . . 141
.
Clean URLs . . . . . . . . . . . . . . . . . . 141
.
.htaccess for clean urls on specific shared hosts . . . . . . . . . 143
.
403 Permission denied error . . . . . . . . . . . . . . 146
.
A mod_rewrite bug causing occasional corruption of the query string . . . . 147
.
Apache 2 configuration of clean URLs on Debian . . . . . . . . . 147
.
Apache 2 on Ubuntu . . . . . . . . . . . . . . . 149
.
Editing apache2.conf . . . . . . . . . . . . . . . 149
.
Editing apache2/sites-available . . . . . . . . . . . . 150
.
Clean URL Support in Abyss . . . . . . . . . . . . . 151
.
Clean URL support in XAMPP . . . . . . . . . . . . . 153
.
Clean URLs in Mac OS X Server . . . . . . . . . . . . . 153
.
Clean URLs with different webservers . . . . . . . . . . . 154
.
Microsoft Internet Services Server . . . . . . . . . . . . 154
.
Lighttpd . . . . . . . . . . . . . . . . . . 154
.
Clean URLs with Easyphp. . . . . . . . . . . . . . . 154
.
Example Clean URL configuration of httpd.conf for performance . . . . . 155
.
Existing URLs for server overwrite Drupal paths . . . . . . . . . 156
.
IIS CleanURLs using some of the available ISAPI filters. . . . . . . . 156
.
Translating Apache’s rewrite rules . . . . . . . . . . . 156
.
Pathauto and Localizer . . . . . . . . . . . . . . . 157
.
Setting up clean URLs above web document root on virtual private servers . . 158
.
reboot vps after making change . . . . . . . . . . . . 159
.
Using Clean URLs with IIS . . . . . . . . . . . . . . 159
.
Alternate method . . . . . . . . . . . . . . . . 160
.
set your sites 403 and 404 Error pages . . . . . . . . . . . . 160
.
Configure your sites error reporting . . . . . . . . . . . . 161
.
Cache support . . . . . . . . . . . . . . . . . 161
.
Primary and secondary links . . . . . . . . . . . . . . 161
.
General Information: . . . . . . . . . . . . . . . 161
.
Setting Up Your Primary and Secondary Links: . . . . . . . . . 162
.
Theming Your Link Menus . . . . . . . . . . . . . . 162
.
Set length of trimmed posts and # of posts on front page . . . . . . . 162
.
URL Alias Optimization . . . . . . . . . . . . . . . 162
.
File system settings . . . . . . . . . . . . . . . . 163
.
Download method . . . . . . . . . . . . . . . . 163
.
Path settings . . . . . . . . . . . . . . . . . 164
.
Date and time settings . . . . . . . . . . . . . . . . 164
.
Customizing the interface . . . . . . . . . . . . . . . 164
.

v
Drupal Handbook 3 Aug 2007

Customizing user login . . . . . . . . . . . . . . . . 165
.
Beginner’s guide for Cron on a shared hosting provider . . . . . . . . 166
.
Check your filters . . . . . . . . . . . . . . . . . 167
.
Configure user registration . . . . . . . . . . . . . . . 168
.
Creating a menu structure . . . . . . . . . . . . . . . 168
.
Creating a menu . . . . . . . . . . . . . . . . . 169
.
Simplifying the workflow . . . . . . . . . . . . . . . 169
.
Helping search engines and robots.txt . . . . . . . . . . . . 169
.
Controlling what gets indexed -- the robots.txt file . . . . . . . . . 170
.
Add ’Disallow: /node/’ if your setup has aliases for all nodes . . . . . 171
.
Selective Bot Crawling . . . . . . . . . . . . . . . 171
.
Increase upload size in your php.ini . . . . . . . . . . . . . 175
.
Need images etc? - check Filtered HTML . . . . . . . . . . . . 176
.
Set default content options - Stop automatic promotion to the front page . . . . 177
.
Show/hide ’Submitted by’ on posts . . . . . . . . . . . . . 178
.
Blocks . . . . . . . . . . . . . . . . . . . . 178
.
Block configuration . . . . . . . . . . . . . . . . 178
.
Restricting blocks to certain pages . . . . . . . . . . . . 179
.
Preventing a block from appearing in Drupal 4.5 . . . . . . . . . 180
.
Custom blocks . . . . . . . . . . . . . . . . . 182
.
Increase memory in your php.ini . . . . . . . . . . . . . . 182
.
Database table prefix (and sharing tables across instances) . . . . . . . 183
.
Share tables across instances . . . . . . . . . . . . . . 184
.
Setup tip for Drupal 5 . . . . . . . . . . . . . . . 185
.
Using schema prefixes with PostgreSQL . . . . . . . . . . . 185
.
Define shared variables for all sites . . . . . . . . . . . . 187
.
Drupal Cookbook (for New Drupallers) . . . . . . . . . . . . 189
.
Purpose . . . . . . . . . . . . . . . . . . . . 189
.
Background . . . . . . . . . . . . . . . . . . . 189
.
Myths . . . . . . . . . . . . . . . . . . . . 189
.
Using the Drupal Web Site . . . . . . . . . . . . . . . 190
.
Typing Convention . . . . . . . . . . . . . . . . . 190
.
Some Preliminary Advice . . . . . . . . . . . . . . . 190
.
Drupal Is Supposed to be Easy? . . . . . . . . . . . . . . 191
.
A. Getting Started . . . . . . . . . . . . . . . . . 192
.
B. Basic Configuration . . . . . . . . . . . . . . . . 193
.
C. Creating Multiple Sites On Your Local Computer . . . . . . . . . 194
.
D. Error Pages . . . . . . . . . . . . . . . . . . 197
.
Page Not Found . . . . . . . . . . . . . . . . . 197
.
Access Denied . . . . . . . . . . . . . . . . . 197
.
E. Accessing Your Test Site(s) . . . . . . . . . . . . . . 198
.
F. Adding Modules and Themes . . . . . . . . . . . . . . 198
.
Installation . . . . . . . . . . . . . . . . . . 199
.
Modules . . . . . . . . . . . . . . . . . . . 199
.
Modules . . . . . . . . . . . . . . . . . . 199
.
This Site . . . . . . . . . . . . . . . . . . 200
.
Themes . . . . . . . . . . . . . . . . . . . 200
.

vi
3 Aug 2007 Drupal Handbook

Themes . . . . . . . . . . . . . . . . . . . 200
.
Logo and Favorite Icon . . . . . . . . . . . . . . . 200
.
G. Creating Content . . . . . . . . . . . . . . . . . 201
.
Content Types . . . . . . . . . . . . . . . . . 202
.
Page . . . . . . . . . . . . . . . . . . . . 202
.
Story . . . . . . . . . . . . . . . . . . . . 202
.
Book Page . . . . . . . . . . . . . . . . . . 202
.
Blog Entry . . . . . . . . . . . . . . . . . . 203
.
G1. Creating a Page . . . . . . . . . . . . . . . . 203
.
G2. Creating a Story . . . . . . . . . . . . . . . . 204
.
What’s a Teaser? . . . . . . . . . . . . . . . . 204
.
G3. Creating a Book Page . . . . . . . . . . . . . . . 205
.
G4. Creating a Blog entry . . . . . . . . . . . . . . . 205
.
H. Custom Blocks . . . . . . . . . . . . . . . . . 206
.
Address . . . . . . . . . . . . . . . . . . . 206
.
Last Updated . . . . . . . . . . . . . . . . . . 206
.
I. Working with the Menu . . . . . . . . . . . . . . . 207
.
Introduction . . . . . . . . . . . . . . . . . . 207
.
How To Menu . . . . . . . . . . . . . . . . . 207
.
Textual Menu . . . . . . . . . . . . . . . . . . 208
.
Tabbed Menu . . . . . . . . . . . . . . . . . . 208
.
Books . . . . . . . . . . . . . . . . . . . . 208
.
More . . . . . . . . . . . . . . . . . . . . 209
.
I2. The Contact Form . . . . . . . . . . . . . . . . 209
.
Set Up . . . . . . . . . . . . . . . . . . . 209
.
Make It Accessible . . . . . . . . . . . . . . . . 209
.
Add "Contact" to the Menu . . . . . . . . . . . . . . 210
.
Using It In Content . . . . . . . . . . . . . . . . 210
.
J. URL Aliases . . . . . . . . . . . . . . . . . . 210
.
K. Moving Entire Drupal Site with Databases . . . . . . . . . . . 211
.
Backup Process with phpMyAdmin . . . . . . . . . . . . 213
.
Backup Process with phpMyAdmin . . . . . . . . . . . . . 213
.
L. Moving Stuff to Your Web Site . . . . . . . . . . . . . 216
.
M. Setting Up Cron . . . . . . . . . . . . . . . . . 216
.
N. Categories (Taxonomy) . . . . . . . . . . . . . . . 217
.
O. Common Problems . . . . . . . . . . . . . . . . 219
.
P. Links and IMG . . . . . . . . . . . . . . . . . 219
.
Q. Additional Tips and Tricks . . . . . . . . . . . . . . 220
.
Q1. Tracking Module Status . . . . . . . . . . . . . . 220
.
Q2. Making Multiple Site Maintenance a Bit Easier . . . . . . . . . 220
.
Q3. Controlling User Log In . . . . . . . . . . . . . . 221
.
How do I disable "Create New Account?" . . . . . . . . . . 221
.
How do I disable User Log In entirely, and how would I get in if I do? . . . 221
.
R. Keeping Your Local and Remote Sites Synchronized . . . . . . . . 222
.
S. More Reading . . . . . . . . . . . . . . . . . . 222
.
T. Glossary . . . . . . . . . . . . . . . . . . . 223
.
Taking your site live . . . . . . . . . . . . . . . . . 226
.

vii
Drupal Handbook 3 Aug 2007

Moving from a temporary location . . . . . . . . . . . . . 226
.
Moving Drupal . . . . . . . . . . . . . . . . . . 226
.
Redirecting your server . . . . . . . . . . . . . . . . 226
.
Excluding paths from Drupal . . . . . . . . . . . . . . 227
.
Core modules . . . . . . . . . . . . . . . . . . . 228
.
Aggregator: publishing syndicated content . . . . . . . . . . . 228
.
Old page . . . . . . . . . . . . . . . . . . . 229
.
Open aggregator links in new browser window . . . . . . . . . 229
.
User Aggregator:user submitted feeds . . . . . . . . . . . . 229
.
What do I need to subscribe to a feed? . . . . . . . . . . . . 230
.
Configuring news feeds . . . . . . . . . . . . . . . 230
.
Filter feeds by keyword, time, by summary . . . . . . . . . . 231
.
Creating categories in the aggregator . . . . . . . . . . . . 231
.
Tagging individual items in the aggregator . . . . . . . . . . . 231
.
Using the news aggregator . . . . . . . . . . . . . . 231
.
RSS feed blocks . . . . . . . . . . . . . . . . . 232
.
Block: controlling content in the sidebars . . . . . . . . . . . . 232
.
Module blocks . . . . . . . . . . . . . . . . . 232
.
Administrator defined blocks . . . . . . . . . . . . . . 233
.
Blog: a blog for every user . . . . . . . . . . . . . . . 233
.
HOWTO: Configure user blogs . . . . . . . . . . . . . 233
.
Most recent blog post block . . . . . . . . . . . . . . 234
.
Navigate throught categories inside a blog . . . . . . . . . . . 234
.
What is a blog or weblog? . . . . . . . . . . . . . . . 234
.
Making user blogs more accessible . . . . . . . . . . . . . 235
.
Additional features . . . . . . . . . . . . . . . . 235
.
BlogApi: post from blog tools . . . . . . . . . . . . . . 236
.
Book: structured document publishing . . . . . . . . . . . . 236
.
Customising the book navigation menu . . . . . . . . . . . 237
.
Maintaining a FAQ using a collaborative book . . . . . . . . . . 238
.
Categories (taxonomy): A way to organize your content . . . . . . . . 239
.
Modules that do more with categories . . . . . . . . . . . . 242
.
Content Management System comparison focused on Taxonomy . . . . . 244
.
Taxonomy - some guidelines for effective design of taxonomies . . . . . . 244
.
Taxonomy Garden: Managing Categories . . . . . . . . . . . 246
.
Taxonomy Garden: Navigation by category . . . . . . . . . . 247
.
Taxonomy Garden: Organize content by category . . . . . . . . . 254
.
The taxonomy module for Drupal 4.x . . . . . . . . . . . . 260
.
Understanding categories for new users . . . . . . . . . . . 261
.
Using taxonomy to organize content . . . . . . . . . . . . 262
.
Using vocabularies for navigation . . . . . . . . . . . . . 265
.
Vocabularies and terms . . . . . . . . . . . . . . . 266
.
Creating a vocabulary . . . . . . . . . . . . . . . 267
.
Creating terms . . . . . . . . . . . . . . . . . 267
.
Advanced taxonomies: using hierarchies . . . . . . . . . . . 268
.
More about Taxonomy . . . . . . . . . . . . . . . 268
.
Creating a Block with links belonging to certain taxonomy terms . . . . . 270
.

viii
3 Aug 2007 Drupal Handbook

Taxonomy terms on a page . . . . . . . . . . . . . . 271
.
Comment: allow comments on content . . . . . . . . . . . . 272
.
Detailed comment documentation . . . . . . . . . . . . . 272
.
User control of comment display . . . . . . . . . . . . 272
.
Additional comment configurations . . . . . . . . . . . . 273
.
Notification of new comments . . . . . . . . . . . . . 273
.
Comment moderation . . . . . . . . . . . . . . . 274
.
Moderation votes . . . . . . . . . . . . . . . . 274
.
Moderator vote/values matrix . . . . . . . . . . . . . 274
.
Creating comment thresholds . . . . . . . . . . . . . 274
.
Initial comment scores . . . . . . . . . . . . . . . 275
.
Aggregator comments . . . . . . . . . . . . . . . 275
.
Contact: a way for users to get in touch . . . . . . . . . . . . 275
.
Make your site wide contact form look prettier . . . . . . . . . . 276
.
Drupal: Drupal sites directory server . . . . . . . . . . . . . 276
.
Old page . . . . . . . . . . . . . . . . . . . 277
.
Filter: Input formats for user content . . . . . . . . . . . . . 277
.
Forum: create threaded discussions . . . . . . . . . . . . . 278
.
HOWTO: Create a forum . . . . . . . . . . . . . . . 279
.
HOWTO: Create forum containers . . . . . . . . . . . . . 279
.
Help: context-sensitive guidance . . . . . . . . . . . . . . 279
.
More about the help module . . . . . . . . . . . . . . 280
.
Legacy: remapping of old-style URLs . . . . . . . . . . . . 280
.
Locale: multi-language support . . . . . . . . . . . . . . 280
.
Adjusting your php.ini settings for importing .po files . . . . . . . . 281
.
Editing text for translation . . . . . . . . . . . . . . . 282
.
How to create Drupal site in Marathi (Devnagari) . . . . . . . . . 282
.
How to install a different language . . . . . . . . . . . . 283
.
HOWTO: Creating a customized language set to replace Drupal terminology . . 283
.
HOWTO: Use a customized language set to change Drupal text and terminology . 284
.
Note for the curious . . . . . . . . . . . . . . . . 286
.
Menu: customize site navigation . . . . . . . . . . . . . . 286
.
Using named anchors with menus . . . . . . . . . . . . . 286
.
Node: the content . . . . . . . . . . . . . . . . . 287
.
Page: post static pages . . . . . . . . . . . . . . . . 288
.
Difference between page and story . . . . . . . . . . . . . 288
.
Specify page by title . . . . . . . . . . . . . . . . 289
.
Path: readable URLs . . . . . . . . . . . . . . . . . 289
.
Mass URL aliasing . . . . . . . . . . . . . . . . 290
.
Ping: notify services of changes . . . . . . . . . . . . . . 291
.
Write a custom module to ping a set of sites . . . . . . . . . . 291
.
Poll: community voting . . . . . . . . . . . . . . . . 292
.
Profile: extending user account information . . . . . . . . . . . 293
.
Enabling user pictures (avatars) . . . . . . . . . . . . . 294
.
HOWTO: Create new profile fields . . . . . . . . . . . . . 295
.
HOWTO: Make a field part of the registration process . . . . . . . . 295
.
Form Validation in plugin . . . . . . . . . . . . . . 295
.

ix
Drupal Handbook 3 Aug 2007

HOWTO: Create a ’country’ profile field . . . . . . . . . . . 295
.
CiviCRM: Tags, Profiles, Groups, advanced community member management . . 296
.
Search: an internal site search system . . . . . . . . . . . . . 297
.
Add searching to your custom module . . . . . . . . . . . . 298
.
Statistics: tracking referrers, page hits, etc. . . . . . . . . . . . 298
.
Story: post static pages . . . . . . . . . . . . . . . . 299
.
System: cron and caching . . . . . . . . . . . . . . . 299
.
Configuring cron jobs . . . . . . . . . . . . . . . . 301
.
Configuring cron jobs on DreamHost . . . . . . . . . . . 302
.
Cron Job configuration line by line . . . . . . . . . . . . 303
.
Cronjobs without wget/lynx or curl . . . . . . . . . . . . 304
.
Configuring cron jobs on Windows . . . . . . . . . . . . 305
.
Throttle: congestion control . . . . . . . . . . . . . . . 306
.
When to use the throttle module? . . . . . . . . . . . . . 307
.
Tracker: viewing new and updated content . . . . . . . . . . . 307
.
Upload: collaborate with files . . . . . . . . . . . . . . 308
.
User: access and management settings . . . . . . . . . . . . 308
.
Access Permissions reference . . . . . . . . . . . . . . 309
.
block module . . . . . . . . . . . . . . . . . 309
.
filter module . . . . . . . . . . . . . . . . . 309
.
menu module . . . . . . . . . . . . . . . . . 309
.
node module . . . . . . . . . . . . . . . . . 309
.
path module . . . . . . . . . . . . . . . . . 310
.
user module . . . . . . . . . . . . . . . . . 310
.
system module . . . . . . . . . . . . . . . . . 310
.
Access rules (email filters) . . . . . . . . . . . . . . . 310
.
Managing access control with permissions and user roles . . . . . . . 311
.
Assigning permissions and users to roles . . . . . . . . . . 312
.
Taxonomy_access: Restrict user roles to access specific categories only . . . 312
.
Adjusting permissions after adding modules . . . . . . . . . . 312
.
User authentication . . . . . . . . . . . . . . . . 313
.
Make a Drupal site use Basic Auth/ldap instead of the normal login block . . 313
.
NTLM Authentication . . . . . . . . . . . . . . . 315
.
User preferences and profiles . . . . . . . . . . . . . . 317
.
Using distributed authentication . . . . . . . . . . . . . 317
.
Distributed authentication . . . . . . . . . . . . . . 317
.
Drupal . . . . . . . . . . . . . . . . . . . 317
.
Watchdog: monitor your site . . . . . . . . . . . . . . . 318
.
End user guide . . . . . . . . . . . . . . . . . . 319
.
Registering as a user . . . . . . . . . . . . . . . . . 319
.
Logging in . . . . . . . . . . . . . . . . . . . 320
.
Changing your account settings . . . . . . . . . . . . . . 320
.
Creating new content . . . . . . . . . . . . . . . . 321
.
A step-by-step example . . . . . . . . . . . . . . . 321
.
Controlling Teaser Location . . . . . . . . . . . . . . 323
.
How to add a page to the Handbook . . . . . . . . . . . . 324
.
Types of content . . . . . . . . . . . . . . . . . 324
.

x
3 Aug 2007 Drupal Handbook

Topics, categories and terms . . . . . . . . . . . . . . 324
.
Permissions . . . . . . . . . . . . . . . . . . 324
.
Moderation and the submission queue . . . . . . . . . . . . 325
.
Creating comments . . . . . . . . . . . . . . . . 325
.
Alternative ways to enter content . . . . . . . . . . . . . 325
.
HOWTO: Posting and editing blog entries with TextMate . . . . . . 326
.
Posting and editing content with w.bloggar . . . . . . . . . . 327
.
Posting content with mailhandler . . . . . . . . . . . . 328
.
Preparing content offline . . . . . . . . . . . . . . 328
.
Editing and deleting content . . . . . . . . . . . . . . . 328
.
Search . . . . . . . . . . . . . . . . . . . . 329
.
Beyond the basics . . . . . . . . . . . . . . . . . 330
.
Sports . . . . . . . . . . . . . . . . . . . . . 331
.
football . . . . . . . . . . . . . . . . . . . . 331
.
Best practices guidelines . . . . . . . . . . . . . . . . 332
.
Back up your Drupal site . . . . . . . . . . . . . . . 332
.
Backing up the database . . . . . . . . . . . . . . . 332
.
Backing up the core files . . . . . . . . . . . . . . . 333
.
Backing up the non-core files . . . . . . . . . . . . . . 333
.
Test your backups . . . . . . . . . . . . . . . . . 334
.
Backup and restore using bash shell scripts . . . . . . . . . . 334
.
Functional Overview . . . . . . . . . . . . . . . 334
.
Usage notes and cautions . . . . . . . . . . . . . . 334
.
Site backup script . . . . . . . . . . . . . . . . 335
.
Usage notes and warnings: . . . . . . . . . . . . . 335
.
fullsitebackup.sh . . . . . . . . . . . . . . . . 336
.
Updated fullsitebackup.sh . . . . . . . . . . . . . 338
.
Site restore script . . . . . . . . . . . . . . . . 340
.
Usage notes and warnings: . . . . . . . . . . . . . 341
.
fullsiterestore.sh . . . . . . . . . . . . . . . . 341
.
Updated fullsiterestore.sh . . . . . . . . . . . . . . 344
.
Accounts and roles . . . . . . . . . . . . . . . . . 346
.
Configuring Apache and PHP for Drupal in a Shared Environment . . . . . 347
.
Creating a Test Site workflow . . . . . . . . . . . . . . 348
.
File and directory management . . . . . . . . . . . . . . 352
.
Other Tips . . . . . . . . . . . . . . . . . . 353
.
Test Sites . . . . . . . . . . . . . . . . . . . 353
.
Version update considerations . . . . . . . . . . . . . . 353
.
Do not modify core Drupal . . . . . . . . . . . . . . . 354
.
Security . . . . . . . . . . . . . . . . . . . . 355
.
Test php before putting it in blocks . . . . . . . . . . . . . 355
.
HowTo: The Advanced user’s guide . . . . . . . . . . . . . 356
.
HowTo: enable Imagemagick for the Image module . . . . . . . . . 357
.
Tips and Tricks . . . . . . . . . . . . . . . . . . 357
.
August 2005: Upgrade, Play B-I-N-G-O!, & E-commerce . . . . . . . 357
.
UPGRADE . . . . . . . . . . . . . . . . . . 357
.
PLAY B-I-N-G-O! . . . . . . . . . . . . . . . . 358
.

xi
Drupal Handbook 3 Aug 2007

E-COMMERCE . . . . . . . . . . . . . . . . . 358
.
Commentator array . . . . . . . . . . . . . . . . 358
.
June 2005: Custom Content Types, WYSIWIG Editors, Organize Your Content & Quick
Support . . . . . . . . . . . . . . . . . . . 359
.
September 2005: Newest modules, Change any string, Remote authentication, and
tracking project issues . . . . . . . . . . . . . . . . 360
.
Get the newest modules -- fast! . . . . . . . . . . . . . 360
.
Change any string . . . . . . . . . . . . . . . . 360
.
Remote authentication . . . . . . . . . . . . . . . 360
.
Keep tabs on project issues . . . . . . . . . . . . . . 361
.
Winter 2005/2006: Tracking projects with RSS and Module Linking . . . . . 361
.
Planning a web site . . . . . . . . . . . . . . . . . 361
.
Server tuning considerations . . . . . . . . . . . . . . . 365
.
Identifying Drupal performance goals . . . . . . . . . . . . 365
.
Analysing your site’s traffic and resource consumption . . . . . . . . 365
.
Understanding and configuring your stack for performance . . . . . . 365
.
Enable default 404 handling for some file types . . . . . . . . . . 367
.
Simple Decision Tree for Drupal Enterprise Scalability . . . . . . . . 368
.
Slow contributed modules determined using the developer module . . . . . 369
.
Squid Caching . . . . . . . . . . . . . . . . . 369
.
Tools, tips, and links on optimizing mysql . . . . . . . . . . . 370
.
Tuning MySQL for Drupal . . . . . . . . . . . . . . 372
.
Tuning PHP . . . . . . . . . . . . . . . . . . 372
.
Persistent database connections . . . . . . . . . . . . . 373
.
PHP caches . . . . . . . . . . . . . . . . . . 373
.
APC : Alternative PHP Cache . . . . . . . . . . . . . 374
.
eAccelerator . . . . . . . . . . . . . . . . . 374
.
Turck MMCache . . . . . . . . . . . . . . . . 374
.
Useful article on optimizing PHP . . . . . . . . . . . . . 376
.
Tuning Drupal on OS X Tiger . . . . . . . . . . . . . . 376
.
Upgrading from previous versions . . . . . . . . . . . . . . 378
.
Introduction to upgrading . . . . . . . . . . . . . . . 378
.
Getting started: Choosing your method and preparing the site . . . . . . 378
.
Preparing the site . . . . . . . . . . . . . . . . 379
.
Do I need to upgrade my database? . . . . . . . . . . . . 379
.
Important! : Backing up the database and existing files . . . . . . . . 379
.
Backing up your site (GUI) . . . . . . . . . . . . . . 379
.
Back up your site (command line) . . . . . . . . . . . . 380
.
Create a test site first or upgrade your existing site? . . . . . . . . 381
.
Copy your live site to a test site (GUI) . . . . . . . . . . . 381
.
Copying your live site to a test site (command line) . . . . . . . . 382
.
Downloading Drupal and installing the files . . . . . . . . . . 384
.
Downloading Drupal and installing the files (GUI) . . . . . . . . 384
.
Downloading Drupal and installing the files (command line) . . . . . . 385
.
Running update.php . . . . . . . . . . . . . . . . 386
.
Optional configuration steps . . . . . . . . . . . . . . 387
.
Post-upgrade steps . . . . . . . . . . . . . . . . 388
.

xii
3 Aug 2007 Drupal Handbook

Testing Your Newly Upgraded Site . . . . . . . . . . . . 388
.
Copy your test site to a live site . . . . . . . . . . . . . 389
.
Copying your test site to your live site (command line) . . . . . . . 390
.
Copy your test site to a live site (GUI) . . . . . . . . . . . 390
.
Differences from 4.7 to 5.x . . . . . . . . . . . . . . . 391
.
Important note on upgrading from 4.7 to 5.1 . . . . . . . . . . 391
.
Important note on upgrading from 4.7 to 5.1 . . . . . . . . . . 392
.
Version specific upgrades . . . . . . . . . . . . . . . 392
.
Upgrading from Drupal 4.4 to 4.5 . . . . . . . . . . . . . 392
.
Upgrading from Drupal 4.5 to 4.6.3 . . . . . . . . . . . . 393
.
Before you Start . . . . . . . . . . . . . . . . . 394
.
Step-by-step Upgrade from Drupal 4.5 to 4.6.3 . . . . . . . . . 394
.
Finalising your upgrade . . . . . . . . . . . . . . . 396
.
Rebuilding your Drupal Search Index. . . . . . . . . . . . 396
.
Blocks . . . . . . . . . . . . . . . . . . . . 396
.
Permissions . . . . . . . . . . . . . . . . . . 396
.
Forums . . . . . . . . . . . . . . . . . . . 397
.
Images . . . . . . . . . . . . . . . . . . . 397
.
Events . . . . . . . . . . . . . . . . . . . 397
.
Upgrading from Drupal 4.6.3 to 4.6.5 . . . . . . . . . . . . 397
.
Before you Start . . . . . . . . . . . . . . . . . 398
.
Step-by-step Upgrade from Drupal 4.6.3 to 4.6.5 . . . . . . . . . 398
.
Upgrading from Drupal 4.6.4 to 4.6.5 . . . . . . . . . . . . 398
.
Before you Start . . . . . . . . . . . . . . . . . 398
.
Step-by-step Upgrade from Drupal 4.6.4 to 4.6.5 . . . . . . . . . 399
.
Differences from 4.6 to 4.7 . . . . . . . . . . . . . . . 399
.
Block visibility settings . . . . . . . . . . . . . . . 399
.
Configure options centralized . . . . . . . . . . . . . . 399
.
core module help text linked to the handbook now . . . . . . . . . 400
.
Creating context sensitive menus with primary and secondary menus . . . . 400
.
Don’t turn off contributed modules that provide an .install file . . . . . . 400
.
Module .install files . . . . . . . . . . . . . . . . 401
.
Primary/secondary links now part of the menu system . . . . . . . . 401
.
queue module removed from core . . . . . . . . . . . . . 401
.
Removal of base href statement from header . . . . . . . . . . 402
.
Some HTML Tags stripped from mission statement . . . . . . . . 403
.
XTemplate engine removed from core . . . . . . . . . . . . 403
.
Troubleshooting FAQ . . . . . . . . . . . . . . . . . 404
.
How to troubleshoot (read this first) . . . . . . . . . . . . . 404
.
Stop and think . . . . . . . . . . . . . . . . . 404
.
Read the errors . . . . . . . . . . . . . . . . . 404
.
Validate your page . . . . . . . . . . . . . . . . 405
.
Read the README . . . . . . . . . . . . . . . . 405
.
Search the right way . . . . . . . . . . . . . . . . 405
.
Identify the source of the problem . . . . . . . . . . . . . 406
.
Dump some diagnostics . . . . . . . . . . . . . . . 406
.
Ask the right questions . . . . . . . . . . . . . . . 407
.

xiii
Drupal Handbook 3 Aug 2007

Identify the module that’s giving you problems . . . . . . . . . 407
.
My admin > modules page is blank . . . . . . . . . . . . . 407
.
How do I get the User Login block back . . . . . . . . . . . . 408
.
Client does not support authentication protocol requested by server... . . . . . 408
.
Webhosting issues for new Drupal users . . . . . . . . . . . . 409
.
Brief intro to Unix file permissions . . . . . . . . . . . . . 409
.
Host-specific error messages . . . . . . . . . . . . . . 411
.
SELinux may cause mysterious permission problems . . . . . . . . 411
.
Typical webhosting setups . . . . . . . . . . . . . . 412
.
Using PHP to change files on the webserver . . . . . . . . . . 413
.
What do all those Unix commands mean? . . . . . . . . . . . 413
.
Some Unix command you’ll see mentioned: . . . . . . . . . . 413
.
Special characters: . . . . . . . . . . . . . . . . 414
.
What permissions does Drupal need? . . . . . . . . . . . . 414
.
Why is this uploading stuff so difficult? . . . . . . . . . . . 416
.
"Headers already sent" error . . . . . . . . . . . . . . . 416
.
"LOCK TABLES sequences WRITE" error . . . . . . . . . . . 417
.
"Method POST is not allowed for the URL /index.htm" error (Error 405) . . . . 417
.
"Page Not Found" error when trying to access a subdirectory . . . . . . . 418
.
Block referrer spam . . . . . . . . . . . . . . . . . 418
.
.htaccess sample list plus domain blocking . . . . . . . . . . . 419
.
Color picker doesn’t appear on theme configuration page . . . . . . . . 420
.
Drupal 4.7 Install inserts CGI-BIN in URL . . . . . . . . . . . 420
.
Duplicate entry error . . . . . . . . . . . . . . . . 421
.
E-Mail from Drupal is bouncing or not being sent . . . . . . . . . 423
.
Relay SMTP mail to external mail server using smtp.class . . . . . . . 423
.
Error 1364 upon importing database.mysql with MySQL 5.0+ . . . . . . . 424
.
Error on installation step 3: Warning: Table ’[database].access’ doesn’t exist [...] . . 425
.
Fatal error: Allowed memory size of X bytes exhausted (tried to allocate Y bytes)... . 426
.
Fatal error: Call to undefined function . . . . . . . . . . . . 426
.
Fatal error: Call to undefined function: form_*() on Drupal 4.7 . . . . . . 426
.
Fatal error: Cannot redeclare blah_function() in ../modules/blah.module . . . . 427
.
Forgotten your Drupal account password . . . . . . . . . . . 427
.
Forum overview stopped working . . . . . . . . . . . . . 428
.
The Fix . . . . . . . . . . . . . . . . . . . 428
.
FTP uploads and file permissions using Transmit . . . . . . . . . . 429
.
Help! I enabled a buggy module and now I can’t disable it! . . . . . . . 429
.
How can I adminstrate my navigation on my Drupal site? (version 4.5 or older) . . 429
.
How do I get rid of the "Welcome to your new Drupal website" on the front page? . . 431
.
How do I get the Navigation block back . . . . . . . . . . . . 432
.
How do I unset the clean URLs? . . . . . . . . . . . . . . 432
.
How to login once you have turned your site off-line for maintenance . . . . . 432
.
HOWTO: Download a fresh copy of a missing or corrupted module/image/file . . 433
.
Installation/configuration . . . . . . . . . . . . . . . 434
.
406 Error when XMLRPC is used . . . . . . . . . . . . . 434
.
Junk {head} {styles} codes as output . . . . . . . . . . . . . 434
.
Login after disabling the User login block . . . . . . . . . . . 435
.

xiv
3 Aug 2007 Drupal Handbook

Login doesn’t work or must be done twice . . . . . . . . . . . 435
.
Cookies . . . . . . . . . . . . . . . . . . . 435
.
Cache Problems . . . . . . . . . . . . . . . . . 435
.
Logging in at www on a site with no www in the baseurl . . . . . . . 436
.
Login problems on PHP 5.2 . . . . . . . . . . . . . . . 436
.
My layout collapses - content appears below left column (IE) or overflows over the right
(FF) . . . . . . . . . . . . . . . . . . . . . 436
.
The content is too wide for the space it’s been given . . . . . . . . 437
.
Validation Woes . . . . . . . . . . . . . . . . . 437
.
Mysterious 403, 404, 406 or 500 errors depending on submitted content . . . . 438
.
Permission denied in includes/file.inc . . . . . . . . . . . . 438
.
Persistent ’Welcome to Drupal’ for anonymous users . . . . . . . . . 439
.
phpinfo . . . . . . . . . . . . . . . . . . . . 440
.
Plain unstyled HTML output . . . . . . . . . . . . . . 440
.
Setting up Clean URLs . . . . . . . . . . . . . . . . 441
.
unblocking account through SQL . . . . . . . . . . . . . 442
.
Weird behaviour - module-theme name collision . . . . . . . . . . 442
.
Where is the taxonomy choice when adding content? . . . . . . . . . 442
.
Miscellaneous . . . . . . . . . . . . . . . . . . 443
.
How can I change Drupal’s character encoding? (UTF-8 and Unicode) . . . . 443
.

xv
3 Aug 2007 Drupal Handbook

Installation and configuration
Here is a guide for installing and configuring a Drupal site. This guide includes extensive
How-to’s for using all core modules and installing themes. It also includes a guide for end users,
the people who visit a Drupal site.

Note: Feel free to add handbook pages relevant to this section.

1
Drupal Handbook 3 Aug 2007

System requirements
1. A Web Server that can execute PHP scripts

2. Recommended: Apache.

Drupal will work on Apache 1.3 or Apache 2.x hosted on Unices or Windows. The
majority of Drupal development is done using Apache so there is more community
experience and testing performed. Optional: You can use the Apache extension
mod_rewrite to allow for clean urls.

Optional: IIS

Drupal core will work using IIS5 or IIS6 if PHP is configured correctly. You will need to
use a third party solution to achieve Clean URLs. In view of Microsoft’s support life
cycle it is suggested you use IIS6.
To achieve clean_url’s you will need to use a third party product.

Drupal is being developed to be web server independent but we have limited or no reports
of successful use on web servers not listed here.

3. PHP

4. Drupal 4.7 and above require PHP version 4.3.3 or higher. PHP 5.2 is a special case; only
Drupal 4.7.5 (and greater) and 5.0 (and greater) run on PHP 5.2, older Drupal versions do
not. We recommend using the latest version of PHP 4.x. or 5.x for security and future
compatibility.

PHP memory of approximately 8MB for a Drupal core installation. In reality you will
probably need to use a higher setting depending on your site and contributed modules
you are using. A good starting point is 16-24 MB.
PHP XML extension (for blogapi, drupal, and ping modules). This extension is enabled
by default in a standard PHP installation; the windows version of PHP has built-in
support for this extension.
PHP needs the following configuration directives for Drupal to work (only directives
that differ from the default php.ini-dist / php.ini-recommended):
session.save_handler: user
error_reporting set to E_ALL & ~E_NOTICE. Work is ongoing to change this to
E_ALL for Drupal 6.
In addition, we recommend the following settings:
session.cache_limiter: none
Some of these settings are contained in the default .htaccess file that ships with Drupal,
so you shouldn’t need to set them explicitly. Note, however, that setting PHP
configuration options from .htaccess only works:

with Apache (or a compatible web server),

2
3 Aug 2007 Drupal Handbook

if the .htaccess file is actually read, i.e. AllowOverride is not None,
if PHP is installed as an Apache module.
See the PHP manual for how to change configuration settings for other interfaces to
PHP.
5. A PHP-supported Database Server

6. Recommended: MySQL 4.1 or MySQL 5.0.

Drupal will work on v3.23.17 and 4.0 but it is strongly suggested you use 4.1 or 5.0 for
future compatibility with Drupal 6 which will drop support for older versions of
MySQL.
NOTE: Drupal makes use of some features not available on some inexpensive hosting
plans so please check that your host allows database accounts with the following rights:

SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE
TEMPORARY TABLES, LOCK TABLES

Note: If your system/host is running MySQL 4.1 or newer and you receive the error
"Client does not support authentication protocol requested by server", address the
problem by following the instructions provided by MySQL AB. There is a minor OS
issue with some MySQL 5+ installations primarily on Windows but affecting some
Unices as well.

PostgreSQL, version 7.3 or newer.

Note, some of the contributed modules are not as abstracted from MySQL specific code
as everyone would like. If you are familiar with PostgreSQL please file issues with
those contributed modules as you find them.

Currently MS SQL and Oracle are not supported but various efforts are underway to supply
schemas. Please see discussions in the Enterprise Group if you are interested in working on
this.

Client System Requirements
Drupal aims to conform with internet standards and deviate where necessary to comply with
popular clients that are not standards compliant.

Javascript
For the Javascript, we currently test for all required API features (DOM APIs) and based on that,
enabled or disable all JS functionality. That way, we don’t care about particular browsers, only
what they support.

3
Drupal Handbook 3 Aug 2007

CSS
For CSS, the situation is quite similar to Javascript. The only difference is that here there is a
strong difference between the standard compliant browsers and Internet Explorer. We can use
CSS2 where needed and provide IE6 workarounds if necessary.

RSS
Drupal RSS feeds should work with any RSS feed reader. (note: could use more information).

Browser Specifics
In practice, this means that IE6, FF1.0/1.5, Opera 8-9 and Safari 1.x/2.0 get the whole experience.
Konqueror should work if it’s the latest version.

Browser Popularity
The general net usage is 85% IE, 10% Ffox, 3% Safari, 2% Opera or so. For Drupal.org, it is 50%
Ffox/Moz, 30% IE, 20% other.

Known Problems
IE5 and IE5.5 will experience some layout issues. IE5.0 will not do any Javascript. We can
assume that for Firefox and Opera, the users have a high chance of running the latest version.

IE4 and NS4, we no longer care about because they are no longer maintained and they are not in
widespread use.

Validation
Drupal HTML and RSS should validate using the W3C Markup Validation Service.

Caveats
These guidelines are the guide for Drupal core, modules, and themes but are not always
completely accurate. In practice, Drupal Core is expected to follow these standards more closely
than various contributed pieces of code. If you find a problem with client compatability that
deviates from the above client support guidelines, please try to find the root of the problem and
submit an issue ideally including a patch to fix the problem.

4
3 Aug 2007 Drupal Handbook

HOWTO: Server requirement recommendations for
your consulting clients
When thinking about the server hardware for a Drupal site, there are two important questions to
ask:

1. Which modules are you going to use? Certain modules require more server power than
others, but generally speaking more modules means more server requirements.

2. How many users will you have and what will they be doing? More users means more of a
demand on the server, but especially if these users login and make comments or nodes you will
need a more powerful server.

You need to consider these two answers together. For example, you could have a highly
complex site with very few users and be able to use a shared hosting environment. You could
also use very few modules, only have one editor, use the cache, and have reasonable traffic on a
shared environment.

If your project is a more interactive environment with more users logging in and posting to the
site you will need to consider more powerful hardware. As you move out of a shared
environment there are other options available to you like using the methods described in the
handbook to Tune Your Server for optimal Drupal performance. Tuning the server may allow
you to continue using the same hardware and not upgrade, but it comes at the cost of time
which can be more expensive than simply buying new hardware.

When deciding which parts of your server to upgrade, remember that "Apache is bandwidth
limited, PHP is CPU limited, and MySQL is memory limited and disk I/O bound".

Message to the Client
It’s probably best to give the message to the client of a "recommended" installation and a level
below that in case their budget is limited and a level above that to provide for future growth
with purchasing new hardware and services.

If you are rolling out a new service (as opposed to installing Drupal in place of an existing
solution) keep an eye towards a solid upgrade path. You can purchase a single server with the
intent of upgrading as your site grows. For example, start with the web server and database on
one server that is optimized for web serving. As the site grows in popularity and you need to
handle more users you can then move the database to it’s own server separate from the web
server. If your site grows beyond a two server "web server" and "database server" configuration
then you can consider using a single web server and multiple database servers in a cluster.

5
Drupal Handbook 3 Aug 2007

Benchmark
One benchmark of a server is MBR.org which required serious intervention for optimisation at
roughly the 2m pages per month mark, on a server running Apache1.3 and MySQL 4.1 with 1GB
of memory. MySQL indexing, database memory use tweaks and abandoning MyISAM for
InnoDB brought it under control - the jury’s out on using persistent connections.

There is a need for more case studies like this to be documented on this handbook page

What Drupal.org runs on
As of April 2007 (and for a long time before that) Drupal.org has been running on a group of 3
servers. For details on those servers see Dries post about the "future" drupal.org hardware as it
was being delivered.

Requirements - older versions
1. A Web Server that can execute PHP scripts
2.
Recommended: Apache. Development is done with version 1.3.x. Successfully tested
with version 2.0.x.
Optional: IIS. Drupal is being developed with IIS compatibility in mind, and IIS5 and
IIS6 work with a correctly configured PHP setup.
3. PHP
4.
As of Drupal 4.6, the CMS requires PHP version 4.3.3+ (PHP 5 is supported for the 4.6
release). Drupal 4.2 to 4.5.2 inclusive require PHP version 4.1+. Older versions of
Drupal will run on PHP 4.0.6+. We recommend using the latest version of PHP 4.x.
PHP XML extension (for blogapi, drupal, and ping modules). This extension is enabled
by default in a standard PHP installation; the windows version of PHP has built-in
support for this extension.
PHP memory of 8MB for a Drupal core install. If you install additional contributed
modules you may need to raise your php allowed memory. Prepackaged Drupal
distributions such as CivicSpace may have higher PHP memory requirements then a
Drupal core install.

PHP needs the following configuration directives for drupal to work:
session.save_handler: user
In addition, we recommend the following settings:
session.cache_limiter: none
(We only mention directives that differ from the default php.ini-dist /
php.ini-recommended starting with PHP 4.0.6)
These settings are contained in the default .htaccess file that ships with Drupal, so you
shouldn’t need to set them explicitly. Note, however, that setting PHP configuration options
from .htaccess only works:

6
3 Aug 2007 Drupal Handbook

with Apache (or a compatible web server),
if the .htaccess file is actually read, i.e. AllowOverride is not None,
if PHP is installed as an Apache module.
See here for how to change configuration settings for other interfaces to PHP.
Using a PEAR-supported Database (see below) requires (of course) PEAR to be installed.
A PHP-supported Database Server

Recommended: MySQL, v3.23.17 or newer (for our use of INNER JOIN’s with
join_condition’s). MySQL 4 is fine.
Drupal makes use of features not available on some inexpensive hosting plans, like
LOCK TABLE
Working well since 4.7: PostgreSQL, version 7.3 or newer (7.2 will probably work too,
but you’ll get some errors when updating from 4.6). Experiences with other databases
are greatly welcome.

Note: If your system/host is running MySQL 4.1 or newer, a link in the troubleshooting
section (http://drupal.org/node/35226) points to this page, which has some helpful info on
addressing this problem with PHP 4.x and PHP5. There is a minor OS issue with some
MySQL 5+ installations primarily on Windows but affecting some *nix installs as well.

Also, xTemplate (the default theme engine for Drupal 4.6.x and previous) is reported to
have issues with PHP 5.0.5 and 5.1. Converting your themes to the phpTemplate engine
(default in 4.7) will work around this issue.

7
Drupal Handbook 3 Aug 2007

Installing Drupal, modules and themes
Installing Drupal, new modules and themes uses roughly the same process so once you are
familiar with it you can repeat as needed.

After you successfully install Drupal, you will want to perform some basic site configuration
starting with the settings menu.

Installing and configuring your site is only part of your responsibilities. You must remember to
backup, test and maintain it as well. Please stop by the Best Practices section for some important
tips on this and sign up for the security newsletter

Installing Drupal
This page is autogenerated from the current development text in CVS. See the various other
provided instructions linked in the menu on the left for additional environments.
// $Id: INSTALL.txt,v 1.39 2007/01/08 11:59:16 dries Exp $
CONTENTS OF THIS FILE
---------------------
* Changes
* Requirements
* Optional requirements
* Installation
* Drupal administration
* Customizing your theme(s)
* Multisite Configuration
* More Information
CHANGES
-------
As of Drupal 5.0 installation has been automated by an install script.
It is no
longer necessary to manually edit the "settings.php" file, and database
tables
are created automatically.
REQUIREMENTS
------------
Drupal requires a web server, PHP4 (4.3.3 or greater) or PHP5
(http://www.php.net/) and either MySQL (http://www.mysql.com/) or
PostgreSQL
(http://www.postgresql.org/). The Apache web server and MySQL database
are
recommended; other web server and database combinations such as IIS and
PostgreSQL have been tested to a lesser extent. When using MySQL,
version 4.1
or greater is recommended to assure you can safely transfer the
database.

8
3 Aug 2007 Drupal Handbook

For more detailed information about Drupal requirements, see
"Requirements"
(http://drupal.org/requirements) in the Drupal Handbook.
Guidelines for setting up a server environment with a variety of
operating
systems and in special cases are available in the Drupal handbook
(http://drupal.org/node/260)
OPTIONAL REQUIREMENTS
---------------------
- To use XML-based services such as the Blogger API, Jabber, and RSS
syndication, you will need PHP’s XML extension. This extension is
enabled by
default.
- If you want support for clean URLs, you’ll need mod_rewrite and the
ability
to use local .htaccess files.
INSTALLATION
------------
1. DOWNLOAD DRUPAL
You can obtain the latest Drupal release from http://drupal.org/.
The files
are in .tar.gz format and can be extracted using most compression
tools. On a
typical Unix command line, use:
wget http://drupal.org/files/projects/drupal-x.x.tar.gz
tar -zxvf drupal-x.x.tar.gz
This will create a new directory drupal-x.x/ containing all Drupal
files
and directories. Move the contents of that directory into a
directory within
your web server’s document root or your public HTML directory:
mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html
2. CREATE THE DRUPAL DATABASE
Drupal requires access to a database in order to be installed. Your
database
user will need sufficient privileges to run Drupal. Additional
information
about privileges, and instructions to create a database using the
command
line are available in INSTALL.mysql.txt (for MySQL) or
INSTALL.pgsql.txt
(for PostgreSQL).
To create a database using PHPMyAdmin or a web-based control panel
consult
the documentation or ask your webhost service provider.
Take note of the username, password, database name and hostname as
you

9
Drupal Handbook 3 Aug 2007

create the database. You will enter these items in the install
script.
3. RUN THE INSTALL SCRIPT
The install script will set the base URL, connect Drupal to the
database, and
create tables in the database.
To run the install script point your browser to the base url of your
website
(i.e. http://www.example.com). You will be presented with the
"Database
Configuration" page.
The install script will attempt to write-protect the settings.php
after
updating it with the information you provide in the installation
routine.
If you make manual changes to that file later, be sure to protect it
again
after making your modifications. Failure to remove write permissions
to
that file is a security risk. The default location for the
settings.php
file is at sites/default/settings.php, but it may be in another
location
if you use the multi-site setup, as explained below.
4. CONFIGURE DRUPAL
When the install script succeeds, you will be directed to the
"Welcome" page.
In "step one" click "create the first account" which will become the
main
administrator account with total control. Login as the administrator
and
complete the initial configuration steps on the "Welcome" page.
Consider creating a "files" subdirectory in your Drupal installation
directory. This subdirectory stores files such as custom logos, user
avatars,
and other media associated with your new site. The sub-directory
requires
"read and write" permission by the Drupal server process. You can
change
the name of this subdirectory at "administer > site configuration >
file
system".
5. CRON TASKS
Many Drupal modules (such as the search functionality) have periodic
tasks
that must be triggered by a cron job. To activate these tasks, call
the cron

10
3 Aug 2007 Drupal Handbook

page by visiting http://www.example.com/cron.php --this will pass
control to
the modules and the modules will decide if and what they must do.
Most systems support the crontab utility for scheduling tasks like
this. The
following example crontab line will activate the cron tasks
automatically on
the hour:
0 * * * * wget -O - -q http://www.example.com/cron.php
More information about the cron scripts are available in the admin
help pages
and in the Drupal handbook at drupal.org. Example scripts can be
found in the
scripts/ directory.
DRUPAL ADMINISTRATION
---------------------
A new installation of Drupal defaults to a very basic configuration
with only a
few active modules and minimal user access rights.
Use your administration panel to enable and configure services. For
example:
General Settings administer > site configuration > site
information
Enable Modules administer > site configuration > modules
Set User Permissions administer > users management > access control
Configure Themes administer > site building > themes
For more information on configuration options, read the instructions
which
accompany the different configuration settings and consult the various
help
pages available in the administration panel.
Community-contributed modules and themes are available at
http://drupal.org/.
CUSTOMIZING YOUR THEME(S)
-------------------------
Now that your installation is running, you will want to customize the
look of
your site. Several sample themes are included and more can be
downloaded from
drupal.org.
Simple customization of your theme can be done using only CSS. Further
changes
require understanding the phptemplate engine that is now part of
Drupal. See
http://drupal.org/handbook/customization to find out more.
MULTISITE CONFIGURATION
-----------------------

11
Drupal Handbook 3 Aug 2007

A single Drupal installation can host several Drupal-powered sites,
each with
its own individual configuration.
Additional site configurations are created in subdirectories within the
’sites’
directory. Each subdirectory must have a ’settings.php’ file which
specifies the
configuration settings. The easiest way to create additional sites is
to copy
the ’default’ directory and modify the ’settings.php’ file as
appropriate. The
new directory name is constructed from the site’s URL. The
configuration for
www.example.com could be in ’sites/example.com/settings.php’ (note that
’www.’
should be omitted if users can access your site at
http://example.com/).
Sites do not have to have a different domain. You can also use
subdomains and
subdirectories for Drupal sites. For example, example.com,
sub.example.com,
and sub.example.com/site3 can all be defined as independent Drupal
sites. The
setup for a configuration such as this would look like the following:
sites/default/settings.php
sites/example.com/settings.php
sites/sub.example.com/settings.php
sites/sub.example.com.site3/settings.php
When searching for a site configuration (for example
www.sub.example.com/site3),
Drupal will search for configuration files in the following order,
using the
first configuration it finds:
sites/www.sub.example.com.site3/settings.php
sites/sub.example.com.site3/settings.php
sites/example.com.site3/settings.php
sites/www.sub.example.com/settings.php
sites/sub.example.com/settings.php
sites/example.com/settings.php
sites/default/settings.php
If you are installing on a non-standard port, the port number is
treated as the
deepest subdomain. For example: http://www.example.com:8080/ could be
loaded
from sites/8080.www.example.com/. The port number will be removed
according to
the pattern above if no port-specific configuration is found, just like

12
3 Aug 2007 Drupal Handbook

a real
subdomain.
Each site configuration can have its own site-specific modules and
themes in
addition to those installed in the standard ’modules’and ’themes’
directories.
To use site-specific modules or themes, simply create a ’modules’ or
’themes’
directory within the site configuration directory. For example, if
sub.example.com has a custom theme and a custom module that should not
be
accessible to other sites, the setup would look like this:
sites/sub.example.com/:
settings.php
themes/custom_theme
modules/custom_module
NOTE: for more information about multiple virtual hosts or the
configuration
settings, consult the Drupal handbook at drupal.org.
MORE INFORMATION
----------------
For platform specific configuration issues and other installation and
administration assistance, please consult the Drupal handbook at
http://drupal.org/handbook. You can view the wide range of other
support options
available at http://drupal.org/support.

Formatted Drupal 5.x Installation instructions for better
readability
Installation
// $Id: INSTALL.txt,v 1.39 2007/01/08 11:59:16 dries Exp $

Table of Contents

1. Changes
2. Requirements
3. Optional requirements
4. Installation
5. Drupal administration
6. Customizing your theme(s)
7. Multisite Configuration
8. More Information

13
Drupal Handbook 3 Aug 2007

Changes
As of Drupal 5.0 installation has been automated by an install script. It is no longer necessary to
manually edit the "settings.php" file, and database tables are created automatically.

Requirements
Drupal requires a web server, PHP4 (4.3.3 or greater) or PHP5 (http://www.php.net/) and
either MySQL (http://www.mysql.com/) or PostgreSQL (http://www.postgresql.org/). The
Apache web server and MySQL database are recommended; other web server and database
combinations such as IIS and PostgreSQL have been tested to a lesser extent. When using
MySQL, version 4.1 or greater is recommended to assure you can safely transfer the database.

For more detailed information about Drupal requirements, see "Requirements"
(http://drupal.org/requirements) in the Drupal Handbook.

Guidelines for setting up a server environment with a variety of operating systems and in
special cases are available in the Drupal handbook (http://drupal.org/node/260)

Optional Requirements
- To use XML-based services such as the Blogger API, Jabber, and RSS syndication, you will need
PHP’s XML extension. This extension is enabled by default.

- If you want support for clean URLs, you’ll need mod_rewrite and the ability to use local
.htaccess files.

Installation
1. Download Drupal

You can obtain the latest Drupal release from http://drupal.org/. The files are in .tar.gz format
and can be extracted using most compression tools. On a typical Unix command line, use:

wget http://drupal.org/files/projects/drupal-x.x.tar.gz
tar -zxvf drupal-x.x.tar.gz

This will create a new directory drupal-x.x/ containing all Drupal files and directories. Move the
contents of that directory into a directory within your web server’s document root or your public
HTML directory:

mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html

2. Create the Drupal database

Drupal requires access to a database in order to be installed. Your database user will need
sufficient privileges to run Drupal. Additional information about privileges, and instructions to
create a database using the command line are available in INSTALL.mysql.txt (for MySQL) or

14
3 Aug 2007 Drupal Handbook

INSTALL.pgsql.txt (for PostgreSQL).

To create a database using PHPMyAdmin or a web-based control panel consult the
documentation or ask your webhost service provider.

Take note of the username, password, database name and hostname as you create the database.
You will enter these items in the install script.

3. Run the install script

The install script will set the base URL, connect Drupal to the database, and create tables in the
database.

To run the install script point your browser to the base url of your website (i.e.
http://www.example.com). You will be presented with the "Database Configuration" page.

The install script will attempt to write-protect the settings.php after updating it with the
information you provide in the installation routine. If you make manual changes to that file
later, be sure to protect it again after making your modifications. Failure to remove write
permissions to that file is a security risk. The default location for the settings.php file is at
sites/default/settings.php, but it may be in another location if you use the multi-site setup, as
explained below.

4. Configure Drupal

When the install script succeeds, you will be directed to the "Welcome" page. In "step one" click
"create the first account" which will become the main administrator account with total control.
Login as the administrator and complete the initial configuration steps on the "Welcome" page.

Consider creating a "files" subdirectory in your Drupal installation directory. This subdirectory
stores files such as custom logos, user avatars, and other media associated with your new site.
The sub-directory requires "read and write" permission by the Drupal server process. You can
change the name of this subdirectory at "administer > site configuration > file system".

5. Cron Tasks

Many Drupal modules (such as the search functionality) have periodic tasks that must be
triggered by a cron job. To activate these tasks, call the cron page by visiting
http://www.example.com/cron.php --this will pass control to the modules and the modules
will decide if and what they must do.

Most systems support the crontab utility for scheduling tasks like this. The following example
crontab line will activate the cron tasks automatically on the hour:

0 * * * * wget -O - -q http://www.example.com/cron.php

More information about the cron scripts are available in the admin help pages and in the Drupal
handbook at drupal.org. Example scripts can be found in the scripts/ directory.

15
Drupal Handbook 3 Aug 2007

Drupal Administration
A new installation of Drupal defaults to a very basic configuration with only aw active modules
and minimal user access rights.

Use your administration panel to enable and configure services. For example:

General Settings administer > site configuration > site information
Enable Modules administer > site configuration > modules
Set User Permissions administer > users management > access control
Configure Themes administer > site building > themes

For more information on configuration options, read the instructions which accompany the
different configuration settings and consult the various help pages available in the
administration panel.

Community-contributed modules and themes are available at http://drupal.org/.

Customizing your theme(s)
Now that your installation is running, you will want to customize the look of your site. Several
sample themes are included and more can be downloaded from drupal.org.

Simple customization of your theme can be done using only CSS. Further changes require
understanding the phptemplate engine that is now part of Drupal. See
http://drupal.org/handbook/customization to find out more.

Multi-site configuration
A single Drupal installation can host several Drupal-powered sites, each with its own individual
configuration.

Additional site configurations are created in subdirectories within the ’sites’ directory. Each
subdirectory must have a ’settings.php’ file which specifies the configuration settings. The
easiest way to create additional sites is to copy the ’default’ directory and modify the
’settings.php’ file as appropriate. The new directory name is constructed from the site’s URL.
The configuration for www.example.com could be in ’sites/example.com/settings.php’ (note
that ’www.’ should be omitted if users can access your site at http://example.com/).

Sites do not have to have a different domain. You can also use subdomains and subdirectories
for Drupal sites. For example, example.com, sub.example.com, and sub.example.com/site3 can
all be defined as independent Drupal sites. The setup for a configuration such as this would look
like the following:

sites/default/settings.php
sites/example.com/settings.php
sites/sub.example.com/settings.php
sites/sub.example.com.site3/settings.php

16
3 Aug 2007 Drupal Handbook

When searching for a site configuration (for example www.sub.example.com/site3), Drupal will
search for configuration files in the following order, using the first configuration it finds:

sites/www.sub.example.com.site3/settings.php
sites/sub.example.com.site3/settings.php
sites/example.com.site3/settings.php
sites/www.sub.example.com/settings.php
sites/sub.example.com/settings.php
sites/example.com/settings.php
sites/default/settings.php

If you are installing on a non-standard port, the port number is treated as the deepest
subdomain. For example: http://www.example.com:8080/ could be loaded from
sites/8080.www.example.com/. The port number will be removed according to the pattern
above if no port-specific configuration is found, just like a real subdomain.

Each site configuration can have its own site-specific modules and themes in addition to those
installed in the standard ’modules’and ’themes’ directories. To use site-specific modules or
themes, simply create a ’modules’ or ’themes’ directory within the site configuration directory.
For example, if sub.example.com has a custom theme and a custom module that should not be
accessible to other sites, the setup would look like this:

sites/sub.example.com/:
settings.php
themes/custom_theme
modules/custom_module

NOTE: for more information about multiple virtual hosts or the configuration settings, consult
the Drupal handbook at drupal.org.

More Information
For platform specific configuration issues and other installation and administration assistance,
please consult the Drupal handbook at http://drupal.org/handbook. You can view the wide
range of other support options available at http://drupal.org/support.

Formatted Drupal 4.7.x Installation instructions for better
readability
Installation
// $Id: INSTALL.txt,v 1.6 2004/11/27 11:28:55 dries Exp $

This document outlines the standard installation process.

17
Drupal Handbook 3 Aug 2007

1. REQUIREMENTS
2. SERVER CONFIGURATION
3. OPTIONAL COMPONENTS
4. INSTALLATION
5. DRUPAL ADMINISTRATION
6. CUSTOMIZING YOUR THEME(S)
7. UPGRADING
8. MORE INFORMATION

REQUIREMENTS
1. Drupal requires a web server, PHP4 (http://www.php.net/) and either
MySQL, PostgreSQL or a database server supported by the PHP PEAR API
(http://pear.php.net/).
2. To Install you will need an FTP program to upload files to the server, or shell access if you
wish to install using the commands listed below; access to run database scripts directly or a
tool such as PHPMyAdmin to manage a database; knowledge of how to use either FTP
programs or shell access to set permissions on directories, and how to run database scripts.
3. NOTE: The Apache web server and MySQL database are strongly recommended;
other web server and database combinations such as IIS and PostgreSQL
are possible but tested to a lesser extent.

SERVER CONFIGURATION
Your PHP must have the following settings:

session.save_handler user

In addition, we recommend the following settings:

session.cache_limiter none

These values are set in php.ini and can be overwritten in a .htaccess
file; you can print out your local PHP settings with PHP’s phpinfo()
function.

OPTIONAL COMPONENTS
To use XML-based services such as the Blogger API, Jabber, RSS
syndication, you will need PHP’s XML extension. This extension is
enabled by default in standard PHP4 installations.
If you want support for clean URLs, you’ll need mod_rewrite and
the ability to use local .htaccess files. (More information can
be found in the Drupal handbook on drupal.org.)

18
3 Aug 2007 Drupal Handbook

INSTALLATION
1. DOWNLOAD DRUPAL
You can obtain the latest Drupal release from http://drupal.org/.
Download the current tar.gz format and extract the files:

$ wget http://drupal.org/files/project/drupal-x.x.x.tgz
$ tar -zxvf drupal-x.x.x.tgz

This will create a new directory drupal-x.x.x/ containing all
Drupal files and directories. Move the contents of that directory
into a directory within your web server’s document root or your
public HTML directory:

$ mv drupal-x.x.x/* drupal-x.x.x/.htaccess /var/www/html

2. CREATE THE DRUPAL DATABASE
These instructions are for MySQL. If you are using another database,
check the database documentation. In the following examples,
"dba_user" is an example MySQL user which has the CREATE and GRANT
privileges. You will need to use the appropriate user name for your
system.

First, you must create a new database for your Drupal site:

$ mysqladmin -u dba_user -p create drupal

MySQL will prompt for the dba_user database password and then create
the initial database files. Next you must login and set the access
database rights:

$ mysql -u dba_user -p

Again, you will be asked for the dba_user database password. At the
MySQL prompt, enter following command:

GRANT ALL PRIVILEGES ON drupal.*
TO nobody@localhost IDENTIFIED BY ’password’;

where

’drupal’ is the name of your database
’nobody@localhost’ is the userid of your webserver MySQL account
’password’ is the password required to log in as the MySQL user

19
Drupal Handbook 3 Aug 2007

If successful, MySQL will reply with

Query OK, 0 rows affected

to activate the new permissions you must enter the command

flush privileges;

and then enter ’\q’ to exit MySQL.

3. LOAD THE DRUPAL DATABASE SCHEME
Once you have a database, you must load the required tables:

$ mysql -u nobody -p drupal < database/database.mysql

4. CONNECTING DRUPAL
The default configuration can be found in the
’sites/default/settings.php’ file within your Drupal installation.
Before you can run Drupal, you must set the database URL and the
base URL to the web site. Open the configuration file and edit the
$db_url line to match the database defined in the previous steps:

$db_url = "mysql://username:password@localhost/drupal";

Set $base_url to match the address to your web site:

$base_url = "http://www.example.com";

In addition, a single Drupal installation can host several
Drupal-powered sites, each with its own individual configuration.
If you don’t need to run multiple Drupal sites, you can skip to the
next section.

Additional site configurations are created in subdirectories within
the ’sites’ directory. Each site subdirectory must have a
’settings.php’ file which specifies the configuration settings. The
easiest way to create additional sites is to copy the ’default’
directory and modify the ’settings.php’ file as appropriate. The new
directory name is constructed from the site’s URL. The
configuration for www.example.com could be in
’sites/example.com/settings.php’ (note that ’www.’ should be omitted
if users can access your site at http://example.com/).

Sites do not each have to have a different domain. You can use
subdomains and subdirectories for Drupal sites also. For example,
example.com, sub.example.com, and sub.example.com/site3 can all be

20
3 Aug 2007 Drupal Handbook

defined as independent Drupal sites. The setup for a configuration
such as this would look like the following:

sites/default/settings.php
sites/example.com/settings.php
sites/sub.example.com/settings.php
sites/sub.example.com.site3/settings.php
When searching for a site configuration (for example
www.sub.example.com/site3), Drupal will search for configuration
files in the following order, using the first configuration file it
finds:
sites/www.sub.example.com.site3/settings.php
sites/sub.example.com.site3/settings.php
sites/example.com.site3/settings.php
sites/www.sub.example.com/settings.php
sites/sub.example.com/settings.php
sites/example.com/settings.php
sites/default/settings.php

Each site configuration can have its own site-specific modules and
themes that will be made available in addition to those installed
in the standard ’modules’ and ’themes’ directories. To use
site-specific modules or themes, simply create a ’modules’ or
’themes’ directory within the site configuration directory. For
example, if sub.example.dom has a custom theme and a custom module
that should not be accessible to other sites, the setup would look
like this:

sites/sub.example.com/:
settings.php
themes/:
custom_theme
modules/:
custom_module

NOTE: for more information about multiple virtual hosts or the
configuration settings, consult the Drupal handbook at drupal.org.

5. CONFIGURE DRUPAL
You can now launch your browser and point it to your Drupal site.

Create an account and login. The first account will automatically
become the main administrator account.

21
Drupal Handbook 3 Aug 2007

6. CRON TASKS
Many Drupal modules have periodic tasks that must be triggered by a
cron job. To activate these tasks, you must call the cron page;
this will pass control to the modules and the modules will decide
if and what they must do.

The following example crontab line will activate the cron script
on the hour:

0 * * * * wget -O - -q http://HOSTNAME/cron.php

More information about the cron scripts are available in the admin
help pages and in the Drupal handbook at drupal.org. Example
scripts can be found in the scripts/ directory.

DRUPAL ADMINISTRATION
Upon a new installation, your Drupal website defaults to a very basic
configuration with only a few active modules, one theme, and no user
access rights.

Use your administration panel to enable and configure services. For
example, set some general settings for your site with "Administration -
configuration". Enable modules via "Administration - configuration -
modules". User permissions can be set with "Administration - accounts
- permissions".

For more information on configuration options, read through the
instructions which accompany the different configuration settings and
consult the various help pages available in the administration panel.

Note that additional community-contributed modules and themes are
available at http://drupal.org/.

CUSTOMIZING YOUR THEME(S)
Now that your server is running, you will want to customize the look
of your site. Several sample themes are included in the Drupal
installation and more can be downloaded from drupal.org.

Customizing each theme depends on the theme. In general, each theme
contains a PHP file themename.theme which defines a function header()
that can be changed to reference your own logos.

22
3 Aug 2007 Drupal Handbook

Most themes also contain stylesheets or PHP configuration files to
tune the colors and layouts; check the themes/ directory for README
files describing each alternate theme.

UPGRADING
1. Backup your database and Drupal directory - especially your
configuration file (www.example.com.conf or includes/conf.php).
2. Log on as the user with user ID 1.
3. Remove all the old Drupal files then unpack the new Drupal files
into the directory that you run Drupal from.
4. Modify the new configuration file to make sure it has the
correct information.
5. Run update.php by visiting http://www.example.com/update.php.

MORE INFORMATION
For platform specific configuration issues and other installation and
administration assistance, please consult the Drupal handbook at
http://drupal.org/. You can also find support at the Drupal support forum or through the
Drupal mailing lists.

10 minute install using PuTTY SSH/Telnet client
I’ve been developing best practices for my development company and wanted to
share/collaborate on some of them.

Development environment:

Server: LAMP
SSH/Telenet Client: PuTTY
Server Interface: WHM
Must have root access.

10 minute Install:

[login root via PuTTY]
# cd /home/youraccountname
# wget
http://ftp.osuosl.org/pub/drupal/files/projects/drupal-x.x.tar.gz
[Note: the "x.x" should be replaced with the version of drupal you’re
installing, e.g. "5.1"]
# tar -zxvf drupal-5.1.tar.gz
# mv drupal-x.x/* drupal-x.x/.htaccess
/home/youraccountname/public_html
[Note: See the note above regarding "x.x"]

23
Drupal Handbook 3 Aug 2007

# rm drupal-x.x.tar.gz
# cd public_html
# mkdir files
# chmod 777 files
# cd sites/all
# mkdir modules
# mkdir themes
# cd modules
# mkdir custom
# mkdir drupal-contrib
# cd ../
# cd themes
# mkdir custom
# mkdir drupal-contrib
# cd ../
# cd ../
# cd default
# chmod 777 settings.php
# mysql
mysql> CREATE DATABASE youraccountname_drupal;
mysql> GRANT ALL PRIVILEGES ON youraccountname_drupal.* TO ’your
accountname_yourusername’@’localhost’ IDENTIFIED BY ’yourpassword’;
mysql> \q
[open your browser. enter your site’s URL, and enter database
information]
[go back to PuTTY to chmod on "settings.php"]
# chmod 755 settings.php
# logout
[back to browser, refresh browser, and then "visit new site" (or
whatever the link says to new website), create first "superuser"
account, etc.]

How I installed Drupal: The Eightfold Way
Try this for a supereasy install.

This installation is for a test site.

The aim is to have a test site: \http://drupal.yoursite.com\

When the test site is functioning, the drupal subdomain prefix will be deleted. Therefore the
domain name in the root will be mysite.com The DNS servers will automatically point to this
(hopefully!). This is what worked for me:

1) Downloaded Drupal 5.0
2) Created a subdomain ("drupal") via my webhost’s control panel
3) Created a database ("dbname") via my webhost’s control panel (note the user name and

24
3 Aug 2007 Drupal Handbook

password). Noted the hostname, e.g., testsite.yoursite.com
4) Using browser, pointed to URL \http://drupal.yoursite.com\
5) The install.php script automatically installed Drupal
6) Entered information. Database name ("dbname"), username, password
7) Clicked "Advanced options"
8) Entered hostname (e.g., testsite.yoursite.com). Went to testsite.yoursite.com in browser.

Installing virtual hosts for Drupal sites and subsites
The purpose of this guide is to concisely summarize how to implement apache vhost settings for
each site or subsite.

All steps for this tutorial were implemented with Debian using Apache version 2.0.54.

1. Gain entrance into your shell system, and su to root or another user that can edit apache2
configuration files.
2. Go to your apache configuration files:
cd /etc/apache2/sites-available
3. Create a configuration file for your new site. For an example site, www.example.com, we
make the site as such:
nano example.com

<VirtualHost *:80>
ServerAdmin me@myserver
DocumentRoot /home/web/drupal/
ServerName www.example.com
ServerAlias example.com *.example.com
RewriteEngine On
RewriteOptions inherit
CustomLog /var/log/apache2/example.com.log combined
</VirtualHost>
<VirtualHost *:443>
ServerAdmin me@myserver
DocumentRoot /home/web/drupal/
ServerName www.example.com
ServerAlias example.com *.example.com
RewriteEngine On
RewriteOptions inherit
CustomLog /var/log/apache2/example.com.log combined
# SSL Specific options
SSLEngine on
SSLCipherSuite
ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
SSLCertificateFile /etc/ssl/apache/CA.crt
SSLCertificateKeyFile /etc/ssl/apache/CA.key
SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown
</VirtualHost>

25
Drupal Handbook 3 Aug 2007

Activate the site’s configuration:
a2ensite www.example.com
Reload Apache’s configuration:
/etc/init.d/apache2 force-reload

Done!

Please post any changes or concerns,

Tarek : )

Mac OS X-specific guidelines
Install and configure Mysql and PHP, if necessary. Server Logistics provides nice pre-compiled
packages and instructions. PHP is also available from Marc Liyanage. PHP may already be
installed on your system, so check first.

The stock version of Apache should be fine (typically 1.33).

Turn on "personal web sharing" in the sharing panel of System Preferences to start Apache. Now
comes the more involved part- changing the webserver configuration.

To make changes to the Apache configuration you should NOT edit /etc/httpd/httpd.conf but
instead edit files in /private/etc/httpd/users/. Any file in the directory
/private/etc/httpd/users/ ending with â.confâ will effectively be appended to
/etc/httpd/httpd.conf. So any changes you want to make should be made in one or more
configuration files of your own construction. System updates will leave these files untouched.
You can create a file /private/etc/httpd/users/drupal.conf for all your Drupal-specific changes
(even if you have no user named Drupal) and they will be loaded when Apache starts up.

Note: for Mac OS X Server 10.4 (Tiger Server) and most likely previous versions as well, do not
make changes to /etc/httpd/httpd.conf expecting the AllowOverride All directive to
work. The correct file to add the AllowOverride All directive is in the directory
/etc/httpd/sites/. In that directory are the virtual host configuration files. Each virtual
server has a configuration file in that directory so it is in those files that you must enable
AllowOverride All. If you only have one web server on your server configured, then the file
you want to modify is /etc/httpd/sites/0000_any_80_.conf.

To enable clean URLs you will need the following code in your conf file. You’ll need to be root
(or sudo) to do this. Don’t forget to restart apache after modifying httpd.conf (turn personal web
sharing off, then back on again, or use /usr/sbin/apachectl restart).

#
# This controls which options the .htaccess files in directories can
# override. Can also be "All", or any combination of "Options",
"FileInfo",
# "AuthConfig", and "Limit"
#

26
3 Aug 2007 Drupal Handbook

# AllowOverride None
AllowOverride All

You may also need to edit this file to enable the PHP module for Apache. You have to
uncomment two lines. First in this section:

#
# Dynamic Shared Object (DSO) Support
#

Uncomment this line (around line 235) by removing the #:

#LoadModule php4_module libexec/httpd/libphp4.so

Then go below to this section:

# Reconstruction of the complete module list from all available
modules
# (static and shared ones) to achieve correct module execution order.

and uncomment this line (around line 278) by removing the #:

#AddModule mod_php4.c

Drupal goes into /Library/WebServer/Documents/, or ~/Sites. If you use ~/Sites, you may
also have to edit the .conf file in /etc/httpd/users that corresponds to your user account. You
must AllowOverride in this file for your ~/Sites for clean URLs to work there.

After any edits to your .conf files, be sure to restart Apache (as described above).

MacZeaolots has a good tutorial on installing Drupal on Mac OS X 10.4. The same tutorial
applies to 10.3 as well. While the tutorial talks about Drupal 4.6, the setup of the server
environment is the same for any version of Drupal.

Important notes for MySQL install:
The version of PHP that Apple included with Mac OS X 10.4.4 has mysql.default_socket set to
"/var/mysql/mysql.sock", while the binary version of MySQL from mysql.com uses
"/tmp/mysql.sock". This will cause PHP to fail to connect to mysql with a message in Drupal
like

can’t connect to local MySQL server through socket ’/var/lib/mysql/mysql.sock’ (2)

Make PHP look for "/tmp/mysql.sock" by setting this in /etc/php.ini:

; Default socket name for local MySQL connects. If empty, uses the
built-in
; MySQL defaults.
mysql.default_socket = /tmp/mysql.sock

27
Drupal Handbook 3 Aug 2007

You can instead set this in /etc/my.cnf.

#Name of the socket file to use.
socket=/var/mysql/mysql.sock

Both work, but the second one may make the MySQL preference pane stop working.

You may also need to restart apache to have this take effect.

Restart from the terminal:

$ sudo apachectl restart

or restart by disabling and re-enabling personal web sharing.

HOWTO: Create a local server environment for drupal using MAMP
MAMP creates a local server environment on Mac OS X by installing PHP, MySQL, and Apache
all at once. This will hopefully make Drupal much easier to install because the components don’t
have to be installed separately. This page is to be used in conjunction with the installation
instructions for Drupal on Mac OS X.

1. Download MAMP
(This will install Apache, MySQL, and PHP in one step.)
Find the latest version here: http://www.mamp.info/
Download and drag to Applications folder to install. Open MAMP and click "start servers," then
"Open start page."

2. Download Drupal
Find the latest Drupal release here: http://drupal.org/.

Move the directory containing the Drupal files into the MAMP htdocs directory:

mv drupal-x.x.x/* drupal-x.x.x/.htaccess /Applications/MAMP/htdocs/

3. Create the Drupal database

Go to the MAMP start page and click "phpMyAdmin." Create a new database and follow the
instructions in INSTALL.mysql.txt to upload the required files from your Drupal installation.

4. Connect Drupal
Set the database URL in the ’sites/default/settings.php’ file in your Drupal installation using the
information provided on the MAMP start page and the name you used for the database you
created in step 3.

$db_url = "mysql://username:password@localhost/databasename";

28
3 Aug 2007 Drupal Handbook

5. Start configuring Drupal!
Go to http://localhost:8888/drupal-x.x.x/ and create the first account.
Continue with instructions in INSTALL.txt.

HOWTO: Installing PostgreSQL and MySQL on the same Mac OS X
machine
If you’re interested in helping to ensure that Drupal and its contributed modules are compatible
with both MySQL and PostgreSQL (also known as "pgsql"), you should consider setting up local
test sites using both database back ends on the same machine. You can even configure both sites
to point to the same Drupal installation, using symbolic links.

Unfortunately, the version of PHP that ships with Mac OS by default is not compatible with
PostgreSQL, so to do this, you will need to compile both pgsql and php from source. While
you’re at it, you might want to upgrade to a newer version of MySQL, as well.

1. Make a directory where you can build all of these programs. For example:
mkdir /usr/local/src
cd /usr/local/src

Download the latest copies of everything you need:
PHP -- http://www.php.net/downloads.php
MySQL -- http://www.mysql.com/downloads
PostgreSQL -- http://www.postgresql.org/download
Unpackage all of these inside /usr/local/src
Configure and build MySQL. Good instructions can be found on this page: MySQL on Mac
OS X. The important thing is that when you run
configure you use a reasonable value for the --prefix flag. For example: ./configure
--prefix=/usr/local/mysql
Configure and build PostgreSQL. Once again, useful installation docs can be found here:
PostgreSQL on Mac OS X, though the section about "Postgres and PHP" isn’t what you want
to read. Again, be sure you use a reasonable value for the--prefix flag. For example:
./configure --prefix=/usr/local/pgsql
Configure and build PHP. After some trial and error, getting PHP working properly with
both MySQL and PostgreSQL required a carefully crafted configure line:
./configure --with-pgsql=/usr/local/pgsql
--with-mysql=/usr/local/mysql --with-apxs --with-kerberos=/usr
--with-zlib-dir=/usr --enable-cli --enable-trans-sid --with-xml
--enable-exif --enable-ftp --enable-mbstring --enable-mbregex
--enable-dbx --enable-sockets --with-iodbc=/usr --with-curl=/usr
--with-config-file-path=/etc --sysconfdir=/private/etc
--with-mysql-sock=/var/mysql/mysql.sock
Some noteworthy things about this command:

This matches the flags used for the default PHP installed on Mac OS X as closely as
possible, while also enabling PostgreSQL support.

29
Drupal Handbook 3 Aug 2007

The path you use for --with-pgsql must match whatever you specified for
--prefix when building PostgreSQL.
The path you use for --with-mysql must match whatever you specified for
--prefix when building MySQL.
The path you use for --with-mysql-sock should match whatever you specified for
--with-unix-socket-path when building MySQL.

Additional information about building PHP on Mac OS X machines can be found on the
developer.apple.com site: PHP on Mac OS X

Installing Drupal on Mac OS X 10.4 Tiger
Mac OS X 10.4 Tiger comes with PHP (though it’s disabled by default) and without MySQL.
Here’s how to get Drupal up and running from a stock Tiger installation.

Installing and Configuring MySQL

Downloaded the latest MySQL installer from dev.mysql.com. I chose the Mac OS X Installer
Package for 10.3.

I double-clicked the file that I downloaded
(mysql-standard-4.1.11-apple-darwin7.8.0-powerpc.dmg), then double-clicked the
mysql-standard-4.1.11-apple-darwin7.8.0-powerpc.pkg icon to run the installer and install
MySQL.

Next, I installed the MySQLStartupItem.pkg because I want MySQL to start up when I start my
Mac.

Then, I copied the MySQL.prefPane into the PreferencePanes folder in my Library folder at the
root level of my hard drive. Tiger asked me to authenticate when I did this. Upon opening my
System Preferences, I can indeed see a pretty MySQL icon.

I wanted to test to see if MySQL would really start up, so I restarted. Sure enough, MySQL was
running.

Next, it was time to set initial passwords for MySQL. To do that, I opened the Terminal (in the
Utilities folder). Then I typed in the following:

export PATH="$PATH:/usr/local/mysql/bin"

This tells your computer that when it interprets commands, it should also look in the freshly
created MySQL installation for MySQL commands. If you want it added permanently instead of
just for this terminal session, you could edit the third line of /etc/profile to read

PATH="/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/mysql/bin"

30
3 Aug 2007 Drupal Handbook

and then start a new Terminal window.

Next, we want to make MySQL secure by setting a MySQL root password. Fortunately a handy
utility is provided to make that easy. I typed in:

mysql_secure_installation

Interacting with the script looked like this (note that at the first prompt I just pressed enter since
no root password has been set yet:

Enter current password for root (enter for none):
OK, successfully used password, moving on...
Setting the root password ensures that nobody can log into the MySQL
root user without the proper authorisation.
Set root password? [Y/n] Y
New password: zoinks
Re-enter new password: zoinks
Password updated successfully!
Reloading privilege tables..
... Success!
By default, a MySQL installation has an anonymous user, allowing anyone
to log into MySQL without having to have a user account created for
them. This is intended only for testing, and to make the installation
go a bit smoother. You should remove them before moving into a
production environment.
Remove anonymous users? [Y/n] Y
... Success!
Normally, root should only be allowed to connect from ’localhost’.
This
ensures that someone cannot guess at the root password from the
network.
Disallow root login remotely? [Y/n] Y
... Success!
By default, MySQL comes with a database named ’test’ that anyone can
access. This is also intended only for testing, and should be removed
before moving into a production environment.
Remove test database and access to it? [Y/n] Y
- Dropping test database...
... Success!
- Removing privileges on test database...
... Success!
Reloading the privilege tables will ensure that all changes made so far
will take effect immediately.
Reload privilege tables now? [Y/n] Y
... Success!
Cleaning up...
All done! If you’ve completed all of the above steps, your MySQL

31
Drupal Handbook 3 Aug 2007

installation should now be secure.
Thanks for using MySQL!

I verified that MySQL was running:

$ mysqladmin -u root -p status
Enter password: zoinks
Uptime: 938 Threads: 1 Questions: 16 Slow queries: 0 Opens: 21
Flush tables: 1 Open tables: 0 Queries per second avg: 0.017

It was running fine. Now on to the task of setting up MySQL for Drupal.

Sending mail

Current versions of OS X use Postfix as the mail server but you have to enable it.

For a detailed how-to, see:
http://www.stepwise.com/Articles/Workbench/eart.index.html

Or save yourself lots of frustration and time and spend $10 for Postfix Enabler and get running
in a couple of minutes.
http://cutedgesystems.com/software/PostfixEnabler/

Creating the Drupal Database and Database User

Now that MySQL is installed and we have a root password established for it, it’s time to create
the database that Drupal will use:

$ mysqladmin -u root -p create drupal
Enter password: zoinks

The database was created. Time to create the user. The user in this example will be called
drupaldbuser and the password for that user will be fuffy.

$ mysql -u root -p
Enter password: zoinks
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 15 to server version: 4.1.11-standard
Type ’help;’ or ’\h’ for help. Type ’\c’ to clear the buffer.
mysql> GRANT ALL PRIVILEGES ON drupal.* TO drupaldbuser@localhost
IDENTIFIED BY ’fuffy’;
Query OK, 0 rows affected (0.04 sec)

If you are using MySQL 4.1 or later, the following command is necessary because Tiger comes
with PHP 4, and the MySQL libraries for PHP 4 use a different authentication protocol.

mysql> SET PASSWORD FOR ’drupaldbuser’@’localhost’ =
OLD_PASSWORD(’fuffy’);
Query OK, 0 rows affected (0.00 sec)

32
3 Aug 2007 Drupal Handbook

Now we apply the new settings:

mysql> flush privileges;
Query OK, 0 rows affected (0.19 sec)
mysql> \q
Bye

Now I paused to rejoice. MySQL was installed and ready for Drupal. Now it was time to install
Drupal itself.

Installing using CVS repository

Development of the Drupal codebase is fairly quick, with a new release every six months or so.
So I decided to use the CVS repository to download Drupal. That way I can use the "cvs update"
command to keep my Drupal installation current with bug fixes and improvements.

I have the cvs option available to me because I installed the developer tools that were included
on the OS 10.4 DVD. If you don’t have them installed, or don’t want to install them, you could
always download Drupal directly and place the resulting directory inside

/Library/WebServer/Documents

First, I navigated to where I want my Drupal installation. Just to be consistent with Mac OS 10.4,
I used /Library/WebServer/Documents:

cd /Library/WebServer/Documents

And now I pulled down the latest version of the Drupal 4.6 release:

cvs -z9 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal
checkout -r DRUPAL-4-6 drupal

This created a directory called drupal that contains the latest code for version 4.6. If, next week, I
hear that a bugfix has been issued for 4.6, all I have to do is

cd /Library/WebServer/Documents
cvs update

By default, Apache on the Mac runs as user ’www’ with group ’www’, so you probably need to
do the following in order to allow drupal to create directories and files:

chown -R www drupal
chgrp -R www drupal

Now it was time to create all the database tables that Drupal needs:

$ mysql -u drupaldbuser -p drupal <
/Library/WebServer/Documents/drupal/database/database.mysql
Enter password: fuffy

33
Drupal Handbook 3 Aug 2007

Now I had MySQL running, and had a Drupal database populated by Drupal’s fields. It was
time to tell Drupal how to find that database.

In the Finder, I went to /Library/WebServer/Documents/Drupal/sites and duplicated the
folder called default, and renamed it localhost. Then inside the new localhost directory I edited
the settings.php file, changing line 81 to read:

$db_url = ’mysql://drupaldbuser:fuffy@localhost/drupal’;

and changing line 90 to read:

$base_url = ’http://localhost/drupal’;

The reason I duplicated the "default" settings folder was to avoid conflicts when I update CVS in
the future, since CVS would have seen the changed settings.php file and tried to merge it with
the original one. By keeping my settings file separate, I avoid this. As long as I access my Drupal
installation through the URL http://localhost/drupal it will use the settings in the localhost
folder.

PHP is not enabled by default on OS 10.4. So I enabled it by editing Apache’s configuration file. I
used BBEdit, but you can use any text editor you want. For example, you could choose Go To
Folder from the Finder’s Go menu and type in /etc/httpd, then double-click on httpd.conf and
OS 10.4 will prompt you for an application to edit the file with. Here’s me opening the file for
editing in BBEdit:

sudo bbedit /etc/httpd/httpd.conf

Then I removed the # from in front of line 240:

#LoadModule php4_module libexec/httpd/libphp4.so

and line 284:

#AddModule mod_php4.c

and line 406:

AllowOverride All

After changing the configuration file, I stopped, then started the Personal Web Sharing service in
the Sharing pane of System Preferences. This forces Apache to reread the configuration file and
apply the changes. So now PHP was enabled.

Now, with my hands shaking from excitement, I entered http://localhost/drupal into my web
browser. I was greeted with Drupal’s welcome page:

34
3 Aug 2007 Drupal Handbook

I clicked on the link entitled "create the first account", and saw:

Since this was the first account I created on Drupal, I knew it would have special privileges, so I
named it admin and typed in my e-mail address. (Warning: naming your administrative account
"admin" is bad security! Don’t do this!) Then I clicked on the "Create new account" button.
Drupal responded with a randomly generated password and an opportunity to log in
immediately:

35
Drupal Handbook 3 Aug 2007

I took the opportunity to log in immediately by clicking the "Log in" button. On the resulting
screen I changed my password to something I could remember and clicked Submit.

Now I’ve got Drupal running on Mac OS 10.4. Time to celebrate with a swig of flavinoid-laden
grape juice.

Prefixed database.mysql for search and replace
Use a texteditor with search & replace functionality to replace ’prefix’ with your own eg. site1,
site2.
This is database.mysql from 4.6.5. Contributed by Shane Birley.

-- MySQL dump 8.22
--
-- Host: localhost Database: drupal_devel
-- Server version 3.23.52-nt
--
-- Table structure for table ’access’
--
CREATE TABLE prefix_access (
aid tinyint(10) NOT NULL auto_increment,
mask varchar(255) NOT NULL default ’’,
type varchar(255) NOT NULL default ’’,
status tinyint(2) NOT NULL default ’0’,
PRIMARY KEY (aid)
) TYPE=MyISAM;
--
-- Table structure for table ’accesslog’
--
CREATE TABLE prefix_accesslog (
aid int(10) NOT NULL auto_increment,
title varchar(255) default NULL,
path varchar(255) default NULL,
url varchar(255) default NULL,

36
3 Aug 2007 Drupal Handbook

hostname varchar(128) default NULL,
uid int(10) unsigned default ’0’,
timestamp int(11) unsigned NOT NULL default ’0’,
KEY accesslog_timestamp (timestamp),
PRIMARY KEY (aid)
) TYPE=MyISAM;
--
-- Table structure for table ’aggregator_category’
--
CREATE TABLE prefix_aggregator_category (
cid int(10) NOT NULL auto_increment,
title varchar(255) NOT NULL default ’’,
description longtext NOT NULL,
block tinyint(2) NOT NULL default ’0’,
PRIMARY KEY (cid),
UNIQUE KEY title (title)
) TYPE=MyISAM;
--
-- Table structure for table ’aggregator_category_feed’
--
CREATE TABLE prefix_aggregator_category_feed (
fid int(10) NOT NULL default ’0’,
cid int(10) NOT NULL default ’0’,
PRIMARY KEY (fid,cid)
) TYPE=MyISAM;
--
-- Table structure for table ’aggregator_category_item’
--
CREATE TABLE prefix_aggregator_category_item (
iid int(10) NOT NULL default ’0’,
cid int(10) NOT NULL default ’0’,
PRIMARY KEY (iid,cid)
) TYPE=MyISAM;
--
-- Table structure for table ’aggregator_feed’
--
CREATE TABLE prefix_aggregator_feed (
fid int(10) NOT NULL auto_increment,
title varchar(255) NOT NULL default ’’,
url varchar(255) NOT NULL default ’’,
refresh int(10) NOT NULL default ’0’,
checked int(10) NOT NULL default ’0’,
link varchar(255) NOT NULL default ’’,
description longtext NOT NULL,
image longtext NOT NULL,
etag varchar(255) NOT NULL default ’’,
modified int(10) NOT NULL default ’0’,

37
Drupal Handbook 3 Aug 2007

block tinyint(2) NOT NULL default ’0’,
PRIMARY KEY (fid),
UNIQUE KEY link (url),
UNIQUE KEY title (title)
) TYPE=MyISAM;
--
-- Table structure for table ’aggregator_item’
--
CREATE TABLE prefix_aggregator_item (
iid int(10) NOT NULL auto_increment,
fid int(10) NOT NULL default ’0’,
title varchar(255) NOT NULL default ’’,
link varchar(255) NOT NULL default ’’,
author varchar(255) NOT NULL default ’’,
description longtext NOT NULL,
timestamp int(11) default NULL,
PRIMARY KEY (iid)
) TYPE=MyISAM;
--
-- Table structure for table ’authmap’
--
CREATE TABLE prefix_authmap (
aid int(10) unsigned NOT NULL auto_increment,
uid int(10) NOT NULL default ’0’,
authname varchar(128) NOT NULL default ’’,
module varchar(128) NOT NULL default ’’,
PRIMARY KEY (aid),
UNIQUE KEY authname (authname)
) TYPE=MyISAM;
--
-- Table structure for table ’blocks’
--
CREATE TABLE prefix_blocks (
module varchar(64) DEFAULT ’’ NOT NULL,
delta varchar(32) NOT NULL default ’0’,
status tinyint(2) DEFAULT ’0’ NOT NULL,
weight tinyint(1) DEFAULT ’0’ NOT NULL,
region tinyint(1) DEFAULT ’0’ NOT NULL,
custom tinyint(2) DEFAULT ’0’ NOT NULL,
throttle tinyint(1) DEFAULT ’0’ NOT NULL,
visibility tinyint(1) DEFAULT ’0’ NOT NULL,
pages text NOT NULL,
types text NOT NULL
) TYPE=MyISAM;
--
-- Table structure for table ’book’
--

38
3 Aug 2007 Drupal Handbook

CREATE TABLE prefix_book (
nid int(10) unsigned NOT NULL default ’0’,
parent int(10) NOT NULL default ’0’,
weight tinyint(3) NOT NULL default ’0’,
log longtext,
PRIMARY KEY (nid),
KEY parent (parent)
) TYPE=MyISAM;
--
-- Table structure for table ’boxes’
--
CREATE TABLE prefix_boxes (
bid tinyint(4) NOT NULL auto_increment,
title varchar(64) NOT NULL default ’’,
body longtext,
info varchar(128) NOT NULL default ’’,
format int(4) NOT NULL default ’0’,
PRIMARY KEY (bid),
UNIQUE KEY title (title),
UNIQUE KEY info (info)
) TYPE=MyISAM;
--
-- Table structure for table ’cache’
--
CREATE TABLE prefix_cache (
cid varchar(255) NOT NULL default ’’,
data longtext,
expire int(11) NOT NULL default ’0’,
created int(11) NOT NULL default ’0’,
headers text,
PRIMARY KEY (cid),
INDEX expire (expire)
) TYPE=MyISAM;
--
-- Table structure for table ’comments’
--
CREATE TABLE prefix_comments (
cid int(10) NOT NULL auto_increment,
pid int(10) NOT NULL default ’0’,
nid int(10) NOT NULL default ’0’,
uid int(10) NOT NULL default ’0’,
subject varchar(64) NOT NULL default ’’,
comment longtext NOT NULL,
hostname varchar(128) NOT NULL default ’’,
timestamp int(11) NOT NULL default ’0’,
score mediumint(9) NOT NULL default ’0’,
status tinyint(3) unsigned NOT NULL default ’0’,

39
Drupal Handbook 3 Aug 2007

format int(4) NOT NULL default ’0’,
thread varchar(255) NOT NULL,
users longtext,
name varchar(60) default NULL,
mail varchar(64) default NULL,
homepage varchar(255) default NULL,
PRIMARY KEY (cid),
KEY lid (nid)
) TYPE=MyISAM;
--
-- Table structre for table ’node_last_comment’
--
CREATE TABLE prefix_node_comment_statistics (
nid int(10) unsigned NOT NULL auto_increment,
last_comment_timestamp int(11) NOT NULL default ’0’,
last_comment_name varchar(60) default NULL,
last_comment_uid int(10) NOT NULL default ’0’,
comment_count int(10) unsigned NOT NULL default ’0’,
PRIMARY KEY (nid),
KEY node_comment_timestamp (last_comment_timestamp)
) TYPE=MyISAM;
--
-- Table structure for table ’directory’
--
CREATE TABLE prefix_directory (
link varchar(255) NOT NULL default ’’,
name varchar(128) NOT NULL default ’’,
mail varchar(128) NOT NULL default ’’,
slogan longtext NOT NULL,
mission longtext NOT NULL,
timestamp int(11) NOT NULL default ’0’,
PRIMARY KEY (link)
) TYPE=MyISAM;
--
-- Table structure for table ’files’
--
CREATE TABLE prefix_files (
fid int(10) unsigned NOT NULL default ’0’,
nid int(10) unsigned NOT NULL default ’0’,
filename varchar(255) NOT NULL default ’’,
filepath varchar(255) NOT NULL default ’’,
filemime varchar(255) NOT NULL default ’’,
filesize int(10) unsigned NOT NULL default ’0’,
list tinyint(1) unsigned NOT NULL default ’0’,
PRIMARY KEY (fid)
) TYPE=MyISAM;
--

40
3 Aug 2007 Drupal Handbook

-- Table structure for table ’filter_formats’
--
CREATE TABLE prefix_filter_formats (
format int(4) NOT NULL auto_increment,
name varchar(255) NOT NULL default ’’,
roles varchar(255) NOT NULL default ’’,
cache tinyint(2) NOT NULL default ’0’,
PRIMARY KEY (format)
) TYPE=MyISAM;
--
-- Table structure for table ’filters’
--
CREATE TABLE prefix_filters (
format int(4) NOT NULL default ’0’,
module varchar(64) NOT NULL default ’’,
delta tinyint(2) DEFAULT ’0’ NOT NULL,
weight tinyint(2) DEFAULT ’0’ NOT NULL,
INDEX (weight)
) TYPE=MyISAM;
--
-- Table structure for table ’flood’
--
CREATE TABLE prefix_flood (
event varchar(64) NOT NULL default ’’,
hostname varchar(128) NOT NULL default ’’,
timestamp int(11) NOT NULL default ’0’
) TYPE=MyISAM;
--
-- Table structure for table ’forum’
--
CREATE TABLE prefix_forum (
nid int(10) unsigned NOT NULL default ’0’,
tid int(10) unsigned NOT NULL default ’0’,
PRIMARY KEY (nid),
KEY tid (tid)
) TYPE=MyISAM;
--
-- Table structure for table ’history’
--
CREATE TABLE prefix_history (
uid int(10) NOT NULL default ’0’,
nid int(10) NOT NULL default ’0’,
timestamp int(11) NOT NULL default ’0’,
PRIMARY KEY (uid,nid)
) TYPE=MyISAM;
--
-- Table structure for table ’locales_meta’

41
Drupal Handbook 3 Aug 2007

--
CREATE TABLE prefix_locales_meta (
locale varchar(12) NOT NULL default ’’,
name varchar(64) NOT NULL default ’’,
enabled int(2) NOT NULL default ’0’,
isdefault int(2) NOT NULL default ’0’,
plurals int(1) NOT NULL default ’0’,
formula varchar(128) NOT NULL default ’’,
PRIMARY KEY (locale)
) TYPE=MyISAM;
--
-- Table structure for table ’locales_source’
--
CREATE TABLE prefix_locales_source (
lid int(11) NOT NULL auto_increment,
location varchar(255) NOT NULL default ’’,
source blob NOT NULL,
PRIMARY KEY (lid)
) TYPE=MyISAM;
--
-- Table structure for table ’locales_target’
--
CREATE TABLE prefix_locales_target (
lid int(11) NOT NULL default ’0’,
translation blob NOT NULL,
locale varchar(12) NOT NULL default ’’,
plid int(11) NOT NULL default ’0’,
plural int(1) NOT NULL default ’0’,
KEY lid (lid),
KEY lang (locale),
KEY plid (plid),
KEY plural (plural)
) TYPE=MyISAM;
--
-- Table structure for table ’menu’
--
CREATE TABLE prefix_menu (
mid int(10) unsigned NOT NULL default ’0’,
pid int(10) unsigned NOT NULL default ’0’,
path varchar(255) NOT NULL default ’’,
title varchar(255) NOT NULL default ’’,
description varchar(255) NOT NULL default ’’,
weight tinyint(4) NOT NULL default ’0’,
type int(2) unsigned NOT NULL default ’0’,
PRIMARY KEY (mid)
) TYPE=MyISAM;
--

42
3 Aug 2007 Drupal Handbook

-- Table structure for table ’moderation_filters’
--
CREATE TABLE prefix_moderation_filters (
fid int(10) unsigned NOT NULL auto_increment,
filter varchar(255) NOT NULL default ’’,
minimum smallint(6) NOT NULL default ’0’,
PRIMARY KEY (fid)
) TYPE=MyISAM;
--
-- Table structure for table ’moderation_roles’
--
CREATE TABLE prefix_moderation_roles (
rid int(10) unsigned NOT NULL default ’0’,
mid int(10) unsigned NOT NULL default ’0’,
value tinyint(4) NOT NULL default ’0’,
KEY idx_rid (rid),
KEY idx_mid (mid)
) TYPE=MyISAM;
--
-- Table structure for table ’moderation_votes’
--
CREATE TABLE prefix_moderation_votes (
mid int(10) unsigned NOT NULL auto_increment,
vote varchar(255) default NULL,
weight tinyint(4) NOT NULL default ’0’,
PRIMARY KEY (mid)
) TYPE=MyISAM;
--
-- Table structure for table ’node’
--
CREATE TABLE prefix_node (
nid int(10) unsigned NOT NULL auto_increment,
type varchar(16) NOT NULL default ’’,
title varchar(128) NOT NULL default ’’,
uid int(10) NOT NULL default ’0’,
status int(4) NOT NULL default ’1’,
created int(11) NOT NULL default ’0’,
changed int(11) NOT NULL default ’0’,
comment int(2) NOT NULL default ’0’,
promote int(2) NOT NULL default ’0’,
moderate int(2) NOT NULL default ’0’,
teaser longtext NOT NULL,
body longtext NOT NULL,
revisions longtext NOT NULL,
sticky int(2) NOT NULL default ’0’,
format int(4) NOT NULL default ’0’,
PRIMARY KEY (nid),

43
Drupal Handbook 3 Aug 2007

KEY node_type (type(4)),
KEY node_title_type (title,type(4)),
KEY status (status),
KEY uid (uid),
KEY node_moderate (moderate),
KEY node_promote_status (promote, status),
KEY node_created (created),
KEY node_changed (changed),
KEY node_status_type (status, type, nid)
) TYPE=MyISAM;
--
-- Table structure for table ‘node_access‘
--
CREATE TABLE prefix_node_access (
nid int(10) unsigned NOT NULL default ’0’,
gid int(10) unsigned NOT NULL default ’0’,
realm varchar(255) NOT NULL default ’’,
grant_view tinyint(1) unsigned NOT NULL default ’0’,
grant_update tinyint(1) unsigned NOT NULL default ’0’,
grant_delete tinyint(1) unsigned NOT NULL default ’0’,
PRIMARY KEY (nid,gid,realm)
) TYPE=MyISAM;
--
-- Table structure for table ’profile_fields’
--
CREATE TABLE prefix_profile_fields (
fid int(10) NOT NULL auto_increment,
title varchar(255) default NULL,
name varchar(128) default NULL,
explanation TEXT default NULL,
category varchar(255) default NULL,
page varchar(255) default NULL,
type varchar(128) default NULL,
weight tinyint(1) DEFAULT ’0’ NOT NULL,
required tinyint(1) DEFAULT ’0’ NOT NULL,
register tinyint(1) DEFAULT ’0’ NOT NULL,
visibility tinyint(1) DEFAULT ’0’ NOT NULL,
options text,
KEY category (category),
UNIQUE KEY name (name),
PRIMARY KEY (fid)
);
--
-- Table structure for table ’profile_values’
--
CREATE TABLE prefix_profile_values (
fid int(10) unsigned default ’0’,

44
3 Aug 2007 Drupal Handbook

uid int(10) unsigned default ’0’,
value text,
KEY uid (uid),
KEY fid (fid)
);
--
-- Table structure for table ’url_alias’
--
CREATE TABLE prefix_url_alias (
pid int(10) unsigned NOT NULL auto_increment,
src varchar(128) NOT NULL default ’’,
dst varchar(128) NOT NULL default ’’,
PRIMARY KEY (pid),
UNIQUE KEY dst (dst)
) TYPE=MyISAM;
--
-- Table structure for table ’permission’
--
CREATE TABLE prefix_permission (
rid int(10) unsigned NOT NULL default ’0’,
perm longtext,
tid int(10) unsigned NOT NULL default ’0’,
KEY rid (rid)
) TYPE=MyISAM;
--
-- Table structure for table ’poll’
--
CREATE TABLE prefix_poll (
nid int(10) unsigned NOT NULL default ’0’,
runtime int(10) NOT NULL default ’0’,
polled longtext NOT NULL,
active int(2) unsigned NOT NULL default ’0’,
PRIMARY KEY (nid)
) TYPE=MyISAM;
--
-- Table structure for table ’poll_choices’
--
CREATE TABLE prefix_poll_choices (
chid int(10) unsigned NOT NULL auto_increment,
nid int(10) unsigned NOT NULL default ’0’,
chtext varchar(128) NOT NULL default ’’,
chvotes int(6) NOT NULL default ’0’,
chorder int(2) NOT NULL default ’0’,
PRIMARY KEY (chid),
KEY nid (nid)
) TYPE=MyISAM;
--

45
Drupal Handbook 3 Aug 2007

-- Table structure for table ’queue’
--
CREATE TABLE prefix_queue (
nid int(10) unsigned NOT NULL,
uid int(10) unsigned NOT NULL,
vote int(3) NOT NULL default ’0’,
PRIMARY KEY (nid, uid)
) TYPE=MyISAM;
--
-- Table structure for table ’role’
--
CREATE TABLE prefix_role (
rid int(10) unsigned NOT NULL auto_increment,
name varchar(32) NOT NULL default ’’,
PRIMARY KEY (rid),
UNIQUE KEY name (name)
) TYPE=MyISAM;
--
-- Table structure for table ’search_index’
--
CREATE TABLE prefix_search_index (
word varchar(50) NOT NULL default ’’,
sid int(10) unsigned NOT NULL default ’0’,
type varchar(16) default NULL,
fromsid int(10) unsigned NOT NULL default ’0’,
fromtype varchar(16) default NULL,
score int(10) unsigned default NULL,
KEY sid (sid),
KEY fromsid (fromsid),
KEY word (word)
) TYPE=MyISAM;
--
-- Table structure for table ’search_total’
--
CREATE TABLE prefix_search_total (
word varchar(50) NOT NULL default ’’,
count int(10) unsigned default NULL,
PRIMARY KEY word (word)
) TYPE=MyISAM;
--
-- Table structure for table ’sessions’
--
CREATE TABLE prefix_sessions (
uid int(10) unsigned NOT NULL,
sid varchar(32) NOT NULL default ’’,
hostname varchar(128) NOT NULL default ’’,
timestamp int(11) NOT NULL default ’0’,

46
3 Aug 2007 Drupal Handbook

session longtext,
KEY uid (uid),
PRIMARY KEY (sid),
KEY timestamp (timestamp)
) TYPE=MyISAM;
--
-- Table structure for table ’sequences’
--
CREATE TABLE prefix_sequences (
name varchar(255) NOT NULL default ’’,
id int(10) unsigned NOT NULL default ’0’,
PRIMARY KEY (name)
) TYPE=MyISAM;
--
-- Table structure for table ’node_counter’
--
CREATE TABLE prefix_node_counter (
nid int(11) NOT NULL default ’0’,
totalcount bigint(20) unsigned NOT NULL default ’0’,
daycount mediumint(8) unsigned NOT NULL default ’0’,
timestamp int(11) unsigned NOT NULL default ’0’,
PRIMARY KEY (nid),
KEY totalcount (totalcount),
KEY daycount (daycount),
KEY timestamp (timestamp)
) TYPE=MyISAM;
--
-- Table structure for table ’system’
--
CREATE TABLE prefix_system (
filename varchar(255) NOT NULL default ’’,
name varchar(255) NOT NULL default ’’,
type varchar(255) NOT NULL default ’’,
description varchar(255) NOT NULL default ’’,
status int(2) NOT NULL default ’0’,
throttle tinyint(1) DEFAULT ’0’ NOT NULL,
bootstrap int(2) NOT NULL default ’0’,
PRIMARY KEY (filename)
) TYPE=MyISAM;
--
-- Table structure for table ’term_data’
--
CREATE TABLE prefix_term_data (
tid int(10) unsigned NOT NULL auto_increment,
vid int(10) unsigned NOT NULL default ’0’,
name varchar(255) NOT NULL default ’’,
description longtext,

47
Drupal Handbook 3 Aug 2007

weight tinyint(4) NOT NULL default ’0’,
PRIMARY KEY (tid),
KEY vid (vid)
) TYPE=MyISAM;
--
-- Table structure for table ’term_hierarchy’
--
CREATE TABLE prefix_term_hierarchy (
tid int(10) unsigned NOT NULL default ’0’,
parent int(10) unsigned NOT NULL default ’0’,
KEY tid (tid),
KEY parent (parent)
) TYPE=MyISAM;
--
-- Table structure for table ’term_node’
--
CREATE TABLE prefix_term_node (
nid int(10) unsigned NOT NULL default ’0’,
tid int(10) unsigned NOT NULL default ’0’,
KEY nid (nid),
KEY tid (tid),
PRIMARY KEY (tid,nid)
) TYPE=MyISAM;
--
-- Table structure for table ’term_relation’
--
CREATE TABLE prefix_term_relation (
tid1 int(10) unsigned NOT NULL default ’0’,
tid2 int(10) unsigned NOT NULL default ’0’,
KEY tid1 (tid1),
KEY tid2 (tid2)
) TYPE=MyISAM;
--
-- Table structure for table ’term_synonym’
--
CREATE TABLE prefix_term_synonym (
tid int(10) unsigned NOT NULL default ’0’,
name varchar(255) NOT NULL default ’’,
KEY tid (tid),
KEY name (name(3))
) TYPE=MyISAM;
--
-- Table structure for table ’users’
--
CREATE TABLE prefix_users (
uid int(10) unsigned NOT NULL default ’0’,
name varchar(60) NOT NULL default ’’,

48
3 Aug 2007 Drupal Handbook

pass varchar(32) NOT NULL default ’’,
mail varchar(64) default ’’,
mode tinyint(1) NOT NULL default ’0’,
sort tinyint(1) default ’0’,
threshold tinyint(1) default ’0’,
theme varchar(255) NOT NULL default ’’,
signature varchar(255) NOT NULL default ’’,
created int(11) NOT NULL default ’0’,
changed int(11) NOT NULL default ’0’,
status tinyint(4) NOT NULL default ’0’,
timezone varchar(8) default NULL,
language varchar(12) NOT NULL default ’’,
picture varchar(255) NOT NULL DEFAULT ’’,
init varchar(64) default ’’,
data longtext,
PRIMARY KEY (uid),
UNIQUE KEY name (name),
KEY changed (changed)
) TYPE=MyISAM;
--
-- Table structure for table ’users_roles’
--
CREATE TABLE prefix_users_roles (
uid int(10) unsigned NOT NULL default ’0’,
rid int(10) unsigned NOT NULL default ’0’,
PRIMARY KEY (uid, rid)
) TYPE=MyISAM;
--
-- Table structure for table ’variable’
--
CREATE TABLE prefix_variable (
name varchar(48) NOT NULL default ’’,
value longtext NOT NULL,
PRIMARY KEY (name)
) TYPE=MyISAM;
--
-- Table structure for table ’vocabulary’
--
CREATE TABLE prefix_vocabulary (
vid int(10) unsigned NOT NULL auto_increment,
name varchar(255) NOT NULL default ’’,
description longtext,
help varchar(255) NOT NULL default ’’,
relations tinyint(3) unsigned NOT NULL default ’0’,
hierarchy tinyint(3) unsigned NOT NULL default ’0’,
multiple tinyint(3) unsigned NOT NULL default ’0’,
required tinyint(3) unsigned NOT NULL default ’0’,

49
Drupal Handbook 3 Aug 2007

module varchar(255) NOT NULL default ’’,
weight tinyint(4) NOT NULL default ’0’,
PRIMARY KEY (vid)
) TYPE=MyISAM;
--
-- Table structure for table ’vocabulary_node_types’
--
CREATE TABLE prefix_vocabulary_node_types (
vid int(10) unsigned NOT NULL DEFAULT ’0’,
type varchar(16) NOT NULL DEFAULT ’’,
PRIMARY KEY (vid, type)
) TYPE=MyISAM;
--
-- Table structure for table ’watchdog’
--
CREATE TABLE prefix_watchdog (
wid int(5) NOT NULL auto_increment,
uid int(10) NOT NULL default ’0’,
type varchar(16) NOT NULL default ’’,
message longtext NOT NULL,
severity tinyint(3) unsigned NOT NULL default ’0’,
link varchar(255) NOT NULL default ’’,
location varchar(128) NOT NULL default ’’,
hostname varchar(128) NOT NULL default ’’,
timestamp int(11) NOT NULL default ’0’,
PRIMARY KEY (wid)
) TYPE=MyISAM;
--
-- Insert some default values
--
INSERT INTO prefix_system VALUES
(’modules/block.module’,’block’,’module’,’’,1,0,0);
INSERT INTO prefix_system VALUES
(’modules/comment.module’,’comment’,’module’,’’,1,0,0);
INSERT INTO prefix_system VALUES
(’modules/filter.module’,’filter’,’module’,’’,1,0,0);
INSERT INTO prefix_system VALUES
(’modules/help.module’,’help’,’module’,’’,1,0,0);
INSERT INTO prefix_system VALUES
(’modules/node.module’,’node’,’module’,’’,1,0,0);
INSERT INTO prefix_system VALUES
(’modules/page.module’,’page’,’module’,’’,1,0,0);
INSERT INTO prefix_system VALUES
(’modules/story.module’,’story’,’module’,’’,1,0,0);
INSERT INTO prefix_system VALUES
(’modules/system.module’,’system’,’module’,’’,1,0,0);
INSERT INTO prefix_system VALUES

50
3 Aug 2007 Drupal Handbook

(’modules/taxonomy.module’,’taxonomy’,’module’,’’,1,0,0);
INSERT INTO prefix_system VALUES
(’modules/user.module’,’user’,’module’,’’,1,0,0);
INSERT INTO prefix_system VALUES
(’modules/watchdog.module’,’watchdog’,’module’,’’,1,0,0);
INSERT INTO prefix_system VALUES
(’themes/bluemarine/xtemplate.xtmpl’,’bluemarine’,’theme’,’themes/engines/xtemplate/xtemplate.engine’,1,0,0);
INSERT INTO prefix_system VALUES
(’themes/engines/xtemplate/xtemplate.engine’,’xtemplate’,’theme_engine’,’’,1,0,0);
INSERT INTO prefix_users (uid, name, mail) VALUES (’0’, ’’, ’’);
INSERT INTO prefix_users_roles (uid, rid) VALUES (0, 1);
INSERT INTO prefix_role (rid, name) VALUES (1, ’anonymous user’);
INSERT INTO prefix_permission VALUES (1,’access content’,0);
INSERT INTO prefix_role (rid, name) VALUES (2, ’authenticated user’);
INSERT INTO prefix_permission VALUES (2,’access comments, access
content, post comments, post comments without approval’,0);
REPLACE prefix_variable SET name=’update_start’,
value=’s:10:"2005-03-21";’;
REPLACE prefix_variable SET name=’theme_default’,
value=’s:10:"bluemarine";’;
REPLACE prefix_blocks SET module = ’user’, delta = ’0’, status = ’1’;
REPLACE prefix_blocks SET module = ’user’, delta = ’1’, status = ’1’;
INSERT INTO prefix_sequences (name, id) VALUES (’menu_mid’, 1);
INSERT INTO prefix_node_access VALUES (0, 0, ’all’, 1, 0, 0);
INSERT INTO prefix_filter_formats VALUES (1,’Filtered HTML’,’,1,2,’,1);
INSERT INTO prefix_filter_formats VALUES (2,’PHP code’,’’,0);
INSERT INTO prefix_filter_formats VALUES (3,’Full HTML’,’’,1);
INSERT INTO prefix_filters VALUES (1,’filter’,0,0);
INSERT INTO prefix_filters VALUES (1,’filter’,2,1);
INSERT INTO prefix_filters VALUES (2,’filter’,1,0);
INSERT INTO prefix_filters VALUES (3,’filter’,2,0);
INSERT INTO prefix_variable (name,value) VALUES
(’filter_html_1’,’i:1;’);
INSERT INTO prefix_locales_meta (locale, name, enabled, isdefault)
VALUES (’en’, ’English’, ’1’, ’1’);

Setup Drupal on Windows XP Pro using IIS
While trying to install Drupal on stand alone machine with Windows XP Pro & IIS I was unable
to find all the installation information at one place therefore I am sharing my experiences and
solutions to the problems. I think it will be useful for people who are new to Drupal because
Drupal on stand alone machine reduces the learning curve.

Setup Drupal on Windows XP Pro using IIS:
1. Download Mysql server and install. (I have used ver. 5.0)
2. Download PHP and install. (I have used ver. 4)
3. Download Drupal (I have used ver. 4.7.3).

51
Drupal Handbook 3 Aug 2007

4. Create a folder with any name for example Drupal in Inetpub folder in C: drive.
5. Open IIS and create virtual folder giving alias and path of the Drupal folder which you have
just created in Inetpub.
6. Untar (you can use Winrar for this) the downloaded drupal file contents in Drupal folder.
7. Create a schema/database with any name example drupaldata and create a user.
8. Now grant privileges to this user.
Grant ALL ON databasename.*
TO ’username’@’localhost’ IDENTIFIED BY ’password’;
Flush privileges;

9. Modify the file C:\Inetpub\wwwroot\[YOURDIRNAME]\sites\default\settings.php by
giving user name, password and database name.

10. Now browse this virtual folder with its alias name in IE example
http://localhost/"aliasname"

11. If following error is displayed;
Client does not support authentication protocol requested by server; consider upgrading
MySQL client

Then use these commands;
SET PASSWORD FOR ’some_user’@’some_host’ = OLD_PASSWORD(’newpwd’);
Flush privileges;

12. Repeat step 10, I hope its working â¦.

Have a look at one of the pretty clean theme implementation in drupal - ENJOY . . .

Basic /sites directory setup
Version 5.x supports a new /sites/all directory. Best practice for basic initial setup is the
following placements in the /sites directory:

Directory Contents
/modules
/drupal/sites/all
/themes
/drupal/sites/default settings.php
/tmp
/drupal/sites/example.com /files
(but see below)

Understand the different common locations. The /sites/all and the /sites/default directories are
exclusive, and are intended for the above items. The critical principle is to keep all your site
customizations within the /sites directory so that it is easy to upgrade when a new minor
version of the Drupal core code is released (e.g. to update from 5.1 to 5.2).

52
3 Aug 2007 Drupal Handbook

Contributed and custom modules should be placed in /drupal/sites/all/modules. Additional
and custom themes should be placed in /drupal/sites/all/themes.

The /files directory is usually best placed in the /sites/example.com directory, which you will
have to create. Then set the ’File system path’ at administer > site configuration > file system. This is
ideal if a second site will likely need a separate /files directory; just create a second site-specific
/files directory at /sites/example2.com/files. The same applies for the /tmp directory.

Upon initial installation the /files directory is set to /sites/default/files (you will need to create
the actual directory). It can be fine to leave it there (or even to use /sites/files) if you are 100%
you will never want to use multi-site features. However, this location shares the /files directory
in a multi-site setup , which may or may not be desired. See "Setup of /sites directory for
multi-site."

Backup is simplified by use of the /sites directory for all customizations. You can then easily
backup all non-core material by backing up the /sites directory and the database.

For multi-site setup, see Multi-site installation and set-up, the sub-topic Setup of /sites directory
for multi-site, and the installation instructions (INSTALL.txt). As stated above, there are two
common locations in Drupal 5.x and above: /sites/default (for settings.php) and/sites/all (for
common /modules and /themes). This allows a new site to be set up using the multi-site
features by simply copying the /sites/default directory to /sites/example2.com

Version 4.6 and 4.7: To simplify backups and updates, the best practice (for a single-site install)
is to place contributed modules in /sites/default/modules/, contributed or custom themes in
/sites/default/themes/, and files in /sites/default/files (or even /sites/files). The /sites/all/
feature was added in Drupal 5.x. It will also work, but be more difficult to update your site, if
contributed modules are placed in /drupal/modules, additional themes were placed in
/drupal/themes, and files are stored in /drupal/files. If you expect to use multi-sites, then you
should make use of /sites/example.com as explained in the "Setup of /sites directory for
multi-site." Using /drupal/modules and /drupal/themes will also still work in 5.x, but the best
practice above allows easier backup and expansion to multi-site.

Special cases
Various special situations (e.g., installing Drupal behind a firewall, installing Drupal in a
subdirectory of the webserver’s document root) are discussed in this section. Information
specific to particular operating systems or database platforms may be found elsewhere.

Compilation failed: this version of PCRE is not compiled with
PCRE_UTF8 support
This error occurrs on release 4.6.1 onwards.

Note: This issue is fixed by default on all VPS3 and new VPS2 servers, resolve-able on VPS1 and old
VPS2 (with some updating).

53
Drupal Handbook 3 Aug 2007

This fix works for Verio VPS2 Servers which are installed with PCRE 6.4 by default (at this time).
I see no reason why it should not work for all unix servers (perhaps with directory changes etc).

The fix is to uninstall pcre and install the correct version as follows:

login as root
Type:
# pkg_info
which will show you the installed packages.
type:
# pkg_delete pcre-6.4 (assuming you see pcre-6.4 as the installed
version, change as required)
change to the directory where your ports collection is.
on FreeBSD it is:
/ports/devel/pcre-utf8
so type into your shell prompt:
# cd /ports/devel/pcre-utf8
# make
# make install
# make clean
then restart the apache server...
something like this (this is a VPS2 specific script, yours may be different):
# restart_apache

Configure .htaccess to allow awstats to work with clean URL’s
When I installed Drupal with clean url’s it made my Awstats (within the cgi-bin) not work and
just return a Drupal page not found error.

Drupal is installed in the root directory (public_html) of my web space so is the cgi-bin folder
that Awstats is in.

I fixed the problem by changing the protect files and adding 1 rewriteCond line to the .htaccess
file as follows:

In the FilesMatch section, find " |code-style\.pl " without the quotes and remove it from the
following code:

# Protect files and directories from prying eyes.
<FilesMatch
"(\.(engine|inc|install|module|sh|.*sql|theme|tpl(\.php)?|xtmpl)|Entries.*|Repository|Root)$">
Order deny,allow
Deny from all
</FilesMatch>

Now add this line (RewriteCond %{REQUEST_URI} "!cgi-bin/") to the following:

54
3 Aug 2007 Drupal Handbook

# Rewrite current-style URLs of the form ’index.php?q=x’.

RewriteCond %{REQUEST_URI} "!cgi-bin/"
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]

This was all done on the default install of Drupal w/.htaccess.

Configuring .htaccess to ignore specific subfolders
Ignoring Subfolders that exist in the DocumentRoot

With clean URL’s enabled, when running other software applications in subfolders
(subdirectories) of a Drupal root installation. your .htaccess file may rewrite those URL’s to
Drupal. This may be a particular problem for those with a Drupal installation in the root of their
domain using Cpanel and Fantastico where Fantastico installs other software into subfolders.
For example, phpSurveyor’s admin interface as installed by Fantastico will not work with
Drupal’s default .htaccess settings. The URL for the admin interface is inaccessible and will
return a "page not found" page in your Drupal site.

The trick is to modify .htaccess to ignore specific files/folders. So for example, if you have two
folders, <folder1> and <folder2> in the root of your Drupal installation, modify your .htaccess
file by inserting the following code:

=========[ start of .htaccess snippet]==========
<IfModule mod_rewrite.c>
RewriteEngine on
#
# stuff to let through (ignore)
RewriteCond %{REQUEST_URI} "/folder1/" [OR]
RewriteCond %{REQUEST_URI} "/folder2/"
RewriteRule (.*) $1 [L]
#
====================[ end ]=====================

For each folder you want to bypass, add a RewriteCond line, and end all but the final
RewriteCond with [OR]. Note that the [L] in the rewrite rule tells it to stop there and bypass the
rest of the rewrite rules.

Ignoring subfolders that are included via Apache Alias directives

As of 4.7, files and directories should be automatically allowed through in drupal’s .htaccess
setup. Thats what the !-f and !-d lines do.

However if you are working with Apache Alias or similar directives the file doesn’t actually
exist so drupal will take over like it should. The best way around it is to just add one more
conditional that matches your location and make it skip it too. Thats what the ! means. Please see

55
Drupal Handbook 3 Aug 2007

below:

RewriteCond %{REQUEST_URI} !^/yourDirectoryName
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]

It essentially means Apply this rule if the REQUEST_URI doesn’t start with
/yourDirectoryName and the REQUEST_FILENAME isn’t a real file or a real folder. Which is
exactly what you want. There is an implied "AND" between the lines of that rule. The ! says "not
like this".

Special thanks to Mike Smullin for help on this fix.

Create a custom php.ini
This article explains how to set up a custom php.ini that overides your servers default php.ini,
providing an easier alternative (in the long run) than using .htaccess to overide php.ini settings.
Itassumes that you have a ssh account set-up and are using a ssh client (e.g. putty - link to be
added). You are also expected to logically replace directory structures given here, with your
own, if they are different.

Procedure for allowing php.ini configuration for a website (shows changing file upload max)

1/ Create a cgi-bin Directory

First you’ll need a cgi-bin directory:

mkdir ~/[your website directory]/cgi-bin/

This directory will be hosting your copy of php and your php.ini file.

2/ Create a script to retrieve the latest copy of php.cgi and php.ini

Make a file in ~/ called php-copy.sh containing the following, where 100M contains whatever
file size limit you like, and [your website directory] is appropriately substituted.

For PHP4:

#!/bin/sh
CGIFILE="$HOME/[your website directory]/cgi-bin/php.cgi"
INIFILE="$HOME/[your website directory]/cgi-bin/php.ini"
rsync -a /dh/cgi-system/php.cgi "$CGIFILE"
# REMOVE THE FOLLOWING LINE TO CREATE THE UPDATE-ONLY SCRIPT:
cp /etc/php/cgi/php.ini "$INIFILE"
perl -p -i -e ’
s/.*post_max_size.*/post_max_size = 100M/;
s/.*upload_max_filesize.*/upload_max_filesize = 100M/;
’ "$INIFILE"

56
3 Aug 2007 Drupal Handbook

For PHP5:

#!/bin/sh
CGIFILE="$HOME/[your website directory]/cgi-bin/php.cgi"
INIFILE="$HOME/[your website directory]/cgi-bin/php.ini"
rsync -a /dh/cgi-system/php5.cgi "$CGIFILE"
# REMOVE THE FOLLOWING LINE TO CREATE THE UPDATE-ONLY SCRIPT:
cp /etc/php5/cgi/php.ini "$INIFILE"
perl -p -i -e ’
s/.*post_max_size.*/post_max_size = 100M/;
s/.*upload_max_filesize.*/upload_max_filesize = 100M/;
’ "$INIFILE"

A more general script with options (for references purposes only, do not do this):

#!/bin/sh
test $# = 0 && exit 1
while test "$1";do
case $1 in
-php5) PHP=php5 ;;
-sm) shift; SM=$1 ;;
-rg) shift; RG=$1 ;;
-pms) shift; PMS=$1 ;;
-umfs) shift; UMFS=$1 ;;
-mqg) shift; MQG=$1 ;;
-met) shift; MET=$1 ;;
-mit) shift; MIT=$1 ;;
-ml) shift; ML=$1 ;;
*) D=$1 ;;
esac
shift
done
test "$D" || exit 1
test -d "$HOME/$D" || exit 1
CGI="$HOME/$D/cgi-bin"
mkdir -m0755 -p $CGI || exit 2
PHP=${PHP:-php}
SM=${SM:-On}
RG=${RG:-Off}
PMS=${PMS:-8M}
UMFS=${UMFS:-7M}
MQG=${MQG:-Off}
MET=${MET:-30}
MIT=${MET:-60}
ML=${ML:-8M}
CGIFILE="$CGI/$PHP.cgi"
INIFILE="$CGI/php.ini"

57
Drupal Handbook 3 Aug 2007

echo "CGI=$CGI MQG=${MQG} UMFS=${UMFS} PMS=${PMS} RG=${RG} SM=${SM}
MET=${MET} MIT=${MIT} ML=${ML}" >&2
rsync -au /dh/cgi-system/$PHP.cgi "$CGIFILE"
[ -s /etc/$PHP/cgi/php.ini ] && \
sed -e "s/^safe_mode[ ]*=.*/safe_mode = $SM/" \
-e "s/register_globals[ ]*=.*/register_globals = $RG/" \
-e "s/magic_quotes_gpc[ ]*=.*/magic_quotes_gpc = $MQG/" \
-e "s/.*post_max_size.*/post_max_size = $PMS/" \
-e "s/.*upload_max_filesize.*/upload_max_filesize = $UMFS/" \
-e "s/.*max_execution_time.*/max_execution_time = $MET/" \
-e "s/.*max_input_time.*/max_input_time = $MIT/" \
-e "s/.*memory_limit.*/memory_limit= $ML/" \
# REMOVE THE FOLLOWING LINE TO CREATE THE UPDATE-ONLY SCRIPT:
/etc/$PHP/cgi/php.ini > "$INIFILE"
chmod 0755 "$CGIFILE"
chmod 0644 "$INIFILE"
[ -s $CGI/.htaccess ] || echo "Options -Indexes" > $CGI/.htaccess
touch $HOME/$D/.htaccess
if grep -q ’^Options’ $HOME/$D/.htaccess; then
grep -q ’+ExecCGI’ $HOME/$D/.htaccess || \
sed -i ’s/^Options\(.*\)/Options\1 +ExecCGI/’ $HOME/$D/.htaccess
else
echo "Options +ExecCGI" >> $HOME/$D/.htaccess
fi
grep -q ’^AddHandler[ ]\+php-cgi[ ]\+.php’ $HOME/$D/.htaccess ||
echo "AddHandler php-cgi .php" >> $HOME/$D/.htaccess
if grep -q ’^Action[ ]\+php-cgi’ $HOME/$D/.htaccess; then
sed -i "s@^Action[ ]\+php-cgi.*@Action php-cgi /cgi-bin/$PHP.cgi@" \
$HOME/$D/.htaccess
else
echo "Action php-cgi /cgi-bin/$PHP.cgi" >> $HOME/$D/.htaccess
fi

3/ Prepare script for execution

Execute the following commands into the shell. This will give you permission to execute the
php-copy.sh that we just created.

chmod +x php-copy.sh

This calls our new shell script to copy the php.cgi and php.ini files into our cgi-bin directory.

./php-copy.sh

If you get the error message: "bad interpreter: No such file or directory", there is probably an
unseen problem with the formatting of the file.

58
3 Aug 2007 Drupal Handbook

Run the following command to convert it to proper Unix format before calling the script again:
dos2unix php-copy.sh

4/ Test your new PHP setup

Open one of your existing PHP pages in your browser to ensure that your newly-installed local
copy of PHP is functioning properly. If there is a problem, go back over the prior steps and use
your debugging skills and your mastery of PHP, shell scripts and Linux to get your
newly-copied PHP interpreter working! Once everything works properly, go on to the next step.

5/ Create a shell script to make a fresh copy of php (for future use)

cp php-copy.sh php-update.sh

Open the newly-created php-update.sh script in your favorite text editor and find this line:

# REMOVE THE FOLLOWING LINE TO CREATE THE UPDATE-ONLY SCRIPT:

Delete that line as well as the line following it. Then save php-update.sh

If you got a "bad interpreter: No such file or directory" error message when you executed
./php-copy.sh previously, remember to convert the new file to unix format by running the
following command: dos2unix php-update.sh

6/ Set up a cron task to keep php up to date

Type:

crontab -e

And then enter the following in the text editor that shows up (replacing ’myusername’ with
your specific username):

@weekly /home/myusername/php-update.sh

This will update the php binary and config file once a week.

7/ Configure your website to use new the php.ini that we just set up

Create the file ~/[your website directory]/.htaccess which contains the lines:

Options +ExecCGI
AddHandler php-cgi .php
Action php-cgi /cgi-bin/php.cgi

This is telling Apache (the webserver) to use the php.cgi and php.ini that php-update.sh copied
into ~/[your website directory]/cgi-bin.

59
Drupal Handbook 3 Aug 2007

How to create a custom php.ini file when nothing else works

I recently needed to increase the memory_limit, upload_max_filesize and
post_max_size values to something higher than the measly amount set by a particular
webhost’s default php.ini file. This account was set up with cPanel and overriding the php.ini
defaults the usual way (by adding various lines to the .htaccess or settings.php files) didn’t work
at all. If you’ve had the same experience, you may find that this how-to works for you.

This how-to is for any version of Drupal running on Linux and Apache. No Drupal modules are
needed, but the devel module certainly helps.

1. Get and modify your custom php.ini file

It’s best to use a php.ini file that somewhat resembles the one already running on your server.
You can probably find one at /usr/local/lib/php.ini or /usr/local/Zend/etc/php.ini and just copy
it into your account’s web folder (it may be called "public_html" or "www" or "htdocs" -- you
know the one).

Edit your php.ini file and save your changes. There are handbook pages on increasing memory
and upload size if you need help on the syntax.

2. Creating your CGI script

Now create a small script and put it in your cgi-bin directory. In your web folder, create another
folder called "cgi-bin" if it’s not there already. Using your preferred text editor, create a file
name "php.cgi" and put the following into it:

#!/bin/sh
exec /usr/local/cpanel/cgi-sys/php5 -c /path/to/drupal/

If you don’t have cPanel on your account, try /etc/php5 instead. In any case, replace the
/path/to/drupal/ part with the full path to your Drupal installation, such as
/home/youraccount/public_html/ or /home/youraccount/public_html/drupal/

Since this is a script that needs to run as an executable file, use the chmod command and type this
at the command line:

chmod -x php.cgi

Don’t have shell access? That’s outside the scope of this how-to, but you can use an FTP
program that can change permissions of files, ask your webhost to make the php.cgi script
executable for you, or make it executable with some PHP code (perhaps with the devel module’s
Execute PHP block).

60
3 Aug 2007 Drupal Handbook

3. Modifying your .htaccess file

Add this one line to your .htaccess file:

Action application/x-httpd-php5 /cgi-bin/php.cgi

This tells Apache to perform an action each time it encounters a file of file type
"application/x-httpd-php5" -- if you’re using a version of PHP older than PHP5, you’ll need to
change this to "application/x-httpd-php" (or upgrade to PHP5 -- ask your webhost).

Finally, scroll down to the part that says "# Protect files and directories from prying eyes" and
add "ini|" to the <FilesMatch> directive so it looks something like:

<FilesMatch
"(\.(ini|engine|inc|info|install|module|profile|po|sh|.*sql|theme|tpl(\.p
hp)?|xtmpl)|code-style\.pl|Entries.*|Repository|Root|Tag|Template)$">
Order allow,deny
</FilesMatch>

Notice the "ini|" on the first line? This will prevent your custom php.ini file (and anything else
ending in .ini) from being accessible to the entire world. (The character after the "ini" part is a
pipe, by the way, not an L.)

4. Test your site

Load up your website and see if it works. If it does, good job! If it doesn’t, go back to step 2 or 3
and check to see what version of PHP your site is using. You can also ask your webhost for help.

If you increased your post_max_size or upload_max_size, then look at your
admin/settings/uploads admin page and see how big your uploads can be. If you
increased your memory_limit, check phpinfo or devel module’s phpinfo() page at
admin/logs/status/php

Create Drupal database using Plesk
Create the database
Login and select Services » Databases

This loads a page with an overview of databases. Depending on your host a database may
already have been created. This is often the case with low-budget hosts, where you are limited to
one database. In that case, use table prefixing. If no limits exists it is best to create a new
database for Drupal via: Add New Database.

Click on the name of the database you wish to use. In the overview page you’ll see all users for
this database. Again, depending on your host, you need to create a new user via: Add New
Database User.

61
Drupal Handbook 3 Aug 2007

If you do not have the option to create new database users, use a pre-existing one.

Load the Drupal database scheme
From the database users overview page click DB WebAdmin

The icon is a blue stack with a monkey wrench. Note that this opens phpmyadmin in a pop-up
that may be blocked by your browser.

First make sure the relevant database is selected. If necessary, click Databases in the
phpmyadmin start screen and then the database name.

Go to the SQL screen via a small button labelled SQL in the left pane of the phpmyadmin screen.

If you’ve created a new user for the Drupal database, you need to grant priviliges to the user:
execute the SQL query:

GRANT ALL PRIVILEGES ON databasename.* TO username@localhost IDENTIFIED
BY ’password’;
where

’databasename’ is the name of your database
’username@localhost’ is the username of your MySQL account
’password’ is the password required for that username

This may not complete successfully; in that case you’ll have to assume / hope the user was
created with the necessary privileges.

To create the database layout, select the tab import files. Upload the file
database/database.mysql with the database scheme.

Drupal with safe mode enabled and open basedir
This is still undergooing some changes as I’m doing more tests...
But it works on a clean drupal 4.7.3 install...

I haven’t tested all modules yet, so please help me out...

Simply: use safe mode based on groups rather then owner and give access to my central code
base for virtual hosts so that open base dir works...

You need to be logged in using ssh as root...
And mind you my examples are from a plesk based system...
With a central code base located in /var/www/apps/drupal
and the virtual hosts directory in /var/www/vhosts/{domain}.{tld}/httpdocs/

1) create a group and a user called drupal...
After -d you can put any home directory you like, but I choose the directory where my drupal
code is installed...
after the passwd you need to give a GOOD password for the user...

62
3 Aug 2007 Drupal Handbook

groupadd drupal
useradd -d /var/www/apps/drupal -g drupal drupal
passwd drupal

2) Change the owner and the group of the single code base...
If you don’t have a single code base, only changing the group (chgrp) is enough

chgrp drupal -R /var/www/apps/drupal
chown drupal -R /var/www/apps/drupal

3) For the virtual hosts, change the group of the sites directory
Also all directories under sites should be chmod to 2775: 2 puts all new subfiles created
automatically into the group of the folder they are placed in (drupal in our case) + 7 for owner
(root or drupal or ftpusername) + 7 for group (drupal) + 5 for guests
If you have any more directories under sites, chmod them too

chgrp drupal -R /var/www/vhosts/{domain}.{tld}/httpdocs/sites
chmod 2775 /var/www/vhosts/{domain}.{tld}/httpdocs/sites
chmod 2775 /var/www/vhosts/{domain}.{tld}/httpdocs/sites/default

4) Add the users to the group
Plesk has a psaserv group don’t worry if you don’t have it...
The drupal group needs the psaadm and psaftp only if you run plesk

vi /etc/group
psaserv:x:2523:apache,psaftp,psaadm,drupal
drupal:x:10002:drupal,apache,psaftp,psaadm,{user_of_ftp_account_of_virtual_host}
restart service apache

5) correct the tmp dir by creating a sub directory and putting the drupal group and user on it...

mkdir /tmp/drupal
chmod 2775 /tmp/drupal
chgrp drupal /tmp/drupal
==> in admin change to /tmp/drupal

6) alter the code of file.inc so directories are made using 2775 rather then 775

find: @chmod($directory, 0775);
replace: @chmod($directory, 02775);
Actually my version of PHP has a bug and doesn’t put the 2!!!
I have to remember to chmod myself then...

7) change your virtual host settings of httpd.conf
In plesk this is done in: /var/www/vhosts/{domain}.{tld}/conf/vhost.conf
Other systems might have another place for the conf which is the configuration for your httpd
server..
With this code I have made sure that only the drupal directories benefit from group based safe

63
Drupal Handbook 3 Aug 2007

mode (safe_mode_gid)... all other directories still use the default safe mode
Remove the second DirectoryMatch in case you want all files and folders to benefit from group
based safe mode...
As I have a central code base in /var/www/apps/drupal, I need to add this dir to the open
basedir... and again only for the drupal directories off course...

#
# allow all documents below this dir access to drupal core
#
<DirectoryMatch "^/var/www/vhosts/{domain}.{tld}/httpdocs">
<IfModule sapi_apache2.c>
php_admin_flag safe_mode on
php_admin_flag safe_mode_gid on
php_admin_value open_basedir
"/var/www/apps/drupal:/var/www/vhosts/{domain}.{tld}/httpdocs:/tmp"
</IfModule>
<IfModule mod_php5.c>
php_admin_flag safe_mode on
php_admin_flag safe_mode_gid on
php_admin_value open_basedir
"/var/www/apps/drupal:/var/www/vhosts/{domain}.{tld}/httpdocs:/tmp"
</IfModule>
</DirectoryMatch>
#
# now limit for all directories below root that are not includes or
modules
# users want other apps installed too... so no access to drupal
#
<DirectoryMatch
"^(/var/www/vhosts/{domain}.{tld}/httpdocs/)(?!includes/|modules/).*/">
<IfModule sapi_apache2.c>
php_admin_flag safe_mode on
php_admin_flag safe_mode_gid off
php_admin_value open_basedir
"/var/www/vhosts/{domain}.{tld}/httpdocs:/tmp"
</IfModule>
<IfModule mod_php5.c>
php_admin_flag safe_mode on
php_admin_flag safe_mode_gid off
php_admin_value open_basedir
"/var/www/vhosts/{domain}.{tld}/httpdocs:/tmp"
</IfModule>
</DirectoryMatch>

64
3 Aug 2007 Drupal Handbook

Generic Mass SQL Import into Drupal
# General Notes for Mass Import into Drupal
#
# The below is a template for an SQL import file to programmatically
# add nodes into Drupal version 4.7.0.
#
# - Currently not tested on 4.7.3, but there does not seem to be any
# radical changes in the Database structure that would break this.
#
# - You will probably need to create a separate program to parse
# your existing content and create the needed looping structures
# to properly create the SQL import file for you system.
#
# - You must follow SQL rules for data entry, see your SQL
# documentation. Incorrect escaping will cause truncated fields.
#
# - Copyright ReasonToFreedom.com
# - Personal use: Free of charge.
# - Professional use: Only with USD $20 donated
# to Drupal.org per domain you use it on.*
#
# - This header and all copyright notices must remain intact
# upon any reprint/redistribution.
#
# - *Don’t stiff Drupal.org, if you’re using this professionally
# on five domains, you can afford to send Drupal.org $100.
#
# ======== Set Once Vars ==========
set @uid_value = 7; # Author ID (User ID)
set @format = 3; # 1 => Filtered HTML | 2 => PHP code | 3 => Full HTML
# ======== End Set Once Vars ==========
# ======== Set Per Node Vars ==========
/* set some variables to zero */
set @node_value = 0, @node_rev_vid_value = 0; # load these values as we
execute.
/* Set some default values */
set @title_value = ’The Title’;
/* May also set entry_date_time like curr_date_time below */
set @entry_date_time = unix_timestamp(’2002-05-20 12:00:00’); # get
specific date and time as number of seconds from 01/01/1970.
set @url_dest = ’the_url.html’;
set @teaser_value = ’<P>Teaser Para 1.</P>
<P>Teaser Para 2.</P>
’;
set @body_value = ’<P>Body Para 1.</P>
<P>Body Para 2.</P>

65
Drupal Handbook 3 Aug 2007

<P>Body Para 3.</P>
<P>Body Para, ad nauseam</P>
’;
set @curr_date_time = unix_timestamp(); # get current date and time as
number of seconds from 01/01/1970.
START TRANSACTION;
/* Increment node_nid field in sequences. */
update sequences set id = id + 1 where name = ’node_nid’;
/* Get new node_nid value from sequences for later */
select @node_value := max(id) from sequences where name = ’node_nid’;
/* Increment node_revisions_vid field in sequences. */
update sequences set id = id + 1 where name = ’node_revisions_vid’;
/* Get node_revisions_vid value from sequences for later */
select @revisions_value := max(id) from sequences where name =
’node_revisions_vid’;
COMMIT;
START TRANSACTION;
Insert into node
(nid, type, title, uid, status, created, changed, comment, promote,
moderate, sticky, vid)
VALUES
(@node_value, ’story’, @title_value, @uid_value, 1, @entry_date_time,
@curr_date_time, 2, 1, 0, 0, @revisions_value);
Insert into node_comment_statistics
(nid, last_comment_timestamp, last_comment_name, last_comment_uid,
comment_count)
VALUES
(@node_value, @curr_date_time, NULL, @uid_value, 0);
Insert into node_revisions
(nid, vid, uid, title, body, teaser, timestamp, format, log)
VALUES
(@node_value, @revisions_value, @uid_value, @title_value, @body_value,
@teaser_value, @curr_date_time, @format, "");
Insert into history
(uid, nid, timestamp)
VALUES
(@uid_value, @node_value, @curr_date_time);
Insert into node_counter
(nid, totalcount, daycount, timestamp)
VALUES
(@node_value, 1, 1, @curr_date_time);
COMMIT;
set @url_src = concat( "node/", @node_value ) ;
Insert into url_alias
(src,dst)
VALUES
(@url_src, @url_dest);

66
3 Aug 2007 Drupal Handbook

# ======== End Set Per Node Vars ==========
# ======== Set multiple Terms per Node ==========
/* set term_value and insert as many times as you need */
set @term_value = 50;
Insert into term_node
(nid,tid)
VALUES
(@node_value, @term_value);
set @term_value = 48;
Insert into term_node
(nid,tid)
VALUES
(@node_value, @term_value);
# ======== End Set multiple Terms per Node ==========
# EOF #

DrupalCon site

design contest entry over at the DrupalCon site and become immortal in the Drupal community.

How to degrade your Drupal db from MySQL 4.1.X/5.0.X to MySQL
4.0.X
I came across this issue when was developing a site for a client. I have MySQL 5.0.X at my
localhost and staging host but client’s hosting still uses MySQL 4.0.X.

So here is the solution:

0. Always make backup first.

1. Drop tables "accesslog", "cache" and "watchdog"

(DROP TABLE accesslog, cache, watchdog;)

2. Recreate tables from Drupal mysql dump for v4.0

CREATE TABLE accesslog (
aid int(10) NOT NULL auto_increment,
sid varchar(32) NOT NULL default ’’,
title varchar(255) default NULL,
path varchar(255) default NULL,
url varchar(255) default NULL,
hostname varchar(128) default NULL,
uid int(10) unsigned default ’0’,
timer int(10) unsigned NOT NULL default ’0’,
timestamp int(11) unsigned NOT NULL default ’0’,
KEY accesslog_timestamp (timestamp),
PRIMARY KEY (aid)

67
Drupal Handbook 3 Aug 2007

);
CREATE TABLE cache (
cid varchar(255) NOT NULL default ’’,
data longblob,
expire int(11) NOT NULL default ’0’,
created int(11) NOT NULL default ’0’,
headers text,
PRIMARY KEY (cid),
INDEX expire (expire)
);
CREATE TABLE watchdog (
wid int(5) NOT NULL auto_increment,
uid int(10) NOT NULL default ’0’,
type varchar(16) NOT NULL default ’’,
message longtext NOT NULL,
severity tinyint(3) unsigned NOT NULL default ’0’,
link varchar(255) NOT NULL default ’’,
location varchar(128) NOT NULL default ’’,
referer varchar(128) NOT NULL default ’’,
hostname varchar(128) NOT NULL default ’’,
timestamp int(11) NOT NULL default ’0’,
PRIMARY KEY (wid)
);
3. Make a dump for MySQL 4.0.X
mysqldump -u root -p -h localhost --compatible=mysql40 mydatabase >
mydatabase.sql

4. Upload this dump to your MySQL 4.0.X server.

5. Refresh your browser a couple of times. Enjoy!

How-To: Virtual Hosting with Drupal
Introduction

This book explaines how I’ve enabled Drupal hosting for my customers.
I hope it is helpfull for other Drupal hosters...

Environment

this is the environment used to setup my drupal hosting

linux RHEL 4
plesk 8.0.1
php 4.3.9
mysql 4.1.12
apache 2.0.52

68
3 Aug 2007 Drupal Handbook

drupal 4.7.x

Requirements

keep safe mode on at all times without the need for chmod 777
keep base dir restriction on at all times
integrate into plesk so that backup, databases, quotas,
etc keeps working
drupal must run as managed application
updates done once for all vhosts :: use single code base
approved modules and themes available for vhosts to select from
pre-activate drupal modules that enhance basic content management:
SEO, security, ...
eaccelerator must speed up php processing efficiently :: use single code
base
Each individual vhost
should be able to use its own themes and modules
should be accessible trough different URLs ::
drupal multisite option
should also be able to use other applications then drupal within the
same site
should experience drupal no different as if we would install drupal
for each vhost seperatly
Enhance security if needed on the drupal package
Single code base should be included in the normal backup mechanism available in plesk

Next pages

As the book seems to order the sub pages by date, I list here the order of further reading:

1. Solution overview: http://drupal.org/node/90144
2. Prepare environment: http://drupal.org/node/90207

How-To: Virtual Hosting with Drupal :: Prepare environment

Introduction

On this page I will explain some preparations of the environment like creating the drupal group,
a tempory files location, application reference location, etc.

Please read previous pages:

Requirements: http://drupal.org/node/80472
Solution overview: http://drupal.org/node/90144

69
Drupal Handbook 3 Aug 2007

The drupal group

As we will enable the safe mode in group mode, we are in need of a system group.
SSH into the server as SU (super user or root)

add the group

$ groupadd drupal
add the apache, psaftp and psaadm users to the group
the group id (10002) could be different
$ vi /etc/group
drupal:x:10002:apache,psaftp,psaadm

The temp directory

Also within the temp directory we need a matching group because uploaded files are
temporarly saved there and then copied to the final destination.
Therefore we will create a seperate directory and chmod it so that each file created their
automatically receives the drupal group. The latter is achieved by addin 2000 to the chmod
command.

$ mkdir /tmp/drupal
$ chmod 2775 /tmp/drupal
$ chgrp drupal /tmp/drupal
You will see an s appear instead of the x at the group part:
drwxrwsr-x 2 root drupal 4096 Oct 16 15:09 drupal

The reference location

This is a directory where all symlinks are placed that point to the current version of an
application. It is this location that all vhosts will reference so that they don’t depend on the
current version.
When switching versions, we only need to alter the symlinks at this location and all vhosts will
be updated automatically. See further pages for more info.
SSH into the server as SU (super user or root)

$ mkdir /var/www/apps

Navigation

As the book seems to order the sub pages by date, I list here the order of further reading:

Previous: Solution Overview: http://drupal.org/node/90144
Next: Single code base: Comming soon...

70
3 Aug 2007 Drupal Handbook

How-To: Virtual Hosting with Drupal :: Solution Overview

Introduction

On this page I will explain in general what solutions are provided for the different requirements

Please read previous Requirements page: http://drupal.org/node/80472

Safe mode

Enabling Safe Mode imposes several restrictions on PHP scripts. These restrictions are mostly
concerned with file access, access to environment variables and controlling the execution of
external processes.
There are problems which may be encountered when this mechanism is turned on, notably
when attempting to work with files owned by different users and files which have been created
at runtime by the script (which will be owned by the owner of the web server process).

In Plesk (and most other virtual hosts system) each vhost gets its own owner (FTP user) that is
set when files are uploaded to the server. As we want a single code base located in a central
place, the owner of the files within that central place will be different then the owner of the files
in the vhost’s location.

In order to work around these issues, a relaxed form of the file permission checking is also
provided by Safe Mode. Using the php.ini directive safe_mode_gid, it is possible to relax the
user ID check to a group ID check.
That is, if the script has the same group ID as the file on which a file operation was requested,
the operation will succeed. If the script owners and the web server are members of the same
group, and all hosted files are owned by this group, the file operations will succeed regardless of
user ID.

Thus, we will create a group "drupal" that will cover all drupal
related files accross vhosts and enable the safe_mode_gid. By doing so
we will still have a more secure system then when we would disable the
safe mode.

Information taken from here: http://www.acunetix.com/websitesecurity/php-security-5.htm

Open Basedir

Open Basedir limits the files that can be opened by PHP to the specified directory-tree, including
the file itself. This directive is NOT affected by whether Safe Mode is turned On or Off.

When a script tries to open a file with, for example, fopen() or gzopen(), the location of the file is
checked. When the file is outside the specified directory-tree, PHP will refuse to open it. All
symbolic links are resolved, so it’s not possible to avoid this restriction with a symlink.

71
Drupal Handbook 3 Aug 2007

In Plesk (and most other virtual hosts system) each vhost gets its own open_basedir restriction
that restruicts the opening of files to the httpdocs directory and the /tmp directory. As we want
a single code base located in a central place, that location will not be accepted trough this
restriction.

Thus, we will alter the open basedir restriction so that it includes
the single code base location. But as we want other applications to be
installed within the same vhost, we will add the location only for
directories using drupal.

Plesk integration

The plesk control panel works great as long as you keep the directory structure and security as it
is provided by plesk. Therefore we need to merge the single code base and each vhost within the
provided structure.

The single code base will be installed as a normal vhost but limiting
web access to the domain. As such a backup of the single code base can
be sheduled and FTP can be enable to upload new modules and themes.
Each vhost will have his own local "sites" directory and will create
its database trough the plesk interface.

Managed application

As the single code base resides as a single vhost, we can upgrade the code, add modules and
themes into one location. To make upgrading easier we need to make sure that each vhost that
uses drupal, references one single point independend of the drupal version.

We will make subdirectories per drupal version in the single code base
location and have one single reference that we can switch when going to
a new version.
Thus their will be a symbolic link called "drupal" pointing towards a
drupal version "drupal-4.7.3" and each vhost that uses drupal will have
symbolic links pointing towards the "drupal" symbolic link. When we
change version, we only need to change the "drupal" symbolic link once
and all vhosts will be adjusted accordingly.

eAccelerator

The eAccelerator speeds up the execution of the php script by precompiling them and putting
them into memory. The dissadvantage is that you need to have the memory and the more you
have the more php files can be kept for fast execution.
Therefore we need to limit the number of php files on the server.

By using the single code base, every vhosts uses the same files and
thus memory usage can be limited and all php scripts run faster.

72
3 Aug 2007 Drupal Handbook

more on eAccelerator can be found here: http://eaccelerator.net

Each individual vhost requirements

as noted above in the "Plesk Integration" part, each vhost gets his own "sites" directory that
enables them to add their own modules and themes. Also as natavely available by drupal, the
multisites mechanism will work for the same reason.
Using symbolic links and this "sites" directory will give the user the feeling that it is a full drupal
install on their system.

The local "sites" directory will allow the flexability required

Navigation

As the book seems to order the sub pages by date, I list here the order of further reading:

Previous: Requirements: http://drupal.org/node/80472
Next: Prepare environment: http://drupal.org/node/90207

HOWTO: copy a site to a local computer using XAMPP
Here are the steps you need to take to get a copy of a Drupal website onto your local computer
for development purposes, using the XAMPP stack and a variety of tools. Many of the steps
taken here have been made so that you can keep your PHP files outside the standard htdocs
DocumentRoot directory of the Apache server while maintaining whatever else you have
running on your XAMPP installation.

1) Install XAMPP software. This gets you Apache, MySQL and PHP all set up in a few clicks.
Skip this step if you have them already set up (Drupal needs things like php and mod_rewrite in
your Apache build.)

2) Download a copy of your production ’drupal’ database to your local MySQL server. If your
production server has phpMyAdmin you can export your database using it and then import
using your local phpMyAdmin. You may also use a program like Navicat MySQL since it
handles UTF-8 data properly (unfortunately my favorite free MySQL client, SQLyog, seems to
lack proper UTF-8 support).

3) Create a user on your local mysql database to match the remote connection settings and give
them full permissions:
% mysql> GRANT ALL PRIVILEGES ON drupal.* TO ’drupaluser’@’localhost’
IDENTIFIED BY ’drupalpassword’ WITH GRANT OPTION; FLUSH PRIVILEGES;

4) Get a copy of the production Drupal site files and folders (In my case, I use a source control
system client like Perforce) and copy them to a location you want to do your work in. An
example: C:/p4/atlas-drupal/drupal. I will call this location %your_drupal_files%
from here out.

73
Drupal Handbook 3 Aug 2007

5) Edit %your_drupal_files%/sites/default/settings.php and change the base URL
to $base_url = ’http://localhost/drupal’; You should still be able to leave the
$db_url connection setting alone.

6) Edit %your_xampp_location%\apache\conf\extra\httpd-xampp.conf and add the
following lines according to where your copy of drupal lives on your computer:

Alias /drupal "%your_drupal_files%/"
<directory "%your_drupal_files%">
AllowOverride AuthConfig FileInfo
Order allow,deny
Allow from all
</directory>
You’ll need that "FileInfo" directive if you are getting 500 errors in your Apache error log like
"RewriteEngine not allowed here". You could also add these lines in standard httpd.conf if
you are not using XAMPP but just plain Apache.

7) (Skip this step if you are using regular Apache and not XAMPP)
Edit %your_xampp_location%\apache\conf\httpd.conf and uncomment out the line
LoadModule rewrite_module modules/mod_rewrite.so You need this so Drupal can
have "clean links".

8) Edit %your_drupal_files%/.htaccess and change the RewriteBase to /drupal.

9) Restart the Apache service (with the XAMPP control panel if you are using XAMPP)

You now should be able to navigate to your sandbox development copy of the site via
http://localhost/drupal

HOWTO: Copy site to another directory for testing
System: Apache + PHP + MySQL + Linux

I had my site at, say, example.com and wanted to set up beta.example.com as a duplicate site to
test some ideas. This meant duplicating the database and code to a separate database and code
tree. That way I could modify beta.example.com without harming example.com.

In my case I’m on a virtual-private-server (same thing as a dedicated server) and have full
control over the system. If you’re on a shared hosting account the steps will be different.
Unfortunately the details of how share hosting accounts are setup vary so widely, I’m not going
to try and generalize the instructions for that.

1. In the DNS, create the beta.example.com subdomain. Remember it can take a little while for
the DNS entries to propogate properly.
2. Duplicate the database tables ... I’m on Mac OS X and used the navicat program to do so,
but you should be able to use mysqldump or other similar programs. That is, create a new
database and copy the tables and data from the example.com database to the one for

74
3 Aug 2007 Drupal Handbook

beta.example.com.
3. Make a directory for the docroot of beta.example.com, and copy the files as so:
(cd example.com/ROOT; tar cf - .) | (cd beta.example.com/ROOT; tar
xvf -)
If you only have FTP access this is a little harder. First FTP the files to your local computer,
then FTP those files into the new docroot directory. You can also edit the files on your local
computer, and then re-FTP them whenever you change something.
4. Config apache’s httpd.conf for a second VirtualHost with beta.example.com in it. Make sure
the VirtualHost entry for beta.example.com preceeds the one for example.com. Make sure the
docroot for beta.example.com is a different directory.
5. Edit sites/default/settings.php and change base_url and the database URL.
$base_url = ’beta.example.com’;
$db_url = ’mysql://username:password@localhost/new-database’;
6. It’s also helpful to override the site name so that the heading on the site glaringly reminds
you that you’re on the BETA site:
$conf = array(’site_name’ => ’BETA this sites name’);

HOWTO: Install Drupal 5.x using cPanel
Many hosting providers use a control panel to shield users from the complexity of their servers.
cPanel is one of those control panels. This small guide explains how to setup Drupal with
CPanel.

Not everything in this guide may be applicable to your situation, because some hosting
providers limit the options available to their users.

The basic assumptions: you have a domain name (http://www.example.com) and want to
install Drupal at the document root, (usually public_html or htdocs), where it is reachable via
the URL http://example.com or http://www.example.com. In order to accomplish this, the
Drupal files such as .htaccess and index.php have to be placed into your server’s document root,
along with the Drupal subdirectories such as includes, modules, themes, etc.

Note that other files present may be overwritten. Make backups before installing Drupal and
remove files that may interfere with installation (e.g. index.php or .htaccess). If the
pre-existing .htaccess file is necessary for other parts of your site, merge it with the one
provided with Drupal.

If you have folders with names like admin/, image/, blog/, etc., these can conflict with Drupal
and stop you from accessing areas of your Drupal site.

If your version of CPanel comes with Fantastico, you can use it to easily install Drupal.
However, this installation does not come with update.php, a file necessary for updating your
database when newer versions of modules are uploaded into your site.

Upload the Drupal files and folders

75
Drupal Handbook 3 Aug 2007

Download the newest version of Drupal.

Upload this to your hosting space using an FTP Program or CPanel’s built in File Manager.

Using the File Manager, extract the contents of the file: click on the file’s name and then select
extract in the menu that pops up on the right.

This will extract the entire archive into a folder named drupal-x.x.x. You will then need to move
the files out of this directory and into your document root directory (such as www or
public_html).

You can also extract all the files and upload them this way; however, this takes much longer.

Create a database

1. Open cPanel
2. Go to MySQL Databases
3. Choose a databasename* for the new database and press "Add Database"
4. Choose a username* and password for the new database user and press "Add User"
5. Grant permissions to the user; select the username and database name, check ’ALL’ and
press ’Grant permissions’

*Note: cPanel usually adds the cPanel username as a prefix to the newly created names.

Install Drupal

Drupal 5.x now comes with an automated installer. You no longer have to manually load the
database tables -- Drupal does it for you.

Go to http://www.example.com/install.php

Here you will be asked for the database name, database user, and password.

If you need to use this database for more than one installation of Drupal (such as with hosting
packages with a limited number of MySQL databases), you may want to click on the Advanced
options and select a prefix for the tables you will be creating (such as "site_" or "main_"),

This will then install Drupal for you, creating and filling all needed tables in your database.

Once it is complete, you can go onto your site and set up the first user.

Setting up your first user account

The first user in your site (often referred to as user/1) is the "super user" on your site. It is
automatically granted all admin and view permissions for your site. As such, it is important to
immediately register on the site, which creates the first user.

76
3 Aug 2007 Drupal Handbook

After submitting your user name and e-mail, you’ll be given the option of changing the
password for the account from the one the Drupal created for you.

Cron tasks

Many Drupal modules (such as the search functionality) have periodic tasks that must be
triggered by a cron job. To activate these tasks, call the cron page by visiting
http://www.example.com/cron.php -- this will pass control to the modules and the modules
will decide if and what they must do. To call cron.php periodically you need to setup a cron job.

cPanel offers a way to set cronjobs via Server » Cron jobs. Carefully read the instructions on
the screen; they may differ from the following example.

To run cron.php every day set the Minute and Hour fields to 0 and the rest of the fields to *. The
command to run is:

GET http://www.example.com/cron.php > /dev/null

Additional modules

Drupal comes with a limited number of modules. To expand the functionality of your Drupal
site, you’ll need to download and add modules to your site.

View the listing of modules and download the ones you want to use.

Be careful to only download those that are for Drupal 5.x, as earlier modules will not work with
your site.

Also, be sure to read the description, as some modules require additional modules to be
installed in order for them to work.

HOWTO: Install Drupal using cPanel
Many hosting providers use a control panel to shield users from the complexity of their servers.
cPanel is one of those control panels. This small guide explains how to setup Drupal with
CPanel.

Not everything in this guide may be applicable to your situation, because some hosting
providers limit the options available to their users.

The basic assumptions: you have a domain name (http://www.example.com) and want to
install Drupal at the document root, (usually public_html or htdocs), where it is reachable via
the URL http://example.com or http://www.example.com. In order to accomplish this, the
Drupal files such as .htaccess and index.php have to be placed into your server’s document root,
along with the Drupal subdirectories such as includes, modules, themes, etc.

77
Drupal Handbook 3 Aug 2007

Note that other files present may be overwritten. Make backups before installing Drupal and
remove files that may interfere with installation (e.g. index.php or .htaccess). If the
pre-existing .htaccess file is necessary for other parts of your site, merge it with the one
provided with Drupal.

Upload the Drupal files and folders

The first step is to download the drupal distritbution archive "drupal-x.x.x.tar.gz" onto your
local computer, and then unpack it using a program such as 7zip, WinZip, WinRAR or tar.

The second step is to upload the drupal files to your server. There are three options for
uploading the files, two that use cPanel’s built-in File Manager, and one that uses an FTP-client.
The latter depends on FTP access provided by your host.

FTP (easiest) - After unpacking the drupal archive on your local computer, upload the files
and folders in the resulting drupal-x.x.x directory to the document root of your webspace.
cPanels built-in File Manager, option 1 - After unpacking the drupal archive on your local
computer, recompress the files and folders in the resulting drupal-x.x.x directory into a zip
file or into a new tar file. The result should be that the top-level directory "drupal-x.x.x" is
no longer present in this archive. Upload this new archive to the document root on the
server and extract its contents. The Drupal files and folders should now be located in the
document root.
cPanels built-in File Manager, option 2 - Upload the entire drupal distribution archive
"drupal-x.x.x.tar.gz" to the document root of the server and extract its contents. Then use
File Manager to move all the files and folders in the resulting drupal-x.x.x directory to the
the server’s document root.

Because you need some files from the drupal archive in a later stage, it’s a good idea to
decompress it locally anyway.

Create a database

This step may not be necessary; some hosting firms provide only one pre-made database.

Before you proceed you should know:

"username" - the username for connecting to the database
"password" - the password for that username
"databasename" - the name of the database

1. Open cPanel
2. Go to Server » MySQL Databases
3. Choose a databasename* for the new database and press "Add Database"
4. Choose a username* and password for the new database user and press "Add User"
5. Grant permissions to the user; select the username and database name, check ’ALL’ and
press ’Grant permissions’

78
3 Aug 2007 Drupal Handbook

*Note: cPanel usually adds the cPanel username as a prefix to the newly created names.

Create database layout

1. Open phpmyadmin (Server » PhpMyadmin)
2. Select the newly created database
3. Depending on the phpmyadmin version select the tab SQL or import
4. Choose the file database/database.mysql and press ’Go’
5. Alternatively copy-paste the contents of database/database.mysql in the query
textfield and press ’Go’

Connecting Drupal
The default configuration file can be found in sites/default/settings.php. Before you
can run Drupal you have to set the database URL and the base URL to the website.

$db_url = ’mysql://username:password@localhost/databasename’;

Set the $base_url to match your websites URL:

$base_url = ’http://www.example.com’;

See INSTALL.txt for more information.
Modify settings.php locally, then upload the modified file. Alternatively use cPanels text-editor
to change the file on the server. Make sure to delete all trailing whitespace from settings.php
when using the latter option or you will encounter the infamous ’headers already sent’
warnings.

Create the first account
Point your webbrowser to your site (http://www.example.com/) and follow the instructions on
the welcome screen.

Cron tasks
Many Drupal modules (such as the search functionality) have periodic tasks that must be
triggered by a cron job. To activate these tasks, call the cron page by visiting
http://www.example.com/cron.php -- this will pass control to the modules and the modules
will decide if and what they must do. To call cron.php periodically you need to setup a cron job.

cPanel offers a way to set cronjobs via Server » Cron jobs. Carefully read the instructions on the
screen; they may differ from the following example.

To run cron.php every day set the Minute and Hour fields to 0 and the rest of the fields to *. The
command to run is:

GET http://www.example.com/cron.php > /dev/null

79
Drupal Handbook 3 Aug 2007

HOWTO: Site to site transfer with phpMyAdmin and a FTP Client
Preparation:

1) Turn OFF Clean URL’s function

FTP Steps: (for downloading and uploading Drupal program files)
Going to assume you have one and know how to use an FTP Client. FileZilla is free and popular.
This is pretty easy stuff and you probably already know most of it. If you don’t know it. DO
ânotâ recommend transferring site, as first lesson with FTP’ing.

NOTE: Do not delete old site until you are 200% sure new site is ok.

1. Download all the Drupal program files from OLD site, to local Hard Drive, using FTP
program. (Don’t worry about mySQL files yet)

2.

3. Be sure to get .htaccess too (it’s a Hidden File that can be found by checking the View
Hidden Files Box on FTP Client.

4.

5. Edit settings.php and cron scripts to reflect new site.

6.

7. FTP files to new site

phpMyAdmin Steps: (for mySQL export and import)
We’re going to assume you know how to use phpMyAdmin for the basic stuff. This is pretty
easy stuff and you probably already know most of it. If you don’t know it. I would ânotâ
recommend transferring my site, as my first lesson with phpMyAdmin

NOTE: Do not delete old site until you are 200% sure new site is ok.

Export:

1. Find database in phpMyAdmin

2.

3. Click the Export Tab (we’re going to do a dump of data to local hard drive)

4.

5. In the âExportâ box â check âselect allâ and be sure the radio button is checked for SQL

6.

80
3 Aug 2007 Drupal Handbook

7. Check the âStructureâ and âDataâ boxes

8. (this ensures that both the structure of the database and the tables, and the content you have
on site - is with you!)

Check âdrop tableâ (so that if the new site is installed already, you can install database on
top of that. "drop table" simply ensures that if the table exists - it will be replaced by the one
you backed up.)

Check âcomplete insertsâ ( to make sure it does not miss anything when rebuilding the site )

Check âSendâ box (this makes the data go to a file instead of the screen)

You can modify the File Name if you wish. (don’t recommend deleting anything that might
be in the file name box already â just add something to it. I usually add MonthDay â Mar09)

You can check âcompressionâ if you so desire.

Click the âGOâ button and you will soon see a pop-up asking you where to save file.

Importing: (with phpMyAdmin)

1. Find NEW database with phpMyAdmin

2.

3. Click the tab SQL (just like when you are adding a module)

4.

5. Go to the âOr Location of the text file:â (just like you would for adding a module)

6.

7. âBrowseâ to local hard drive and find file.

8.

9. Click âGOâ

81
Drupal Handbook 3 Aug 2007

10.

11. It’s going to take a few minutes for everything to come over.

Final process:

1. Check new site and I do mean check everything, until you’re bored

2.

3. Since I usually do this stuff at night. I check everything that night and then I check once
more in the morning. !Checking data is a lot faster than repairing or re-entering data :-)

4.

5. Turn Clean URL’s back on

Problems you might encounter

with phpMyAdmin

1. phpMyAdmin has some limitations on the size of file that can be transferred. My Host
has it set to 10Mb, others might be lower or higher limits. If file is bigger than limits you
have to make some choices.
2. You can save the file as âcompressedâ (but you might time out on the upload)
3. You can âEmptyâ (NOT DROP) a few of tables. Below are some the tables you might
want to think about cleaning up before you make data dump. (Not in any order.)
a. Aggregator Items (the data from news feeds)
b. Accesslog
c. Cache
d. Watchdog
e. Search_Index

with FTP (still working on this section)

NOTES:

1. If you run cron make sure to change this also in /scripts/cron-lynx.sh - so it points to
cron at new site.

Import a MySQL data dump with BigDump
What is BigDump?

Importing large SQL dumps (when replicating or moving a database) can be difficult for those
with only web access to the MySQL server. phpMyAdmin has certain shortcomings when
importing files of more than a modest size. BigDump can be a helpful utility in such cases. From
the BigDump website:

82
3 Aug 2007 Drupal Handbook

Staggered import of large and very large MySQL Dumps (like phpMyAdmin 2.x Dumps)
even through the web-servers with hard runtime limit and those in safe mode. The script
executes only a small part of the huge dump and restarts itself. The next session starts
where the last was stopped.

Setting up BigDump

Download BigDump from http://www.ozerov.de/bigdump.php. Once downloaded you need
to open the file bigdump.php in any simple text editor (or php editor) to modify the variables
required for your server and database.

Commencing at line 78 with "// Database configuration" you need to setup the usual variables
to connect to your database (same as are required for Drupal). There is one extra piece of
information which the script needs to work well and that is the name of the sql file to be used to
setup the database.
Tip: Make sure you upload the file containing the SQL export of your database and
bigdump.php to the same directory (root is best) on your webserver.

<?php
// Database configuration
$db_server = "localhost";
$db_name = "your_DB_name";
$db_username = "your_DB_user_name";
$db_password = "your_DB_password";
// Other Settings
// Specify the dump filename to suppress the file selection dialog
$filename = "the_file_you_wish_to_execute";
// Lines to be executed per one import session
$linespersession = 3000;
// You can specify a sleep time in milliseconds after each session
// Works only if JavaScript is activated. Use to reduce server overrun
$delaypersession = 0;
?>

Save the file once you have set the above (best in the same folder as your sql file backup).

Uploading the sql file and bigdump.php to the webserver

Open your FTP program and open a new session connecting to your webserver root directory
and the folder where the sql file and prepared bigdump.php reside on your computer.

Upload both files in ASC11 mode to the webserver root directory.

83
Drupal Handbook 3 Aug 2007

Running BigDump

Once the files are uploaded you simply need to connect to the bigdump.php script by using the
URL
http://www.your_domain.com/bigdump.php

If successfully connected bigdump will greet you with a screen like the below.

BigDump: Staggered MySQL Dump Importer ver. 0.21b
<a>Start Import</a> from "the_file_you_wish_to_execute.sql" into
"your_DB_name" at "localhost"
© 2003-2005 Alexey Ozerov - BigDump Home

If it all looks good (ie: all the relavent names are correct) then click "Start Import" and the
database will be setup by running in short automated stages to prevent server timeouts.

At the completion BigDump will notify you that it is finished.

That’s it! You have now copied, moved, migrated, synchronized or duplicated your mySQL
database. Well Done!

Thanks go to markus_petrux for the original tip about BigDump

Installing Drupal behind an Actiontec GT701-WG router
The popular Actiontec GT701-WG (and possibly other routers) DSL modem/router has a
peculiar behavior that affects how base_url must be set up in
sites/default/settings.php. The solution is to replace the PHP code that sets base_url
with some code that is available below.

Here’s the scenario: you are using computer A to access and use your Drupal site, computer B is
the server that is hosting the Drupal site, and both computers are plugged into a GT701 router,
which in turn is linked to the Internet. Internet users can access your server from the outside by
typing in www.example.com (because you set up port forwarding on the GT701). However, the
GT701 will not allow you to type that address in from computer A, because the GT701 interprets
such an action as a request to view the GT701’a administrative interface. Instead, you must type
in the local network IP address (usually 192.168.0.xxx) of computer B to access and use your
Drupal site.

However, this causes a problem because base_url is used by Drupal to create all the site’s
links. If base_url is set for www.example.com, you will be unable to use the site from computer
A (even if you type in the local IP). If base_url is set for the local network IP address, Internet
users will not be able to use the site.

In other words, base_url has to be different for internal network users (computer A) and
Internet users. To do this, replace the line $base_url = "http://www.example.com";
with the following PHP code:

84
3 Aug 2007 Drupal Handbook

<?php
$ipaddress = getenv(REMOTE_ADDR);
$local= strpos($ipaddress, ’192.168.’);
if ( $local=== false ) {
$base_url = "http://www.yourdomain.com";
} else {
$base_url = "local network IP address";
}
?>

Here, replace www.example.com with the actual URL and local network IP address with the
proper IP address (something like 192.168.xxx.xxx). It is possible that your local network IP
addresses do not begin with 192.168; in that case, you would need to change the code to look for
the local IP range accordingly.

With this setup, you can access the Drupal site using computer A by typing in Computer B’s
local IP address in your browser, while Internet users can continue to access it by typing in
www.example.com

Installing Drupal in a subdirectory in 4.6
If you install Drupal in a subdirectory, you need to alter the .htaccess file in Drupal’s root.

Change ErrorDocument to:

# Customized server error messages:
ErrorDocument 404 /subdirectory/index.php

Change RewriteBase to:

# Modify the RewriteBase if you are using Drupal in a subdirectory
and the
# rewrite rules are not working properly:
RewriteBase /subdirectory
Remove any #’s in front of the RewriteBase line in case it’s commented out.

Make sure your $base_url in conf.php is set correctly as well.

More than one Drupal site on one machine
There are several possible configurations for running multiple Drupal servers on the same
hardware. You can separate them by directories or by vhosts, they can share configurations or
split them or, in some cases, have a mixture, but all of these methods have at their heart the
./sites/domain_or_host_name/settings.php configuration file and the
search-sequence where the Drupal program will search first for a configuration named for the
current page and then to the current host before settling for the default.

85
Drupal Handbook 3 Aug 2007

General rules for multiple Drupal deployments

Each of the possible multi-drupal scenarios is discussed in more detail in the sections that
follow, but the general form for the alternate configuration filename is:

./sites/<i>vhost.uri</i>/settings.php

Note how the path separator (’/’) must be changed to a dot. As an example, the vhost
drupal.mysite.net may have one primary drupal server at the DOCUMENT_ROOT location,
but a second site may begin at DOCUMENT_ROOT/altserver. For this case, the configuration
file would be ./sites/drupal.mysite.net.altserver/settings.php

Within that configuration file, the most common and minimal option is to set the $db_url that
specifies the host, database and login for the Drupal tables, as well as the $base_url. But you can
also include assignments to override anything in the VARIABLES table. This allows you to
redefine the theme, the site footer and contact email, blocks per-page limits, even the name you
use for anonymous.

Drupal IDs: When using multiple drupal servers on the same hardware, each new configuration
will result in a new host component for the username@<i>host</i> Drupal login ID (used
when logging into a foreign Drupal server). For example, if you have a directory partitioned
host at drupal.mysite.net/altserver your usename to login to some other Drupal server
would be USENAME@drupal.mysite.net/altserver.

Prefixing Database Tables to put them in One Database If you only have one database then it
is necessary to use database table prefixing. See this handbook page for details on how to
achieve that.

Moving your Drupal installation to a new directory
If for instance you need to move your installation from www.mysite.com/development/ to the
root directory of www.mysite.com, just follow these simple steps:

Copy Files

Copy the files of your Drupal installation from the old directory to your new directory.
Make sure you include .htaccess.

Change Path

In your new directory, open the file (4.5 or earlier) includes/conf.php or (4.6)
sites/default/settings.php

Look for a line that begins with "$base_url = ", update this so that $base_url equals the path
to your new directory. Save the file and close it.

86
3 Aug 2007 Drupal Handbook

You might need to modify the .htaccess file as well.

Update Cron

If you set up Cron on your old installation, make sure you update it to point to your new
installation.

Delete Old Directory

Test that everything is working in your new installation. If so, it is now safe to delete the
files in your old Drupal directory.

PCRE_UTF8 solution for VPS servers | FreeBSD
installation PROBLEMS? - PCRE_UTF8 support on VPS server accounts? Look here!
I receive the same error on every page with a basic install however everything seems to be
functioning otherwise fine.

warning: preg_match(): Compilation failed: this version of PCRE is not
compiled with PCRE_UTF8 support at offset 0 in
/home/brandform/www/drupal.brandform.net/includes/unicode.inc on line
32.

The solution was much more difficult to find than i had hoped so maybe this post will be
useful to some others as well.
I had to uninstall the pcre package and reinstall the proper one with utf-8.
heres the procedure:

login to server via shell,
on VPS2 accounts,
# su root
then type password
basically you want to be root user.
then type:
# pkg_info
which will show you the installed packages.
type:
# pkg_delete pcre-6.4
for me it was 6.4 but yours may be different. make sure to enter the proper version of pcre
displayed in pkg_info.
then you want to change to the directory where your ports collection is.
on FreeBSD it is:
/ports/devel/pcre-utf8
so type into your shell prompt:

# cd /
# cd ports/devel/pcre-utf8
# make

87
Drupal Handbook 3 Aug 2007

# make install
# make clean
then youll want to restart the apache server...
something like this:
# restart_apache

thats it...
fixed everything for me.
after over a day of pulling my hair out and almost abandoning the effort......

Known causes of PCRE server errors

In the event that you see the following error:

warning: preg_match: internal pcre_fullinfo() error -3 in
/SERVER_PATH/includes/common.inc on line 592.

Be aware that this issue exists at the server level, outside of Drupal code. Put plainly, the error
means that the server’s PCRE (Perl Compatible Regular Expression) library is not configured
correctly.

This error may be caused any time a Drupal module calls a PCRE function. Typically, the error
appears within common.inc, but this is not always the case.

Depending on the server environment, there are several different causes (including a reported
bug in some versions of PHP 5).

This manual page is designed to capture known instances of this bug,

Known Causes

An upgrade of RedHat included a bad library and required a patch. (Details to follow)

Recommendations

Send the content of the error to your system admin and have them debug your PHP’s PCRE
module.

Redirecting specific pages to new URLs (301 redirects in Drupal)
If you are porting over an existing website to Drupal, one consideration is how you redirect the
old page URLs to the appropriate pages on the Drupal version of the site. If you don’t want to
create custom rewrite paths within Drupal for those nodes -- or perhaps cannot due to clean
URLs or filename suffixes -- then 301 redirects are considered the best way to handle redirected
pages, for they inform search engines to update their databases with the new paths. This way,
you should not risk your search engine pagerank or lose site visitors with 404 "not found"
errors.

88
3 Aug 2007 Drupal Handbook

However, 301 redirects cannot be done using the common approach. Yet establishing 301
redirects is quite easy, provided you have mod_rewrite enabled in your .htaccess file.

How to create 301 redirects in Drupal Apache mod_rewrite

Edit your .htaccess file in a text editor. [Note: Be sure to save the file in "UTF-8" format.]

In the file, you will find the commands:

# Various rewrite rules.
<IfModule mod_rewrite.c>
RewriteEngine on
# Modify the RewriteBase if you are using Drupal in a subdirectory
and
# the rewrite rules are not working properly.
#RewriteBase /drupal
RewriteBase /

Immediately after that code -- and before the Drupal-provided "Rewrite old-style URLs"
commands -- add your rewrite rules using the following format:

#custom redirects
RewriteRule ^old/URL/path$ http://yourdomain.com/new/path [R=301,L]
#end custom redirects

Note the convention: The old path is simply the path off the root. The new path is the full path,
including the domain. The [R=301,L] code is the 301 redirect instruction. (axbom notes: "The 301
tells browsers and spiders it is a permanent redirect, and the L ensures that no other rewrites are processed
on the URL before it reaches Drupal; Hence place this code above Drupal ’s own URL rewrite, but below
the command RewriteEngine on.")

If you have more paths to add, insert the rewrite commands as their own line as above.

For more information, see the forum thread at http://drupal.org/node/16084 [from where I
drew this information]

The tolerant base URL
Note: 4.7 already has this feature built in

Instead of using a hard coded domain as your $base_url in the settings.php file, you might want
to use

<?php
$base_url = ’http’ . (isset($_SERVER[’HTTPS’]) ? $_SERVER[’HTTPS’] ==
’on’ ? ’s’ : ’’ : ’’);
$base_url .= ’://’ .$_SERVER[’HTTP_HOST’];
if ($dir = trim(dirname($_SERVER[’SCRIPT_NAME’]), ’\,/’)) {

89
Drupal Handbook 3 Aug 2007

$base_url .= "/$dir";
}
?>

This has the advantage that whatever domain the user used to get to the site, he will maintain
throughout his session.

Warning

Email notifcations may be issued under the domain which is used by the poster. If you
access your site using http://localhost, you could send emails with that invalid URL. The
only module which behaves this way today that I know of is subscription.module from
Contrib.

Using .htaccess to stop page caching
If your Drupal site is being accessed on a LAN with a proxy server to cache pages, you may find
that user identities become confused. A user may login under their username, but when they
access another page, the proxy server sends the cached page of another user, effectively
switching the identities of the user as far as Drupal is concerned.

Proxy servers can be instructed to stop caching pages for a Drupal site using HTML Meta Tags
and/or HTTP Headers. While using meta tags may be more convenient (one need only modify
the theme header), some proxy servers only respond to instructions embedeed in the HTTP
headers sent by the webserver. Apache webservers can use mod_expires to send this instruction.
Assuming that mod_expires is enabled on your web server, try adding the following lines to
your .htaccess file to stop the proxy server from caching Drupal pages:

ExpiresActive on
ExpiresDefault "access plus 0 seconds"

Linux specific guidelines
Installing PHP, MySQL and Apache under Linux
Installing MySQL shouldn’t be too much of a burden, when using a Linux distribution that can
handle RPMs. All you have to do is grab the RPMs from the MySQL website. Please do note that
you’ll also need the MySQL client RPM, not only the MySQL server one. Once MySQL has been
installed, download Apache and PHP, and unpack them in the same directory. To install Apache
together with PHP and MySQL, follow the "quick install"-instructions in the INSTALL-file
located in your PHP directory. When configuring PHP do not forget to replace ’apache_1.3.x’
with your version of Apache.

After the compilation process you have to set the DocumentRoot in Apache’s httpd.conf to the
path of your drupal-directory. Make sure your Apache is setup to allow .htaccess files so drupal
can override Apache options from within the drupal directories. Therefore, set AllowOverride to
"All" instead of "None". Somewhat down httpd.conf they ask you to set Directory to whatever

90
3 Aug 2007 Drupal Handbook

you set DocumentRoot to. The last thing to do is to add index.php in IfModule mod_dir.c behind
DirectoryIndex. Apache will then look for index.php in the DocumentRoot and will display it as
its main page.

XAMPP for Linux Packages
The distribution for Linux systems (tested for SuSE, RedHat, Mandrake and Debian)
contains: Apache, MySQL, PHP & PEAR, Perl,ProFTPD, phpMyAdmin, OpenSSL, GD,
Freetype2, libjpeg, libpng, gdbm, zlib, expat, Sablotron, libxml, Ming, Webalizer, pdf class,
ncurses, mod_perl, FreeTDS, gettext, mcrypt, mhash, eAccelerator, SQLite and IMAP
C-Client.

Installing XAMPP in Debian

Download XAMPP Latest version from the following link

http://sourceforge.net/project/showfiles.php?group_id=61776&package_id=6...

At the time of writing this article XAMPP version is 1.5.3a

#wget http://kent.dl.sourceforge.net/sourceforge/xampp/xampp-linux-1.5.3a.tar....

Now you should be having xampp-linux-1.5.3a.tar.gz file in your downloaded location

Go to a Linux shell and login as root:

$su -

Extract the downloaded archive file to /opt

#tar xvfz xampp-linux-1.5.3a.tar.gz -C /opt

XAMPP is now installed below the /opt/lampp directory.

Start XAMPP Server

To start XAMPP simply call this command:

#/opt/lampp/lampp start
Starting XAMPP for Linux 1.5.3a...
XAMPP: Starting Apache with SSL (and PHP5)...
XAMPP: Starting MySQL...
XAMPP: Starting ProFTPD...
XAMPP for Linux started.

Test Your XAMPP Installation

91
Drupal Handbook 3 Aug 2007

OK, that was easy but how can you check that everything really works? Just type in the
following URL at your favourite web browser:

http://localhost

XAMPP Security Configuration

As mentioned before, XAMPP is not meant for production use but only for developers in a
development environment. The way XAMPP is configured is to be open as possible and
allowing the developer anything he/she wants. For development environments this is great but
in a production environment it could be fatal.

Here a list of missing security in XAMPP:

The MySQL administrator (root) has no password.

The MySQL daemon is accessible via network.

ProFTPD uses the password "lampp" for user "nobody".

PhpMyAdmin is accessible via network.

Examples are accessible via network.

MySQL and Apache running under the same user (nobody).

To fix most of the security weaknesses simply call the following command:

#/opt/lampp/lampp security

It starts a small security check and makes your XAMPP installation more secure.

Start And Stop Server Services

start

Starts XAMPP.

stop

Stops XAMPP.

restart

Stops and starts XAMPP.

startapache

92
3 Aug 2007 Drupal Handbook

Starts only the Apache.

startssl

Starts the Apache SSL support. This command activates the SSL support permanently, e.g. if you
restarts XAMPP in the future SSL will stay activated.

startmysql

Starts only the MySQL database.

startftp

Starts the ProFTPD server. Via FTP you can upload files for your web server (user "nobody",
password "lampp"). This command activates the ProFTPD permanently, e.g. if you restarts
XAMPP in the future FTP will stay activated.

stopapache

Stops the Apache.

stopssl

Stops the Apache SSL support. This command deactivates the SSL support permanently, e.g. if
you restarts XAMPP in the future SSL will stay deactivated.

stopmysql

Stops the MySQL database.

stopftp

Stops the ProFTPD server. This command deactivates the ProFTPD permanently, e.g. if you
restarts XAMPP in the future FTP will stay deactivated.

security

Starts a small security check programm.

For example: To start Apache with SSL support simply type in the following command (as root):

#/opt/lampp/lampp startssl

You can also access your Apache server via SSL under https://localhost.

Important Configuration Files And Directories

opt/lampp/bin/ - The XAMPP commands home. /opt/lampp/bin/mysql calls for example the
MySQL monitor.

93
Drupal Handbook 3 Aug 2007

/opt/lampp/htdocs/ - The Apache DocumentRoot directory.

/opt/lampp/etc/httpd.conf - The Apache configuration file.

/opt/lampp/etc/my.cnf - The MySQL configuration file.

/opt/lampp/etc/php.ini - The PHP configuration file.

/opt/lampp/etc/proftpd.conf - The ProFTPD configuration file. (since 0.9.5)

/opt/lampp/phpmyadmin/config.inc.php - The phpMyAdmin configuration file.

If you want to confiure apache2 you have to use /opt/lampp/etc/httpd.conf(If you want to
change Apache DocumentRoot directory you can chage in this file).If you want to configure
namebased and ip based virtual hosts check here

If you want to configure proftpd check here

If you want to configure mysql check here

Stopping XAMPP

To stop XAMPP simply call this command:

#/opt/lampp/lampp stop

You should now see:

Stopping LAMPP 1.5.3a...
LAMPP: Stopping Apache...
LAMPP: Stopping MySQL...
LAMPP: Stopping ProFTPD...
LAMPP stopped.

And XAMPP for Linux is stopped.

Uninstall XAMPP From your Machine

To uninstall XAMPP just type in this command

#rm -rf /opt/lampp

Windows-specific guidelines
Several packages exist which install Apache, PHP, and MySQL in one easy download. These
include the following:

94
3 Aug 2007 Drupal Handbook

ApacheFriends XAMPP
Miniserver
Foxserv
PHPHome

If you want to install them separately, see the guidelines below.

How to install Drupal for newbies using FTP and phpMyAdmin
There are three things to do: upload the database, get drupal ready and change "/tmp" on your
drupal site.

Change "/tmp" on your drupal site.

1. Open a browser and go to your new drupal site, whatever its domain is.
2. Create a new user account. You enter a username and password and now you are the admin
for your new site.
Important: the first user you create has access to every administration setting on your
Drupal site.
3. On the left side of your screen, there is a link, "administer." Click "administer," then
"settings."
4. Scroll down to "File system settings" and in the "Temporary directory" field you will see
"/tmp." Remove the "/" from in front of "tmp." So now in "Temporary directory" the field
should only contain "tmp." Click "Save configuration," at the bottom of the screen.

Get Drupal ready

1. Download Drupal
2. Extract Drupal to your desktop (or wherever you like on your computer). You need to have
a program like 7-zip or Winzip installed first. You will have to extract the files twice.
3. Edit conf.php. It’s in the drupal-4.5.2/includes directory after you extract the files. You have
to edit two lines in this file.
4.
To edit the file, you may need to load your text editor (Windows comes with Notepad
and Wordpad, either of which will do fine) first then find the file by clicking the File
menu, then Open.
5. Change: $db_url = "mysql://user:password@localhost/drupal";
You must replace "user" and "password" with your username and password for your
phpMyAdmin login and "drupal" with your database’s name.
6. Change: $base_url = "http://www.example.com";
You must replace "example.com" with your domain name.
7. Put drupal on your server. You need an FTP program like FileZilla.
Open your FTP program and navigate to the directory where your index.htm file
would normally go. This is usually called public_html/ or www/ This is where you
put the drupal files. The drupal files that go there are the contents of drupal-4.5.2, that
you extracted. You don’t put the folder itself on the server, just the contents. That

95
Drupal Handbook 3 Aug 2007

means you are uploading six folders (database, includes, etc.) and ten files (.htaaccess,
cron.php, etc.).
8. Create a new directory on your server.
In your FTP program, right click on the server side, select "create directory" and name
the new directory "files." You want "files" in the main directory. After you create it, you
should see it in between "database" and "includes."
9. Now you open up your new directory, "files," and create a new directory inside called,
"tmp."
10. Change the file attributes of both "files" and "tmp" by right clicking on them one at a time,
selecting "file attributes" and entering "755" in the "numeric value" field (if you see errors on
your drupal site later saying "files" and "tmp" are not writeable you have to change the file
attributes to "777," which is less secure).

Upload the database

1. Login to your phpMyAdmin (on your server).
2. Click "Create new database."
3.
- name it "drupal" (or whatever you like).
4. You should see "drupal" at the top of the left column. Click "drupal."
5. In the center column you should see some tabs to choose from. Click "SQL."
6. At the bottom of the box that comes up it says, "Location of the textfile:" and there’s a button
that says, "Browse". Click "Browse" and navigate to the file "database.mysql." Its on your
computer inside the folder you extracted, "drupal.4.5.2," inside the "database" folder. Select
"database.mysql" and click "open."

HOWTO: Create an apache sandbox using Windows and
Apache2Triad
One of the most useful and productive techniques for working with Drupal is to install it on
your own computer. Having Drupal installed on your local computer allows you to rapidly
prototype Drupal sites using any combination of contributed modules and themes, dry-run
upgrade installations of Drupal without interrupting production sites, and perform any other
Drupal task much more quickly by allowing you to work locally instead of remotely. This
tutorial addresses a simple method of setting up a web server on your own computer that
functions identically to many commercial web hosting services, however it is not intended as a
tutorial for turning your computer into a web server or using it to host a site. This tutorial
focuses on installing the web server software as a means of working on a copy or prototype
Drupal site, i.e. the result is not part of the internet, and can’t be accessed from the internet. The
advantage is that the software runs much faster on your own computer.

While Drupal will work with Microsoft’s Internet Information Services (IIS), this tutorial will
focus on a specific package, apache2triad, available for download from sourceforge.net. Though
all that is needed to run Drupal is a web browser, apache, PHP4 (4.3.3) or higher and mySQL,
apache2triad comes with a variety of other features that will not be covered in this tutorial.

96
3 Aug 2007 Drupal Handbook

Best of all, however, apache2triad requires no additional configuration in order to set up and
install Drupal, making it an ideal choice for novice web site creators wishing to learn to set up
and use a Drupal site with only very modest skills and almost no previous experience.

Tools needed to complete this tutorial:
A web browser.
An archive program capable of extracting .tar and .gz files, such as 7-Zip.
An FTP client like coreFTP (optional).

Before you begin

Apache2Triad comes in three different configurations; a legacy version for Windows 9x systems,
and PHP4 and PHP5 versions for Windows XP. If you intend to work on a copy of Drupal that
you plan to transfer to a production server provided by your web hosting service, you may wish
to find out which versions of PHP and MySQL are installed. If your web hosting service is
currently providing PHP/MySQL 4.x, you may wish to download the corresponding version of
Apache2Triad, in order to avoid compatibility issues. If so, you may also wish to inquire your
hosts’ timetable for upgrading PHP and MySQL since 4.x versions are no longer supported by
their respective development teams.

As of this writing, the following versions of Apache2Triad were available for download from
Sourceforge:

Edge (Apache2.2 PHP5 MySQL5) v1.5.4 95.8MB space required 348.7MB
Stable (Apache2.0 PHP4 MySQL4) v1.4.4 75.3MB (somewhere between "edge" and "legacy")
Legacy for Win9X (limited Apache2.0 PHP4 MySQL4) v1.2.3 48.0MB space required 200.3MB

While each version of Apache2Triad shown has been tested with various versions of Drupal in
recent years, this tutorial focuses on using the "edge" version as installed under Windows XP.

Installing Apache2Triad

1) Download the version of Apache2Triad that best suits your needs.
2) Double-click the icon from the file you downloaded. This opens a small configuration window
to begin the Apache2Triad installation. Leave the default settings as they are and click the button
labeled "next".
3) The next dialog window allows you to set the destination folder, which for most people will
be "C:\apache2triad", but it works equally well installed wherever you like (provided there is
room available, see space requirements above). It is recommended that Apache2Triad be
installed at the "root level" of the drive chosen, for example, "C:\apache2triad" as opposed to
"C:\Program Files\apache2triad\", as this will save you typing later on.
4) The next dialog asks you to set a password of no less than eight characters. It will be
important to know this password as you will need it later on. Select an eight character password
(ideally one easily remembered), write it down, then click the button labeled "next", then the
button labeled "I Agree" on the following dialog to complete the license agreement and begin the
installation.
5) After the files have been installed to the directory of your choice, a dialog will open that alerts
you that post configuration is needed. Click the button labeled "OK" to continue. Several

97
Drupal Handbook 3 Aug 2007

windows will open and close as the installer automatically configures most options for you,
eventually stopping at a CMD window asking you to type your password from step 4. Do so
now and press the "enter" key; post-configuration will complete itself, and at last open a window
requesting that you reboot, which is necessary to start apache, php and mysql as Windows
services.

Note that depending on how Windows is configured for your computer, you may notice that
there is now a "user" account named apache2triad; ignore this and log on with your regular
account.

Installing Drupal

1) Obtain a copy of Drupal 4.6x, 4.7.x or 5.0 (cvs) from drupal.org as well as any contributed
modules or themes you wish to use.
2) Use your archive program to extract any files from step 1; note that because the files are stored
in both .gz and .tar formats, it may be necessary to extract them twice. You may wish to create a
directory named DrupalX, where ’X’ is the version of Drupal, and unarchive your files to this
location in order to stay organized; by copying the files you wish to use instead of using the
originals, it is safe to move the archived versions to the recycle bin if you like.
3) Browse to the location you installed Apache2Triad and open it’s folder, then look for the
folder labeled "htdocs". This folder is where you will place your Drupal files in order to access
them through apache and your web browser. You may wish to place a shortcut to htdocs on
your desktop, or create a shortcut in a toolbar with bookmarks and other shortcuts to tools. See
the Support and Help Center under the Start Menu for details about how to accomplish these
tasks.
4) For purposes of this tutorial, Drupal was extracted to drupal-4.7.3 and drupal-cvs in order to
illustrate their installation. Note that the installation procedure for Drupal 4.6.9 is identical to the
one for Drupal 4.7.3. Note that in doing so, Drupal is being installed to a sub directory and
follows installation procedure accordingly. If Drupal were to be installed at the "document root"
level of the server, the files inside the drupal-x folder extracted themselves would be place in the
htdocs folder inside the Apache2Triad installation. In this tutorial, the whole folder is placed in
htdocs (for simpler organization) and this affects how Drupal will be configured in later steps.

Note that you may also use the folder name of your choice, such as the sub directory used on
your web hosting server, "sandbox" or anything else that makes sense for your project.

Copy the folder you have created (or the files inside it to htdocs, if you want to install to the
"document root") now.

5) Open your favorite web browser, select the text in the address bar and type:

http://localhost/phpmyadmin/

This will load the PHPMyAdmin logon page, which will ask for a username and password; the
username is "root" and the password is whatever you selected when Apache2Triad was
installed. Enter these now.
6) This will load the PHPMyAdmin main page. At this stage of this tutorial, it is useful to
provide a brief introduction to PHPMyAdmin, which is also discussed in the Drupal handbook

98
3 Aug 2007 Drupal Handbook

section How to install Drupal for newbies using FTP and phpMyAdmin. For intents and
purposes, PHPMyAdmin is a tool used to create, backup and restore MySQL databases.
Although it has considerably more sophisticated features, this tutorial focuses only on those
needed to complete a given task.
7) Select a database name and type it into the text field labeled "create database", then click the
button labeled "create". The next steps vary depending on whether 5.0 or 4.7.x or earlier is being
installed. If you are installing 5.0 from scratch, you may skip the next step. For purposes of this
tutorial, databases named drupal-4.7.3 and drupal-cvs were created (if creating multiple
databases, click the ’home’ button to the left of the PHPMyAdmin page to return to the database
creation page). Minimize your browser (we’ll come back to it, later) before moving on to the next
step.
8) Open your htdocs folder and look for the folder labeled "sites" if you installed Drupal to your
document root, or inside the Drupal folder you created earlier, if you are installing Drupal 4.7.x
or earlier. Here it is necessary to open the settings.php file and specify the installation options
described in the INSTALL.TXT file that came with Drupal. Note that if you require multiple
Drupal installations to use the same copy of Drupal, you should modify the settings.php file
according to your configuration requirements. For single-version Drupal sites, the settings.php
file you’ll want to use is in the folder labeled "default". Right-click the settings.php file with your
mouse, select "open with" from the context menu, and select "notepad" from the application list.

Depending on how you have Drupal configured, your settings.php file entries will vary,
however the entry:
$db_url = ’mysql://root:password@localhost/drupal-4.7.3’
will use "root" in place of the username and the password you selected when installing
Apache2Triad. Don’t forget to set the entry for $base_url if you did not install Drupal to
document root to the folder name you installed Drupal to. For example:
$base_url = ’http://localhost/drupal-4.7.3’; // NO trailing slash!

IMPORTANT
"localhost" must be substituted for "www.example.com" in order to work on your local machine.

For those working on copies of Drupal that will be hosted on production servers, it is handy to
keep two copies of your settings.php entries, one for local use and one for remote use. This way,
you can switch between configurations just by commenting or uncommenting the appropriate
lines, for example:

# Remote setting:
# $base_url = ’http://www.example.com/drupal-4.7.3’; // NO trailing
slash!
# Local setting:
$base_url = ’http://localhost/drupal-4.7.3’; // NO trailing slash!

Once your settings.php file’s entries are correct, restore your browser window and locate the
PHPMyAdmin page tab labeled "import" and click the button labeled "browse". For Drupal 4.7.x
and earlier, the database that will be imported will be in the database folder, which will be in
htdocs under the Apache2Triad installation you created earlier. Browse to that folder and select
the appropriate sql file: database.mysql for Drupal 4.6.x, database.4.0.mysql for Drupal 4.7.x and

99
Drupal Handbook 3 Aug 2007

MySQL4 (Apache2Triad "stable" installation), and database.4.1.mysql for PHP5. Note that it is a
good practice not to mix MySQL 4 and MySQL 5 databases in order to avoid potential
compatibility conflicts. Click the "Go" button on the MySQL database to import the database
you’ve selected.
9) The next step will depend on where you installed Drupal in your htdocs folder. Select the text
of your address bar in your web browser and type:
http://localhost/drupal-cvs/
substituting "drupal-cvs" for the folder name you used in htdocs or omitting it if you installed to
document root.

If you are installing Drupal 5.x, this will open the Database configuration page for your new site,
which will prompt you for a database name (the one you created with PHPMyAdmin earlier), a
username (root) and a password (the one you created when you installed Apache2Triad). Enter
these now: if your Drupal installation uses a database prefix, select the advanced option and
enter the prefix at this time. Select the appropriate radio button, depending on if you are
installing the MySQL or PGSQL version of the database (most likely MySQL). Click the "save
configuration" button and your installation is complete. You will be taken to the welcome screen
where you will create the first user logon for your new site.

Drupal 4.7.x users will be taken directly to the welcome page to create the first user logon
directly.

Importing and exporting Drupal databases updated with PHPMyAdmin

There are certain circumstances when you may wish to work on a site that is a copy of one
running on a production server, backup the database, and perform other tasks specific to
making changes to your databases. This section of the tutorial focuses on using PHPMyAdmin
to do so. If PHPMyAdmin is not available on your hosting provider’s server for you to use, you
may be able to install it yourself if it is unavailable; check with your hosting service to find out
what your options are if you are unsure.

Because any possible task is going to entail some permutation of exporting, copying and/or
importing databases from one a remote server to your personal computer, this section of our
tutorial focuses on two basic operations within PHPMyAdmin that have tabs labeled
accordingly; "import" and "export".

To export a database with PHPMyAdmin

1) Using your web browser, browse to the PHPMyAdmin location of the server where the
database you wish to export resides. For example:
http://www.example.com/phpmyadmin/
for a remote database and
http://localhost/phpmyadmin/
for a database hosted on your Apache2Triad installation. Select the name of the database you
wish to export from the combo box on the left side of the page and you will be taken to that
database’s main operations page. Next, click the tab labeled "Export" and you will be taken to
the Export database page.
2) Fill out the sections of the form located on the Export database page as follows:

100
3 Aug 2007 Drupal Handbook

a) Click the link marked "select all" in the group labeled "Export" to select all of the tables in the
database for export. The radio button selected below should be "SQL".
b) Select the check box labeled "add DROP TABLE" in the group labeled "Structure". The check
boxes labeled "Add AUTO_INCREMENT value"
and "Enclose table and field names with backquotes" should be selected as well as the checkbox
next to "Structure", leave them as they are if already selected or set if needed.

IMPORTANT
Selecting "add DROP TABLE" means that if the copy of the database created is later imported to
another Drupal installation, the tables in the imported copy will overwrite them if they exist in
the target database. You should be careful to keep track of your databases, and make sure you
only import and export the correct databases for your task.

c) Under the group labeled "Data" select the check box marked "Complete inserts". The checkbox
labeled "Use hexadecimal for binary fields" may be selected (select it if not) and the combo box
labeled "Export type:" should be set to "INSERT" (select if needed).
d) Put a check in the box in the "Save as file" group, then type a name for the database and click
the button labeled "Go". Note if a radio button other than "None" is enabled in the group
"compression". Uncompressed databases may be larger, but are sometimes easier to work with.
e) Select a location to save your database to (preferably something easy to remember, like the
database folder of your Drupal installation in htdocs, for example).

To import a database with PHPMyAdmin

1) Using your web browser, browse to the PHPMyAdmin location of the server where the
database you wish to import resides. For example:
http://www.example.com/phpmyadmin/
for a remote database and
http://localhost/phpmyadmin/
for a database hosted on your Apache2Triad installation. Here you will either need to select an
existing database name in the combo box on the left side of the PHPMyAdmin page, or create a
new one. Note that if you are setting up a database on a remotely hosted site, your host may
have prohibitions on the creation of MySQL databases that require they be created outside of
PHPMyAdmin by means of a control panel or other mechanism; check with your web hosting
service for specific details of their requirements.
2) One you have selected or created the appropriate database name, select the tab labeled
"Import" on the PHPMyAdmin page to be taken to the import page.
3) Find the control group in the Import page form labeled "Location of the text file" and click the
button labeled "Browse", following the resulting dialogs to select the database file of your choice.

IMPORTANT
If you are importing a database that you exported using the instructions in this tutorial,
remember, the tables of the imported database will overwrite any that exist in the database you
are importing to, overwriting them. Therefore it is important to double-check that the database
you are selecting and the target you are importing to are correct before proceeding. If uncertain,
you should back up the target database before importing a new one into it.

101
Drupal Handbook 3 Aug 2007

4) Click the button labeled "Go" to import your new database.

Using bigdump.php to deal with large databases

While bigdump.php is not included with Apache2Triad, it is a useful tool that greatly simplified
working with large databases and Drupal. Used correctly, it can greatly speed importing large
databases under Apache2Triad, and will also assist in importing large databases hosted on
remote servers where restrictions are placed on the size of databases that may be imported. This
is done by breaking up one big import operation into several small ones, reducing load on the
computer and avoiding import file size limitations.

1) Download a copy of bigdump.php, unzip the file, and open the file "bigdump.php" by right
clicking it with your mouse, selecting "Open with" from the context menu and then "Notepad"
from the list of applications.
2) Find the following section of the file:

// Database configuration

$db_server = ’localhost’;
$db_name = ’drupal’;
$db_username = ’root’;
$db_password = ’password’;

The entries should be as shown above, substituting the correct values depending on where the
database that is to be imported is located. Close this file and save a copy of it to your desktop or
somewhere it will be easily remembered.
3) If you are using bigdump to import a database into your Apache2Triad installation, you
should place a copy of the file you just edited in your htdocs folder along with a copy of the
database you intend to support. If you are importing the database to a remotely hosted Drupal
installation, you will need to transfer copies of the database and the bigdump.php file you
edited to your server.
4) Open your web browser, select the text in the address bar, and type:
http://localhost/path-to-my-drupal-folder/bigdump.php
if you are importing to Apache2Triad and
http://www.example.com/path-to-my-drupal-folder/bigdump.php
5) Bigdump.php should run unattended after it has run, and will inform you of it’s success when
the database has been completely installed.
6) If you are importing to a remote database, you should delete the bigdump.php file for security
purposes with your ftp program or other utility as suggested in the bigdump.php
documentation, and you may wish to remove the old database at this time as well, to free up
server space.

Installing Apache (with PHP) on Windows
As of this writing, the current version of Apache is 2.2.4 and PHP is 5.2.2.

102
3 Aug 2007 Drupal Handbook

1. Download the Apache Windows MSI Installer from Apache.org
2. Download the PHP Windows Zip Package from PHP.net.

The first step to getting Drupal running on your Windows machine is to set up the Apache web
server by running the Apache MSI installer. The following steps will walk you through the
installation:

1. Select Next
2. Select "I accept the terms in the license agreement"
3. Select Next
4. Fill in your server information if it is known. A typical setup will use the "for All Users, on
Port 80, as a Service" option. If this is being setup as a test machine, you may use localhost
as the Network Domain and the Server Name. Select Next.
5. Select the Typical Setup
6. Choose a Destination Folder for the Installer to place the program files into. Note: the
default Apache Installer location is C:\Program Files\Apache Software
Foundation\Apache2.2. Because of the spaces in the directory name, using this folder may
cause cgi and php scripts to not find the paths correctly.
7. Select Finish
8. If a Firewall is enabled, make sure that port 80 is unblocked and open.
9. To test if the Apache server is running, open up http:\\localhost in a browser. A plain black
and white page should come up that reads "It Works!"

Configuring Apache:

1. Using a text editor such as Notepad, open the httpd.conf file. This file is found in the /conf
sub-directory under the directory that was set up during installation. Alternatively, a
shortcut may be found in the start menu under the Apache HTTP Server folder.
2. Note: Windows based systems uses backslashes \ and Unix based systems use slashes / for
paths. In the Apache configuration files, slashes / should be used in path names.
3. Change the DocumentRoot to point to the location of the root document folder. In the
default httpd.conf file, this is found on line 149 and if the defaults were used during the
installation, it would point to "C:/Program Files/Apache Software
Foundation/Apache2.2/htdocs".
Note: Wrapping the path name in quotes will escape out any spaces that are used.
4. Change the Directory path to match the one used in the previous step. This is found on line
177 of the default httpd.conf file.
5. Add to index.php to the DirectoryIndex. This is found on line 212 of the default httpd.conf
file.
6. Append the following lines to the end of the httpd.conf file:
LoadModule php5_module "c:/php/php5apache2_2.dll"
AddType application/x-httpd-php .php
PHPIniDir "C:/php"
7. Save and Close

103
Drupal Handbook 3 Aug 2007

Installing PHP:

1. Unzip the PHP files to C:\php
2. Copy c:\php\php-ini-recommended.ini and rename itc:\php\php.ini
3. Uncomment the Windows include_path on line 506
Note: In the PHP.ini file, semicolons are used to denote that something is commented out.
To uncomment a line, simply remove the semicolon.
4. Update the doc_rootto match the one that was set up in the httpd.conf file on line 513.
Note: The PHP INI files uses the Windows style backslash \ for path names.
5. Update the extension_diron line 520 to "C:\php\ext"
6. Uncomment php_gd2.dll extension on line 637.
7. Uncomment mysql.dll extension on line 651.
8. Update the sessions.save_pathto the Windows temporary files directory (i.e. C:\Temp).
9. The PHP directory needs to be added to the Path Environment Variables
1. Open the Control Panel
2. Open System > Advanced > Environment Variables
3. Append ;C:\php to the end of the Path System Variables list and Click OK.
10. Restart Apache
11. To test PHP on Apache, go to the root directory (i.e. C:\Program Files\Apache Software
Foundation\Apache2.2#92;htdocs) and create a new php file in it. In this file, use PHP’s
phpinfo() function to see the server’s configuration information. For example:
<html>
<body>
<?php phpinfo() ?>
</body>
</html>
Open this file in a browser (i.e. http:\\localhost\filename.htm).

Alternative Options: Bundled Packages

Apache2Triad
Apache Friends - XAMPP

Installing MySQL on Windows
1. After downloading the latest stable release version of MySQL, locate the setup.exe, and
execute it. When prompted choose custom install.
2. Choose a path to install it. I recommend keeping to the default, which is c:\mysql.
3. Select all components, and continue until done.
4. Go to the MySQL folder, and start winmysqladmin.exe
5. Choose a username and password for yourself.
6. In the console, click on the my.ini tab, and choose "create shortcut in startmenu" option.
7. In the my.ini tab, also chck that all the configurable options are correct in accordance to
your computer.
8. Close the admin console and restart it. If admin program runs with a green light, everything
fine.

104
3 Aug 2007 Drupal Handbook

Installing PHP4 on Windows
After obtaining the latest stable release of PHP, extract the archive to c:\php or something
similar.
Copy php.ini-optimized to php.ini

Make the following modifications:
Change include_path to ’’.’’
Change sendmail_from to ’’your@email.address’’
Change SMTP to ’your.smtp.mail.service’ If you don’t know your smtp server, use the
same configuration as your email client uses.
Change session.save_path to a temporary folder (’’drive:pathtotemp’’) and make sure
the temporary folder exists.
Change doc_root to your preferred work folder (’’drive:pathtofiles’’). Make sure it
exists and is the same folder your specified in the Apache setup procedure.
Set register_globals to equal "On"
Save the changes, and copy the php.ini file to your Windows directory.
Create a basic php file, for example test.php which contains the following:
<?PHP phpinfo(); ?>

and save it in your work folder.

Open your web browser, and type in: http://localhost/test.php. If you get the PHP
information page, then everything is set up correctly. If not, just go over the settings again
for PHP to make sure everything is ok.

Drupal 4.7 on Windows/IIS Requires PHP in ISAPI mode

When installing Drupal version 4.7 and later on Windows servers running IIS rather than
Apache, PHP must be run in ISAPI rather than CGI mode.

A relatively obscure bug in IIS discards PHP session information when the PHP script that sets
the session also redirects to another page. In Drupal 4.7 and later, the user login screen
automatically redirects to the home page on a successful login. The IIS bug is triggered,
preventing the new session data from being sent to the user’s browser, and making it impossible
for users to log in.

As the bug only affects IIS when PHP is running in CGI mode, switching to ISAPI mode will
solve the problem.

Installing PostgreSQL on Windows
Postgres is easily installed and administered on Windows. See PostgreSQL on Windows for the
options you have.

105
Drupal Handbook 3 Aug 2007

As of this writing, the apparently easiest choice for PostgreSQL on Windows is "UltraSQL
by PeerDirect" mentioned at above link. It is available from here. See the README file
enclosed in the download and Installing the PeerDirect PostgreSQL beta for Windows for
more instructions. After completing installation, the username for your DB is your windows
login name and there is no password.
You might want to install phpPgSQL in order to admin your database. It will save you
frustation at the command line. A more complete list of all known PostgreSQL GUI tools is
available at PostgreSQL GUI’s
Go ahead and create your database tables via phpPgSQL or via the command line as
described here.

Multiple Drupal Sites under Windows
One troublesome area in Drupal-on-Apache/Windows is multiple Drupal sites. Nowhere is this
documented as being possible to do using a single code base. The weakness is in the fact Drupal
uses symbolic links to point to the directory where Drupal’s code resides. In Linux, this is easy
by creating a symbolic link to Drupal’s root directory:

\Drupal\Site1 -> \Drupal
\Drupal\Site2 -> \Drupal
In Windows, this isn’t that easy. Shortcuts in Windows are not usable except when browsing the
file system. What not many people know, is that Windows DOES support symbolic links. What
Windows doesn’t have is a built in capability to build symbolic links. That’s where a 3rd party
utility is required. I use Junction by Sysinternals. Using the tool is similar to the ln command in
Linux.
c:\> junction.exe c:\drupal\Site c:\drupal
Will make a link to c:\drupal from c:\drupal\site

Using this, AND the directions located elsewhere on this site regarding the strutcure of the
drupal\sites directories, you can make an attempt at getting multiple drupal sites running under
Windows.

Running multiple sites on a local PC (localhost) from a single
codebase, using Windows
Here’s how to get mutltiple sites working on localhost using Windows XP. This should work
with Drupal 4.6.x and assumes that you have PHP, Apache, MySQL, phpMyAdmin and Drupal
all installed and working.

There are four stages to go through, but it’s not difficult:

1. Set up your databases, one for each website
2. Set up each website in Drupal
3. Edit the virtual host settings in Apache
4. Update the Windows hosts file

106
3 Aug 2007 Drupal Handbook

In the following example we will add a local site"http://testsite1" in addition to the default site.
We’ll assume Drupal is installed in c:/www (and that your web root is set to c:/www in the
apache confic file).

Databases
=========

Firstly we will set up a new database for ’testsite1’

1. Open your phpMyAdmin page

2. Type a name for your database in the ’create database’ textbox (’testsite1’ is as good as
anything) then click the create button. You should get a message to say your database is created.

3. Next we need to add the necessary tables. Click the ’sql’ tab, then use the browse option to
navigate to the ’includes’ folder of your Drupal installation, e.g. c:/www/drupal-4.6.3/includes.
Select the file ’database.mysql.inc’ then ’go’.

4. phpMyAdmin will run the script and install the necessary tables.

Drupal
======

1. Make a copy of the folder /sites/default and call it /sites/testsite1. i.e. you should now have
two folders in your sites folder, default and testsite1.

2. Open file sites/testsite1/settings.php using notepad. Edit the $db_url line to match the
database defined in the previous steps:

$db_url = "mysql://username:password@localhost/database";

where ’username’, ’password’, ’localhost’ and ’database’ are the
username, password, host and database name for your set up.

3. Set $base_url to match the address to your Drupal site:

$base_url = "http://testsite1";

4. Save the file.

Apache
======

1. Open the apache config file ’http.conf’ (it’s in the apache/conf folder in Apache 1. I think it
has moved somewhere else in Apache2)

2. Scroll to the end of the file, where you will find the virtual hosting setup. Assuming your
websites are all located in the folder c:/www then add the following lines (edit the paths as
necessary)

107
Drupal Handbook 3 Aug 2007

NameVirtualHost 127.0.0.1:80
<VirtualHost 127.0.0.1:80>
DocumentRoot "C:/www/"
ServerName localhost
</VirtualHost>
<VirtualHost testsite1>
DocumentRoot "C:/www/Drupal-4.6.3"
ServerName testsite1
</VirtualHost>

There are lots of other things you can add into your VHost settings - see the Apache
documentation.

Windows
=======

We now need to tell Windows that the domain ’testsite1’ is hosted locally, i.e. not to look on the
Internet for it. Open the ’hosts’ file with notepad. It can usually be found in
c:/windows/system32/drivers/etc

Edit the end of the file to read:

127.0.0.1 localhost
127.0.0.1 testsite1

Save the file.

Apache, again
=========

OK, that’s (almost) it. All that is left is to restart the Apache webserver. You could reboot your
computer but a better way is to open a command prompt window (a DOS window as we used
to call it) and type ’net stop apache’. When the service has stopped, restart it using ’net start
apache’

Now when you open your favourite browser and enter ’http://testsite1’ you should see your
shiny new Drupal site, just waiting to be customised.

You can add as many sites as you need by following the process above.

Untar
When you download Drupal packages you will need to decompress the files. Drupal packages
are double compressed ’tar’ and ’gz’. To untar packages in Windows several programs are
recommended.

108
3 Aug 2007 Drupal Handbook

7zip
Winzip
Winrar
Winace

Installing Drupal on Windows
[this page used to contain verbose windows installation guidelines. they got removed because
they were a) just a copy of the general installation guidelines, b) misleading ("start by extracting
the archive to the PHP working folder"), and c) we don’t want to maintain redundant
documentation. this page should only contain windows specific guidelines that differ significantly
from the general guidelines. preferably, latter would be put so generally that we don’t need
anything here (eg. don’t rely on "wget" and "tar" etc.)]

PostgreSQL specific guidelines
1. Create a PostgreSQL database for your site. createdb -U <i>username</i> -W
<i>dbname</i>where username is the owner of the database (this user must have
permission to create databases) and dbname is the name of your database. You will be
prompted for that user’s password. On success, the following is displayed:
CREATE DATABASE
.
The user must also have the correct PSQL Grant privileges to use the database correctly.
2. Once you have a proper database, dump the required tables into your database:
psql -U username -W dbname < database/database.pgsqlYou will be
prompted for your database password. You should see a progress report as the tables are
created. All has gone well if there are no lines marked "Error:" printed to the screen.
3. Set the database options in includes/conf.php so Drupal can access the database you have
created. Edit
the following line in includes/conf.php:
$db_url = "pgsql://username:password@hostname/dbname";

ERROR: DB connect failed
You may need to update pg_hba.conf file, to support access for loopback connections:

host drupal drupal 127.0.0.1 255.255.255.255 password

When getting this type of error, it may help to look into apache error log. Postgresql 7.3.4 does
not enable tcp/ip sockets per default, so you have to either enable it by uncommenting:

tcpip_socket = true
port = 5432

109
Drupal Handbook 3 Aug 2007

in postgresql.conf, which may not be a good solution for security concerned people, or enable
unix domain sockets:

$db_url = "pgsql://admin:password@unix(/tmp)/drupal"

/tmp works on a slackware 9.0 Linux 2.4.21, no commas needed.

ERROR: language "plpgsql" does not exist
If you get an error about plpgsql being an invalid language, you just need to install by running
the following at the command line:

createlang plpgsql drupal

(substitute your database name for "drupal")

Then go back and rerun the final part of the database.pgsql file - where the "greatest" function is
created.

ERROR: null value in column "uid" violates not-null constraint
Try the following to fix:

psql -U drupalDbOwner -d drupalDbName -ec "alter table sessions alter
uid set default 0;"

PostgreSQL support in Drupal 4.7.x
The PostgreSQL support in Drupal 4.7.x has improved dramatically. This page lists remarks and
points to remember when installing and using Drupal 4.7.x with PostgreSQL database.

The installation instructions, specific for PostgreSQL, are in INSTALL.pgsql.txt file
PL/pgSQL is no longer required for Drupal working
You should not use schema as a $db_prefix. For example, use foo_, but not foo.. If you
use schema prefix, you will run into errors when upgrading to the next stable release (e.g.
from 4.7.x to 4.8.x). The errors are easy to fix, but it’s impossibile to support both foo_ and
foo. type prefixes

Drupal 4.5 and PGSQL 8 configuration
The exact order of commands I used to get drupal working on PostgreSQL 8.0.0 beta[345].

Differences to the (excellent) supplied documentation:

Create the db user first
createdb -O instead of -U. This sets the owner of the new database to the user, but that
user need not have create database permissions.
Remember the createlang command as pointed out (thank goodness!) by another user

110
3 Aug 2007 Drupal Handbook

psql expects -U instead of -u. Use -f to load the file.

1) Create a new database user (I used "drupal").

As the postgres user:

postgres$ createuser --pwprompt
Enter name of user to add: drupal
Enter password for new user:
Enter it again:
Shall the new user be allowed to create databases? (y/n) n
Shall the new user be allowed to create more new users? (y/n) n

2) Create the new drupal database owned by the user created in 1) above

As the postgres user:

postgres$ createdb -O drupal drupal

3) Add the plpgsql language to the database

As the postgres user:

postgres$ createlang plpgsql drupal

4) Finally, read in the supplied database.pgsql file.

As root postgres user:

postgres$ psql -U drupal -d drupal -f database/database.pgsql

5) Set $db_url as mentioned in above documentation.

Installing contributed modules
Once you have the Drupal core files installed, you can begin adding third-party contributed
modules to extend or alter Drupal’s behavior.

The basic instructions are as follows: Download the module, extract the files, upload the
resulting folder, and enable the module in administer > site building > modules (version 5.x) or
administer > modules (version 4.7 or under).

The detailed instructions are:

1. Download the module. Make sure the version of the module matches your version of
Drupal. Note that modules labeled "CVS" are in a development stage. They may be written
for a previous/current/future version of Drupal, and they are considered unstable and
should be handled with care.
2. Extract the files. When you first get the module, it will appear in a compressed file format

111
Drupal Handbook 3 Aug 2007

such as ’tar.gz’. On Windows, use a program like WinZip to extract it. On the Mac, you can
use Stuffit Expander. To extract the file using the Unix command line:

tar -zxvf modulename-drupalversionnumber.tar.gz

You should see a list of files extracted into a folder.

3. Upload the folder. FTP your files to the desired modules folder in your Drupal installation.
Since the /modules/ folder is typically reserved for Drupal core modules, as of version 5.x you
should create a sites/all/modules/ directory and put uploaded modules there. This will also
make it easier to update your Drupal site later on. For version 4.7 and below, put contributed
modules into /sites/example.com/modules/ (multi-site setup) or /sites/default/modules/
(single site setup)
4. Read the directions. If the module has an installation file (usually INSTALL.txt and/or
README.txt), read it for specific instructions. There are modules that require special treatment,
and even modules that depend on other downloaded files to function properly. Sometimes the
readme filename has no .txt extension. When you try to double-click on it, your computer
doesn’t know what program to use. In that case, open Notepad (or your favorite text editor) first,
and then open the file using Notepad’s ’open’ command.
5. Enable the module. Version 5.x users go to administer > site building > modules while 4.7 or
prior use administer > modules. Check the ’Enabled’ box next to the module and then click
the ’Save Configuration’ button at the bottom. NOTE: If you’re upgrading an existing module
you’ll need to browse to your update page at www.example.com/update.php and click on
’run the database upgrade script’.
4.6 USERS: As of 4.7, modules have an .install file so that any database tables which the
module requires are created automatically when the module is enabled. If the new module
doesn’t have one, look for modulename.mysql and/or modulename.pgsql. If you see
those, the module isn’t using .install files yet, and you need to read step 6 of the 4.6
instructions. If there are none of those files, the module doesn’t affect the database.
6. Set file permissions. Some modules will require you change permissions or settings to get
them working. Permissions and settings info may be in the instructions that came with the
module. Usually, go to administer > users > access control. Scroll down to see if the module
appears in the list and, if it does, give the appropriate permissions to roles.
7. Adjust settings. In 5.x, settings are with the module. In 4.7 and prior, go to administer >
settings and see if the name of the module you just installed is in the list. If it is, click the
module name and configure as appropriate.
8. If you run into problems, search the forums. If your problem hasn’t already been addressed,
post a question and someonw will try to help you out.

Note: To keep up-to-date on any issues and fixes related to your newly installed module(s), you
can create a user account (if you haven’t done so all ready) and then subscribe to each module
you are using.

Note: You can have only one copy of a module with the same name in each Drupal site.

112
3 Aug 2007 Drupal Handbook

HOWTO: Install glossary module
I just finished installing the Glossary module in three Drupal 4.7x websites, so I thought I’d
write out some basic steps here:

Where is the Glossary?
One of the first things to try to understand is that, although we will install a "Glossary Module",
all the glossary content is actually entered and created in "Administer>Categories*" as entries in
a Vocabulary. Although Taxonomy Vocabularies are quite powerful, and contain many other
uses (many of which I don’t yet understand or I’m not yet aware of), this article only explains
Vocabularies as they relate to the Glossary Module. The Glossary Module takes the Vocabulary
entries and turns them into one or more Glossaries. Each time you create a new "Vocabulary",
you are creating (the potential for) a new Glossary. (The Vocabulary terms are only turned into
Glossaries when chosen in the "Administer>Input Formats" section.) (More about this later below.)
*Note: Although the Glossary content is entered through "Administer>Categories>Vocabularies" , don’t
get this confused with the optional, but different, Category Module, which adds it’s own
"Administer>Categories" menu listing.

What is the purpose of the Glossary Module, and what does it do?
Creates Glossary Page(s), the Glossary Module creates a glossary page of all your terms, with
the definitions. You may create one or multiple glossaries.

Terms Identified:, on any page on your website, whenever you use any of the words in the
glossary, those words will be identified on each page. You can choose whether the words will be
identified by being underlined (with a broken line), or using a superscript letter (or word), such
as the superscript letter "i", like this i (You can actually type in any letter or word that you want), or
by using a small icon by the word. (You can also chose whatever icon you like)(see instructions
below)

Definitions Available on "Hover", whenever the visitor "hovers" the mouse pointer over any
one of the identified terms, the definition will "pop up" in a small box for about 6 seconds. This
way the definitions of all the words in your glossary will be readily available every time you use
any of those words.

Instantly Go to Glossary. If you click on the underlined word, or one of the identifiers (the
superscript "i" or the small icon), you will immediately be taken to the full glossary page.

Full Page Definitions, you can attach full page (or multiple pages) of descriptions to any, or all,
of the glossary terms. (see instructions for this at the bottom). If you have attached any full pages
to any glossary term, the pop up definition will still work, but when you click on the word, you
will be taken to the full page descriptions instead of to the glossary page. If you have multiple
pages attached to the glossary term, then you will be shown the teasers of all the definition
pages. You can then choose to look at any of those pages.

113
Drupal Handbook 3 Aug 2007

Installing the Glossary Module
More detailed instructions (for some of the following steps) can be found in the Glossary
Readme file.

1. First download the Glossary Module from http://drupal.org/project/glossary onto your
computer.(Some website control panels allow you to upload an archived file; zip, tar, etc. and then
unarchive it after the file is on your website in a folder. If this is the case, then just upload the
Glossary Module tar or zip file to your website. Otherwise, unzip the file on your computer, then ftp
the whole folder to you website folder.)

Using either a ftp program, such as FileZilla, or from your website control panel: file
manager, upload the folder/files to (mywebsite.com/drupal/modules)

Configuring the Glossary
1. On your Drupal website, go to "Administer>Modules" and enable the glossary module
and save the new configuration.
Go to Administer>Categories: Add one or more Vocabularies. You might give the
vocabularies names that will encompass all your terms. For example, since I do upholstery, I
might name one of my Vocabularies "Upholstery Terms" , then add some terms.
Go to Administer>Input Formats: Choose one of the input formats, for example chose
âFiltered HTMLâ, At the right side, under "Operations", click on âconfigureâ. This will take
you to the "’Full HTML’ input format" page.
Under the âViewâ tab (which is the default), under âFilters,â enable the "Glossary filter", At
the bottom of the page, click âSave Configurationâ. After it is saved, you will be on the same
page.
Now, at the top of the page, click on the âconfigureâ tab.
Click on âGlossary Filterâ which will open up some choices. In the âSelect Vocabularyâ
box, click on the vocabulary term(s) that you created in Administer>Categories.
Next, do you want all the terms of your glossary to show on one page? (This would be
suitable for small glossaries) If not, click in the box by "Show glossary across many
smaller pages"
The next choice is "Match Type". I haven’t figured that one out yet, so I leave it alone on
"Word".
Chose whether you want your glossary terms to be case sensitive or insensitive. I usually
chose case insensitive, since I want all the tems to show up, whether capitalized or not.
Next, do you want all the terms on any given webpage to be identified as being in the
glossary, or do you only want the first term on any page identified? Chose Replace
Matches: "Only The First Match" or "All Matches".
Under "Indicator Settings", you now make choise about how you want your terms
identified on the website pages.
Under "Term Indicator" Choose "superscript", "icon", or "replace with acronym link":
Superscript:If you want a superscript letter (or word) by each word, like this i or this term
Icon: A default icon is installed with Drupal. the icon will follow the term in place of the

114
3 Aug 2007 Drupal Handbook

superscript. If you want to choose a different icon, upload it somewhere on your website,
such as your picture gallery, or a file, copy the URL to your chosen icon, and enter that URL into
the Glossary Icon URL: text box.
Underline: If you’d rather have all you terms underlined (only with a broken line), then
choose "replace with acronym link" in the Term Indicator box.
When you are finished with all of your choices, click on âsave configurationâ

Glossary Administration: Finally, Choose which type of user(s) that you want to be able to
administer the glossary, such as all "authenticated users" or only members in a "specific user
role", or just the "administrator(s)". To make this choice, go to "Administer>Access
Control>Permissions. Scroll down to "glossary module" and enable your chosen user role(s).

Your Glossary Module should be working now. Go back to
"Administer>Categories>Vocabularies" to enter your glossary/vocabulary terms. I would
suggest that you keep your terms down to one brief paragraph. This paragraph will display all
through the website whenever a user’s mouse pointer "hovers" over the indicated word; it will
only display for about 6 seconds. Keep your paragraph down to about 6 seconds of comfortable
reading. (Yes, a user can go back to the indicated word and get the definition to pop up again, but
why should they have to? You can put more detailed definitions or explanations on other page(s), which
can be connected to any glossary/vocabulary term(s).)

Adding Full Page Definitions
Do you want to allow any registered user to add full page definitions to the glossary, or do
you want only specific persons to have this ability? This is controlled through the
"Administration>Input Formats". If you want every authenticated user to be able to add full
pages to the glossary, then you would enable the glossary with each of the input formats
available to those users. However, if you only want specific users to have that abililty, Use or
create an input format that only those users, or type of users, will be using.
.............>>> More to be added here later <<< .................

Adding Glossary To Menus
This part (below) needs to be written better, more later.

1. To create additional glossary entries, go to Administer>Categories (as you did above)
and enter more.
(when your create Vocabulary (in Administer>Categories above), menu items and blocks
are created for them, but not enabled.)
If you want your Vocabulary to be on the website menu, go to Administer>Menus and
enable them.
If you want your Vocabulary to have its own menu block, go to Administer>Blocks and
enable them.

Stephen Winters
Winters Sewing
Winters Sewing: Upholstery Information Website

115
Drupal Handbook 3 Aug 2007

Kingwood Bible: Community Website

Leech - automating content addition
The Leech module is an amazing module that automagically adds content to your site. Once its
set up it will read RSS feeds and "leech" the articles from the originating site and each article as a
node on your drupal site.

This is how you set up leech (4.7.x-1.6 as of 3/3/2007).:

Enable the following 2 modules:

1. leech

node_template (which comes with leech)

next, according to modules/leech/README.txt you have to do the following:

1. create a story called "template story" and in the body of the story, put any place holder
like "template node". Under publishing options disabled "Published"
2. After creating the story, you will find the node now has a new tab called "template".
Click on that and then on the button named "create"
3. Next go to admin/settings/content-types and enable leech using the template created
above. and save
4. The final and most important part of the leech puzzle is from
http://drupal.org/node/116859. which says you have to create a PAGE for each RSS
feed. When you create content/page you will now find there is a new option called
leech. put in your rss feed’s url and wait for like 10 to 30 seconds. the advanced options
will fill up with the data for your feed. Give your new leech feed a name and save. I
don’t believe any body would want this new leech feed posted to their front page so
uncheck that option from under publish.
5. once saved, there is still no data, depending on how often you set your leech module to
check for updates (dependent on cron) you will either have to wait for the next cronjob
or click on leech data now and VOILA! NEW STORIES!

NB. its supposedly possible to use other node types and even CCK but i havent tried and
the above is exactly what i need

Relationships between modules
This is a start to explain how similar or related modules are related and why you would use one
vs another.

Internationalization
- Locale (core), i18n also known as Internationalization, and Translation

116
3 Aug 2007 Drupal Handbook

http://drupal.org/project/locale
- provides multiple translations of strings generated by drupal
- now part of the core code of drupal, critical if you want the site in something other than english

http://drupal.org/project/i18n
- provides a mechnanism to define multiple a single piece of content in multiple languages.
- requires locale module
- only use this if you want your site in English AND french

http://drupal.org/node/12875
- translation module which allows for people to switch between node content in other languages
- must require locale and i18n module
- designed to make it easier to produce sites in both english AND french

Module Comparisons

- http://drupal.org/project/scheduler vs http://drupal.org/project/event (applied to nodes)

- http://drupal.org/node/19813 vs taxonomy

Installing new modules (Drupal 4.6 or older)
After installing Drupal, you have the option of installing extra modules to extend or alter
Drupal’s behavior.

In brief. Download the module, extract, upload the folder into your Drupal modules folder, run
the mysql file if necessary, and enable the module in administer » modules.

1. Download the new module. Make sure the version of the module is compatible with your
version of Drupal. Also note that modules labeled CVS are considered unstable and should
be handled with care. Often, CVS modules work only with the CVS version of Drupal. They
may be in draft form, or be in the midst of active development.
2. Extract the module. When you first get the module, it will probably come in a compressed
file format such as tar.gz. On Windows, use a program like WinZip to extract it. On the
Mac, you can use Stuffit Expander. To extract the file using the Unix command line:

tar -zxvf modulename-4.5.tar.gz

You should see a list of files extracted in to a folder.

3. When you’ve extracted the file, upload the files via FTP to a folder inside the modules/
folder of your Drupal installation.
4. Read the installation file (usually INSTALL.txt and/or README.txt). Sometimes the
installation file has no extension, so when you try to click on it, your computer doesn’t
know what program to use. In that case, open Notepad (or your favorite text editor) first,
and then open the file into it.
5. There are modules that modify the database. You can generally tell if there is a
modulename.mysql and/or modulename.pgsql file included with the module. If you

117
Drupal Handbook 3 Aug 2007

do have to modify the database, see the next few steps. If you do not, please skip to step 7.
6. If you have to modify the database to get your module running, you will need to add tables
to the database you made when you installed Drupal. Instructions given here are for MySQL.
Using phpMyAdmin:
If you have phpmyadmin, log in and go to your drupal database. If you have it, but do
not know how to access it, please contact your host.
Click on the tab that says ’SQL’
You should see a text area labeled ’Run SQL query/queries on database
yourdrupaldatabase’. Underneath, it says ’Or Location of the textfile:’ Click browse,
and find the modulename.mysql that came with the module. Click go. Unless your
instructions for the module says anything else, that should be all you have to do to the
database.
Using the Unix command line:
Run the following command.
mysql -u username -ppassword database_name < modulename.mysql
Replace ’username’ with your MySQL username, ’password’ (but keep the -p before it)
with your MySQL password, ’database_name’ with the database Drupal uses, and
’modulename.mysql’ with the SQL file that the module comes with. You can generally
find this out from settings.php in either the sites/default folder or the
sites/sitedomain.com folder, replacing sitedomain.com for the domain that hosts
Drupal.)
7. For most modules, all that is left is to activate it! To activate your module, you need to click
administer » modules, check the box next to your new module name, and click on ’Save
configuration’ at the end.
8. Some modules will require you change permissions or settings to get them working as you
like them. Permissions and settings info may be in the instructions that came with the
module. If not:
9.
1. Click administer » access control. Scroll down to see if the module appears in the list
and, if it does, give the appropriate permissions to roles.
2. Click administer » settings and see if the name of the module you just installed is in the
list. If it is, click the module name and configure as appropriate.
10. If you still run into the problems, search the forums. If your problem hasn’t already been
addressed, post a new post.

Note: To keep up to date on any issues and fixes you can create a user account (if you haven’t
done so all ready) and subscribe to each module you are using.

Note: You can have only one copy of a module with the same name in an Drupal installation.

Multi-site installation and set-up
Instructions on multi-site configuration (also known as "multisite" and "single code base"
installations) can be found within the installation instructions.

118
3 Aug 2007 Drupal Handbook

Here are some useful links:

Search results
4.6 Multi-Site from single code base
Multi-Site .htaccess configuration
multi-site, single installation, shared db, single sign on. is this possible?
Automatic Multi-site registration
Using Multi-Site
Multihosting Off Single Codebase
Multisite and symlinks doesn’t work
Sharing tables between installations

10 Minute Multisite Install & Configuration
Multisite 10 minute Install:

Server: LAMP
SSH/Telenet Client: PuTTY
Must have root access to your server.

If website in question is an addon domain, i.e., addon.mydomain.tld, then substitute "www" for
"addon" in steps below.

For list of Linux commands visit: http://www.oreillynet.com/linux/cmd/ or
http://www.ss64.com/bash/

Here we go:

[login via PuTTY]

Get to location where Drupal core will be located:

[/]# cd /var/www

Upload Drupal core:

"x.x" should be replaced with the version of Drupal you’re installing, e.g. "5.1"

[/var/www]# wget
http://ftp.osuosl.org/pub/drupal/files/projects/drupal-x.x.tar.gz

Unpack Drupal core:

[/var/www]# tar -zxvf drupal-5.1.tar.gz

Move contents of Drupal core (including .htaccess) to html:

119
Drupal Handbook 3 Aug 2007

[/var/www]# mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html

Clean-up:

[/var/www]# rm drupal-x.x.tar.gz
[/var/www]# rm drupal-5.1

Create the files directory per Drupal instructions and change permissions (will change
permission again after install):

[/var/www]# cd html
[/var/www/html]# mkdir files
[/var/www/html]# chmod 777 files

Make directories that will hold custom and contributes modules and themes:

[/var/www/html]# cd sites/all
[/var/www/html/sites/all]# mkdir modules
[/var/www/html/sites/all]# mkdir themes
[/var/www/html/sites/all]# cd modules
[/var/www/html/sites/all/modules]# mkdir custom
[/var/www/html/sites/all/modules]# mkdir contrib
[/var/www/html/sites/all/modules]# cd ../
[/var/www/html/sites/all]# cd themes
[/var/www/html/sites/all/themes]# mkdir custom
[/var/www/html/sites/all/themes]# mkdir contrib

Create directory "www.mydomain.tld":

[/var/www/html/sites/all/themes]# cd ../
[/var/www/html/sites/all]# cd ../
[/var/www/html/sites]# mkdir www.mydomain.com

Change permission of "settings.php" per Drupal instructions and copy "settings.php" in default
to www.mydomain.tld:

[/var/www/html/sites]# cd default
[/var/www/html/sites/default]# chmod 777 settings.php
[/var/www/html/sites/default]# cd ../
[/var/www/html/sites]# cp -rp sites/default sites/www.mydomain.tld

Create database and user with permissions:

[/var/www/html/sites]# mysql
mysql> CREATE DATABASE wwwmydomaintld_drupal;
mysql> GRANT ALL PRIVILEGES ON wwwmydomaintld_drupal.* TO
’wwwmydomaintld_myusername’@’localhost’ IDENTIFIED BY ’mypassword’;

120
3 Aug 2007 Drupal Handbook

mysql> \q

Go back to PuTTY to chmod on settings.php in www.mydomain.tld:

[/var/www/html/sites]# cd www.mydomain.tld
[/var/www/html/sites/www.mydomain.tld]# chmod 755 settings.php
[/var/www/html/sites/www.mydomain.tld]# logout

What next?:

Make changes to "settings.php" in www.mydomain.tld? I’ve read that it’s not necessary to
make changes to setting.php.
Make changes to "httpd.conf" in /usr/local/apache/conf?

I’ve been using WHM to create accounts, putting Drupal in public_html and having no
problems. But when it comes to parting from the WHM abstraction and getting multisite set-up
correctly this is the end of the proverbial road for me.

Could use help...:

1. Help making improvements to steps articulated above
2. Help with next steps so that I/we can get on to grander things, like creating modules,
custom themes, profiles, (and maybe - just maybe - spend some time working on business
strategy :-)

Access all multisites with www. only [.htaccess]
The default .htaccess RewriteRule to redirect every multisite.com to www.multisite.com does
not work properly.

If you have problems with that too, just leave the two lines uncommented, and ADD THE
FOLLOWING 3 LINES FOR EVERY MULTISITE you set up:

RewriteCond %{HTTP_HOST} mysite\.com$ [NC]
RewriteCond %{HTTP_HOST} !^www\. mysite\.com$ [NC]
RewriteRule ^(.*)$ http://www.mysite.com/$1 [L,R=301]

(Thanks to Florian!)

Drupal as a library
Short introduction on how to share drupal with all users on a shared server (without having
troubles with file-permissions).

Note: it is still possible to use the Multisite option of drupal.

121
Drupal Handbook 3 Aug 2007

example server’s file-structure:

/path/to/phplibraries/drupal (chmod 644)
/home/
user1/ (example.com)
lib (symbolic link => /path/to/phplibraries/)
public_html/
main/
files/
includes (symbolic link =>
/home/user1/lib/drupal/includes)
misc (symbolic link => /home/user1/lib/drupal/misc)
modules (symbolic link =>
/home/user1/lib/drupal/modules)
profiles (symbolic link =>
/home/user1/lib/drupal/profiles)
sites/
all (symbolic link =>
/home/user1/lib/drupal/sites/all)
default (symbolic link =>
/home/user1/lib/drupal/sites/default)
example.com/
settings.php
themes (symbolic link =>
/home/user1/lib/drupal/themes)
.htaccess (copy from drupal/.htaccess)
cron.php (copy from drupal/cron.php)
index.php (copy from drupal/index.php)
install.php (copy from drupal/install.php)
robots.txt (copy from drupal/robots.txt)
update.php (copy from drupal/update.php)
xmlrpc.php (copy from drupal/xmlrpc.php)
.htaccess (1)
user2/ (example2.com)
(same as user1)
user3/ (example3.com)
(same as user1)
etc...

.htaccess (1)
this isn’t neccessary but it keeps public_hml/ clean when several sites are maintained by one user. When
only one site is maintained the contents of the main/ directory could be moved to public_html/ itself

Options +FollowSymLinks
DirectoryIndex index.php
<IfModule mod_rewrite.c>
RewriteEngine on

122
3 Aug 2007 Drupal Handbook

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{HTTP_HOST} ^example\.com$ [NC]
RewriteRule ^(.*) main/$1 [L,QSA]
</IfModule>

Multi-site setup in 5.x using CPanel
After some searching around, I found out how to do multi-site setup using CPanel.

1. Create your initial Drupal site at www.yourdomain.com. Drupal 5.x makes this very easy to
do, as it will automatically install the database for you -- all you have to do is input the database
information.

2. Create a folder in the sites/ folder that matches the subdomain you want to create (so for
site1.yourdomain.com, the folder name would be site1.yourdomain.com).

3. Duplicate the settings.php file from the default folder and place it in your newly created
folder from step 2.

4. Edit the settings.php file you just placed in the site1.yourdomain.com folder so that it points to
the correct database.

5. In CPanel, set up the subdomain. For the above example of site1.yourdomain.com, a folder
named site1 will be automatically created by CPanel.

6. Delete the folder that was created.

7. Use the following example to create and upload a php file onto your site. An easy way to do
this is to use Notepad, pasting in the text below, editing as necessary, and then saving as
multisite.php. Afterwards, upload via FTP or CPanel’s File Manager.

<?php
symlink( ’/home/username/public_html/’, ’site1’ );
?>

8. Go to the location of the php file in your browser (such as
www.yourdomain.com/multisite.php)

This will create a symlink, allowing your subdomain to work properly.

9. Go to your subdomain. Drupal will install the tables necessary to run the new site.

10. You’re all set to use the new site.

If you run into any problems, or have questions, use the contact form attached to my user
account here to contact me.

123
Drupal Handbook 3 Aug 2007

Multi-Site, Single Codebase, Shared Database, Shared
Sign-on 4.6
I used this option, having a network of interrelated sites. While each site has its own domain,
offers its own theme and own primary (homepage) content, the sites are essentially related and
needed to share user registration accounts and forums. With a shared database, they also share
information, e.g. the site which offers reviews can also display news headlines in a sidebar; the
site which offers classified ads can offer reviews in a sidebar; etc.

An unintended consequence of this approach is that savvy users can effectively navigate any
and all content from any and all sites (once they understand breadcrumbs and drupal-specific
navigation), so they get, essentially, whatever content they want in whatever theme they want.

Apache (http) Configuration
All domains will point to one document root. That cannot be emphasized enough. When using
virtual hosting, do not create a separate virtual domain for each site -- only for the first site.
When using a control panel such as cPanel or Ensim, create only the first domain. In the first
domain’s alias area, list all the additional domains and subdomains to be used. Your virtual
hosting entries should end up like this:

ServerName www.firsthost.com
ServerAlias firsthost.com
ServerAlias secondhost.com www.secondhost.com
ServerAlias thirdhost.com www.thirdhost.com forums.thirdhost.com
etc...

DocumentRoot /home/virtual/whatever/var/www/html
etc...

Any request for any of the domains will all run to /home/virtual/whatever/var/www/html
for response. This is the desired result.

Download and Placement
The code base should sit in the DocumentRoot defined above. Download the tar ball for the
latest stable version (4.6 as of this writing) and open it in the doc root. Note: all remaining
commands assume you are sitting in your doc root, so go there.

wget http://drupal.org/files/projects/drupal-x.x.x.tar.gz
tar -zxvf drupal-x.x.x.tar.gz
mv drupal-x.x.x/* .
mv drupal-x.x.x/.htaccess .

Check ownership and permissions - if you’ve downloaded directly, they’re likely to be very
wrong. Security note of caution: I typically go through and change permissions to 444
(read-only) for all .php, .gif, .jpg and .css files. In drupal, that’ll also mean .module files. You’ll

124
3 Aug 2007 Drupal Handbook

have trouble editing these files, but that’s the point. It’s easier to change permissions temporarily
on a file you want to hack than it is to fix a break-in.

chown -R siteX:siteX .
chmod -R 444 *.php *.gif *.jpg *.css *.tar *.module

SQL Setup
There are two ways to do this: on the command line and via a control panel. Some control panels
(Ensim, for example) require that you create new databases through their interface (so they can
limit a site to a set number of databases).

If you can create new databases through the command line, do it like in the install file -

mysqladmin -u user -p create Name
mysql -u user -p
GRANT ALL PRIVILEGES ON Name.* TO user@localhost IDENTIFIED BY
’password’;
flush privileges;

I substituted Name for ’drupal’ in the instructions -- really, name your database something other
than ’drupal.’ Helps to prevent hacking if the attacker isn’t intimately familiar with the site
configuration. Even if you call it mysite_drupal, that’s something.

I also have no idea why the installation instructions suggest permissions for ’nobody,’ so I
changed that to the database user. If you don’t have a database user setup for this site, setup an
SQL user with its own unique password. phpMyAdmin makes it easy to do this.

If you have to create databases via your control panel, open it and go to the SQL page. Create a
new, empty database associated with the correct host and call it what you will (see notes above
about calling it ’drupal.’ Most systems create a database user for each site; if yours doesn’t,
create that user and give it permissions for the database you just created.

Just because you have to create the database via the control panel doesn’t mean you have to fill it
that way. You can now return to the command line and setup the database structure.

mysql -u user -p Name < database/database.mysql
chmod 000 database/database.*

Technically, you’re done after the first line, but I like to lock up all setup files once I’m finished
with them. This prevents someone else from trying to reset my system to hack in and prevents
me from erasing my database in a fat-fingered typing accident.

125
Drupal Handbook 3 Aug 2007

Individual Site Configuration & Theming
Now, to the individual site information. Drupal will parse the http request and provide the
correct content based on the domain name and settings files. You’ll need one directory for each
domain name and one settings file for each. You can link aliases together. In the example below,
Drupal will load this settings.php file for calls to http://firsthost.com and
http://www.firsthost.com.

mkdir sites/firsthost.com
cp sites/default/settings.php sites/firsthost.com
ln -s sites/firsthost.com sites/www.firsthost.com

Now, edit sites/firsthost.com/settings.php and enter the following values (using the SQL values
above for user, password and database Name). This allows the site to connect up to the database
created above, and to create links to itself correctly.

$db_url = ’mysql://user:password@localhost/Name;
$base_url = ’http://firsthost.com’; (or www.firsthost.com depending on preference)

And add the following lines (using site values). This overrides any theme or database settings to
provide unique values for this site. Things you may want to override include the individual
site’s name, slogan, and theme. Also, you can use site_frontpage to set a default module. In the
case below, we’ve chosen ’node’ (generic stories) as the home page for this site.

$conf = array(
’site_name’ => ’Name of the First Site’,
’site_slogan’ => ’My Original Drupal Site’,
’site_frontpage’ => ’node’,
’theme_default’ => ’pushbutton’,
’anonymous’ => ’Visitor’
);

Now, repeat from the ’mkdir’ command for each new site. Some things will remain the same.
The configuration variables will change. In the example below, we’ve changed the homepage to
the book module and the theme to bluemarine. When Drupal parses a request for this second
site, it will present those options.

$conf = array(
’site_name’ => ’Name of the Second Site’,
’site_slogan’ => ’The We Love Drupal Fan Site’,
’site_frontpage’ => ’book’,
’theme_default’ => ’bluemarine’,
’anonymous’ => ’Dude’
);

126
3 Aug 2007 Drupal Handbook

You have working multisites. Call up the first domain, setup your administrative user and run
with it. Keep in mind that sites/default is the settings.php file which will be used if Drupal
doesn’t recognize the http call, so you might want to set that one up to run with your default site
... or set it up to notify you if someone tries it.

Some things which can be improved:
- I have yet to try to use the FOAF module ( http://drupal.org/project/foaf ) to automate logins
from one domain to the other. At the present time, users must login separately to each site, even
though they use the same account info.

- I don’t use the statistics module, so I can’t say what it does, but it can be difficult to get
individual domain info out of the Apache logs. Unless you do some fancy configuration, you get
one combined log.

- Note that to use different databases (completely different Drupal sites) with the same code
files, you can still follow the above instructions, creating a separate database and user for each
one. Then, point each settings.php file to the appropriate database instead of pointing them all to
the same one.

Keywords: multisite multi-site multi site, multihost multi-host, host, sharing code, one codebase,
site configuration, step by step

Multi-Site, Single Codebase, Shared Database, Shared
Sign-on 5.x
This document is written with assumptions that you have:

installed Drupal 5 before
access to your server via ssh / telnet
access to MySQL database / you can setup your own MySQL database

In this example, I will setup two sites using:

Drupal 5
One database on MySQL
Linux-based server

Also:

Website’s url is: www.example.com
Drupal is installed in: /var/www/drupal
Names of sites are: âsite_1’ and âsite_2’

These sites will share session and user-related tables so once users login to one of the sites, they
can view the other site without logging in. User roles and profiles are also shared among the two
sites.

127
Drupal Handbook 3 Aug 2007

1. Prepare database and database user

1.1. create a database and user
In this example, I will use:

DB name: drupal_db
DB username: druser
Password: twosites
Access right: SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER,
CREATE TEMPORARY TABLES, LOCK TABLES

2. create and modify site configuration
2.1. duplicate settings folder
Duplicate a folder contains site config information under drupal/sites/

dru@/var/www/drupal/sites: cp âR default/ www.example.com.site_1
dru@/var/www/drupal/sites: cp âR default/ www.example.com.site_2

2.2. Modify config files

2.2.1. provide DB connection detail
Open settings.php in a folder under www.example.com/site_1. Go to line 93 (or somewhere
around there) and you should find a line that goes:

$db_url = ’mysql://username:password@localhost/databasename’;
change this line with your DB name, DB user and password. It will look like:
$db_url = ’mysql://druser:twosites@localhost/drupal_db’;

2.2.2. set prefixes for table names
just below the line we just changed above, there is a line that goes like:

$db_prefix=’’;
Since we want to share a database among two sites but not completely, we decide which tables
to share / not to share. This can be done by adding prefixes to table names. An example given
below is for sharing user-related tables, sequences (this table is a âcounter’ of users, nodes and
other stuff) and session information.
$db_prefix = array(
’default’ => ’site_1_’,
’users’ => ’shared_’,
’sessions’ => ’shared_’,
’role’ => ’shared_’,
’authmap’ => ’shared_’,

128
3 Aug 2007 Drupal Handbook

’sequences’ => ’shared_’,
’profile_fields’ => ’shared_’,
’profile_values’ => ’shared_’,
’users_roles’ => ’shared_’,
);

the second line that goes:

’default’ => ’site_1_’,
this means tables that are not shared with other sites will have a prefix âsite_1_’. So for example,
table name ânode’ will be âsite_1_node’.

Now, when you finish editing this file, open and edit
drupal/sites/www.example.com.site_2/settings.php. This time, you enter the exact same
information for the database connection. So the line around 93 should look like:

$db_url = ’mysql://druser:twosites@localhost/drupal_db’;
Then, you add an array of prefixes, which will look like:
$db_prefix = array(
’default’ => ’site_2_’,
’users’ => ’shared_’,
’sessions’ => ’shared_’,
’role’ => ’shared_’,
’authmap’ => ’shared_’,
’sequences’ => ’shared_’,
’profile_fields’ => ’shared_’,
’profile_values’ => ’shared_’,
’users_roles’ => ’shared_’,
);
notice a prefix in the second line is now âsite_2_’. At the installation, all tables will have this
prefix except for the ones that are specifically given a prefix âshared_’.

3. create static links
In order to access site_1 and site_2 from web browser, you have to make static links to drupal
directory. In the directory /var/www/drupal, enter the following commands:

ln -s drupal site_1
ln -s drupal site_2

now access âwww.example.com/site_1’ (and âsite_2’). If you see a drupalicon and a message
like âUnable to select database’, go back to 2.2.1 of this manual and check if you have all details
correct, including a single-quotation and semicolon.

If you see hundreds of messages like âWarning: Table ’continuu_test.access’ doesn’t exist’, you
are almost there. While this may look scary or makes you think you have done something
wrong, it is just saying that it cannot find tables Drupal needs to have access to. This is simply
because we have not yet finished installing Drupal. All the necessary tables will be created in the

129
Drupal Handbook 3 Aug 2007

next step, which is described below.

4. install drupal
Since we have entered information for database connection, we can run the install script
(install.php) straight away, instead of giving all the detail to installation wizard. From your web
browser, just access:
http://www.example.com/site_1/install.php
http://www.example.com/site_2/install.php

Installation should complete within a second (or two). If you fail to install:

read the error message and find out what is wrong (wrong DB name, username or
password, etc.)
make sure $db_url (around line 93 in settings.php) ends with a quotation mark and
semicolon. ( â; )

If you have two separate Drupal sites and are thinking about merging them with above method,
I would recommend you not to do it. Yes, it is not impossible. You can rename tables and
modify values in sequence table and so on, but i tried it and had a hell of a hard time... If you
have sites already setup, using CAS or other authentication services is more appropriate than
merging.

Multiple domains or vhosts using different databases
Apache supports both IP- and name-based virtual hosts (vhosts). While running more than one
engine (by using vhosts) can be very useful for development and testing purpose, it might even
be more interesting for hosting companies. Therefore, we tried to support vhosts in the best
possible way in order to make the life of any administrator easier. We do so by making it
possible to run an unlimited amount of vhosts on the same physical source tree, though by using
different configuration files. Moreover, you can setup multiple configuration files in your
includes-directory.

$ ls -l sites/*/*.php
-rw-rw-r-- 1 drupal drupal
sites/www.example1.com/settings.php
-rw-rw-r-- 1 drupal drupal
sites/www.example2.com/settings.php

The only thing left to be done is to setup the corresponding vhosts in your Apache configuration
file. Note that the DocumentRoot points to the same source tree twice:

NameVirtualHost 127.0.0.1
DocumentRoot /home/www/drupal
ServerName www.example1.com
DocumentRoot /home/www/drupal
ServerName www.example2.com

130
3 Aug 2007 Drupal Handbook

Remember that as of Drupal 4.6, you can have site specific modules and themes as well. Just
create a directory under the sites/www.example1.com called ’modules’ and place the site
specific modules. The same applies to themes as well.

Consult the INSTALL.txt that came with your Drupal installation for more details.

Sharing Drupal tables between databases using MySQL5 Views
Note: The more Drupalish way to achieve this is through advanced table prefixing. The docs are
in this handbook.

Problem: You’d like to share some data between two different drupal websites without changing
any Drupal code or otherwise having to lift much of a finger. But you don’t want to share
information unless it meets certain requirements (for example, only users labeled "foo" in
somedatabase.sometable) For our example, we’ll use the users table.

Solution: Use MySQL5 Views (http://dev.mysql.com/doc/refman/5.0/en/views.html)

Our "master" users table resides in a database called "master". The database of the site that will
have restricted access to our masters users table is called "banana". Assumming you’re starting
with a fresh instance of the Drupal schema in your database "banana", do this:

mysql> use banana;
mysql> drop table users;
mysql> CREATE VIEW users AS
mysql> SELECT *
mysql> FROM master.users
mysql> WHERE uid IN (
mysql> SELECT uid
mysql> FROM somedatabase.sometable
mysql> WHERE uid = 0
mysql> OR label = ’foo’
mysql> )

Drupal will use banana.users just as it would a normal users table. No other modifications are
necessary. Now only "foo" users will be included in the users table for your banana website.

Note: Drupal has a dependency that is not really documented. Every users table must have an
entry that contains uid=0. It’s a "stub" entry that Drupal needs to function properly. A
workaround for this dependency is to include "user 0" in the results set that defines your view.

See, wasn’t that easy?

131
Drupal Handbook 3 Aug 2007

Multiple domains using the same database
If you want to host multiple domains (or subdomains) on top of the same database (e.g.
http://example.com/ and http://www.example.com/), simply use symbolic links to setup the
required configuration files:

$ ln -s sites/example.com sites/www.example.com
$ ls -l sites
-rw-rw-r-- 1 drupal drupal sites/example.com
lrwxrwxrrx 1 drupal drupal sites/www.example.com ->
sites/example.com

If your installation isn’t in the root folder then you need to specify the path to the Drupal
installation. For example if the URL to your installation is http://www.example.com/drupal/
you would use sites/www.example.com.drupal with a settings.php file in it.

If you want cookies to be shared between two sites, you will need to set the value of PHP’s
session.cookie_domain correctly. In the case above, set it to ".example.com". You can do this
through Drupal’s .htaccess file.

Same codebase, completely different content and users
This document assumes the following:

You want to create more than one Drupal site using the same codebase (the same basic set
of Drupal files, uploaded into one location).

You know how to install mysql tables in your database.
You know how to set up subdomains/folders/other domains that you want to use.
You have already downloaded Drupal 4.7, and set up one MAIN site.

This document contains instructions on how to create completely separate Drupal
site, with different configurations, users and content. Nothing is shared between
the installations except the codebase.

Some definitions:

codebase: the basic set of Drupal files, included in the .tar.gz
file. the stuff that makes Drupal work.

database: a collection of tables that stores data.

Affected files:

settings.php (sites/default/...)

132
3 Aug 2007 Drupal Handbook

database.mysql

For this example, we will assume the following:

www.example.com: the MAIN site, where the codebase has already been uploaded,
and settings.php has been properly configured.

sub1.example.com; www.example.com/sub2; www.subexample.com : the other sites
we will create.

1. Create the following folders in your sites directory:

sites/sub1.example.com/

sites/www.example.com.sub2/

sites/www.sub3example.com/

Copy the settings.php file from sites/default into each of the above folders.

2. There are different database files (inside the database folder). Select
the one that is appropriate for your database version. Copy it to each of the
folders you made in step 1. This is OPTIONAL, but it will help you keep things
straight.

3. Decide on SEPARATE PREFIXES for each site. Below is what we will use for
the example:

site
database prefix

sub1.example.com
sub1_

www.example.com,sub2
sub2_

www.sub3example.com
sub3_

4. Configure your settings.php for each site.

This code MUST BE CHANGED FOR EACH SITE:

$db_url = ’mysql://username:password@localhost/databasename’;

Note; if you are using the same database as the MAIN site, the $db_url is the
same.

133
Drupal Handbook 3 Aug 2007

OPTIONAL:

# $base_url = ’http://www.example.com’; // NO trailing slash!

# $conf = array(
# ’site_name’ => ’My Drupal site’,
# ’theme_default’ => ’pushbutton’,
# ’anonymous’ => ’Visitor’
# );

For sub1.example.com, the settings would be:

$db_prefix = ’sub1_’;
$base_url = ’http://sub1.example.com’;
$conf = array(
’site_name’ => ’My SUB1 Drupal Site’,
’theme_default’ => ’pushbutton’,
’anonymous’ => ’Visitor’
);

For www.example.com/sub2, the settings would be:

$db_prefix = ’sub2_’;
$base_url = ’http://www.example.com/sub2’;
$conf = array(
’site_name’ => ’My SUB2 Drupal Site’,
’theme_default’ => ’fancy’,
’anonymous’ => ’Anonymous’
);

For www.sub3example.com, the settings would be:

$db_prefix = ’sub3_’;
$base_url = ’http://www.sub3example.com’;
$conf = array(
’site_name’ => ’My SUB3 Drupal Site’,
’theme_default’ => ’marvin’,
’anonymous’ => ’Guests’
);

6. Upload the modified settings.php files in their respective folders.

7. Open the database file you copied into each sites folder. Find the following (don’t forget
the SPACE at the end!!!):
CREATE TABLE
INSERT INTO

134
3 Aug 2007 Drupal Handbook

Replace each ’create table’ and ’insert into’ with ’create table dbprefix_’ and ’insert into
dbprefix_’

For sub1.example.com:
CREATE TABLE >> CREATE TABLE sub1_
INSERT INTO >> INSERT INTO sub1_

8. Upload the modified mysql files into the database you specified in your settings.php.

9. Voila!

Setup of /sites directory for multi-site
Drupal’s multi-site hosting capability is built in with any installation. This is great news for
users who run numerous web sites from a single hosting account. A single Drupal installation
can be used to run multiple domains, which makes it much easier to manage and maintain the
code base. Even if you are dealing with only one domain, the multi-site capability may be
valuable by providing the ability to run a separate domain or sub-domain for a development
version.

This page describes the set-up of the /sites directory for multi-sites. The single-site basics are
discussed at Basic /sites directory setup.

With version 5.x, the intended location for all non-core elements of a Drupal installation is in a
separate /sites directory inside the Drupal installation.

Directory Contents
/drupal/sites/all /modules
(used by all sites) /themes
/drupal/sites/default /files
(used when there is no /sites/example.com directory) settings.php
/files
/module
/drupal/sites/example1.com /themes
/tmp
settings.php
/files
/module
/drupal/sites/example2.com /themes
/tmp
settings.php

135
Drupal Handbook 3 Aug 2007

The intended best practice configuration is to create a /sites/example.com directory for each
domain. It should contain a site-specific settings.php file and /files directory. Configure Drupal
site settings to specify ’File System Directory’ of ’sites/example.com/files’ instead of the default
’files’. It’s possible to do this with an existing web site, but moving file uploads around can cause
a lot of confusion if there are already URLs pointing to the old locations.

Domain specific modules and themes should also be placed in /sites/example.com/modules
and /sites/example.com/themes respectively.

Contributed modules and additional themes which are for use by all domains in a multi-site
installation should be placed in /sites/all/modules and /sites/all/themes. Note that there
shouldn’t be a /sites/all/files or /sites/all/settings.php.

The /sites/default directory should contain /files and settings.php, for use if the
/sites/example.com directory doesn’t exist for a domain.

In addition to multiple sites, such as www.example1.com and www.example2.com, sub
domains are also easily set up. Adding sub3.example2.com and sub3.example2.com/site4, the
directory structure for these four sites would be:

/drupal/sites/all/modules
/drupal/sites/all/themes
/drupal/sites/default/files
/drupal/sites/default/settings.php
/drupal/sites/example1.com/files
/drupal/sites/example1.com/modules
/drupal/sites/example1.com/settings.php
/drupal/sites/example1.com/themes
/drupal/sites/example1.com/tmp
/drupal/sites/example2.com/files
/drupal/sites/example2.com/modules
/drupal/sites/example2.com/themes
/drupal/sites/example2.com/tmp
/drupal/sites/example2.com/settings.php
/drupal/sites/sub3.example2.com/files
/drupal/sites/sub3.example2.com/modules
/drupal/sites/sub3.example2.com/settings.php
/drupal/sites/sub3.example2.com/themes
/drupal/sites/sub3.example2.com/tmp
/drupal/sites/sub3.example2.com.site4/files
/drupal/sites/sub3.example2.com.site4/modules
/drupal/sites/sub3.example2.com.site4/settings.php
/drupal/sites/sub3.example2.com.site4/themes
/drupal/sites/sub3.example2.com.site4/tmp

136
3 Aug 2007 Drupal Handbook

Once you’ve done this, the file structure of your site will be cleanly organized:

The main Drupal directory will contain only the standard ’core’ files.
All of your custom themes, add-ons, settings, and so on will be in /sites/example.com,
/sites/all, or /sites/default.
/sites/default/settings.php and /files will be used if there is no /sites/example.com
directory.
/sites/all/modules and /themes will be available to all sites.
Backing up the /sites directory and your Drupal database will give you everything you
need to restore the site in the event of a crash, or to move to a new server.
Adding a domain is easy: just copy the /sites/default directory to /sites/example5.com

Symbolic links can be used for several purposes:

Even if using default settings, a good option is to use links from /sites/example.com
directory to point to the /sites/default directory. That way, if the settings and /files are
ever changed from the default and actually placed in /sites/example.com, their location
does not ’move’ and no links are broken.
Links could also be used to point the /sites/default directory to your primary site.
A /files directory could easily be shared across two domains without being shared across
the remaining domains.
A non-domain-name path for /files can be setup. If it is possible that the domain name
might change (say, from a development name), then you can set up a link from
/drupal/sites/moniker to /drupal/sites/example.com, where ’moniker’ is a short version
of the site name that will remain constant even if /example.com changes.

Although the /sites/default directory could contain a /modules and /themes directory, these
elements should usually be placed in /sites/all or /sites/example.com. Similarly, although
contributed modules could be placed in /drupal/modules as was the practice in version 4.7, this
is not recommended.

Multi-site directory setup for sub-domains, including non-standard ports, is described in the
installation instructions (INSTALL.txt).

See multidomain for a contributed module that allows spanning one site across multiple
domains, so that specific content types appear on specific domains or sub-domains.

Version 4.6 and 4.7: Best practice for multi-site set-up under version 4.6 and 4.7 is similar to 5.x.
The primary difference is that there is no /sites/all directory. Instead, /modules and /themes
that are available for all domains are kept in /drupal/modules and /drupal/themes.

Installing new themes
Once you get Drupal installed and you start to come to terms with it you will probably want to
customize the way it looks.

137
Drupal Handbook 3 Aug 2007

There are several themes which you can download from the Drupal web site which should get
you started.

Installing a new theme is very straightforward:

1. Download a new theme package. Note that themes for different Drupal versions are not
compatible, version 4.4 themes do not work with Drupal 4.5 and reverse.
2. Read any README or INSTALL files in the package to find out if there are any special
steps needed for this theme.
3. Check to see if you have the required theme engine to be able to display your theme. Theme
engine files go in a folder in themes/engines in your Drupal directory.
4. Upload the contents of the theme package to a new directory in the themes directory in
your Drupal site. For example;
in 4.7 you place your theme in themes/box_grey.
in 5.0 you place your themes in /sites/all/themes/box_grey
5. Click administer » themes and enable the new theme (Drupal will auto-detect its presence).
6. Edit your user preferences and select the new theme. If you want it to be the default theme
for all users, check the default box in the themes administration page.

Note: You can see a variety of themes on themes.drupal.org. Some of these themes shown there
are available for download from Drupal.org and others are merely samples.

138
3 Aug 2007 Drupal Handbook

Basic site configuration
Drupal is an extremely flexible platform that provides you with many options for changing how
your site looks, how users interact with it, and the kinds of information you wish to display.
Although there are many configuration options, Drupal works well "out of the box" and there is
very little initial configuration to perform. As your site evolves and your demands grow, Drupal
makes it easy for you to dramatically alter its look and add to its functionality. Best of all,
because it is released under the GNU General Public License, Drupal is infinitely customizable
and lets you tailor it to your specific needs.

You will want to start your configuration with your drupal site’s basic settings can be found on
the settings page, which you can reach by clicking administer » settings in the navigation
block. You must be logged in and have permission to access this page. After you change the
settings, don’t forget to click "Save configuration" at the bottom of the page.

The information you enter here is stored in Drupal’s database to help Drupal decide how to
prepare and serve your pages. Keep in mind that the settings on this page are only basic
configuration settings. There are many other places to configure Drupal. These are discussed in
the appropriate sections of this handbook. Much of the configuration information can be found
in the modules help file or in the modules section of the handbook. For more advanced
configuration then an out of the box modules provide, see the Customization and theming
handbook.

A lot of the information you are asked to supply on the settings page is self-explanatory and
there are brief help messages below each setting to guide you. Note that the "Slogan," "Mission,"
and "Footer message" may or may not be immediately visible, depending on the theme you are
using. If you are new to Drupal, we recommend supplying all the information for these boxes. If
you decide that you don’t need or like how Drupal uses them, you can change it later (see the
handbook section on configuring themes for more on this).

Settings
Below are links to provide you with explanations and tips for some of the more technical
settings on the "settings" page. If you just want to get Drupal up and running, you can safely
ignore these settings. You’ll always be able to come back and experiment with them later. The
one possible exception to this is the "file system settings" which you may wish to set now. For
more information on the "File system settings," click its link below. This link can also help you
resolve issues with errors that often appear at the top of the "settings" page after Drupal is
freshly installed.

You can

configure your sites basic settings at administer >> settings.

139
Drupal Handbook 3 Aug 2007

General settings
The General settings area is where you configure some basic information for your site.

Name: this is where you set the name displayed for your site.

E-mail address: A valid e-mail address for this website, used by the auto-mailer during
registration, new password requests, notifications, etc. You can set this to a real email address
that people can reply to or to something generic no-reply@example.com that is outbound only.
The email server that your site uses is set in the php.ini file and not by Drupal.

Slogan: The slogan of this website. Some themes display a slogan when available. It will also by
displayed in the title bar of your sites visitor web browser.

Mission: Your site’s mission statement or focus. Your mission statement is enabled in your
theme settings and requires that the theme support it’s display.

Footer: This text will be displayed at the bottom of each page. Useful for adding a copyright
notice to your pages.

HTML formating can be used in the mission and the footer areas.

Anonymous user: Users who interact with your site without being logged in are labeled as
"Anonymous" by default. Drupal gives you the option to change this to something different (e.g.
"Anonymous coward"). The name you give anonymous users is used by Drupal when creating
bylines for posts which typically reads something like, "Posted by Anonymous on January 1,
2006".

Default front page
This setting gives you control over what Drupal-generated content a user sees when they visit
your Drupal installation’s root directory. For example, you might have created a node with a
large collection of links to act as a table of contents to the different sections of your site and you
want this directory to be what users see first.

This setting tells Drupal which URL users should be redirected to. It’s important to note that the
URL is relative to the directory your Drupal installation is in. So, instead of

"http://www.example.com/node/83"

or

"http://www.example.com/drupal_installation_directory/node/83,"

you need only type "node/83". For those not using clean URLs, note that there is no need to type
in "?q=" before typing the URL.

140
3 Aug 2007 Drupal Handbook

By default, the "Default front page" is set to "node," which simply displays articles that have
been "Promoted to front page." Note that when you change the "Default front page" to
something other than "node", nodes that are "Promoted to front page" will no longer appear on
the front page. They can however, still be viewed by visiting the relative URL path "node".

If you enter a value in here that is not a valid Drupal path, the user will be confronted with a
"Page not found" error. You cannot redirect users to any web documents (e.g. a static HTML
page) not created by your Drupal site.

Examples
Problem 1:
You want a particular node to be the first page user’s see when they visit
http://www.example.com (we are assuming Drupal is installed in the site’s root directory).
Solution:
Determine the id number of the node you wish to have Drupal redirect users to. One way to
determine the node’s id number is to visit the node and look at the number after the last
slash in your browser’s address bar. This is your node’s id number. Now set the "Default
front page" to "node/id#". So, assuming your node’s id is "83," you would type "node/83".
Problem 2:
You want user blogs to be the front page.
Solution:
Set the "Default front page" to "blog".
Problem 3:
You want content from a single category to appear on the front page
Solution:
Determine the category’s id number. You can determine the id number by going to
administer » categories. Roll the mouse on top of the "edit term" link next to the category to
reveal the URL in your browser’s status bar (usually located at the bottom of your browser’s
window). The number after the last slash in the URL is the category’s id number. Now set
the "Default front page" to "taxonomy/term/id#". If your category’s id number is "5" for
example, you’d write "taxonomy/term/5".

Clean URLs
By default, Drupal passes path arguments to itself via its internally generated URLs. This results
in URLs that look like the following: "http://www.example.com/?q=node/83." This can make
URLs hard to read and it also stops many search engines, like Google, from indexing the pages
with these URLs.

You can tell Drupal to use "clean URLs", eliminating the "?q=" in internal URLs. Note that this
works only for Apache servers which have the LoadModule rewrite_module configured and
mod_rewrite enabled in httpd.conf configuration file.

141
Drupal Handbook 3 Aug 2007

There are two ways to enable URL rewrites in Apache. If there is complete control of the Apache
webserver clean URLs should be enabled in the httpd.conf as this has better performance and
security.

Warning. Enabling "Clean URLs" if your server is not properly configured can make it difficult
to navigate back to administration pages to undo your mistake. If you find yourself in this
situation, you can return to the administrative settings page by typing in the URL in the
’non-clean’ form: http://www.example.com/?q=admin/settings.

Enabling clean URLs involves three steps:

1. Enable mod_rewrite for Apache. Please talk to your web host or consult the Apache
documentation for mod_rewrite to get more information on how to do this. At a minimum,
this will involve making sure that mod_rewrite is enabled for your installation of Apache. It
will have to be either compiled-in or made available as a loadable module. Generally
speaking, you can tell Apache to load the module by including
LoadModule rewrite_module modules/mod_rewrite.so
AddModule mod_rewrite.c

in your Apache configuration file. Be sure to uncomment AddModule mod_rewrite.c. Note
that this may not be the case for all distributions of *nix operating systems. Consult your
distribution’s documentation that came packaged with your Apache software. We also
recommend disabling multiviews in Apache as they conflict with clean URLs.

2. Edit your Apache configuration files for your site: the configuration information may be
found in httpd.conf, a virtual-host-specific file, or in an .htaccess file in your Drupal
installation directory. You can find this file usually in /etc/httpd/conf/httpd.conf. You
may use
find /etc -name httpd
to find the file if it is located else where in your Unix system. The main configuration option
which may need to be changed for your site is the RewriteBase. For example, if your
Apache DocumentRoot is /var/www/ (i.e., /var/www/index.html is what is displayed
when you point your browser at http://www.example.com/) and your Drupal installation
is installed in the subdirectory /var/www/mysite/, then the RewriteBase should be set to
/mysite. In some configurations setting
RewriteBase /
will allow mod rewrite to work.

If you don’t use the .htaccess that comes with Drupal you’ll need to add some rewrite rules
into your apache directory directive. Consult the .htaccess file in Drupal for examples of
rules.

142
3 Aug 2007 Drupal Handbook

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

You will also need to set the Allow Override settings in httpd.conf so that local .htaccess
commands will be run for you site. If you are changing the .htaccess file in the Drupal
distribution you want to set it to

AllowOverride All
to ensure rewrites are enabled. Read "Behind the scenes with Apache’s .htacces for a
thorough review of .htaccess.Here are samples of Apache 2 directives.
3. You should ensure your Drupal site has the path module enabled and the correct
permissions set in order to create custom URLs. You can enable the path module in
administer >> modules. You can then set permissions to administer URL aliases and create
URL aliases. Enable clean URLs on your administration >> settings page. First, see if you
can go to the settings page on your site using clean URLs: type in the URL
http://www.example.com/admin/settings (where www.example.com is replaced by your
hostname). If you get no errors and get to the same page you would have gotten to by clicking
on "administer" then "settings" , then you know that you have setup the ReWriteRule rules
successfully and can then click the Yes checkbox for "Clean URLs:" . If you have problem you
can read the instructions to unset clean URLs. If you If you still have problems with clean
URLs you can set the Drupal Settings.php $conf[’clean_url’]=1;.

Note: The standard Drupal installation contains a sample .htaccess file which supports clean
URLs. It is easy to miss copying this file, because of the leading "dot".

Note Regarding MultiViews: The Apache webserver supports a feature called "MultiViews"
(more generally: "Content Negotiation"), which allows navigation to your pages without the
need for file extensions. For instance, if you had a file called "evaluation.txt", a
MultiViews-enabled site could access this file with the URL "example.com/evaluation". While
MultiViews can be a handy feature when used knowingly, they can cause problems when
Drupal’s Clean URLs are enabled. Unless you know what you’re doing, you should consider
disabling MultiViews if you plan to use the clean URLs feature of Drupal. Be aware that there’s a
good chance that MultiViews is already disabled, however; it’s not enabled in a default Apache
installation. Consult the Apache documentation for further information about MultiViews.

.htaccess for clean urls on specific shared hosts
zorroposada posted this .htaccess file, the use of which then allowed clean urls to be enabled
when using several hosts like 1and1.com, mediatemple.net, ehostpros.com, ehosting.ca

143
Drupal Handbook 3 Aug 2007

bobdonohue reported that this .htaccess file worked on dotster.

This code was taken from the boost.module and modified just a little bit.

There is no guarantee this will work for you though.

Instructions:

Create a text file, copy and paste the code below and save it as .htaccess

Upload the file and put it in the public_html directory of your site.

Modify "RewriteBase /" in line 68 to "RewriteBase /example" if your site is in
subdirectory "example."

#
# Apache/PHP/Drupal settings:
#
# Protect files and directories from prying eyes.
<FilesMatch
"(\.(engine|inc|install|module|sh|.*sql|theme|tpl(\.php)?|xtmpl)|code-style\.pl|Entries.*|Repository|Root)$">
Order deny,allow
Deny from all
</FilesMatch>
# Set some options.
Options -Indexes
Options +FollowSymLinks
# Customized error messages.
ErrorDocument 404 /index.php
# Set the default handler.
DirectoryIndex index.php
# Override PHP settings. More in sites/default/settings.php
# but the following cannot be changed at runtime.
# PHP 4, Apache 1
<IfModule mod_php4.c>
php_value magic_quotes_gpc 0
php_value register_globals 0
php_value session.auto_start 0
</IfModule>
# PHP 4, Apache 2
<IfModule sapi_apache2.c>
php_value magic_quotes_gpc 0
php_value register_globals 0
php_value session.auto_start 0
</IfModule>
# PHP 5, Apache 1 and 2
<IfModule mod_php5.c>
php_value magic_quotes_gpc 0

144
3 Aug 2007 Drupal Handbook

php_value register_globals 0
php_value session.auto_start 0
</IfModule>
# Reduce the time dynamically generated pages are cache-able.
<IfModule mod_expires.c>
ExpiresByType text/html A1
</IfModule>
# Various rewrite rules.
<IfModule mod_rewrite.c>
RewriteEngine on
# If your site can be accessed both with and without the prefix www.
# you can use one of the following settings to force user to use only
one option:
#
# If you want the site to be accessed WITH the www. only, adapt and
uncomment the following:
# RewriteCond %{HTTP_HOST} !^www\.example\.com$ [NC]
# RewriteRule .* http://www.example.com/ [L,R=301]
#
# If you want the site to be accessed only WITHOUT the www. , adapt
and uncomment the following:
# RewriteCond %{HTTP_HOST} !^example\.com$ [NC]
# RewriteRule .* http://example.com/ [L,R=301]
# Modify the RewriteBase if you are using Drupal in a subdirectory
and
# the rewrite rules are not working properly.
RewriteBase /
# Rewrite old-style URLs of the form ’node.php?id=x’.
#RewriteCond %{REQUEST_FILENAME} !-f
#RewriteCond %{REQUEST_FILENAME} !-d
#RewriteCond %{QUERY_STRING} ^id=([^&]+)$
#RewriteRule node.php index.php?q=node/view/%1 [L]
# Rewrite old-style URLs of the form ’module.php?mod=x’.
#RewriteCond %{REQUEST_FILENAME} !-f
#RewriteCond %{REQUEST_FILENAME} !-d
#RewriteCond %{QUERY_STRING} ^mod=([^&]+)$
#RewriteRule module.php index.php?q=%1 [L]
# Rewrite rules for static page caching provided by the Boost module
# BOOST START
<IfModule mod_mime.c>
AddCharset utf-8 .html
</IfModule>
RewriteCond %{REQUEST_URI} !^/cache
RewriteCond %{REQUEST_URI} !^/user/login
RewriteCond %{REQUEST_URI} !^/admin
RewriteCond %{HTTP_COOKIE} !DRUPAL_UID
RewriteCond %{REQUEST_METHOD} ^GET$

145
Drupal Handbook 3 Aug 2007

RewriteCond %{QUERY_STRING} ^$
RewriteCond %{DOCUMENT_ROOT}/cache/%{SERVER_NAME}/0/%{REQUEST_URI} -d
RewriteCond
%{DOCUMENT_ROOT}/cache/%{SERVER_NAME}/0/%{REQUEST_URI}/index.html -f
RewriteRule ^(.*)$ cache/%{SERVER_NAME}/0/$1/index.html [L]
RewriteCond %{REQUEST_URI} !^/cache
RewriteCond %{REQUEST_URI} !^/user/login
RewriteCond %{REQUEST_URI} !^/admin
RewriteCond %{HTTP_COOKIE} !DRUPAL_UID
RewriteCond %{REQUEST_METHOD} ^GET$
RewriteCond %{QUERY_STRING} ^$
RewriteCond
%{DOCUMENT_ROOT}/cache/%{SERVER_NAME}/0/%{REQUEST_URI}.html -f
RewriteRule ^(.*)$ cache/%{SERVER_NAME}/0/$1.html [L]
# BOOST END
# Rewrite current-style URLs of the form ’index.php?q=x’.
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]
</IfModule>
# $Id: boosted.txt,v 1.4 2006/12/05 10:39:19 arto Exp $

403 Permission denied error
So you’ve tried every advice above but still get the 403, "You don’t have permission to access",
error when testing for clean urls. This is how I solved it after many tedious hours of googling....

Apparently there’s an option called Multiview in apache which enables the server to look for
files without an extension in the parent directory of the directory you specified, if it can’t find
the directory. So if you type www.mysite.com/admin/settings and it can’t find the directory it
looks for a file named settings.(some extension) in www.mysite.com/admin, however if you
also have directory browsing turned of and it can’t find a file it will report it as you trying to
find a file in www.mysite.com/admin which you don’t have a permission to view or doesn’t
exist i.e. the 403 error. To solve this you either turn of diretory browsing in your .htaccess file by
writing:

Options +Indexes

instead of

Options -Indexes

However if you don’t feel like having directory browsing on, I guess most people do, you just
turn of Multiviews like this under the other options in your .htaccess file:

146
3 Aug 2007 Drupal Handbook

Options -MultiViews

A mod_rewrite bug causing occasional corruption of the query string
It seems that using mod_rewrite to set or modify the query string can corrupt it. One case where
it certainly fails is if the URL has %2B (a urlencoded "+" character) in it.

As a demonstration, try searching for the string "alice + bob". You can see on
http://drupal.org/search/node/alice+%2B+bob that the rewrite rules change the %2B to a
space, while on http://drupal.org/?q=search/node/alice+%2B+bob it work correctly without
clean URLs.

The reason I am posting it here as a warning and not as a bug report is that it’s not a Drupal
issue, but a mod_rewrite issue. (It would be worth a bug report for mod_rewrite, but they have
such bug reporting guidelines that require a few hours’ work to follow...)

Apache 2 configuration of clean URLs on Debian
If you’re running Apache2 on Debian stable, in order to install the rewrite module you simply
need to:

# a2enmod rewrite

then restart the webserver:

# /etc/init.d/apache2 restart

then edit either /etc/apache2/sites-enabled/drupal or to your .htaccess and ensure it looks
something like this:

#
# Apache/PHP/site settings:
#
# Protect files and directories from prying eyes:
<Files ~
"(\.(conf|inc|module|pl|sh|sql|theme|engine|xtmpl)|Entries|Repositories|Root|scripts|updates)$">
order deny,allow
deny from all
</Files>
# Set some options
Options -Indexes
Options +FollowSymLinks
# Customized server error messages:
ErrorDocument 404 /index.php
# Set the default handler to index.php:
DirectoryIndex index.php
# Overload PHP variables:
<IfModule sapi_apache2.c>

147
Drupal Handbook 3 Aug 2007

# If you are using Apache 2, you have to use <IfModule
sapi_apache2.c>
# instead of <IfModule mod_php4.c>.
php_value register_globals 0
php_value track_vars 1
php_value short_open_tag 1
php_value magic_quotes_gpc 0
php_value magic_quotes_runtime 0
php_value magic_quotes_sybase 0
php_value arg_separator.output "&amp;"
php_value session.cache_expire 200000
php_value session.gc_maxlifetime 200000
php_value session.cookie_lifetime 2000000
php_value session.auto_start 0
php_value session.save_handler user
php_value session.cache_limiter none
php_value allow_call_time_pass_reference On
</IfModule>
# Various rewrite rules
<IfModule mod_rewrite.c>
RewriteEngine on
Options All
# Modify the RewriteBase if you are using Drupal in a subdirectory
and the
# rewrite rules are not working properly:
RewriteBase /drupal
# Rewrite old-style URLS of the form ’node.php?id=x’:
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{QUERY_STRING} ^id=([^&]+)$
RewriteRule node.php index.php?q=node/view/%1 [L]
# Rewrite old-style URLs of the form ’module.php?mod=x’:
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{QUERY_STRING} ^mod=([^&]+)$
RewriteRule module.php index.php?q=%1 [L]
# Rewrite URLs of the form ’index.php?q=x’:
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]
</IfModule>
# $Id: .htaccess,v 1.58 2004/10/09 20:41:49 dries Exp $

This is because the debian package installs the drupal "sites-enabled" virtual host, result being
that drupal is accessed from http://yourhost.com/drupal, hence the need to uncomment
RewriteBase. Change it to the base that corresponds to your system.

148
3 Aug 2007 Drupal Handbook

ref: http://www.debian-administration.org/articles/136
http://drupal.org/node/14322

--
Sean K. O’Brien
CTO
Colley Graphics, LLC
http://www.colleygraphics.com

Apache 2 on Ubuntu
Two methods here:

Editing apache2.conf

First thing to do is make sure you have apache up and running:
/etc/init.d/apache2 start

Then you have to enabled the rewrite module(mod_rewrite). You no longer have to do the:
LoadModule rewrite_module modules/mod_rewrite.so
AddModule mod_rewrite.c

It’s now as easy as:
a2enmod rewrite

To disable this module it’s just:
a2dismod rewrite

with Apache version 2, the httpd.conf has been depreciated and the new file is located at:
/etc/apache2/apache2.conf

in this file you need to add your directory and the allow override to give access to your drupal
site.
so look for a section in your apache2.conf that has Directory tags and just add another section:

<Directory /var/www/drupal_website_install>
AllowOverride all
</Directory>

*keep in mind that my website is in a subdirectory (drupal_website_install) and so you may
need to edit the above to reflect this. By this I mean if i go into my webbrowser I need to go to
http://localhost/drupal_website_install/

After you edit you apache2.conf as listed above you need to restart the server by:
/etc/init.d/apache2 restart

149
Drupal Handbook 3 Aug 2007

If you are having problems with getting your rewrite to work you can always use logging. To do
that add this to the end of you apache2.conf:

RewriteLog "/var/log/apache2/rewrite.log"
RewriteLogLevel 3

Level 0 is no logging
Level 9 is log everything
You can pick the level to determine the amount of output you need.
***Security Warning: Make sure to take the log code out, disable it, or put the log file in a
directory that can’t be read by normal users (as shown above) otherwise it can result in a
security breach.***
hopefulley this helps some people and saves them the time that I spent trying to get it working.

Editing apache2/sites-available

My configuration:
drupal 5.x
apache 2.2
mysql 5.0
debian/ubuntu server install

drupal path: /www/drupal/sites/site1...site2

I have root access to my server.

First, from the linux command line, I enabled the rewrite module for apache like this:

a2enmod rewrite

Next I restarted Apache:

sudo /etc/init.d/apache2 restart

Then I reloaded Apache config files:

sudo /etc/init.d/apache2 reload

Finally, I changed the file located at:

/etc/apache2/sites-available/default

(in the sites-available directory, you should see as many files as you have websites enabled. One
is named default and the others should reflect the names of your additional sites if you are
running virtual hosts. If you have only a single site, it will most likely be named default. You can
open these files in an editor such as nano and make changes.)

150
3 Aug 2007 Drupal Handbook

change this directive in the file(s) found in sites-available:

AllowOverride None to AllowOverride All

Save this file and then restart apache as we did above.

Now browse to your site with your browser, login, click administer, find "Clean URLs" and
browse to that page, run the test for "Clean URLs" buried in the paragraph explaining "clean
Urls".

If your setup is like mine, you should now have Clean URLs in drupal.

Clean URL Support in Abyss
This clean URL implementation has been tested on Abyss X1, one which has a properly set
Custom Error Page 404 to any arbitrary file that, for this purpose, will be referenced as
"/url_rewrite.php". Due to the generalized design of this solution, this method could
theoretically work on virtually any webserver that can redirect missing URI location onto a php
resource. The method described here works only on webservers with a singular host
configuration.

One esoteric requirement is for the webserver to pass the server variable REQUEST_URI
containing the value of the original resource requested. For more information on configuring
Abyss X1 for this purpose, please visit this Aprelium forum resource.

This solution could be rendered academic if Aprelium finally decides to implement URL rewrite
in Abyss internally. This method is useful for Abyss webservers version 2.3.2 and most other
versions prior to this specific release. Another drawback is that the URL rewrite becomes only
invisible to the machine but is always visible to the human.

The idea is to pass (or redirect) the missing URI location on the HTTP-404 handler
"/url_rewrite.php". For illustrative examples, let’s look at the following scenarios:

1. http://www.example.com/node/add => "/node/add" not found, pass to 404 handler
"/url_rewrite.php" => "/url_rewrite.php" determines "/index.php?q=node/add" exists and
serves that instead.
2. http://www.example.com/admin/settings => "/admin/settings" not found, pass to 404
handler "/url_rewrite.php" => "/url_rewrite.php" determines
"/index.php?q=admin/settings" exists and serves that instead.
3. http://www.example.com/no_exist/location => "/no_exist/location" not found, pass to
404 handler "/url_rewrite.php" => "/url_rewrite.php" determines
"/index.php?q=no_exist/location" exists and serves that instead but lets Drupal display the
proper "page not found" informational message.

Here are the steps in letting this method apply to your setup.

151
Drupal Handbook 3 Aug 2007

1. Create the following file and save it as "/url_rewrite.php".
<?php
/* Add in this array the list of (old path => new path) pairs */
$redirection = array(
’^(.*)$’ => ’index.php?q=$1’
);
if (!file_exists($_SERVER["REQUEST_URI"]))
/* Get the URI and trim leading slashes */
$uri = ltrim($_SERVER["REQUEST_URI"], "/");
{
foreach ($redirection as $key => $value)
{
if (eregi($key, $uri))
{
/* Convert the replacement string syntax - $1 -> \1 */
/* and perform the substitution */
$uri = str_replace("index.php","",substr($uri,0));
$new_uri = str_replace("?","&",$uri);
$new_uri = "/index.php?q=".$new_uri;
$new_uri = str_replace("%26","&",$new_uri);
break;
}
}
}
if (isset($new_uri))
{
header("Status: 307");
header("Location: $new_uri");
exit;
}
?>
<!-- Your 404 error page -->
<HTML>
<HEAD>
<TITLE>Not Found</TITLE>
</HEAD>
<BODY>
The object <tt><?php echo $uri; ?></tt> is not available.
</BODY>
</HTML>
2. In the Abyss web console, enter the Custom Error Pages, add a 404 Status Code entry with
the Associated URL value "/url_rewrite.php". Click OK and restart the Abyss webserver.
3. Test for functionality by querying your website directly with URI’s such as:
http://www.example.com/admin/settings
http://www.example.com/node/add

152
3 Aug 2007 Drupal Handbook

If the redirection works properly, proceed to the next steps. If the redirection would not
work, check if the steps above have been strictly followed. Modify only those things that you
have absolute knowledge of.

4. Log on to your website and log on to your "/admin/settings" page. Under General Settings
section, enable Clean URLs. If the Clean URLs option is grayed out, add the line
"$conf[’clean_url’] = 1;" in your settings.php, then repeat this step. Don’t forget to click the "Save
configuration" button.
5. If things do not work out, completely remove the line "$conf[’clean_url’] = 1;" from your
settings.php. And browse to your http://www.example.com/index.php?q=admin/settings
page to disable Clean URLs properly.

Clean URL support in XAMPP
Clean URLs do not work out of the box on XAMPP 1.5.x with PHP4 due to a problem in
Apache’s module load order; mod_rewrite will not work properly. To remedy this edit the file
[path_to_xampp]/apache/conf/httpd.conf.

Move the line

LoadModule rewrite_module modules/mod_rewrite.so
to just above or below
#LoadModule cache_module modules/mod_cache.so

You also have to set AllowOverride All for the directory Drupal is in. Do this in
httpd.conf or extra/httpd-xampp.conf

Always restart Apache or changes to its configuration files won’t have an effect.

If Drupal is not installed in the document root, the next thing you’ll have to do is to modify the
file .htaccess, that comes with Drupal. Remove the commentsign (#) in front of RewriteBase
and, if necessary, modify the path:

RewriteBase /drupal

Finally, in Drupal go to administer » settings (admin/settings) and click the "Enabled" option for
Clean URLs and save the settings.

Clean URLs in Mac OS X Server
For Mac OS X Server 10.4 (Tiger Server) and most likely previous versions as well, do not make
changes to /etc/httpd/httpd.conf expecting the AllowOverride All directive to work.
The correct file to add the AllowOverride All directive is in the directory
/etc/httpd/sites/. In that directory are the virtual host configuration files. Each virtual
server has a configuration file in that directory so it is in those files that you must enable
AllowOverride All. If you only have one web server on your server configured, then the file
you want to modify is /etc/httpd/sites/0000_any_80_.conf.

153
Drupal Handbook 3 Aug 2007

Clean URLs with different webservers
Microsoft Internet Services Server

Windows ISS MySQL PHP(WIMP)-Tips for Configuring Drupal on WIMP

Lighttpd

For those who have stepped up a notch in performance and moved from Apache to Lighttpd,
you can use the following configuration for Lighty’s mod_rewrite module:

url.rewrite-final = (
"^/system/test/(.*)$" => "/index.php?q=system/test/$1",
"^/([^.?]*)\?(.*)$" => "/index.php?q=$1&$2",
"^/([^.?]*)$" => "/index.php?q=$1"
)

The first line ensures that Drupal’s clean URL check (when saving Settings) succeeds (Drupal
makes an HTTP request for a path of the form /system/test/yLgnwqqUu5cWnvPi4Hrz.png). It’s a
special case that must be handled separately (read on for the reason).

The two following lines let Drupal handle any URL that doesn’t contain a dot. This is significant
because we can assume, fairly confidently, that addresses like /node/add are Drupal URLs, but
addresses such as /themes/bluemarine/style.css are physical files. So the above configuration will
work for all cases where this assumption holds true; if there are exceptions to the rule, they can
be manually added to the rewrite configuration.

See also the related discussion at http://drupal.org/node/20766

I just successfully set up lighttpd 1.4.8 with php4 via fastcgi using those rules above.
As per lighttpd documentation I also set up /etc/php4/cgi/php.ini to have that cgi fix. Then I
added those rewrite rules for corresponding virtual_host.

Ubuntu breezy’s php4-cgi package
bougyman’s lighttpd package (see http://www.lighttpd.net/download/ for details)

Clean URLs with Easyphp.
To get that the clear URLs works in Easyphp 1.8 you have to join the httpd.conf file and change
this two lines:

#LoadModule rewrite_module modules/mod_rewrite.so

and

#AddModule mod_rewrite.c

154
3 Aug 2007 Drupal Handbook

and leave like this in the same line.

LoadModule rewrite_module modules/mod_rewrite.so

y

AddModule mod_rewrite.c

and Re-start the server.

Easyphp have the mod_rewrite within.

If there is any problem tell me.

Oskar Calvo.

Example Clean URL configuration of httpd.conf for performance
This was tested and applies to FC4/php5/Apache 2.0.54.

Enabling .htaccess in Apache requires more work on the part of the server. A full explanation
can be found here:
http://www.serverwatch.com/tutorials/article.php/3436911
Suffice it to say that it is in your interest to not use .htaccess files and even disable them if you
are concerned about squeezing more performance out of apache.

I moved the rewrite rules (all of the sample .htaccess file really) to /etc/httpd/conf/drupal.conf.
Then for each virtual host, one can add the line:

Include conf/drupal.conf
The rewrite rules change slightly:
# Rewrite current-style URLs of the form ’index.php?q=x’.
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ /index.php?q=$1 [L,QSA]

Note that I added %{DOCUMENT_ROOT} and a leading slash in front of index.php -- because I
have index.php installed in my document root. If you install it in another directory, you will
want to give the relative path to it from document root with the leading slash.

Important: If you forget the leading slash (more specifically, forget to give the relative path with
leading slash), Apache will give you a "400 Bad Request" error.

This is better. But we still have a problem where every request will check for the existence of a
file and a directory before we apply the rewrite rule. The OS may be able to cache some of that
information, but it would still be better to avoid the two file-system checks in the first place.

155
Drupal Handbook 3 Aug 2007

There are some directories that we should not rewrite. And there are certain extensions that we
should not rewrite. Using this information, we can update the rewrite rule to send everything to
index.php that does not fall into this category. The first rule excludes the directories "files",
"misc", and "uploads". The second rule excludes the extensions you see. Add more if you have
other extensions in your directory that should not get passed to index.php.

RewriteCond %{REQUEST_FILENAME} !^/$
RewriteCond %{REQUEST_FILENAME} !^/(files|misc|uploads)(/.*)?
RewriteCond %{REQUEST_FILENAME}
!\.(php|ico|png|jpg|gif|css|js|html?)(\W.*)?
RewriteRule ^(.*)$ /index.php?q=$1 [L,QSA]

Existing URLs for server overwrite Drupal paths
If your server has existing paths like /admin then you can either move your Drupal instance to a
subdirectory like /home/admin or you can create a virtual link to ?=admin.

IIS CleanURLs using some of the available ISAPI filters.
There is a free version called ISAPI_Rewrite Lite that should get clean URLs working for IIS.
Install that and insert these rewrite rules.

# Accept a url with the following extensions and pass them through
unchanged.
RewriteRule (.*.gif|.*.png|.*.jpg|.*.pdf|.*.js|.*.css) $1 [I,L]
# Make URLs sane
RewriteRule /index.php.* $0 [I,L]
RewriteRule /(.*)\?(.*) /index.php\?q=$1&$2 [I,L]
RewriteRule /(.*) /index.php\?q=$1 [I,L]

Next, add the following line to the end of your settings.php file for your site:

$conf[’clean_url’] = 1;

Translating Apache’s rewrite rules

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d

In plain English: If the REQUEST_FILENAME variable does not exist (not an existing file and
not an existing directory) then apply the rule:
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]"

After much research this exact functionalty does not appear to exist in any ISAPI module for IIS.
I think the following solution will help solve this issue. It probably works with most "ISAPI
rewrite" modules (they just need the "stop the rewriting process" option).

156
3 Aug 2007 Drupal Handbook

With this approach you basically revert the "Apache Rewrite" logic. First define rules for
known files/folders (like /themes/ ..etc..). Have those "matching rules" exit, so rules processing
stops before going to the next rule. With mod_rewrite.dll you can do that with the option [l].

Here is what my rules file looks (so far) like (using mod_rewrite.dll):
RewriteRule ^/index.php\?q\=(.*)$ /index.php?q=$1 [l]
RewriteRule ^/themes/(.*)$ /themes/$1 [l]
RewriteRule ^/misc/(.*)$ /misc/$1 [l]
RewriteRule ^/(.*)$ /index.php?q=$1 [l]

Remember, you have to add an "exiting" rule for all known folders/files before hitting the final
rule. The first rule is to avoid recursion and exit immediatly if the URL already has
index.php?q=.

To better understand the Apache rules here are the definitions of the main options:
’last|L’ (last rule)
Stop the rewriting process here and don’t apply any more rewriting rules. Use this flag to
prevent the currently rewritten URL from being rewritten further by following rules.

’qsappend|QSA’ (query string append)
This flag forces the rewriting engine to append a query string part in the substitution string to
the existing one instead of replacing it. Use this when you want to add more data to the query
string via a rewrite rule.

REQUEST_FILENAME
The full local filesystem path to the file or script matching the request.

’-d’ (is directory)
Treats the TestString as a pathname and tests if it exists and is a directory.
’-f’ (is regular file)
Treats the TestString as a pathname and tests if it exists and is a regular file.

Note: Getting Apache running on MS Windows is not that bad (I had been delaying it for years).
In reality it’s a matter of a few hours to get going. http://www.sitebuddy.com aims to save you
time in that endeavor.

Pathauto and Localizer
I was looking for a way to include node language into pathauto recognizable variables, this is
how I managed to do it, you will be able to use [locale] in your nodes path.

In your pathauto_node.inc you need to add these lines:

This one is shown in the pathauto config

<?php
function node_pathauto($op) {
switch ($op) {

157
Drupal Handbook 3 Aug 2007

case ’settings’:
$settings[’bulkdescr’] =
?>
...
<?php
// LOCAL ADDON
t(’[locale]’) => t(’The locale used for this node.’),
?>

These will be loading the data

<?php
function node_get_placeholders($node) {
?>
...
<?php
// LOCAL ADDON
$result = db_query("SELECT locale FROM {localizernode} WHERE
nid=’%d’", $node->nid);
$nodelocale = db_fetch_object($result);
$placeholders[t(’[locale]’)] =
pathauto_cleanstring($nodelocale->locale);
?>

Hope this helps someone !

Setting up clean URLs above web document root on virtual private
servers
To set up clean URLs above web document root on virtual private servers, you need to change a
setting in httpd.conf.

(default setting)
Options FollowSymLinks
AllowOverride None

Change it to
Options FollowSymLinks
AllowOverride All

None of the other changes discussed in this section of the handbook were necessary (and in fact
had to be undone).

The hosting provide said this does not provide any security issues (no guarantees).

158
3 Aug 2007 Drupal Handbook

reboot vps after making change

This is excellent advice. I installed a test site at /var/www/test. My live site is at
/var/www/html. The live site worked fine. In the test site i went to set clean url’s and got an
apache error.

This fixed it.

One minor note. I had to reset the vps before the changes took affect. With my hosting company
this is simply a menu selection in their control panel, so if you have this setup and make the
change and it does not work.

Ask your provider to reset your Virtual Private Server. This is simular to stopping and starting
Apache on a Windows install.

Using Clean URLs with IIS
Drupal can display brief, pretty URLs like those at drupal.org. For Apache sites, mod_rewrite
powers this feature. For IIS, you will use a custom error handler for this. You probably want to
disable logging in IIS, since every page view is considered an error using this technique.

make sure your Drupal is working well without clean urls enabled.
open your Internet Services Manager or MMC and browse to the root directory of the web
site where you installed Drupal. You cannot just browse to a subdirectory if you happenned
to install to a subdirectory.
right click and select properties -> custom errors tab
set the HTTP Error 404 and 405 lines to MessageType=URL, URL=/index.php. If you are
using Drupal in a subdirectory, prepend your subdir before /index.php
paste the following code into the bottom of settings.php file, which is usually located
under sites/default/. the first two lines should be edited. If you aren’t using a
subdirectory, set $sub_directory to "". then set $active=1 and enjoy!
<?php
// CONFIGURATION
$sub_dir = "/41/"; // enter a subdirectory, if any. otherwise, use
""
$active = 0; // set to 1 if using clean URLS with IIS
// CODE
if ($active && strstr($_SERVER["QUERY_STRING"], ";")) {
$qs = explode(";", $_SERVER["QUERY_STRING"]);
$url = array_pop($qs);
$parts = parse_url($url);
unset($_GET, $_SERVER[’QUERY_STRING’]); // remove cruft added by
IIS
if ($sub_dir) {
$parts["path"] = substr($parts["path"], strlen($sub_dir));
}
$_GET["q"] = trim($parts["path"], "/");

159
Drupal Handbook 3 Aug 2007

$_SERVER["REQUEST_URI"] = $parts["path"];
if ($parts["query"]) {
$_SERVER["REQUEST_URI"] .= ’?’. $parts["query"];
$_SERVER["QUERY_STRING"] = $parts["query"];
$_SERVER["ARGV"] = array($parts["query"]);
parse_str($parts[’query’], $arr);
$_GET = array_merge($_GET, $arr);
$_REQUEST = array_merge($_REQUEST, $arr);
}
}
?>
at this point, you should be able to request clean url pages and receive a proper page in
response. for example, request the page /node/1 and hopefully you will see your first node
shown. you should not use the q= syntax; use the clean url syntax. if you get an IIS error, you
have a problem. please fix redo the above and then retest.
browse to index.php?q=admin/system, enable clean URLS, and press Submit.
you may get a php error if your php error reporting in your php.ini file is set to high. Try
this setting in your php.ini file

error_reporting = E_ALL & ~E_NOTICE

Note: This method seems to work for IIS5 but not IIS6. Check this thread for some approaches
using ISAPI_Rewrite.

Alternate method

Alternatively, you can use ISAPI Rewrite by Helicon software to add mod_rewrite-like
functionality to IIS:
www.isapirewrite.com

set your sites 403 and 404 Error pages
Drupal’s page error messages are meant to be direct and to the point. If you want page error
messages that are a little more user-friendly, Drupal allows you to customize them. Just follow
these steps:

1. Create two nodes, one for each kind of page error (403 and 404).
2. Determine the id number of the node you wish to have Drupal redirect users to. One way to
determine the node’s id number is to visit the node and look at the number after the last
slash in your browser’s address bar. This is your node’s id number.
3. Now enter the paths to your nodes into the appropriate boxes. For example, if the node id
number for 403 error codes is "83," you would type "node/83" into the "Default 403 (access
denied) page" setting.

160
3 Aug 2007 Drupal Handbook

Because you are creating nodes for this, they will show up in the tracker and popular content
blocks and anywhere else real nodes would show up. If this isn’t acceptable, there is a
contributed module called Custom Error that avoids this problem.

Configure your sites error reporting
Where Drupal, PHP and SQL errors are logged. On a production server it is recommended that
errors are only written to the error log. On a test server it can be helpful to write logs to the
screen. By default, errors are displayed to the screen. You should change this to ’Write errors
only to log’ only for your production site.

You can tell Drupal to automatically discard error log entries older than the age you specify.
This requires a crontab (yoursite.com/cron.php) to be set up. See step 6 of the install.txt for
example of setup.

Cache support
Busy Drupal sites may want to consider caching their pages to lighten the load on their server
and speed up page generation times.

Normally, every time you visit a Drupal page, Drupal makes dozens of queries to the database
to pull out the data needed to generate the HTML that your web-browser renders. On a large
site with many modules installed or with lots of content on a page, the number of queries per
page could rise into the hundreds. Usually, you don’t notice all the work Drupal does because
computers are very fast and Drupal is very efficient. However, on very busy sites with many
hundreds or thousands of page views per minute, the amount of work required to serve each
page may start to slowing the server to a crawl.

Busy sites can reduce the work required to generate pages by enabling Drupal’s page cache.

With the cache turned on, Drupal stores all the HTML code for any page visited by an
anonymous user directly into the database. When another request for the same page comes
along, Drupal knows to fetch this page out of the database rather than re-generating it from
scratch. The result is that hundreds of queries are replaced with one single query, thereby
significantly lightening the load on the web server.

Primary and secondary links
General Information:
In versions 4.6 and below, primary and secondary links were handled in the theme
administration.

As of 4.7, primary and secondary links have been incorporated into the menu system. To have
primary and secondary links in your theme, you make them menu items. A fresh Drupal 4.7
install comes with an empty menu called "Primary Links" that is set to be used to display both

161
Drupal Handbook 3 Aug 2007

the primary and secondary links.

Setting Up Your Primary and Secondary Links:
There are two configuration screens that deal with these links:

On admin >> settings >> menu you choose which menu is used for the primary links and
which for the secondary links. If you have added items to the default "Primary Links" menu and
they are not showing up, check to make sure the option on this page hasn’t been changed to "No
Primary Links".

On admin >> menu you will find the default "Primary Links" menu and you should add your
links to that. You can also create a menu to hold the secondary links or create a different menu
for the primary links. Be sure to change the options on admin >> settings >> menu to use the
correct menu(s).

Theming Your Link Menus
You can display your links in two ways:

1) You can add the menu block to a region just like any other menu.
2) You can insert this code where you want the links to show up:

<?php if (isset($primary_links)) { ?><div id="primary"><?php print
theme(’links’, $primary_links) ?></div><?php } ?>
<?php if (isset($secondary_links)) { ?><div id="secondary"><?php
print theme(’links’, $secondary_links) ?></div><?php } ?>

You can then use CSS to theme your DIVs however you like.

Set length of trimmed posts and # of posts on front page
admin >> settings >> post

Here you can set the number of posts on main page and the length of trimmed posts. You also
set whether previewing posts is optional or required.

URL Alias Optimization
Drupal 6.0 implements a new feature to enhance site-performance: a whitelist/blacklist for URL
alias lookups. Database queries to find url aliases created by the path module are among the
most frequent in many Drupal installations. The performance setting allows administrators to
either define paths which will no be looked up (blacklist), or paths which will (whitelist).

Similar to the block visibility settings, you can use the * wildcard to define ranges of URLs.

162
3 Aug 2007 Drupal Handbook

The blacklist comes with a set of useful default urls. For many sites, enabling the blacklist will
reduce the number of overall queries to the database without degrading any functionality.
However, if you make extensive use of URL aliases, you should think about what settings work
best for you. If you have a small number of aliases, setting them up as a whitelist may be even
better.

File system settings
Drupal provides configuration settings to control whether, and how, users and administrators
can upload files for use by Drupal.

Note: Unconfigured or improperly configured Drupal installations may display one or more
error message at the top of the "settings" page, indicating that either the "Temporary directory"
or "File system path" directories do not exist and/or their permissions are not set properly.
Simply create these directories and set their permissions so that Drupal can write and read from
the directory.

If you are unsure about where or how to create these directories or how to change their
permissions, contact your web hosting service or software documentation for further assistance.

Download method
Download settings are configured in Administer >> Settings >> File system

There are two possible settings for download method: Public and Private.

Set to Public if you don’t care if any user, even anonymous users, can download the files
uploaded by other users.

Set to Private if you wish to restrict the ability of some users to download files uploaded by other
users.

Please note that if you set your download method as private, you should set your "files"
directory to be outside the document root for your drupal installation (i.e. not in
your_drupal_site/files or your_drupal/site/sites/all/files). The private download method also
has performance implications which you may want to consider.

If you change your settings at a later date, all download urls will change, therefore it’s best to
plan ahead when you set your drupal site up and think carefully about whether you’ll need to
restrict file downloads. If that’s the case we strongly recommend setting the file download
method to private when you first create your site to avoid broken links later on. If your
download method is set as private, all users will still be able to download files until you set
otherwise.

163
Drupal Handbook 3 Aug 2007

Path settings
File system path
By default, this is set to "files". We recommend leaving this setting alone.

Temporary directory
By default this is set to "/tmp" which is the temporary directory common in GNU/Linux
distributions. If you are using a Windows or other kind of server, we recommend setting it to
"tmp" (no slash). Drupal will automatically create the temporary directory as a subdirectoy of
the "File system path."

If it does not due to permissions or other configuration issue’s, you can create the file manually.

Date and time settings
Drupal allows you to configure how dates and times are formatted and displayed. When
making the format settings, you should probably consider the culture of your target audience.
Below are suggested configurations for the "Default time zone" and "Configurable time zones"
options.

For sites where most users live in a small geographic region:
Set the "Default time zone" to the time zone of the region and disable configurable time zones.

For sites where most users live a region that spans a few time zones:
Set the "Default time zone" to the time zone usually considered to be the "standard" time zone
and disable configurable time zones. For example, in the United States, you’d set your site’s time
to the timezone that corresponds to Eastern Standard Time.

For sites where users are likely to be scattered across the globe:
Set the "Default time zone" to the time zone to GMT (+0000) and enable configurable time zones.

Customizing the interface
When launching a new drupal site, here are some things you can do to personalize the design
and architecture of your drupal site.

Choose a Theme.

The look and feel of Drupal is primarily controlled by the theme you have applied to your
site. A site can even have multiple themes. A good first step is to go to administer > themes
and set a new theme as your default. You can find more themes on the download page after
the list of modules. Once you download a new theme you will need to install it on your
system.

Create your own Theme.

164
3 Aug 2007 Drupal Handbook

Many Drupal sites will need a more unique look than these pre-built themes can offer.
Therefore, many developers will want to write their own themes. Theme development
requires a working knowledge of HTML/CSS and possibly some rudimentary PHP depending
on the complexity of your theme.

Customize the Navigation.

The menus that are displayed on the top and bottom of the page are configured in administer
> themes. Select the configure tab and scroll down to Menu Settings. The primary and
secondary links can be defined here, using straight HTML. If the primary links are left blank
your navigation will be created based on your installed modules.

Each theme has an individual configuration page (listed at the top of the global settings
page) as well. Unfortunately, in Drupal 4.6 and previous using PHPTemplate your navigation
must be defined in that theme’s individual theme area.

In 4.7 PHPTemplate engine is incorporated into the Drupal core and the Primary and
Secondary links are now part of the menu system. Mention of this can be found here.

Customize Text Strings

You can also change the text strings throughout drupal using the locale feature, which was
designed for running drupal in different languages, you can personalize almost all of the text in
drupal.

In fact, you can replace a string like "create blog entry" with html markup such as references
to graphics.

Customizing user login
In the default setup the Drupal login block is always displayed unless a user is logged in. This
may not always be desirable. For example, if you are using Drupal to create a site that has a very
small number of people actually logging into the system to create or edit content, then you
probably don’t want a large portion of your screen real-estate taken up with a login block that
doesn’t relate to them. This also confuses the majority of your users that will not have the option
to login.

To disable the login block:

1. Goto the block configuration (administer » blocks)
2. Deselect the check box for User login in the Enabled column

Your regular content editors and administrators can still login to the site by directly accessing
the login page, http://www.example.com/?q=user. If you are using clean URLs you may also
use http://www.example.com/user, but remember that the ?q=user version will always work
whether you have clean URLs enabled or not.

165
Drupal Handbook 3 Aug 2007

You can also create more customized login blocks.

You can create name and email filter rules in admin >> access control >> account rules.

Set up username and e-mail address access rules for new accounts. If a username or email
address for a new account matches any deny rule, but not an allow rule, then the new
account will not be allowed to be created.

Beginner’s guide for Cron on a shared hosting
provider
This guide is excerpted from the original article on ThemeBot.com:
Time to talk about Cron - a beginner’s guide

If you have downloaded and installed Drupal 5, you will notice that there is an error in the
administrative log when you first sign in with your administrative account.

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

When you look at the status report you can go ahead and click the link "run cron manually" and
this will remove the error. However, you will eventually want to set up a Cron job to do this.
Having the Cron maintenance run regularly on an automatic schedule is important for keeping
your site indexed. If this is not done, new content that is added will not be included in search
results. Cron can also perform other tasks in Drupal, such as cleaning up log files. Also, some of
the contributed modules require that Cron maintenance is run regularly.

With the Drupal 5 installation package, there is a script included for Cron and it is called
cron.php. This file is located in the root directory of your Drupal installation. You can actually
run Cron maintenance by entering, for example, the URL
"http://www.yourwebsite.com/cron.php" into a web browser. But we want to get this done
automatically, so we need to call on the help of the Lynx browser. Lynx is a text browser that is
often installed on servers. You will need to contact your hosting provider to make sure that they
have Lynx installed (most probably do).

Once you know that Lynx is installed, you will need to find the configuration panel for setting
up a Cron job in your hosting account.

The first thing to do is enter the command. The following example is the command I use to make
Lynx run cron.php:

lynx -source http://www.yourwebsite.com/cron.php

You may need to adjust this command depending on your hosting provider.

166
3 Aug 2007 Drupal Handbook

The next step is to decide on a schedule to have this Cron job run. Running Cron does use
system resources, so you don’t want to have it running every minute if you don’t need to. It is
up to you to decide on an appropriate schedule for having each Cron job run. Understanding the
format for entering a schedule can take a little getting used to. Here is a quick rundown on
scheduling options that can be entered:

Minute â any integer from 00 to 59 (specifies the minute the job will be run on)
Hour â any integer from 0 to 23 (specifies the hour the job will be run on)
Day â any integer from 1 to 31 (must be a valid day if a month is specified)
Month â any integer from 1 to 12
Weekday â any integer from 0 to 7, where 0 or 7 represents Sunday

The asterik (*) specifies that the task should be run every time for any sub-constraint. This
statement doesn’t even make sense to me so let’s just have a look at the examples to figure it out.
You can also use the command */ to have jobs run every interval. Here the examples to help you
get the hang of it.

Run cron.php task every 30 minutes:

*/30 * * * * lynx -source http://www.yourwebsite.com/cron.php

Run cron.php task once a week at 1:00 am every saturday (you can see that saturday is
represented by 0):

00 1 * * 0 lynx -source http://www.yourwebsite.com/cron.php

Run cron.php task on the first day of every month at 12:00 am (midnight) :

00 0 01 * * lynx -source http://www.yourwebsite.com/cron.php

I hope this is helpful for beginners who have installed Drupal and are wondering how to setup
Cron.

Check your filters
Drupal input filters are a little known but powerful feature. They can give a site administrator a
lot of control over the input of their site. Some contributed modules add filters here to control
content display and link behavior.

In the Navigation menu, select administer / input formats. (?q=admin/filters)

167
Drupal Handbook 3 Aug 2007

Configure user registration
Configure the user registration options for your site (?q=admin/user/configure). The three
options for your Drupal based site are listed here.

Only site administrators can create new user accounts.
Visitors can create accounts and no administrator approval is required.
Visitors can create accounts but administrator approval is required.

If you allow user registration, take the time to customize the message to something appropriate
to your site and community. User picture support is also enabled/disabled here and relies on
the theme to have support for it.

These settings can be found in admin >> users >> configure in Drupal 4.6.

These settings can be found in admin >> settings >> users in Drupal 4.7.

Some sites may want to establish rules for user names, or block registration from certain email
domains. This can be done through the Account Rules tab in admin >> access
control(?q=admin/access/rules).

Set up username and e-mail address access rules for new accounts. If a username or email
address for a new account matches any deny rule, but not an allow rule, then the new
account will not be allowed to be created.

There is allowance for wildcards as well.

%: Matches any number of characters, even zero characters.
_: Matches exactly one character.

For example a rule of

%- :would prevent any user names ending in a dash
w_rd :would prevent any combination or w any 2nd character and rd

%: Matches any number of characters, even zero characters.
_: Matches exactly one character.

There is also a checking tool to check the effect of your rules.

Creating a menu structure
Drupal comes with a menu module that allows you to create infinitely nested menu trees. You
can activate this module at administer > modules if you can’t see the menu item labeled "menu" in
the "administer" menu.

168
3 Aug 2007 Drupal Handbook

A screencast of building a basic site navigation system using menu module is also available for
Drupal 4.7 users.

Creating a menu
1. To add a new menu, go to the menu module’s page at administer > menus. Click on "add menu"
and supply a title for your new navigation. If it is the main navigation, simply call it "Main
navigation" or "Default menu" or whatever you find appropriate.

2. Now that you have created your menu, enable it on the administer > blocks page checking the
"Enabled" checkbox after the menu name that you entered in step one. You can also change the
region and the weight of the menu. This affects where the menu is placed on the page. For a
detailed description of what are blocks and how to use them, consult the block module’s
handbook page. After having enabled the block, you should see an empty section on the side
that has the title you supplied for the menu.

3. Create menu entries. This can be done by going back to the menu module’s page and clicking
on "create menu item". Now you can enter a title for the new menu item, supply a short
description, define its path (for a detailed description on paths or url aliases, consult the
path.module’s handbook page).
Select the parent for the menu item. That means, you can select under which navigation item
your new menu item is filed. Selecting the item with the same title as your menu’s title means
that the new item is a top level item.
Select the weight. This defines at which position the menu item is. A lower weight means that
the item "floats" above items with "heavier" weight.

You can also create multiple menu items for one node. This allows you to find the node on more
than one place. But generally your visitors get only confused if they can find the same content on
multiple places, so use this feature carefully and only when it’s appropriate.

Simplifying the workflow
In Drupal version 4.6.x, always having to go to the menu module page is sometimes annoying if
you just want to quickly add a page to your site. For this purpose, the Menu-on-the-fly module
has been created. It adds a section on every create content that allows you to create a new menu
item along with the node quasi on the fly (as the module’s name indicates). This functionality is
built into the core menu module in 4.7.x

Helping search engines and robots.txt
Drupal by itself is very search engine friendly. For example it is not uncommon for Drupal based
sites to have have a Google ranking of 5 or higher (out of 10) where using the same content on
another CMS would score much lower.

169
Drupal Handbook 3 Aug 2007

Still, you can make Drupal even more search engine friendly by changing some default
parameters. There are several Drupal settings you can tweak to make Drupal even more search
engine friendly.

1. First of all you might want to enable friendly URL’s
2. Then, make sure that you get rid of the session ID in the URL by changing the .htaccess if
you are using version 4.5.x. On 4.6, session IDs in URLs are disabled by default.
3. Optionally, use URL aliasing for some or all nodes. You can use the pathauto module to
automatically create aliases for new nodes.

Controlling what gets indexed -- the robots.txt file
The robots.txt file is the mechanism almost all search engines use to allow website
administrators to tell the bots what they would like indexed.

A robots.txt is included with Drupal 5.x. Drupal 4.x does not come with a robots.txt file.

By adding this file to the root of your (virtual) webserver, you can quide the search engines’
"bots" through your site or forbid indexing parts of your site. See for an example the file for
drupal.org itself at http://drupal.org/robots.txt.

If you want to have a robots.txt file, please follow the instructions below. For more details check
http://www.robotstxt.org

Create a file with the content as shown below and call it "robots.txt"

# small robots.txt
# more information about this file can be found at
# http://www.robotstxt.org/wc/robots.html
# lines beginning with the pund ("#") sign are comments and can be
deleted.
# if case your drupal site is in a directory
# lower than your docroot (e.g. /drupal)
# please add this before the /-es below
# to stop a polite robot indexing an exampledir
# add a line like (delte the #’s)
# user-agent: polite-bot
# Disallow: /exampledir/
# a list of know bots can be found at
# http://www.robotstxt.org/wc/active/html/index.html
# see http://www.sxw.org.uk/computing/robots/check.html
# for syntax checking
User-agent: *
Crawl-Delay: 10
Disallow: /aggregator
Disallow: /tracker
Disallow: /comment/reply

170
3 Aug 2007 Drupal Handbook

Disallow: /node/add
Disallow: /user
Disallow: /files
Disallow: /search
Disallow: /book/print

This file tells indexing robots that they should avoid pages that contain content for users only,
for example the search page, or the ’Add a comment’ forms for nodes.

Many robots obey the "Crawl-delay:" parameter. Since Drupal sites seem to be popular with
search engines and lots of people have more aggresive bots than visitors at their site, it might be
wise to slow down the robots by adding a robots.txt line like this:

User-Agent: *
Crawl-Delay: 10

Here 10 is the delay in seconds between page requests.

Both "Slurp" (The robot that is indexing for yahoo and altaVista) and the Microsoft robots for the
MSN sites obey this parameter. Googlebot does not use the "crawl-delay" parameter yet but will
likely do so in an upcoming version.

Change the file as you wish and save it. Now upload it to your webserver and make sure it is in
the root of the (virtual) webserver. If you have installed Drupal in a subdirectory (for example
/drupal), then change the URL’s in the robots.txt file but place the file in the root of the
webserver, not in the root of your drupal instalation.

Now watch the robots visit your site and after some time, monitor your log files ("referrer log")
to see how many visitors came from a search engine.

Add ’Disallow: /node/’ if your setup has aliases for all nodes
If your Drupal setup has aliases for all nodes (mostly happens when you use path and pathauto
both) then add Disallow: /node/ to your robots.txt. Nodes with aliases are accessible from 2
URIs: the default URI and the aliased URI. Search engine bots will discover both over a period of
time and this might lead to penalisation for duplicate content as well as twice as much crawling
as is really required.

I learnt this the hard way. It is best to do this when the site is new.

Selective Bot Crawling
here’s a copy of my robots.txt file:

# AllTheWeb
User-agent: fast-webcrawler
Crawl-Delay: 10
Disallow: /aggregator

171
Drupal Handbook 3 Aug 2007

Disallow: /tracker
Disallow: /comment/reply
Disallow: /node/add
Disallow: /user
Disallow: /files
Disallow: /search
Disallow: /book/print
Disallow: /admin
Disallow: /cron.php
Disallow: /xmlrpc.php
Disallow: /database/
Disallow: /images/
Disallow: /includes/
Disallow: /modules/
Disallow: /scripts/
Disallow: /themes/
Disallow: /email_disclaimer
Disallow: /privacy_policy
Disallow: */add/
# AltaVista
User-agent: scooter
Crawl-Delay: 10
Disallow: /aggregator
Disallow: /tracker
Disallow: /comment/reply
Disallow: /node/add
Disallow: /user
Disallow: /files
Disallow: /search
Disallow: /book/print
Disallow: /admin
Disallow: /cron.php
Disallow: /xmlrpc.php
Disallow: /database/
Disallow: /images/
Disallow: /includes/
Disallow: /modules/
Disallow: /scripts/
Disallow: /themes/
Disallow: /email_disclaimer
Disallow: /privacy_policy
Disallow: */add/
# Googlebot
User-agent: googlebot
Crawl-Delay: 10
Disallow: /aggregator
Disallow: /tracker

172
3 Aug 2007 Drupal Handbook

Disallow: /comment/reply
Disallow: /node/add
Disallow: /user
Disallow: /files
Disallow: /search
Disallow: /book/print
Disallow: /admin
Disallow: /cron.php
Disallow: /xmlrpc.php
Disallow: /database/
Disallow: /images/
Disallow: /includes/
Disallow: /modules/
Disallow: /scripts/
Disallow: /themes/
Disallow: /email_disclaimer
Disallow: /privacy_policy
Disallow: */add/
# Looksmart
User-agent: wisenutbot
Crawl-Delay: 10
Disallow: /aggregator
Disallow: /tracker
Disallow: /comment/reply
Disallow: /node/add
Disallow: /user
Disallow: /files
Disallow: /search
Disallow: /book/print
Disallow: /admin
Disallow: /cron.php
Disallow: /xmlrpc.php
Disallow: /database/
Disallow: /images/
Disallow: /includes/
Disallow: /modules/
Disallow: /scripts/
Disallow: /themes/
Disallow: /email_disclaimer
Disallow: /privacy_policy
Disallow: */add/
User-agent: zyborg
Crawl-Delay: 10
Disallow: /aggregator
Disallow: /tracker
Disallow: /comment/reply
Disallow: /node/add

173
Drupal Handbook 3 Aug 2007

Disallow: /user
Disallow: /files
Disallow: /search
Disallow: /book/print
Disallow: /admin
Disallow: /cron.php
Disallow: /xmlrpc.php
Disallow: /database/
Disallow: /images/
Disallow: /includes/
Disallow: /modules/
Disallow: /scripts/
Disallow: /themes/
Disallow: /email_disclaimer
Disallow: /privacy_policy
Disallow: */add/
# MSN
User-agent: msnbot
Crawl-Delay: 10
Disallow: /aggregator
Disallow: /tracker
Disallow: /comment/reply
Disallow: /node/add
Disallow: /user
Disallow: /files
Disallow: /search
Disallow: /book/print
Disallow: /admin
Disallow: /cron.php
Disallow: /xmlrpc.php
Disallow: /database/
Disallow: /images/
Disallow: /includes/
Disallow: /modules/
Disallow: /scripts/
Disallow: /themes/
Disallow: /email_disclaimer
Disallow: /privacy_policy
Disallow: */add/
# Yahoo Vertical Crawler
User-agent: yahoo-verticalcrawler
Crawl-Delay: 10
Disallow: /aggregator
Disallow: /tracker
Disallow: /comment/reply
Disallow: /node/add
Disallow: /user

174
3 Aug 2007 Drupal Handbook

Disallow: /files
Disallow: /search
Disallow: /book/print
Disallow: /admin
Disallow: /cron.php
Disallow: /xmlrpc.php
Disallow: /database/
Disallow: /images/
Disallow: /includes/
Disallow: /modules/
Disallow: /scripts/
Disallow: /themes/
Disallow: /email_disclaimer
Disallow: /privacy_policy
Disallow: */add/
# Exclude every other bot (hopefully)
User-agent: *
Disallow: /

... this way, it blocks every bot, except the ones i listed.

a much more logical approach, methinks.

also, a little off-topic, but don’t forget to Disable PHP’s session use_trans_sid for cleaner search
engine listings.

Increase upload size in your php.ini
Drupal’s limits on upload file size are determined by your server’s PHP settings. The default
values for PHP will restrict you to a maximum 2 MB upload file size.

Drupal 4.7.x and above calculates and displays the maximum file size that you can set in the
settings page for the upload module based on two PHP settings, ’post_max_size’ and
’upload_max_filesize’. Since ’post_max_size’ is the limit for all the content of your post,
potentially including multiple uploaded files, the upload module limits the size of a single
attachment to be 50% of post_max_size, or 100% of upload_max_filesize, whichever is smaller.
The default PHP values are 2 MB for upload_max_filesize, and 8 MB for post_max_size.

Depending on your host, changing these two PHP variables can be done in a number of places
with the most likely being php.ini or .htaccess (depending on your hosting situation).

For example, to increase the limit on uploaded files to 10 MB:

Add the below to the relevant php.ini file (recommended, if you have access). Note that for
some hosts this is a system-wide setting. However, for hosts running PHP as a CGI script
with suexec (for example) you may be able to put these directives in a php.ini file in your
Drupal root directory.

175
Drupal Handbook 3 Aug 2007

upload_max_filesize = 10M ;
post_max_size = 20M ;
Add the below to your .htaccess file in the you Drupal root directory.
php_value upload_max_filesize 10M
php_value post_max_size 20M

The PHP documentation states that the memory_limit setting also affects file uploading.
Generally speaking, memory_limit should be larger than post_max_size. If this is an issue, see
the page on how to Increase memory in your php.ini

Need images etc? - check Filtered HTML
As you start creating content like a story or an article, it’s easy to overlook "input formats" -
where there are options for filters like Full HTML or Filtered HTML.
But these are very important; and the well-meaning Filtered HTML can trip up many a Drupal
newbie: certainly caught me out, and had me searching for solution. The Filters remove HTML
that isn’t listed as acceptable, as website code is processed for previews or actual views, to
safeguard your site from potential harm. Can set the site’s default filter, plus decide which user
groups have permission to use certain filters.

For me, as plenty of others, an apparently weird early problem was that I added an image to my
text, but couldn’t see it in Preview or web pages.

The reason: I’d left "input format" in default mode, which uses Filtered HTML. And this, by
default, is so enthusiastic in stripping out potentially dangerous HTML that it also removes
<img> tags. Result: no images!

One solution is to use Full HTML, so Drupal’s bodyguards stand down, and all HTML code
entered is allowed on actual site. This, though, is unwise if you’ll have untrusted users
contributing to the site.

It’s better, then, to permit <img> and perhaps a few other HTML tags in Filtered HTML for
untrusted users (if you’re site superuser, can use Full HTML as needed).
Or, better still, create one or more new Filters: which, you’ll find, can include other filters.

Creating a Filter (site configuration - input formats - add filters), you’ll see that you have the
option to include existing main filters, such as Filtered HTML and - depending on modules -
things like a filter for menalto Gallery, and inline images filter from Image Assist.

But, in Drupal 5 at least, you can’t see the HTML tags in your custom filter.
To see these, save your Custom Filter. Then, choose "configure" from the list of key filters, and
then configure again.

Now, you can revise the list of tags.
At least add <img>. But since the default Filtered HTML seems like some latterday Ebeneezer
Scrooge of the website world, can also add more.
As I type this, Drupal site notes: Allowed HTML tags: <h1> <h2> <h3> <h4> <h5> <h6>

176
3 Aug 2007 Drupal Handbook

<em> <strong> <code> <del> <blockquote> <q> <sub> <p> <br> <ul> <ol>
<li> <dl> <dt> <dd> <a> <b> <u> <i> <sup>
There’s a post on TINYMCE - http://drupal.org/node/59769 - suggesting that use:
<quote><a> <em> <strong> <u> <cite> <code> <ul> <ol> <li> <dl> <dt>
<dd> <img> <p> <sub> <sup> <strike> <blockquote> <hr> <br></quote>
for fckeditor, a suggested list (posted by someone helping me with Filtered HTML troubles) is:
<a> <em> <strong> <small> <sup> <sub> <cite> <blockquote> <code> <ul>
<ol> <li> <dl> <dt> <dd> <h1> <h2> <h3> <h4> <img> <br> <br/> <p> <div>
<span> <b> <i> <font> <color>

You’ll want to leave option "strip disallowed tags".

It may be useful to create extra Filters, for finer control on users and HTML they can input.
For instance, if someone will be writing and editing articles, could allow them a wide range of
tags. (If you have, say, a user group "writers n editors", might create Filtered HTML for Editors.)
But for folk who register and can just add comments, post to forum, could have tighter list. This,
perhaps, could obviate need for BBcode, albeit a few fckeditor style buttons would be more
user-friendly than listing of code tags.

Note that the input formats are stored as you save text etc. So if you change filter you want to be
used as default for your site, won’t affect saved pages.

Set default content options - Stop automatic
promotion to the front page
Configure the default content workflow suitable for your site. Out of the box, Drupal modules
are set to promote to the front page. While this is desirable in many instances, it is not something
you always want.

The administration menu has changed in 4.7, so the config screen for this has moved.

In 4.6 and older:
Go to the Administer > Content
Select the Configure tab and then the Content Types sub tab.

In 4.7:
Go to Admin > Settings > Content-types

In 5.x
Go to Administer > Content Management > Content-types

Click on the configure for the node type in question and change the default workflow options to
something suitable for your site.

If you add or enable modules such as CCK that create additional node types, you will need to
revisit these settings. Remember that.

177
Drupal Handbook 3 Aug 2007

Show/hide ’Submitted by’ on posts
Set appropriate post information for your site.

In 5.x:
In (Administer > Site building > themes), select the "configure" tab, then "Global settings." Select the
appropriate "Display post information on" that are right for your site.

Available options will be determined by the installed modules on your site. Other options can be
configured on the individual theme’s configuration page.

In 4.7 and before:
In (administer > themes) (URL: ?q=admin/themes/settings) menu, select the "configure tab" and
"Global settings" sub-tab. Select the appropriate options for your site in the "Display post
information" menu.

Blocks
Blocks are the boxes visible in the sidebar(s) of your Drupal website. Most of the blocks that you
will see (e.g., recent forum topics) are generated on-the-fly by various Drupal modules, but you
can also create your own blocks.

Whether, and where, a given block will appear on a page depends on both the theme enabled
and on administrative block settings. Block settings are controlled from the block administration
screen, which you can reach by clicking administer » blocks. From this screen, you will be able to
control whether each block is enabled where it will be placed on the page, and which pages it
should appear on.

Block configuration
Whether a block appears on a page depends on a number of factors.

First, the block must be enabled by checking its "enabled" box on the block management
page;
Second, the block’s custom visibility settings must permit the block to be displayed for a
given user. You can configure a block to appear always; to be displayed by default unless
disabled by individual user preferences, or to be disabled by default but visible if enabled
by individual users. Individual users can select or disable optional blocks from their "my
account" page;
Next, whether the block appears on pages for a given section of the site can be configured
by the administrator by setting the block’s path;
The block can be configured to appear only for certain content types;
Finally, if the throttle module has been enabled, and the block has its throttle box checked on
the block management page, then it will only appear if the site’s traffic is below a given
threshold.

178
3 Aug 2007 Drupal Handbook

Once you have configured a block to appear as required on specific pages and in the correct
column, you may wish to adjust the block’s weight to position the block vertically within its
column. A block’s weight is set via a pull-down selector on the block management page. Heavier
blocks (those with a more positive weight) "sink" to the bottom of a column, while lighter blocks
"float" towards the top.

More infomration can be found in the modules section of the handbook on block

Restricting blocks to certain pages
Below the Page Specific Visibility Options options, you will see a large text box. On each line,
you can specify which pages that block will appear on -- or not appear on, depending on what
you selected above.

The following are some annotated examples. They all assume that you choose the second option
above; if you chose the first option, blocks will appear on all pages other than what you specify
below. You’re welcome to add more than one listing, each separated by lines. (Note that you
cannot specify pages on which blocks appear as well as pages on which blocks do not appear. It
is either one or the other.)

<front> Specifies that the block appears on the front page.
Specifies that the block will appear on the item with the node
node/42
ID of 42.
aggregator Specifies that the block appears on just the aggregator.
Specifies that all URLs that start with blog/ will show the
block. Note: if you want the block(s) to also appear on the main
blog/*
blog page, you need to add blog (that is, without the
trailing slash) as well.

Some users have reported they receive the error "warning: Delimiter must not be alphanumeric
or backslash in [your drupal install] modules/block.module on line 354." if they do not surround
their paths in <> like <node/42>

Another example, if you have HTML, Javascript or PHP blocks you don’t think are necessary for
administrators to see, you can select "Show on every page except the listed pages." and use the
following
wildcard for the block:

admin/*

Administrators can select which content type blocks appear on as well. This can be found under
"Content specific visibility settings" after clicking the "configure" link for an individual block.
Choose which content type blocks appear on by checking the box next to that content type. You
can use content type-specific blocks in conjunction with the above restrictions based on URLs.

179
Drupal Handbook 3 Aug 2007

Examples of using PHP for visibility combined can be found in the PHP Snippets section of the
Handbook in the article Overview Approach to Block Visibility

Preventing a block from appearing in Drupal 4.5
I’m baffled....I have reviewed the Drupal guide on the site and read through numerous
postings from the archive of this list, and have tediously tested many alternate paths.

I currently have this path (which works)

<^(?!event)>

it used to to keep certain blocks off the month view of the calendar.

I want to add to that string something that does not display a block on a specific page (e.g.
node/635)

I tried

<^(node/635)|^(?!event)>
(did not work)
<(^node/635)|^(?!event)>
(did not work)

I’m not sure I am using the vertical bar | correctly. I had trouble finding examples of
multiple paths.

I am also not specifying the node/635 correctly, as I could not get to work even when I
removed the second part

^(?!event)

Thanks,
Andrew

Hi Andrew,

I can empathize with your situation! This is one of the most powerful, but also one of the most
difficult, aspects of the block mechanism in Drupal.

Both power and difficultly spring from the same source - regular expression syntax. There are
entire books on the subject, so please don’t feel stupid! It really is pretty heavy going.

You’ll want to place the entire regular expression in angle brackets, as in your examples.

The caret (^) anchors your regular expression to the start of a line, that is, the part of the URL
immediately following the hostname.

180
3 Aug 2007 Drupal Handbook

Hence <^node> will match http://www.example.com/node,
http://www.example.com/node/foo, and http://www.example.com/node/123, if your server
is www.example.com.

If you omit this and type <node> for example, your regular expression will match
http://www.example.com/node, but also http://www.example.com/nodessert,
http://www.example.com/blog/how_to_delete_a_node, etc.

OK so far?

As you have perceived, parentheses group sub-expressions (sort of in the same way that
parentheses group sub-expressions in arithmetic, or even in written communication, as in this
example!). The ’pipe’ operator (|) is used to separate alternatives. Read it as ’or’. So,

<^(foo)|(bar)>

can be read as ’match foo or bar at the start of the line’.

The expression (?!...) is called a negative look-ahead operator. It says to match only if the
subexpression following the ?! does not match from the point where the ?! is evaluated
(matched)

So <^foo(?!(t))> matches http://www.example.com/fool and
http://www.example.com/fooze but not http://www.example.com/foot, or
http://www.example.com/football.

One more thing - letters and numbers ’match themselves’, but obviously certain other special
characters have special meaning (e.g., we’ve already seen that ^,?, !, | and parentheses are
treated specially). These are called metacharacters. To match a metacharacter you need to ’escape’
it, by preceding it with a ’\’ (backslash).

So, to match the pattern ’foo?!’ you’d have to type <foo\?\!>.

Now, we can put all of the pieces together. Just as in arithmetic, or in writing compound
sentences, you can create long expressions by combining short ones.

Regular expressions can be combined by simply catenating them:<foo> matches ’foo’, and
<bar> matches ’bar’; catenate them to get <foobar> matching ’foobar’. You can also combine
by alternation: <(foo)|(bar)> matches foo or bar. You can specify that a subexpressions
matches zero or more times by following it with an asterisk: <(foo)*t> matches ’t’, foot,
foofoot, foofoofoot, and so on. (I’ve omitted the server part of the URL for brevity)

On to your example:

<^(?!(node\/635)|(event))>

matches (at the beginning of the line) anything that doesn’t match the subexpression following
?!, namely, node/635, or event. I’ve escaped the slash - I don’t know if this is necessary (but it
doesn’t hurt - any regular character when escaped just matches itself)

181
Drupal Handbook 3 Aug 2007

If you’re beginning to love this stuff, there’s hundreds of more pages of fun examples in various
books and on other websites (for example at http://www.php.net). Just search for ’regular
expression’ or PCRE (perl compatible regular expressions)

Hope this helps,

Djun

Custom blocks
A custom block contains content supplied by you (as opposed to being generated by a module).
Custom content may be either static (i.e., HTML) or dynamic (PHP generated content). Virtually
all of the functionality of Drupal is accessible from within a PHP content block. The flexibility of
blocks provides an extremely powerful way to customize your Drupal website.

You can create a custom block via the block management screen (click on administer » blocks).
Select the new tab and complete the form.

Each custom block has a title, a description, and a body. The content within the body can be as
long as you wish.

Note: In Drupal 4.6, the title of the block is used as its identifier in the database table. Therefore
you can only have one custom block without a title (this issue has been fixed in newer Drupal
versions).

One workaround for this is to enter a title such as this: <!--title of custom block-->. This satisfies
Drupal’s need for a block title but the comment markers (<!-- ... -->) prevent it from being
displayed.

Increase memory in your php.ini
While Drupal core will run with 8 MB of memory configured for your server, you may need to
increase this depending on how may modules you use on your site.

In Drupal 4.7.x and below, when you go into ?q=admin/modules, you may experience a blank
screen. This is caused by Drupal loading all the modules of your site into memory, whether you
have them turned on or not. If you get a blank screen here, you have two choices; increase your
allocated memory for PHP or delete unused modules.

In Drupal 5.x and above, this problem has been fixed, and the modules page no longer loads all
modules. If you are still getting out of memory problems, you should either reduce the number
of modules used or increase your allocated memory for PHP.

Depending on your host, this can be done in a number of places with the most likely being
php.ini or htaccess depending on your hosting situation.

182
3 Aug 2007 Drupal Handbook

Add for example:

memory_limit = 12M to your php.ini file (recommended, if you have access)
ini_set(’memory_limit’, ’12M’); to your sites/default/settings.php file
php_value memory_limit 12M to your .htaccess file in the Drupal root

You will need to experiment with the value that is right for you.

Database table prefix (and sharing tables across
instances)
Some web hosts limit their customers to one database. Thus, no duplicate table names are
possible. In order to assure that these admins can still use Drupal, and even use multiple
installations of Drupal, Drupal offers table prefixing.

In order to use this feature, you must currently edit the script database/database.x in order
to create tables prefixed by the string of your choice. If you are adding contributed modules you
will need to also modify INSERT and REPLACE statements to have a prefix as well. For
example, change all statements from the format of

CREATE TABLE access
INSERT INTO system VALUES
(’modules/filter.module’,’filter’,’module’,’’,1,0,0);
Becomes,
CREATE TABLE dr1_access
INSERT INTO dr1_system VALUES
(’modules/filter.module’,’filter’,’module’,’’,1,0,0);

Then use dr1_ (for example) as value of $db_prefix in your
sites/example.com/settings.php file.

You can also use the prefix.sh in the scripts subdirectory of your Drupal install to do this
automatically. You can then update several sites in one swoop with a (bash shell) command-line
like

for F in ’’ prefix1 prefix2; do \
for S in ‘find ./modules --name \*mysql‘; do \
scripts/dbprefix.sh $F < $S | grep -v DROP |\
mysql -h DBHOST -u DBUSER -pPASSWD DATABASE; \
done;
done
NOTE:that not all scripts end in mysql, but you get the idea; the ’’ prefix tells the script to run
with no prefix at all, ie a straight cat - command that just lets me process all my sites together.
Here is a PHP script that creates all of the database tables for all sites in /drupal/sites/*. It
works for DRUPAL-4-6. See the Database Table Creation script issue for more info.

183
Drupal Handbook 3 Aug 2007

If you want to share users across multiple sites, you’ll need to use a $db_prefix along these lines:

<?php
$db_prefix = array(
’default’ => ’thissite_’,
’authmap’ => ’shared_’,
’profile_fields’ => ’shared_’,
’profile_values’ => ’shared_’,
’role’ => ’shared_’,
’sequences’ => ’shared_’,
’sessions’ => ’shared_’,
’users’ => ’shared_’,
’users_roles’ => ’shared_’,
’users_uid_seq’ => ’shared_’, // for pgsql
);
?>

See the sharing tables and sharing tables across databases sections.

Share tables across instances
Table prefixing may be optionally applied to some tables and not others. This has the effect that
multiple Drupal installations can share common tables. One interesting application for this is to
share the taxonomy tables (vocabularies, term_data). Another interesting use is to share users
across Drupal installations.

In order to use this capability, create two drupal installs in same DB using different database
prefixes. In this example, one is prefixed ’master_’ and the other ’slave1_’. Then edit the
conf.php file of ’slave1_’ so that it points some tables to the ’master_’. For sharing users, add the
following:

$db_prefix = array(
"default" => "slave1_", // the prefix for tables that are not
shared.
"users" => "master_",
"sessions" => "master_",
"authmap" => "master_",
"sequences" => "master_"
"profile_fields" => "master_",
"profile_values" => "master_",
);

Note: The actual tables that you will share depends on your installation.
However, the following tables contain data that is highly site specific and therefore should not
be shared:

184
3 Aug 2007 Drupal Handbook

cache
variable

There is a limitation in that you can only explicitly specify which tables will be shared and not
the other way round. The following may fail (however a recently deleted comment on this page
by marcob suggests this has been fixed:

$db_prefix = array(
// Be careful of this setup.
’default’ = ’primary_’,
’cache’ = ’slave1_’,
’node’ = ’slave1_’,
’system’ = ’slave1_’,
// etc...
);

Setup tip for Drupal 5
For Drupal 5+, an easy way to get started with table sharing across instances is to run the
installer twice using the same database - it will create the prefixed tables and handle all the
initial INSERTS (as with the ’system’ and ’menu’ tables, etc) for all your different prefixes.

Using schema prefixes with PostgreSQL
This page discusses usage of PostgreSQL schemas for prefixes. "Normal" prefixes can be used in
the same way as in MySQL, so they won’t be discussed here.

PostgreSQL has something called ’schemas’
(http://www.postgresql.org/docs/current/static/ddl-schemas.html). They can be very handy
sometimes, but if you don’t know what they are, you probably don’t actually need them and can
stop reading here.

Schemas can be used as prefixes within Drupal. That is, with a multisite setup, each site can
reside in its own schema, and shared tables can reside in a "shared" schema (or even in the
public schema).

There is one annoyance: the upgrade will fail. This is unfortunate, but nothing can be done as the
"normal" (not schema) and schema prefixes are just incompatibile. If you are interested in the
details, please see http://drupal.org/node/40034.

But, don’t worry. This can be easily fixed by changing the update script (update.php and
updates.inc) a bit. The problem lies in the CREATE [UNIQUE] INDEX and ALTER TABLE ...
DROP/ADD CONSTRAINT statesments. When schema prefixes are used, queries like this are
executed:

CREATE INDEX prefix.search_total_word_idx ON prefix.search_total(word)
ALTER TABLE prefix.boxes DROP CONSTRAINT prefix.boxes_title_key

185
Drupal Handbook 3 Aug 2007

ALTER TABLE test.contact ADD CONSTRAINT test.contact_category_key
UNIQUE (category)

The prefix must be removed from the index and constraint name--that is they must be changed
to:

CREATE INDEX search_total_word_idx ON prefix.search_total(word)
ALTER TABLE prefix.boxes DROP CONSTRAINT boxes_title_key
ALTER TABLE test.contact ADD CONSTRAINT contact_category_key UNIQUE
(category)

You can easily search for CREATE INDEX, CREATE UNIQUE INDEX and ADD/DROP
CONSTRAINT statements and remove the {} from index/constraint names.

The best way is to run a test upgrade. You’ll see a list of failed queries and it will be easier for
you to change them.

Another remark: you can’t use prefix.sh to prefix the tables, it will produce incorrect CREATE
[UNIQUE] INDEX queries. This, also, can be easily fixed, by changing:

s/^CREATE INDEX \(.*\) ON /CREATE INDEX $PREFIX\\1 ON $PREFIX/;
s/^CREATE UNIQUE INDEX \(.*\) ON /CREATE UNIQUE INDEX $PREFIX\\1 ON
$PREFIX/;

to:

s/^CREATE INDEX \(.*\) ON /CREATE INDEX \\1 ON $PREFIX/;
s/^CREATE UNIQUE INDEX \(.*\) ON /CREATE UNIQUE INDEX \\1 ON $PREFIX/;

An alternate approach
Here’s what you need to do if you want to solve it this way:

1. Add the following at the top of your database.pgsql file:

CREATE SCHEMA schemaname;
SET search_path TO schemaname;

2. Edit drupal/includes/database.pgsql.inc, replacing the function db_connect() with:

<?php
function db_connect($url) {
$url = parse_url($url);
$db_and_schema = explode(".",substr($url[’path’], 1));
$conn_string = ’ user=’. $url[’user’] .’ dbname=’.
$db_and_schema[’0’] .’ password=’. $url[’pass’] . ’ host=’ .
strtr($url[’host’],’+’,’/’);
$conn_string .= isset($url[’port’]) ? ’ port=’ . $url[’port’] : ’’;
$connection = pg_connect($conn_string) or die(pg_last_error());
if(!empty($db_and_schema[’1’])) pg_query(’SET search_path TO

186
3 Aug 2007 Drupal Handbook

’.$db_and_schema[’1’]);
return $connection;
}
?>

3. Finally, use a db_url akin to such in your settings.php file(s):

$db_url = ’pgsql://user:password@+tmp/dbname.schemaname’;

Not thoroughly tested, but works for me (on 4.6.3).
This also fixes the inability to specify a Unix socket as the host - the +tmp gets replaced with
/tmp for pg_connect().

Define shared variables for all sites
When you create a multi-site installation, an important table to duplicate is the variable table.
However, by duplicating this table, you will also duplicate some variables that you might prefer
not to. To force a set value for these variables, for all of your websites, you can do the following.

First, you will probably have a settings.php file for each site in your installation, like
sites/example.com/settings.php. Edit each file and add the following to the end.

include_once (’./sites/default/shared_variables.php’);

Now, in the default directory, add a file called sites/default/shared_variables.php
containing the following.

<?php
/**
* These variables are fixed for all sites that have this line of
* code in their settings.php file:
*
* include_once (’./sites/default/shared_variables.php’);
*/
$conf = array(
’site_name’ => ’All these sites are belong to us.’,
’theme_default’ => ’pushbutton’,
’anonymous’ => ’Visitor’
);

The element names (eg. ’site_name’) correspond to a variable in the variable table. So no
matter how many copies of the variable table that you need, each site in your multi-site
installation will defer to the variables that you define in the $conf array in your
shared_variables.php file.

187
Drupal Handbook 3 Aug 2007

The disadvantage is that these variables cannot be edited via the Drupal admin pages.

188
3 Aug 2007 Drupal Handbook

Drupal Cookbook (for New Drupallers)
Purpose
I am one of the many Drupal "newbies" who seemed overwhelmed at first. Well, I still am. But I
have learned a lot in my first month with Drupal. I’m even answering question in the forums
(actually, I think it’s fora.)

With some encouragement from other newbies, I decided to start on writing down what I’m
doing to build my sites. (Shoot, at my age, I can’t rely on my memory, I have to write it down.)
Yes, that’s plural. As of this writing I have three sites in production, plus a test site for playing
around.

Background
The basis of this book is going to be my efforts to build new test sites on my PC, running
Windows. Hopefully by the time I get to that point in this book, I’ll have figured out how to
transfer the developed sites onto the remote production servers. Pretty much all of this is
directly appicable to building a site directly on a web server.

Myths
It is a pure myth that you have to know how to program (especially in php) to use Drupal. It
doesn’t hurt to have some basic knowledge of php, HTML, and CSS, but it is not required. Here
are some good resources for you:

W3 Schools - for virtually everything Internet-related.
The Official PHP Site - the full php implementation.
PHP Builder - some tutorials and code ready-to-use.

Now, to be honest, I have used HTML in this book, and tweaked the CSS on my site a little bit.
But I have not used one line of php code.

Another common myth is that your learning curve for Drupal is going to be steep and it will
take you months, or even years, to get a web site up and running. Hogwash! I had my first,
largely static, web site with 36 pages up in less than a week after I installed my first copy of
Drupal. Then, because my hosting provider pulled the plug, I got my group’s site up in the time
it took to get the domain name transferred (about 5 days). That was after about 16 days from
starting with Drupal. That site had a lot of static content, but also required a taxonomy-based
access control module, a fancier theme, meta tags, photo albums, and a calendar - and it all had
to work right away!

189
Drupal Handbook 3 Aug 2007

You can do it! Yes, YOU.

Using the Drupal Web Site
There are a few things you need to know before you post anything on the Drupal web site:

Search to see if the subject has already been covered. If it has, then recreating the subject will
probably get you negative comments. If you don’t understand the responses (I certainly
identify with that feeling), don’t hesitate to say "I’m a newbie, can you say this in easier to
understand terms?"
You need to get a few basic terms right or you will be flamed.

Node: This is, in simple terms, a unit your content. It may, for example, be a "page,"
"story," "book page," or "blog entry."
Theme: This is the way your site is displayed (or rendered) to the end-user.
Block: This is a "container" for pieces of content on your displayed page. For example,
your navigation menu and log-in are blocks. You may also have "Recent posts,"
"Sponsor links," or "Who’s online."
Try to completely describe the situation. For example, if a page is not showing up correctly,
it could be a browser problem, so make sure you tell the reader what browser you’re using.
Always mention which release of Drupal you’re using (4.7.x, 5.x, etc).

Typing Convention
Throughout this site, as well as the Drupal site, you will see things like Administer>>Access
control>>User management>>Roles. This means click on "Administer" in the navigation
menu, then "Access control," then "User management," and then "Roles."

I will occasionally refer to "production" or "live" sites. These terms are pretty much
interchangeable. The latter term is more modern and accepted in reference to web sites and
means the site that your end-users interact with. The former term is largely synonymous but is a
more "traditional" data processing term.

Some Preliminary Advice
This is from a post by ebrad on March 26, 2007, with some minor editing.

I don’t know if I could call my sites "great;" it’s taken about 9 months to really get a good
understanding of how to use Drupal and its modules. This doesn’t include learning the API or
writing my own modules.

These are some recommendations I would have given myself before I began with Drupal:

190
3 Aug 2007 Drupal Handbook

Never try anything for the first time on a live site. Use a test site that uses the same modules
and same data (different database). I keep 2 tests sites going at all times.
Don’t try to make the "perfect site" on your first shot. Muddle through for a while until you
understand a better way. Stressing over the perfect solution will slow you down.
Stay away from Views, Category, CCK, and Organic Groups modules until you at least
have a little experience under your belt. These modules require a good bit of understanding
to master and it might discourage you if you try to dive in too fast. However, over time you
will come to realize that these are some of the most powerful and flexible modules out
there. [Nancy’s note: also stay away from access control (security) modules until later. They can
really destroy your site if you don’t know what you’re doing.]
Customize one of the default themes before creating your own, the Theme Developer’s
Guide in the handbook is a big help.
When you run into a problem with a module, make sure to read the "readme," then do
several searches with different terms, only rarely have my problems not already been
answered in the forums or in an issues queue.
To make a site really successful, make it work for the users, not against them. Once you
have the basic site set up, get your friends, family, or anyone who will talk to you to look at
your site and give honest feedback, or do user testing for a more formal approach (I run a
company Intranet and I do user testing every couple of months).
Help out in the forums when you can. It’s surprising how explaining something to someone
else helps you understand it yourself.
Go easy on what I call "gadgets" such as useless blocks, images, and graphics that clutter the
page. I prefer simplicity and I only place something on the page if it is needed. This of
course depends on your application

Good Luck!

Drupal Is Supposed to be Easy?
Drupal is very powerful and flexible. That means it must have a significant degree of
complexity. Do you think the folks at Myspace don’t have their terminology or managed to roll
out that site in a day? I don’t know who told you Drupal was easy, but many people make it
harder than it has to be by thinking they need to understand everything at once.

Terminology is necessary in order to properly convey what one is trying to say or ask. If you talk
about "that box-like thingy on the right side of my screen" you could be referring to many
things. Contrast that with "the Author Information block in the right sidebar" - now you are
precise and everyone knows exactly what you mean. You’ve told them what it is, where it is,
and even how it got there and part of how you’ve styled it.

Start by trying to understand the basic parts of Drupal, don’t try to understand everything at
once. For example, it is imperative that you know what a node is (look in my book). Then
understand what content types are. Learn the basic parts of the rendered page (header, footer,
left and right sidebars, and the center, or content areas). Check out the administration pages so
you have some idea where things are, even if you don’t understand them all today.

191
Drupal Handbook 3 Aug 2007

It’s all fine and good to have "Myspace" as your target, but you are one person with a new tool.
The people that put that together are many and using tools that they already were familiar with.
(BTW, I find Myspace to be rather illogical.)

Just start by getting something up and visible. Then celebrate that you’ve done that. Now you’re
ready to move on to more wonderful things, but do it one step at a time. Don’t add tons of
modules right away; get comfortable with what you have. Add modules one at a time and get
familiar with them - one at a time.

As for making Drupal easier and more logical, you’re welcome to submit feature requests or
explain why something is not done in the most logical manner. But don’t demand it, or threaten
to abandon Drupal if you don’t get it your way. And certainly don’t resort to name calling or
derogatory comments.

A. Getting Started
Assuming that you want to build a site on your PC (with Windows), I suggest a visit to
DeveloperSide.net to download their package. Hey - there’s no need to re-invent the wheel!

This package has already integrated the following things:

Apache 2.2 HTTP Server
MySQL 5.0 Database
PHP 5.2 and Perl 5.8 Scripting Languages
GUI WAMP-stack Controller
Dynamic DNS Client
Tomcat Servlet/JSP Container
mod_aspdotnet ASP.NET Host Interface
OpenSSL Cryptography Toolkit
mod_security Web Application Firewall
phpMyAdmin MySQL Administration
Joomla
Drupal
WordPress
MediaWiki
phpBB

Don’t ask me what all of those mean, because I have no idea. Did I need them all? I doubt it. But
disk space is cheap, and the key thing I looked at was that it had Drupal 5.0 (the latest release)
integrated.

I followed their instructions, which built me a working system! Yay! I don’t remember if it was
automatic or not, but you will find it useful to have the "Web-Developer Controller" icon on
your desk top.

192
3 Aug 2007 Drupal Handbook

The only "fly in the ointment" was that when I went to the Drupal web site to start pulling my
modules and themes, there was a big announcement on the front page saying that 5.1 had been
released and was highly recommended.

What’s a girl to do? Do I stick with 5.0 any way, or try to update it to 5.1?

Well, in for a penny, in for a pound. I downloaded 5.1. I then unzipped it (using WinZip).

Of course, that created a directory called "Drupal-5.1," but the other software I had installed was
looking for a directory called "Drupal." Well, by getting Apache and its services shut down, I
managed to rename the two directories so that 5.1 was now called "Drupal." It worked! I now
had a running 5.1 system!

And it was all fairly painless and straight-forward. [Well, you know the plot will thicken, don’t
you?] But at least I’m not as afraid to install a new release of Drupal any more.

B. Basic Configuration
Whether you run one site or several, there are some basic things you should do right now.
Here’s what I do right off the bat; the advantage to doing it in the "root" database is that when I
make copies for my other sites this has already been done. I’d give you a link to something on
the Drupal site, but I never found anything like this.

1. Go to Administer>>User management>>Roles and create an "administrator" role.
2. Go to Administer>>User management>>Users and create a user entry for yourself.
This allows you to test the site by changing your role to meet your needs.
3. Go to Administer>>User management>>Access control and allow the
"administrator" role to do everything.
4. While you’re there, go ahead and set what the "authenticated users" (logged in) and
"anonymous user" (not logged in) can do, such as using your contact form. This is not
engraved in stone; you can change it any time you want.
5. Go to the Administer>>Site configuration>>Site information page and, near
the bottom, set the "Default front page" to "node." As long as you’re on this page, set basic
defaults for the other fields. I don’t know about everyone, but I don’t like, when I visit a site,
being called "Anonymous" so I change the designation to "Visitor."
6. If there are any modules (core or contributed) that you use on all sites, go ahead and enable
them now ((Administer>>Site building>>Modules). For example, you will probably
use "Page" on all sites, and maybe "Story." I am finding more and more uses for "Book."

7. I do recommend turning on (enabling) the "Path" core module so you can use "normal"
names for your pages.

If you want to use the contact form to email anyone from the site, be sure to enable the
"Contact" module.

193
Drupal Handbook 3 Aug 2007

8. The same goes for themes.

There are a few things I recommend that you do in all your databases, so this is a good time to
do it:

Turn on "CLEAN URLS" to make your site more user friendly. Go to Administer>>Site
configuration>>Clean URLs. At the bottom of the verbiage there is a link to run the
"Clean URLs Test." If it passes, then the "Enable" radio button will un-dim. Click on that. (If
the URLs stop working for some reason here are instructions to unset clean URLs.)
In order for me to create any kind of content, I go to Administer>>Site
configuration>>Input formats and set "Full HTML" as the default until I get the site
ready to go live. Then I still allow administrators (like my other ID) to use that format. Do
this now and you will avoid a very common problem with building your site.
I don’t like having "Promoted to front page" as a default for content, so I go to
Administer>>Content management>>Content types and turn that off - in each
format.
While you’re there, decide on your default comment mode. Go to Administer>>Content
management>>Comments>>Settings and set the comments to be entered on a "separate
page" and make sure that "Preview comment" is set to "Required."
Now, let’s turn on the Contact form so your users can send you a message. Go to
Administer>>Site building>>Menus and locate the "Contact" item. Click on the
"enable" link. Remember that later on you will want to go to Administer>>Site
building>>Contact form and finish setting that up.

C. Creating Multiple Sites On Your Local Computer
Need another test site? Here’s how to do it the "easy" way. [Hint: if you want several test sites,
make a list right now. Read these instructions all the way through. Now you can do some of the
steps in bulk to save some time.]

Why create extra sites? In addition to my having several sites running already, I had some ideas
in the back of my head, not the least of which being a site where I could document everything I
do (like this book). I also had some idea for other sites that I might put up in the future. So
before you totally pooh-pooh the idea, give it a few minute’s thought. And you can always
change your mind later; it just might be a bit messier then.

At the very least, I would create a "working" site other than my "root" site. This makes it easier to
start all over again if you get totally out of control later on.

This may look like a long process, but it’s deceiving because I spell it out in detail. It is expanded
and updated from the post "Running multiple sites on a local PC (localhost) from a single
codebase, using Windows." For more details on the "official&quot. stance on the sites directories,
read Setup of /sites directory for multi-site.

194
3 Aug 2007 Drupal Handbook

Open phpMyAdmin (using "other" in Web-Developer Controller)

start bulk loop 1

On the left, select the Drupal51 database. This is the one that was created by the package
installation.
Click on "Operations"
Scroll down to "Copy Database to:"
Enter the new database name.
Verify that the radio buttons are clicked for:

Structure and data
CREATE DATABASE before copying
Switch to copied database
Click on the Go button just below this area.
When the copy is complete, click on "SQL".
In the "Run SQL query/queries on database" box, enter:
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER,
CREATE TEMPORARY TABLES, LOCK TABLES ON databasename.* TO
’admin’@’localhost’ IDENTIFIED BY ’superpw’;
FLUSH PRIVILEGES;
admin is what I call my administrative role (this is the "super-user" name);
superpw is the password for this user (I tend to use the same one for all my databases to
make it easy).
Hint: I created and saved this in c:/www/drupal/grant.txt so I could copy and paste.
Change databasename to the new database’s name.

end bulk loop 1

Close phpMyAdmin.
Go to the www/Drupal/sites directory.

start bulk loop 2

Copy one of the site folders (e.g. default) and name it for your new site.
Open the directory, then open the settings.php file in Notepad.
Change the $base_db and $base_url lines. The $base_db line should have the name of
the database you just created. The $base_url will be how you want to access the site.
Close the file.
If you are going to have site-specific modules or themes, go ahead and create directories in
this site to hold them (named "modules" and "themes").

end bulk loop 2

Navigate to the /www/Apache22/conf folder.
Locate and open the "httpd.conf" file (Hint: I always make a copy of things I’m about to
change, just in case I mess up.)

195
Drupal Handbook 3 Aug 2007

I did notice that my version of Apache sets index.html ahead of index.php, so don’t have an index.html in your
directory.

Find the line that says "# Virtual hosts." Remove the "#" from the next line. This allows you
to make all your other changes in a separate, and less dangerous file.
Save it.
Navigate to the /www/Apache22/conf/extra folder.
Open the httpd-vhosts.conf file.
At the bottom of the existing list, comment out ("#") the examples.

start bulk loop 3

At the bottom of the existing list, enter:
<VirtualHost *:80>
DocumentRoot /www/drupal/
ServerName databasename
</VirtualHost>
Change databasename to the new database’s name.

end bulk loop 3

Close the file.
Navigate to the /windows/system32/drivers/etc folder.
Open the Hosts file with Notepad. Hint: these two steps can be done by using "other" in
Web-Developer Controller.

start bulk loop 4

Add a line that says:
127.0.0.1 databasename
Change databasename to the new database’s name.

end bulk loop 4

Close the file.
Go back to Web-Developer Controller.
Click on Apache2 (top left).
Click the Stop Service button.
Wait for it to change to "stopped."
Click the Start Service button
Wait for it to say "running."

Go for it. You can now start the browser and enter http://databasename.

196
3 Aug 2007 Drupal Handbook

For more details on directories for multiple sites, see Setup of /sites directory for multi-site.

D. Error Pages
Occasionally, a user may do something that confuses Drupal, such as typing a wrong page name
or trying to access content they shouldn’t. These will generate 404 and 403 errors, respectively.

A recent SEO newsletter, they mentioned the value of letting Drupal handle these errors:

Your unique 404 error page should look like a regular page of your site. It should include
your site’s header, footer and navigation bar so that the site visitor can easily click on
another area of your site. The content of this unique 404 error page should contain text
explaining that the page selected is no longer available along with contact information so
the site visitor has the option of emailing or calling your company.

This was one of those "Duh" moments for me. How obvious it is that you should make it easy for
the user to get "back into" your site.

The same more or less goes for the "access denied" (403) error message. Let them know they did
a no-no and try to explain why.

Just go to "Create content" and select "Page." I title them "Access Denied" and "Page Not Found"
but you can call them whatever makes sense to you and your users. When you submit them,
note the node ids. Then go to Administer >> Site Configuration >> Error
Handling and enter "node/nnn" in the appropriate boxes.

Page Not Found
Here’s the HTML for my 404 page:

<p>Sorry! The page you were looking for no longer exists. We redesigned
our site and many of the pages have changed.</p>
<p>&nbsp;</p>
<p>If you are unable to find something on our new site or have a
question about our site or services feel free to <a
href="/contact">contact us</a>.</p>
<p>&nbsp;</p>
<p>--Webmistress</p>

Access Denied
Here’s the HTML for my 403 page:

<p>We’re sorry, but you must have permission to view the page you
requested.</p>
<p>&nbsp;</p>
<p>If you are already a registered member of this site, please try <a

197
Drupal Handbook 3 Aug 2007

href="user">logging in</a>.</p>
<p>&nbsp;</p>
<p>If you are not a member, you need to <a href="/join_us">join
us</a>.</p>
<p>&nbsp;</p>
<p>If you have any questions about our site or group, please feel free
to <a href="/contact">contact us</a>.</p>
<p>&nbsp;</p>
<p>--Webmistress</p>

Don’t worry that you haven’t created the "join_us" page yet. This is an advantage to having URL
Alias support (the Path module) enabled. Just add to your to-do list to create this page when you
get to the "Creating Content" step a few chapters later in this book.

E. Accessing Your Test Site(s)
Okay, great, now we have all that software installed. But how do we use it?

First, open the "Web-Developer Controller" that you put on the desk top. Look at the top left.
You want to see, and should, if Apache and MySQL are running. If they are, you’re just about
ready. If not, select Apache, then click on the "Start Service" button. Within a few seconds it
should change to "Running." Now select "MySQL" and start it.

Fabulous, we have the software ready for us. Now let’s get us ready.

Fire up your favorite browser. In the Address field type in http://localhost/drupal/ to
access your "root" database. Since you’ve done everything right, you’re now into your Drupal
database.

Congratulations! Now the work begins.

F. Adding Modules and Themes
Let me first say that a newbie shouldn’t worry a lot about adding modules and themes at first.
Work on the basics of your site first, then worry about add-ons.

Themes are largely a matter of taste. For example, I have no idea why anyone would use a "fixed
width" theme, but lots of people do. One nice thing about themes are they are pretty much
independent of your content (later on you can look at the many submissions that are dependent
on content).

Contributed modules are ways to add or extend functionality of your site. The only module I,
personally, consider necessary is the Nodewords (a.k.a Meta Tags) module; in my opinion, it
should be promoted to "core" status. This one allows you to add the "content," "keywords," and
"robots" meta tags to your pages. This is useful if you’re interested in your search engine
rankings. You will also find that many contributed modules also require the Views module; I go
ahead and make that a standard one for my sites.

198
3 Aug 2007 Drupal Handbook

Now, if you experiment with different themes and modules, as I know you will, despite my
suggestions, you should also look at the Update Status and Site Documentation modules to
make sure you are current and to document and clean up the mess your experimentation will
make.

Installation
Installing a module or theme is pretty much the same until you get to enabling them. Now keep
in mind that I use a Windows based PC (development) and Linux servers (on my live sites).

1. Go to the Drupal site and click on the "Downloads" tab. Then select either "Modules" or
"Themes" depending on what you’re after.
2. Locate the module or theme you want.
3. I always click on "Find out more" and read the stuff again. This gives you the chance to see
if there is support for your release of Drupal. You can also look at pending bugs and feature
requests - it might change your mind.
4. Download the proper release. (I put them in a Drupal folder in "My Downloads.")
5. Unzip the downloaded file (I use WinZip). It may tell you that there is only one file in the
zipped file; click "yes" or "OK."
6. Extract the code to to your Drupal/sites/sitename/modules or themes folder. If you
are not running multiple sites, this would be Drupal/sites/all/modules or themes.
7. That’s it! Now you need to enable it.

Modules
Modules
You enable a module at Administer>>Site building>>Modules. The non-core modules
are listed farther down. With 5.x, they now show you some of the inter-module dependencies. I
turn them on and "Save configuration" in order of the dependencies. For example, "Views UI"
requires "Views", so I turn on "Views" first, save the configuration, then turn on "Views UI." and
save again.

Ah, now the real work begins. Go to Administer>>User management>>Access control
to select who can use the features of the new module.

If the module introduced new content types, go to Administer>>Content
management>>Content types and configure them. Don’t forget this may also affect your
"Input formats" (Administer>>Site configuration>>Input formats) and "Categories"
(or taxonomy, Administer>>Content management>>Categories); you’ll have to check
those too.

Okay, now you can start using the new module.

199
Drupal Handbook 3 Aug 2007

This Site
My documentation site is a relatively "vanilla" implementation of Drupal.

Core Modules
Contributed Modules in Use
Enabled
Blog Codefilter - Provides tags for automatically escaping and formatting large
Book pieces of code.
Comment Meta Tags (Nodewords) - Allows users to add meta tags, eg keywords or
description.
Contact
Site Documentation - Documents and cleans up your configuration.
Help
Menu
Path

To get some idea of what modules are available, check these links: module handbook and
contributed modules handbook.

Themes
Themes
You enable a theme at Administer>>Site building>>Themes

If it has never been enabled on this site, you will have to check the "enable" box and then click
the "Save configuration" button at the bottom.

To set up how the theme works, click on the "Configure" link (not the tab at the top).

Fill in the fields.

Save the configuration.

Don’t leave the page yet.

Logo and Favorite Icon
Now use that "Configure" tab

I prefer to do this part under the "Global Settings" but it can be done theme-by-theme if you
prefer.

The "Default Logo" is that little picture (usually) in the upper left corner of the page. For
example, on the "Bluemarine" theme, it’s the Drupal logo.

200
3 Aug 2007 Drupal Handbook

If you want to change it, here’s how:

1. First, find out what size it is because you’ll want your own logo to be about the same. (If
you are comfortable with HTML and CSS you can also edit the theme’s code to
accommodate your logo rather than resizing the image. How to edit theme code is not
covered in this beginner’s guide.)
2.

Theme Name Width Height
Bluemarine 48 55
Chameleon 49 57
Garland 64 73
Minelli 64 73
Pushbutton 144 63
Fancy 80 80

3. Under "Logo image settings" either type in the path to your logo, or upload it from your PC.
4. Note: Neither one of those options turns off the "Use default logo" radio button. You must
select the correct radio button yourself.
5. The "Shortcut icon" (a.k.a. the favorite icon, or "favicon.ico") is the same way. If you want to
change this, you must specifically say, "Hey, Drupal, I’m changing this."

Now you click the "Save configuration" button. If you did this in "Global settings" it affects all
themes (assuming they behave properly); if you did it for a single theme, then only that theme is
changed.

For a list of all available themes, check Themes.

HINT: Going to make a few (or a lot) of changes to a standard theme? Think about copying it
over to your /sites/sitename/themes/ folder and renaming it. Then you can do anything
you want and still be able to undo it easily by recopying. If the changes ae a bit bigger, think
about contributing it back to the community (with your name, of course).

G. Creating Content
"Wow, I’ve done all this and I still don’t have any content on my site!" Well, let’s fix that.

201
Drupal Handbook 3 Aug 2007

First, let me explain that the page your visitor sees first upon entering your site is usually called
the "home" page. Drupal calls this the "front" page, much like a newspaper. This page is special
to Drupal. I know you’re in a hurry, but read about both "pages" and "stories" before you decide
which to use to create your front (home) page.

Content Types

Page
Drupal says, "If you want to add a static page, like a contact page or an about page, use a page."
If you’re used to building web sites with HTML, this is what you’ve done in the past. In general
a "page" is going to stand on its own and will probably have a menu entry. You may also later
add it into a book. When I created my first two sites (based on former static HTML sites, I made
the front page a "page;" I have since changed to a "story."

Story
Drupal says, "Stories are articles in their simplest form: they have a title, a teaser and a body, but
can be extended by other modules. The teaser is part of the body too. Stories may be used as a
personal blog or for news articles." Why they say to use it for a blog, I have no idea; they supply
a blogging module as part of the core support.

Okay, you’ve seen the Drupal site and noticed that there are "pieces" all over the place. Look at
the front page; you’ll see several announcements with space between them - those are "stories."

I have now switched my sites to use stories on the front page. The "welcome" message is one
story. I have an announcement story node that any of my admins can edit. If you want to have
weather or cartoons, a story is a good idea. Another use is if you are on a net ring - put the ring
links into a story.

Book Page
Drupal says, "A book is a collaborative writing effort: users can collaborate writing the pages of
the book, positioning the pages in the right order, and reviewing or modifying pages previously
written. So when you have some information to share or when you read a page of the book and
you didn’t like it, or if you think a certain page could have been written better, you can do
something about it."

Another way to use a book is to collect related information together. A book has its own
navigation, so it can also be used to de-clutter your menu.

202
3 Aug 2007 Drupal Handbook

Blog Entry
You probably already know what a blog is, but just in case: A blog is a diary, collection of
thoughts, or other time-ordered content.

So have you decided what kind of content you want? No, okay, just start with a page; it’s easy.
As you go create your content, be thinking about the menu as well.

G1. Creating a Page
A page is probably the simplest content, other than maybe a blog.

Click on "Create content" in the menu, then select what kind.

The title and body are pretty self-explanatory. Below these are a number of collapsible fields.
"Input format" controls what you can put into the page; I’m assuming you are the "super-user"
(user/1), so give yourself the priviledge of "Full HTML."

If you have Nodewords installed, the next section is "Meta Tags." It’s pretty well documented.

I have no idea why you’d use the "Log message" but I’m sure someone has a reason.

Hopefully, you already set your default "Comment settings" but the front page rarely deserves
comments, so you can disable them.

If you turned on the "Path" core module, you’ll have URL path settings next. You can enter a
"normal" name here rather than being required to use "node/2" when you refer to it later on.
Hint: if you are converting a site that was static pages, you might want to go ahead and add
".htm" or ".html" to the name so that the search engines will continue to find the page.

"Menu settings" is the next section. "Title" is what will show in the menu normally. "Description"
will show when the user hovers the cursor over the menu item. "Parent item" allows you to
create multi-level menus that collapse and expand. "Weight" allows you to set a relative position
within the menu; unfortunately, some Drupal core items are hard-coded at 0.

Chances are you won’t need "Authoring information" unless you want to attribute the page to
someone else. The other use for this section is to control the page or story order when they are
based on the time and date it was created.

Finally, "Publishing options," which you set defaults for earlier, right? You want the page
"Published" so it will show up. If this is your "Welcome" page, you’ll want it "Promoted to front
page."

"Submit" it.

203
Drupal Handbook 3 Aug 2007

Congratulations, you now have some content on your site!

G2. Creating a Story
Most of what goes for a page is also true for a story. You can largely consider the two types to be
interchangeable, and it is goodness to have at least two content types because conflicts can arise
in the way content types are used (for example, taxonomy "collisions").

Stories have a "teaser" or opening statement intended to grab the reader’s attention. The length
of the teaser is set in one of two ways:

In Administer>>Content management>>Post settings. The default there is 600
characters. You can change that.
By specifically identifying a break point with ‘‘< !--break-->’’ in your content (before the
default limit; leave out the space).

Note: You may see some places that tell you to use ‘‘<break>’’ to set a teaser point. This was
originally changed in 5.0 and created a considerable controversy, so it was backed out.

A story probably shouldn’t have a menu entry. If you use the general "convention" that a "page"
is for static or generated content that stands alone, and "story" is for collections of related content
(e.g. RSS feeds, newsletter articles, press releases, etc.), then a story is usually going to be
displayed with other stories, so which one would be the menu item? Generally the menu for a
set of stories will be a description of how they are selected for display.

You may want to promote the story to the front page. For your ‘‘Welcome’’ message, you
probably also want to make it ‘‘Sticky at top of lists.’’ Alternatively, you can give it a lighter
‘‘weight’’ so it "floats" up the list.

What’s a Teaser?
This is from a post by zoon_unit on January 10, 2007.

A ‘‘teaser’’ is essentially a snippet of text designed to tell the user the content of a post without
reading the entire post. Since most writers have embraced the common journalistic style of
explaining the nature of an article in the first paragraph, teasers work well for most articles.

Here’s what happens:

1. A node contains an entire article.
2. Drupal’s ‘‘teaser’’ function, ‘‘node_teaser,’’ strips the first x number of characters from the
article and makes it available as content. The exact length is determined by the value set in
Drupal’s Administer » Content management >> Post settings.
3. So, you list a bunch of articles on a page. You want the articles to display only a snippet of
text from the full article, so that you can fit a bunch of articles on a page without requiring
the user to page down through tons of text. If the user likes the ‘‘teaser’’ content of the
article, they will click on the article’s title and see the full content of the article on its own

204
3 Aug 2007 Drupal Handbook

page. In a sense, teasers function like summaries of an article, except that the software
decides where to cut off the text. If you want to determine where a teaser article ends, you can
insert the comment tag to instruct Drupal exactly where to fashion the break between full text
and teaser text.

NOTE: There is a bug in the core Node module. Check the issue status. It is a simple change (can
be done manually) and must be applied in order for some modules to render teasers correctly.
By the way, you might want to add your own experience to that bug report in order to increase
its attention by the developers.

G3. Creating a Book Page
Generally, I only create one book page for each book. This is the first one, usually the
introduction. All other pages will be added as "Child pages" (to be accurate, child pages will still
have the "book page" content type set for them).

In addition to the things I said about pages, a book page has a "Parent." For the first page, this
will be "<top-level>." If you use "Add child page" the "Parent." selection should be already filled
in with the book’s name. If you create another book page, you would need to make sure you
properly select which book or page teh new one is to be made a child of.

The top page of the book probably deserves a menu entry. The rest do not, unless they are really
special. Remember, a book has its own navigation.

You are currently reading a "book."

G4. Creating a Blog entry
Blog entries are a little different. Assuming you enabled the "Blog" module, you should see a
"My blog" entry in your navigation menu. When you click on that, there will be a "Post new blog
entry" link on that page.

If the blog is a diary, you probably want to use the date for the title.

If it’s a collection of thought, give it a meaningful title.

Type in the content of the entry.

Your blog will always show the most recent entries on the beginning page when visitors view it.

205
Drupal Handbook 3 Aug 2007

H. Custom Blocks
I’m not going to say a lot about custom blocks. But I will show you some really simple ones to
give you a flavor. There’s a lot I still don’t know about custom blocks, and that fills many posts
on the Drupal web site. One good starting point is: Blocks.

Address
A business or support group should always let people know how to contact them. One easy
thing is to include your mailing address on your pages. This is about the easiest kind of block to
start with.

1. Go to Administer>>Site building>>Blocks. I should already be sitting on your
default theme, but if not, select the right one.
2. Click on the "Add block" tab.
3. Fill in the "Description" and "Body." Here’s a sample body:

4. My company name<br>123 Main St.<br>Mytown, State Zip<br>USA<br>(123) 456-7890

5. Save the block.
6. For some strange reason, you now need to "Configure" the block to add the block’s name
and placement.
7. Add the name.
8. Determine whether users can turn to block on or off. Then which roles can see it; leave this
with no selections to allow everyone to see it. Then choose which pages it will be shown on;
I show the address on all pages.
9. Save the block.
10. Now you’re back on the block list. Locate the block you just created. Select its location; I like
the address in the left sidebar. You can use the "Weight" parameter to set its position with in
the selected area; again, I like the address at the bottom, so I use a heavier weight.
11. Click on the "Save blocks" button.

That wasn’t so bad was it?

Last Updated
It is fairly common practice, especially on a group site to let the visitors know when the site was
last updated. This example requires you, the webmaster or administrator (sometimes called the
"super user") to maintain the block. There are ways to automate it, but I leave that until we are
all farther along in our Drupal education.

I followed pretty much the same process for the address block, giving this one a slightly
heavier weight to sink it to the bottom.

<address>Feb. 12, 2007 - NEW</address><br>
<small>Best viewed in a full window with Internet Explorer 5.5 or

206
3 Aug 2007 Drupal Handbook

higher. Tested with IE6, Netscape 8, and Firefox 2.</small>
The main difference is that I wanted it only on the home (front) page. So under "Page
specific visibility settings," I clicked on the "Show only on the listed pages" radio button, and
entered <front> in the pages box.

Okay, now you’re an "expert" on blocks.

I. Working with the Menu
Introduction
This will not be an exhaustive piece on the subject of menus. My main point will be to start you
on building your menu and giving you a flavor for how it works. A more complete guide to
menus can be found at Creating a menu structure.

As we all know the menu, or navigation system, can make or break a web site. It must be easy to
follow, often referred to as "intuitive." It must be complete, yet compact.

There is a lot of content on the Drupal site on menus. Most newbies have trouble understanding
it all. I’ve been using Drupal for just over a month as I write this and I still have a long way to go
on completely understanding menus.

For beginners it can be very confusing to understand the difference between menus and
categories. The menu is a navigation system and categories is a system to order content data. So
menus is to arrive at content and categories to order it. Initially to understand Drupal well, you
have to see these as two separate things.

With a menu you can point directly to a node, like a page or a story, but you can also point to a
term in a category, which would show you a summary list of stories or pages.

How To Menu
Drupal offers three primary ways, which may be combined, to provide your users with site
navigation.

1. Textual menu - this is the "standard" line-by-line type of menu, like what you see on most
sites, including mine. It can be enhanced in a few ways, such as using a CSS or separate
book navigation (as I have done here).
2. Tabbed menu - becoming more popular because it’s a little more "gee-whiz" in its
presentation. It is debatable as to whether it is any more effective for your visitors. In
Drupal, it is divided into "Primary" (the tabs you always see) and "Secondary" (the part that
drops down, or slides out). Not all themes support secondary links.
3. Books - Books are organized separately from menus, but have their own navigation, which
you can see on this site. See my section Creating a Book Page.

207
Drupal Handbook 3 Aug 2007

Textual Menu
The textual navigation is the easiest to understand. As a matter of fact, I still don’t understand
how to make the "secondary" part of tabbed navigation work the way a lot of people think it
should (drop down).

You may see the terms "primary links" and "secondary links" in many posts. This is one area
where I find the Drupal documentation confusing (at best). While they sounded great, and I am
now using them, they may not be the best thing for someone just starting out. Stick to the
standard "Navigation" menu until you have a better feel; you can always go back and change
this later.

For the most part, the "standard" menu is best built as you create content, but may require a little
tweaking as you see how it lays out.

When you create a page, story, blog, or book page, one of the fields that you may (should) fill in
before submitting, is the menu entry (if the node is to have one). You have the "title" (what is to
appear in the menu as people see it) and a "description" (what they will see if they hover the
cursor over that entry).

I rarely worry about the "weight" until I see how it shows up in the menu. At that point, you can
either go back and edit the content you created or go to Administer >> Site building >>
Menus and edit it there.

Okay, that was the easy part. Now let’s say you want this particular content listed in the menu
as a
child of some other page. No problem! Let’s say you have a subject’s introductory page already
listed in the menu, for example "Family History." The page you’re creating is "1860-1899." When
you build the menu entry, you’ll notice a selection box labeled "Parent Item." Scroll down the list
until you find "Family History." Now when you submit this page, it will be a child of "Family
History," making that item an expandable menu item. You just created a hierarchical menu!

Tabbed Menu
In those themes that support this technique, the "Primary" seems to get built automatically as
you build the "Navigation" menu, unless you specify a different menu set. I have no idea yet
how to make drop down "secondary" links part work - I think it requires a separate module. I do
know how to make the secondary links appear in a block, if they exist. I like the way that works,
but it may not be for everyone.

Books
The book "menu" is built automatically for you. The only thing you have to worry about is the
order of the entries (hint: weight).

208
3 Aug 2007 Drupal Handbook

The only "complicated" part is turning on the book navigation block, which is done at
Administer >> Site building >> Blocks. All you really need to do is to tell Drupal
which region to place it in and its relative weight. You can get fancy, if you want, with your style
sheets.

More
Later you might consider using the taxonomy_menu module. It will add to your confusion, but
it will be good when there are frequent changes in your vocabularies. It will make the difference
between menu and categories almost completely disappear, because it allows you to make
vocabularies appear as a menu. This way menus will be generated automatically.

If you want hierarchical drop down menus, the nice_menus module might come in handy.

I2. The Contact Form
For something as simple as a contact form, this is one of the most complicated things to get set
up and operating.

Set Up
First, the contact module must be enabled. Go to Administer >> Site building >>
Modules and locate it in the list of core modules. Click the check box and go to the bottom to
save the change.

Go to Administer >> Site building >> Contact form. Here you can set up the
"Categories" - or recipient name/office. [Don’t confuse this with taxonomy categories.]

For example, email for the Sales Department might be given a category of "Sales." The email
address that the form is sent to may be sales@mycompany.com. If you want a reply
automatically sent to the person sending the contact email, you can specify that here. Don’t
worry if you don’t know them all right away, you can come back and change this at any time.
Click the "Submit button."

Now click on the "Settings" tab. Here you can limit how many contact emails an individual may
send in an hour -- this helps limit spamming. You may also turn on personal contact forms here;
this allows users to contact each other. Click on the "Save configuration" button.

Make It Accessible
To me this step seems totally unnecessary, but I suppose that some people want it.

209
Drupal Handbook 3 Aug 2007

Go to Administer >> User management >> Access control, locate the "Contact
module" entry and enable it for the roles you want to be able to use Contact. Save your changes.
The menu link (next step) will not be visible to any one not having access.

Add "Contact" to the Menu
Go to Administer >> Site building >> Menus. Under "Navigation," enable "Contact" as
described in the instructions. Save your changes.

Using It In Content
To add a link to a content page use <a href="/contact">Contact Us</a>. Unfortunately,
this does not give you the capability to specify which contact to send it to. Fortunately, there is
help! Check out the Contact List module.

Need a customized contact form? Check the WebForm Module. A recent change to the
Contact_List module allows you to use these two modules together.

J. URL Aliases
"URL" is an abbreviation of "Universal Resource Locater." It is a fancy way of saying "my page’s
address (or name) on the web." It is the "name" by which a browser identifies a page to display.
We’ve all seen advertisements that say "Check us out at abcxyz.com." Well, abcxyz.com is a URL
for the home page of their web site (well, sort of - there is an implied add-on to that, such as
index.html).

By default, Drupal calls your content "nodes" and identifies them by their position in your
database. So your page on "The History of the Macadamia Nut - Part 1" might be known as
"node/167." That’s all fine and well for Drupal, because it understands that. But your visitor
really doesn’t care where the page is in the database; all they want to do is find the page again,
or know what the entry in their bookmarks list is.

So Drupal has a feature called "URL Alias" that allows you to provide a more understandable
name to the content. As far as browsers, servers, and search engines go, it is totally unnecessary.
But for humans, it is nearly mandatory. This is why I tell people to always turn on the Path core
module, which supports URL Aliasing. (I will mention another module shortly, called Pathauto.)

So, just before you submit that exhaustive treatise on macadamia history, and if you have the
Path module enabled (I told you that you’d want it), then you’ll see a section on the edit page
that says "URL path settings." So let’s say you want your visitors to see it as
http://www.mysite.com/MacadamiaHistory.htm. In the URL field, you enter
MacadamiaHistory.htm.

210
3 Aug 2007 Drupal Handbook

Now, some people will argue that putting that ".htm" on the end is not necessary. That’s
absolutely true. But then it’s not necessary to do any of this. My opinion is that if you want your
visitors to see a "normal" name, it should look like a normal WEB name. Web pages have some
kind of type, such as ".htm" so we should too. But it’s your preference.

Oops, forgot to do this before you submitted the page? Not to worry - Drupal to the rescue!

First, visit the page you created. In your browser’s address field, you’ll see its URL. On the end it
will probably say "node/xxx" where xxx is some number. Write down that number. Now go to
Administer>>Site building>>URL Aliases. There’s an "Add Alias" tab at the top. In the
top box (sorry, they seem to have dropped a label in 5.1), enter "node/xxx" from above. In the
second box, enter "MacadamiaHistory.htm".

Now go back and visit that page and look at your browser’s URL field.

If your site is going to have lots of content, particularly user-submitted content, you might want
to looks at the PathAuto module. Not only will this module automatically generate URL aliases
for new content (according to rules you can set up), but can even go back and change aliases in
bulk.

K. Moving Entire Drupal Site with Databases
Start with Moving entire Drupal site with databases

This might help too: Backing Up Your Database

I know the "official" process is to load the "tar" file to the host and unpack it. As an alternative,
one can copy the code directly from your test site on your PC. I’ve tried uploading code from my
machine twice with disastrous effects. (Okay, so I was born blonde!) So, I’ve worked out my
own process that works. [By the way, this also reduces the bandwidth usage for those who
might be running short on that.]

What has always worked for me is to install Drupal with cPanel/Fantastico (I know there are
some people out here who will speak ill of Fantastico, but it has always done me right). Now, to
be fair, one needs to understand what Fantastico can and cannot do.

Fantastico only supports core functions. It does not support custom themes, contributed
modules, or custom code (outside of content). Fantastico does not use "update.php" (as a matter
of fact, doesn’t even load it), so it is not a good idea to use it to upgrade your installation. As
long as you understand this, you’re much less likely to have problems.

Make sure that the correct versions of modules and themes are working on your test site.

211
Drupal Handbook 3 Aug 2007

Here’s my process: (by the way, this should pretty much work for changing hosts as well)

1. Keep a pencil and paper handy to write down what changes you have to make. You can use
this if you need to restart, or to think about changes to your site that slow down moving to
new releases.
2. Use phpMyAdmin (on some hosts, it’s hidden under MySql) to back up your live database.
If you have a site that is actively receiving new content, you may have to put the site into
maintenance mode to prevent losing new content.
3. It would also be a good idea to back up your test database, just in case...
4. Import the database into your test site.
5. Download any pictures you’ve uploaded and any folders that are created by the modules
you have installed.
6. If your live site and test site are not at the same version, you will need to run "update.php."
7.
Open your browser to your test site. Don’t panic if everything looks strange, or even
blank.
In the URL bar, append "update.php" and press Enter. If it says you don’t have the
access rights, don’t worry.

Using Notepad or similar text editor, open "update.php".
Near the top, you will see:
// Enforce access checking?
$access_check = TRUE;
Change it to FALSE and save it.
Try "update.php" again.
If you have any errors listed, search the Drupal site for fixes. There’s a good chance
that someone else has had the problem. If it appears to be a new error, post a
request for help. Take your site out of maintenance mode and plan to start over
when it’s fixed.
Change $access_check back to TRUE.
If you had a custom theme, you probably need to re-enable it for the site to look right.
Now check out all your module settings. They’ll probably be okay.
Look through your content, especially the front page. Make sure your menus are
correct.
Check out any content that uses custom code, especially if you are changing Drupal
versions.
Does everything check out? Good, you’ve done all the real work. Now the easy(er) part.
8. Okay, now it’s time to do the damage. For me, the rest of this takes less than 15 minutes, so
the outage to your users is minimal.
9. If your current site was installed with Fantastico, delete the current installation. If not, then
you have to manually remove all the folders.
10. Now tell Fantastico to install the current version. Leave the directory field blank to put it in
your "root" directory (probably "public_html"). The userid and password you supply will be
your "super user" (user/1).
11. When it is done, I always tell it to email me the installation summary.

212
3 Aug 2007 Drupal Handbook

12. If you have any customized themes, non-core modules, or pictures, upload them (FTP) to
the correct places on the server.
13. If there were pictures or module-related folders, upload them now.
14. When that’s done, use phpMyAdmin on your test site and create a back up.
15. Then go to your cPanel again and invoke phpMyAdmin. When you get there, select your
Drupal database and then "Import." There’s a section to locate the back up on your local
computer (Browse). Find it, and then Click on the "Go" button.
16. If you have a customized theme, go to Administer>>Site Configuration>>Themes
and enable it. [Hint: Do not panic if your site looks weird at first. Remember you can always
login with http://www.mywebsite.com/?q=user (yes, "user," not your ID.]
17. If your test and live directories are not identical, you may need to update IMG links, etc.
18. You should be in business.
19. One more little bit of business if you used Fantastico: go to the main Drupal directory on
your PC and copy (FTP) the update.php script to your server. I don’t know why they
leave it out, other than they don’t use it. You may need it later.

Backup Process with phpMyAdmin

Backup Process with phpMyAdmin
The screen shots here are from phpMyAdmin 2.9.2, which I have on my local computer. My web
hosts have 2.9.0.2 and look very similar. They certainly produce exchangeable results.

1.
2. Log into phpMyAdmin on your server.
3.

4. Select the
name of your database - or your Drupal database if you have several databases.

213
Drupal Handbook 3 Aug 2007

5.

6. The next screen will show
you all the tables inside your Drupal database. Ignore those, and click the "Export" tab on the top
set of tabs.
7.
8.

214
3 Aug 2007 Drupal Handbook

Look at the left box at the top of the Export section. All the tables in the database you selected
are in that box.
9.

If you have other programs that use the database, then choose only those tables that
correspond to your Drupal installation.

If you only have Drupal installed, in the left column, click "Select All."

10. Ensure that the SQL button is selected too.
11.
12. In the Structure section tick the following boxes: Structure, "Add DROP TABLE," "Add
AUTO_INCREMENT," and "Enclose table and field names with backquotes."
13.

215
Drupal Handbook 3 Aug 2007

14. In the DATA section leave the boxes inside this section unticked, but make sure to keep the
check box next to the "DATA" heading checked.
15.
16. Tick the "Save as file" option, and leave the template name alone.
17.
18. For now, select "None" for compression.
19.
20. Now click "Go" and you should be prompted for a file to download. Save the file to your
computer.
Depending on the database size, this may take a few moments.
21.

You have now backed up your database! (Not so bad, was it?)

Once that download is complete, you may check the "zipped" option, click "Go", and download
the next file. If you want, you can download a backup in each of the compression formats. Your
choice.

L. Moving Stuff to Your Web Site
Occasionally, you need to update something other than your content (database), like the style
sheets, or new code levels.

FTP stands for File Transfer Protocol. It is pretty much the standard way to move stuff (files,
code, style sheets, etc.) to your site. This is not how you will create content; that goes into the
Drupal database.

Now, the postings on the Drupal site will tell you to get a fancy FTP program. If you are at least
on Windows 2000, there is absolutely no need. You can do it with Windows itself and it will look
just like another older and you can drag and drop. I find this process to be easier if you use
Internet Explorer than some of the other browsers.

In your "Address" bar for your browser, enter ftp:username:password@ftp.domain.com
where username is your user name at your site (not Drupal), password is the password for that
username, domain.com is your site’s domain name (without "www").

This will take you to your site. In Linux, you’ll probably have to click into the "public_html"
folder to get to your Drupal stuff. Then just navigate to the correct folders from there.

M. Setting Up Cron
I could not get a decent answer from the Drupal site on setting up the Cron jobs that it keeps
complaining about. Nor would my hosting support people help ("That’s a user problem...").

216
3 Aug 2007 Drupal Handbook

My hosting provider does not allow me to have Shell access (probably a wise move). But they do
provide the more-or-less-standard cPanel function. On my version, the "Cron" entry is in the
lower left.

I also had WebCalendar installed on one of my sites. When I went to cPanel, I noticed that
WebCalendar had a command already set up. Modifying it a bit, this is what I came up with to
put in:
cd ’/home/username/public_html/’ ; php -q ’cron.php’;

Note that username is my host’s user ID for domain management and my Drupal installation is
in my "root" folder (actually "public_html").

This worked for getting Cron run, but did generate some error messages.

I was happy that Cron ran, but a bit concerned about those messages. So I did some searching on
the Drupal site and came up with several posts of the same messages, but no solutions. So I
posted again. This time someone saw it through.

They suggested using WGET, but I don’t have shell access. But I did, for some reason, check the
"Advanced" mode on cPanel again. I noticed that there was now a helpful hint there (of course in
a small font). It said to use GET http://nanwich.info/cron.php (obviously, use your own
URL). I did and the error messages went away and Cron is working great!

For Cron jobs another possibility is http://drupal.org/project/poormanscron

For every page view, this module checks to see if the last Cron run was more than 1 hour
ago (this period is configurable). If so, the Cron hooks are executed, and Drupal is happy.
These Cron hooks fire after all HTML is returned to the browser, so the user who kicks off
the Cron jobs should not notice any delay.

N. Categories (Taxonomy)
You will see a lot of posts on the Drupal site about creating and using a Taxonomy (or
"vocabulary" and "terms"). Most of those posts will be over your head - many are still way over
my head.

While it is true that the more content you have the more obvious the need for a taxonomy
becomes, there is certainly no reason why a smaller website that has things to classify can’t use
it.

For example, I run a web site for a group that has members submit articles for a monthly
newsletter. They wanted a way to organize it so that they could go back and review it by date or
topic. So I created two vocabularies, one for the issue date and one for the topic. Now they can,
with one click, read all the book reports, movie reviews, or humorous articles. And, every month
when they submit new articles, they automatically show up in those lists.

217
Drupal Handbook 3 Aug 2007

Another use is to categorize collections of FAQs, which I do on another site. They had, at the
time I set it up, three hard-coded HTML pages with different types of FAQs; no one wanted to
touch them. I installed the FAQ module (which is great), and set up the three terms in a single
vocabulary. That allowed them to actually grow their FAQ library to now contain six categories,
and it is trivial for them to maintain it.

But to try to help you get a slightly better idea of how to use them, I’ll use a case study here.

The Recipe module is probably a good example. On one of my sites, in order to foster a bit more
"community" feel and encourage visits to my site, I decided to add a group cookbook (a real one,
not like this book). The recipe module does that.

It didn’t take me very long to realize that entering a bunch of recipes without any organization
would get messy pretty quick. Well, recipes fall into several categories: Appetizers, Entrées,
Desserts, etc. So let’s set up those things as a "vocabulary" with which we can organize the
recipes.

1. Go to Administer>>Content management>>Categories and click on the "Add
vocabulary" tab.
2. Enter the name, for example "Recipes." Then a "Description" like "Our community
cookbook."
3. Select the type of content this applies to. The Recipe module introduces a "recipe" type.
4. I selected a "single" hierarchy. Later on, if the number of contributions gets large, I can
always add sub-categories (like "Beef," "Poultry," and "Pork") and change to multiple level
hierarchy.
5. I then selected "Required" to force the users to choose a category for any recipe they enter.

That’s it for the "vocabulary," so click on the "Submit" button. You’ll go back to the Categories
list. You should see your new vocabulary listed.

Towards the right, you’ll see a link to "add terms." Click on it.

1. Since this is a single level hierarchy, the "Parent" should say "<root>."
2. In "Term name" enter your first term, such as "Appetizers."
3. Enter a "Description" such as "Things for before the meal."
4. Don’t worry about the rest yet, just click the "Submit" button.
5. Keep adding the rest of your terms ("Salads," "Soups," "Side dishes," etc.

Now when a user goes to Create content and selects "Recipe," they will be required to
choose one of these categories for it. And if they go to the "Cookbook" menu item they’ll see a
list of categories that they can browse.

That wasn’t as complicated as all those posts sound like, was it?

For another example, I run a web site for a group that has members submit articles for a monthly
newsletter. They wanted a way to organize it so that they could go back and review it by date or
topic. So I created two vocabularies, one for the issue date and one for the topic. Now they can,
with one click, read all the book reports, movie reviews, or humorous articles. And, every month

218
3 Aug 2007 Drupal Handbook

when they submit new articles, they automatically show up in those lists. [By the way this was
done with a custom content module that is easily adapted to other uses. It is available through
me.]

Another use is to categorize collections of FAQs, which I do on another site. They had, at the
time I set it up, three hard-coded HTML pages with different types of FAQs; no one wanted to
touch them. I installed the FAQ module (which is great), and set up the three terms in a single
vocabulary. That allowed them to actually grow their FAQ library to now contain six categories,
and it is trivial for them to maintain it.

Some newbies swear by these articles: Drupal and the New Paradigm and The Power of Drupal
Categories

O. Common Problems
There are some problems we all seem to "find;" this section documents a few of them.
[Remember to always search before posting on the forums.]

Tables messed up, images not showing, other "strange" problems with HTML - I think every
Drupal user finds this problem. Drupal defaults to filtered HTML; that is, only certain tags are
allowed. Further, that input format also breaks long lines of text. The fix is real easy: switch to
the "Full HTML" input format. I make that the default for administrators (like me). Note that you
may still want the URL Filter and Code Filter modules turned on for this input format; they are
not defaults.

Help, I turned on Site Maintenance, now I can’t login! - About 3 out of 4 Drupal users have
done this to themselves (including me). You can still log in with
http://www.example.com/?q=user. Note that "user" is exactly that - do not put your
username there.

I don’t want anonymous users to see "Create content." - "Create content" is actually a child
menu item of "Content" which is usually disabled. Go to your menus administration screen and
enable the "Content" parent above "Create Content." Then you will see a "Reset" link appear.
Click on that. Once again, "Content" will be disabled, but "Create content" will not be shown to
anyone who does not have the access permissions to do so (especially anonymous users).

Also read the handbook section Troubleshooting FAQ

P. Links and IMG
Yes, you can link between pages in Drupal. It’s the same as not having Drupal, except the name
may be weird if you’re not using the Path module (URL Aliasing).

219
Drupal Handbook 3 Aug 2007

The biggest mistake people make is not knowing that there needs to be a leading slash ("/").
Omitting this will probably cause a "404:Page not found" error and, depending on which
browser you’re using, additional problems, like being logged out.

My home page on this site is node #4, so a link to it would look like this: <a
href="/node/4"&gt;Home</a>, but with URL Aliasing turned on, I can also code it like this:
<a href="/home">Home</a>

The picture on the "Accessing Your Site" page is created with this tag: <img
src="/files/pictures/Docs/WDP.jpg" align="right" hspace=1>

Q. Additional Tips and Tricks
This section gives you some ideas for improving your site or making life easier for you.

Q1. Tracking Module Status
A "site" you might want to build on your PC is a "catch-all" site for monitoring module and
theme status with the Update Status module.

This module will check with the Drupal site and let you know if newer releases of your modules
are available.

Before you pooh-pooh this idea, let me suggest this additional tip: Many people eventually find
that they need (want) to patch, tweak, or otherwise modify modules or themes. If you create a
"catch-all" site, you can place unmodified code here so that you always have a "clean" copy to
fall back on. You can then copy it to the correct site before changing it. Now, not only do you
have the fall-back plan, but you get the added advantage of knowing if it needs to be updated.

Q2. Making Multiple Site Maintenance a Bit Easier
A lot of people don’t realize that there browser home page does not have to be out on the web
somewhere. It can be right on your computer.

220
3 Aug 2007 Drupal Handbook

Here’s part of my home page. As you can see, I have links for all my maintenance tasks (cPanel,
FTP, etc.) included, so I don’t have to keep looking them up.

I also included links to my test sites, so they are easy to get to as well.

Q3. Controlling User Log In
How do I disable "Create New Account?"
It’s in Administer » User management >> User settings. Click the radio button that
says: Only site administrators can create new user accounts.

How do I disable User Log In entirely, and how would I get in if I do?
First, you can go to Administer » Site building >> Blocks and change the "Region"
setting for the "User Login" block to <none>. Now your user login block will disappear.

In order for you to login, I offer two techniques:

Enter http://www.myexample.com/user (or, if you don’t use Clean URLs,
http://www.myexample.com/?q=user). Yes, it is the word "user" -- not your user ID.
Go to your Site information settings and stick a "login" link in the footer. <a
href="/user">login</a> I do this on several sites.

221
Drupal Handbook 3 Aug 2007

R. Keeping Your Local and Remote Sites Synchronized
The point of a test site is to have a place to experiment or develop new content without
impacting your users or giving away your latest gee-whiz before its time. But it is also important
to make sure that you always have a good working version of your live site on your test site.

Let’s ignore, for the moment, that in an "ideal" world you will have a staging site which is always
identical to the live site and nothing goes live without being staged.

There are two basic techniques for keeping your sites synchronized:

Manually making sure that the content of the two sites are the same.
Frequent uploads or downloads of database back ups.

The first technique is quite time consuming and it’s difficult to keep user comments on your test
site. It also relies on your memory to know what’s been changed, unless you update both sites at
the same time. If there are things that are dependent on other things (sorry for the technical
terminology), you have to be careful that you update them in the right order so that your
random visitor doesn’t break something.

The second technique allows for user comments to be downloaded to your test site. From there
they can be incorporated into the content and deleted, or left as is. You just have to be careful
that you don’t lose new, experimental, or incomplete content that hasn’t been put onto the
production site yet.

Which is better? I can’t answer that question for you. You need to weigh the risks and benefits
and decide that for yourself. Personally, at my age and with my memory, the second technique
is probably better for me, at the risk of losing something not yet uploaded. I also have the bad
habit of updating things on the live site and not bring the change back to my test site.

More to come

S. More Reading
Now that you’re a Drupal expert, there are some additional topics you might find useful:

Adding Hidden Site Design Notes - how to put design or maintenance notes on your site
that only admins can see.
Core modules - what the many core modules do.
Contributed modules - a starter list to get you to the right modules, if you need them.
Site recipes - collection of tricks and techniques.
Multi-site Installation
Site configuration challenge: corporate brochure - many ways to get to a "Corporate
Brochure" type site.
Best practices guidelines - a guide to doing the right things.
My favorite module or theme is outdated. What next? -- it happens!

222
3 Aug 2007 Drupal Handbook

PHP and Javascript snippets -- useful code to use as is or adapt to your own needs.
SQL snippets -- database stuff.
CSS Tips, Tricks, and Techniques
Theme developer’s guide
Special cases
How to write automated tests
The Road to Drupal Hell -- this should be required reading for anyone who wants to do
something not in the core Drupal.
Using Drupal in an Academic Environment

T. Glossary
Okay, "Glossary" may not be the best description for this section. I’m trying to explain terms in a
[over-]simplified way so that the beginning Drupaller can get her/his arms around Drupal.

You might also want to look at the handbook section on Basic Terminology.

A node is a container for stuff (sorry for the technical term). Some of that stuff is the content you
create. Drupal itself creates a few nodes for its own stuff.

A module is a way to extend the functionality of Drupal. It is usually a lot of programmed code
(usually in php) and, usually, a style sheet (CSS). For example, if you want to include meta tags
to describe your content, you would add on the "Nodewords" module (also known as "Meta
Tags").

A theme is a means of manipulating and describing how you want your content displayed to
your visitors. This includes elements such as your header, icons, block layout, etc. It also
includes programming and style sheets.

A server is (generally) a computer that provides services to the Internet. These services may be
things like running the database or managing the gathering and dissemination of information.

A browser is the "program" that you use to display content from the Internet. In reality, it is
usually a set of programs, not a single one; it is also a set of tables (e.g. settings) that are used to
control its display. Examples are Internet Explorer, Netscape, and Firefox. This operates on the
client, or user, side of the presentation.

HyperText Markup Language (HTML) is the standardized language of the web. It has its own
"vocabulary," consisting of tags, elements, and descriptors. A tag is the basic component and is
used to say, "The following content is to be displayed according to these rules." An example of a
tag is a level one heading (<H1>). Most tags can have additional information to tell the browser
more specifically how you want it to render the content. This specification is called an element.

223
Drupal Handbook 3 Aug 2007

Most elements require more information to make them work, this is the descriptor, which really
should be called "value." For example, if you want that heading centered, you would use the
"align" element and give it a descriptor (value) of "center." So , completely constructed it would
look like this: <H1 ALIGN="CENTER">.

A Taxonomy is a way of characterizing stuff. It can be used for grouping, selecting, and
protecting stuff. Many people who are new to Drupal think this is a very difficult subject
(admittedly, we can make it so), however, virtually all of us had an introduction to taxonomy in
school: classifying living creatures (i.e. the Linnaean taxonomy). In that taxonomy, we classified
living things according to kingdoms (plant or animal), phylum, class, and so on, down to genus
and species. In reality there is an additional classification below species; sub-species (animals) or
varietal (plants). [Oh, yeah, I vaguely remember that! That’s a taxonomy?]

In Drupal, the highest level of taxonomy description is the "vocabulary;" it is used for defining
the terms, or tags, that actually end up on your stuff to be used for the various purposes. In the
above example, think of "Living things" as the vocabulary. Each vocabulary has one or more
"terms" that are used to tag (i.e. define, or describe) your stuff. Terms may be hierarchical; that is
they may exist in levels. Genus and species would be hierarchical terms. The vocabulary is
assigned to input types (e.g. stories, recipes); terms are assigned to a given piece of content (e.g.
"Groundbreaking Research on Macadamia Nut Yields" or "My Fabulous Macadamia Brittle").
Notice that I said "terms" - plural - because an individual node may have more than one term
associated with it; for example, the "Research" news article may be assigned to "Nuts," "Trees,"
and "Harvesting." It could then be viewed through any of those terms (or keywords).

Breadcrumbs is a term borrowed from Hansel and Gretel, who left crumbs of bread along their
path so they could find their way back out of the forest. In current computer parlance, it refers to
the section, usually near the top of the page, that shows the path you followed to locate the
current page. For example, it might show Home > Macadamia Nuts > Current Events >
News Articles, meaning that you started at the home page, clicked on "Macadamia Nuts" in
the menu, then selected "Current Events" in the sub-menu, and finally selected, "News Articles."

A database is a container for containers. It is a collection of related "tables" that are generally
used for a single application (such as Drupal). A table is a collection of data used for a specific
purpose within that application, such as identifying users. Within a table, each individual
grouping of data is referred to as a row (or in traditional terms, a "record"). Each row is
identified by one or more keys that allow easy retrieving of the row. Each row is then broken
down into columns (often called fields, although this is more appropriate for forms on which the
data is displayed). A column holds a specific piece of information for the row, such as a user
name or country.

Now, just to complicate things a bit, some times we describe the collection of item-related table
rows with a collective term. One such term is "node." For example, information about a page on
your site may exist in several tables; yet we describe all of this as a "node."

224
3 Aug 2007 Drupal Handbook

Still confused? Let’s try to relate this to an example you’re probably familiar with. Let’s relate
this to your windows computer.

Your [hard] disk (or disc) is sort of like a database; it is a collection of your data. On that disk,
you have folders; they are analogous to tables within a database. Inside those folders, you have
documents or programs; these relate to rows. Within the document (e.g. a Word document), you
have paragraphs; these are much like columns.

Okay, let’s add to the analogy a little. Word or Lotus 1-2-3 would be your theme, as they
describe and manipulate the content before it is displayed to you. It’s a bit of a stretch for several
reasons, but you can then think of Windows itself as your browser, since it is responsible for the
final rendering of the content to you.

Does that help a little?

The Structured Query Language (SQL) is a standard specification for how database engines
locate data that you want. An example might be SELECT country FROM user_profile
WHERE username = "Nancy"; this would get the value from the column "country" in the
"user_profile" table using column "username" as the key.

225
Drupal Handbook 3 Aug 2007

Taking your site live
Once you’ve got your Drupal installation set up just the way you want it, there are a few final
considerations before you unleash it on the world.

Moving from a temporary location
It’s likely that you’ve put Drupal in a subfolder on your server, so it doesn’t interfere with your
existing website while you get it set up. So you have www.example.com showing your old site,
www.example.com/drupal showing drupal, and you want www.example.com to show off your
new site to the world. There are two ways you can go about this:

Moving Drupal
As of version 5, moving the Drupal base folder shouldn’t pose any problems. For older versions,
some settings may need to be changed so Drupal can find everything. See this forum thread for
more details.

Redirecting your server
Alternatively, you can leave Drupal where it is in a subfolder, and just have your webserver fool
everyone into thinking that folder is www.example.com.

With Apache, you need to add the following to the .htaccess in the root folder (or create an
.htaccess file if there isn’t one there):

RewriteEngine on
#
# stuff to let through (ignore)
#RewriteCond %{REQUEST_URI} "/folder1/" [OR]
#RewriteCond %{REQUEST_URI} "/folder2/"
RewriteRule (.*) drupal/$1 [L]

Use the RewriteCond rules to let through URLS without modification (for example, you might
have other subfolders you still want accessible). Replace ’drupal’ with the name of the folder
Drupal is in.

You also need to modify the settings.php file for your site. By default, this is at
sites/default/settings.php. Uncomment (or change) the line that sets $base_url, and set it to the
URL you want browsers to see as the base for your site:

$base_url = ’http://www.example.com’;

226
3 Aug 2007 Drupal Handbook

In other words, ensure that this does not include the drupal subdirectory. This changes the links
that Drupal generates so they point to the correct location.

Excluding paths from Drupal
It may be that your site is made up components other than Drupal, or that you have an archive
version of your old site you want to be browsable. Drupal in a root folder takes over all URLs;
Drupal in a subfolder fooled into thinking it’s root likewise.

Either way, the .htaccess file in the root folder needs to be changed to let through the paths to
files or folders you Drupal to ignore.

In the case where Drupal is in the root folder, here’s what you need to to:

1. In the your webserver root’s .htaccess file, find the section marked with the comment ’#
Various rewrite rules.’
2. Below ’RewriteEngine on’ but before any other rules, add lines in the following form:
RewriteRule /folder - [L] # a subfolder Drupal should ignore
RewriteRule /file.html - [L] # a file in root Drupal should ignore

This page is a work in progress. Please suggest other tasks it should cover.

227
Drupal Handbook 3 Aug 2007

Core modules
The pages below give help for the modules that come with Drupal. When you install Drupal,
these modules are automatically installed. To make use of a module, first make sure it’s enabled
at administer >> site building >> modules. (Some modules automatically are.) Then set the right
permissions for it at administer >> user management >> access control.

You can further extend the features of Drupal by using "contributed modules." A list of help
pages for contributed modules is available at the contributed modules page.

If you would like to add a module help page, follow the authoring guidelines. The site
maintainers can create and update pages for you.

Aggregator: publishing syndicated content
The news aggregator is a powerful on-site RSS news reader that can gather fresh content from
news sites and weblogs around the web and make it available from your site.

Users can view the latest news chronologically in the main news aggregator display or by
source.

You can add, edit, and delete feeds and choose how often to check each individual feed for
updated news. You can also tag individual feeds with categories, offering selective grouping of
some feeds into separate displays. Listings of the latest news for individual sources or
categorized sources can be enabled as blocks for display in the sidebar through the block
administration page.

The news aggregator requires cron to check for the latest news from the sites to which you have
subscribed. Drupal also provides a machine-readable OPML file of all of your subscribed feeds.

You can

administer your list of news feeds administer >> aggregator.
add a new feed administer >> aggregator >> add feed.
add a new category administer >> aggregator >> add category.
configure global settings for the news aggregator administer >> settings >> aggregator.
control access to the aggregator module through access permissions administer >> access
control >> permissions.
set permissions to access new feeds for user roles such as anonymous users at administer
>> access control >> permissions.
view the aggregator page.
run your cron job manually at your sites cron page.
read about configuring cron jobs.

228
3 Aug 2007 Drupal Handbook

Old page
Thousands of web sites, especially news sites and weblogs, syndicate their most recent site
content for others to display. The syndicated content always includes titles, also known as
headlines, for the newest published stories. Each headline acts as a direct link to the stories on
the remote site. Along with the headline, most sites typically provide either the first few
paragraphs of the story or a short summary. Many individuals use client-based news
aggregators on their personal computer to aggregate content, such as FeedDemon (for
Windows), NetNewsWire (for Macs) and AmphetaDesk (Windows, Mac and Linux).

Drupal also has a news aggregator built in as a standard feature. With it, you can subscribe to
feeds from other sites and display their content for your site users. Simply enable the aggregator
module in administer » modules, then click administer » aggregator and enter the feeds that
you choose.

Open aggregator links in new browser window
Many people would like to keep users on their site. In order to have users open links in a new
browser window instead of leaving your site you can modify two theme functions:
aggregator_page_item and aggregator_block_item.

An alternative approach would be to modify the output directly.

Here is a sample of code that could be used: $output .= "link\"
target=\"_blank\">$feed->link\n";

User Aggregator:user submitted feeds
http://drupal.org/node/30865

User Aggregator allows users to add a syndication feed to a site’s aggregator via their user
profile.

Features:
Site administrator can set
- visible and default categories that will be assigned to user entered feeds. Default categories do
not have to be visible
- default refresh interval for user entered feeds
- option to show on account setup
- allow users to select single or multiple categories
Users can select or unselect visible categories
User entered feeds go to a pending table for administrative review

229
Drupal Handbook 3 Aug 2007

What do I need to subscribe to a feed?
The standard method of syndication is using the XML-based RSS format. RSS stands for Really
Simple Syndication, RDF Site Summary, or Rich Site Summary, depending on whom you talk to.
To syndicate a site’s content, obtain the full URL of the RSS page providing syndication.
Common file tags for RSS pages are .rss, .xml and .rdf. Example:
http://slashdot.org/slashdot.rdf.

Most weblog sites that offer syndication will have an obvious link on the main page. Often you
need only look for a red XML button, such as the one Drupal uses for site syndication.

Some sites do not make their RSS feeds as easy to find. Or maybe you want to find a number of
feeds on a given topic, without extensively searching the web. In that case, try an RSS
syndication directory such as Syndic8.

To learn much more about RSS, here are some good introductions:

Mark Pilgrim’s What is RSS
WebReference.com’s The Evolution of RSS

NOTE: Enable your site’s XML syndication button by turning on the Syndicate block in
administer » blocks.

Configuring news feeds
To subscribe to an RSS feed on another site, click administer » aggregator.

Once there, select the add feed tab at the top of the aggregator administration page. Drupal will
then ask for the following:

Title -- The text entered here will be used in your news aggregator, within the
administration configuration section, and as title for the news feed block. As a general rule,
use the web site name from which the feed originates.
URL -- Here you’ll enter the fully-qualified URL for the feed for the site you want to
subscribe to.
Update interval -- The update interval is how often Drupal will automatically access the
RSS URL for the site for fresh content. The 1 hour default is typically a good minimum to
use. Accessing another site’s RSS page more frequently can be considered impolite because
it requires the other site’s server to handle your automatic requests. To take advantage of
this feature, note that cron.php must be configured to have your feeds updated regularly.
Otherwise, you’ll have to manually update feeds one at a time within the news aggregation
administration (administer » aggregator) section.

Once you submit your new feed, check to see if it is working properly. Select update items on the
main news aggregation page. If you do not see any items listed for that feed, edit the feed and
make sure that the URL was entered correctly.

230
3 Aug 2007 Drupal Handbook

Filter feeds by keyword, time, by summary
To filter by keyword: http://drupal.org/node/13047
Filtering by time and by summary to be added.

Creating categories in the aggregator
1. Go to administer » aggregator then click on the add category tab.
2. Add a title to the category, then a description.
3. If you wish to have a block of the last x items from that category, select the number of items
in "Latest items block". To place the block on your sidebar, go to administer » blocks and
look for the category you just created.

Now every time you add a feed, you can select a category which the items will automatically
appear under. Alternatively, you can tag individual items in your aggregator to appear in a
category.

Tagging individual items in the aggregator
1. To get to the categorization screen, in your sidebar navigation, click news aggregator
2. Here you have two options:
1. click categories, then the category you wish to look at, then the categorize tab.
2. click sources, then the feed source you with to look at, then the categorize tab.
3. You will be presented with a list of items to categorize, plus to the right, the categories
which you can assign to each item. If you have the multiple-select option enabled in the
aggregator configuration, you can select more than one category for an item by holding
down CTRL (PC) or CMD (Mac) and clicking on each category.

Using the news aggregator
The news aggregator has a number of ways that it displays your subscribed content:

Latest News -- Displays all incoming content in the order received
with

The title of the original post.
The name of the source, which acts as a link to an individual feed page, listing information
about that feed and incoming content for that feed only.
A description, the first few paragraphs or summary of the originating post (if any).
The list of categories that the feed (or feed item) belongs to, with a link to each category.

News by Source: Organizes incoming content by feed, displaying titles which link to the
originating post. Also has an icon which acts as blog it link.
News by Topic: Organizes incoming content by bundles, displaying titles which link to the
originating post. Also has an icon which acts as blog it link.

231
Drupal Handbook 3 Aug 2007

News Sources: Displays an alphabetical listing of all subscribed feeds and a description.
The title acts as a link to an individual feed page, listing information about that feed and
incoming content for that feed only.

RSS feed blocks
In addition to providing subscribed content through the news aggregator, Drupal automatically
can create a block for every feed as well as every category, though the administrator can choose
whether or not a feed or category gets its own blocks by configuring the individual feeds and
categories. Enable any or all of the blocks using block management by clicking administer »
blocks.

Block: controlling content in the sidebars
Blocks are the boxes of related/grouped data that are visible in the left and/or right sidebar(s) of
your web site. They can also be placed anywhere on your page using regions. These are usually
generated automatically by modules (e.g. recent forum topics), but administrators can also
create their own defined blocks.

The sidebar each block appears in depends on both which theme you are using (some are
left-only, some right, some both), and on the settings in block management.

The block management screen lets you specify the vertical sort-order of the blocks within a
sidebar. You do this by assigning a weight to each block. Lighter blocks (smaller weight) "float
up" towards the top of the sidebar. Heavier ones "sink down" towards the bottom of it.

The block management screen also provides checkboxes and a configure link for customizing the
visibility of individual blocks. A block’s visibility depends on:

The Enabled checkbox. Disabled blocks are never shown.
The Throttle checkbox. Throttled blocks are hidden during high server loads.
Page specific visibility settings. Individual blocks can be configured to only show/hide on
certain pages. You can also show/hide blocks based on the result of a PHP snippit.
Custom visibility settings. Individual blocks can be configured so that users decide whether to
show/hide certain blocks.
Its function. Dynamic blocks (such as those defined by modules) may be empty on certain
pages and will not be shown.

Module blocks
Module blocks are available when modules are enabled. These blocks can be administered in
block administration.

232
3 Aug 2007 Drupal Handbook

Administrator defined blocks
An administrator defined block contains content supplied by the administrator. Each
admin-defined block consists of a title, a description, and a body which can be as long as you
wish. The Drupal engine will render the content of the block.

Note: Blocks are configured per theme so if you use multiple themes on a site you will need to
enable and configure blocks for each theme.

You can

enable throttle and configure blocks at administer >> block.
add a block at administer >> block >> add block.

Blog: a blog for every user
The blog module allows registered users to maintain an online weblog (commonly known as a
blog), often referred to as an online journal or diary. Blogs are made up of individual posts that
are time stamped and are typically viewed by date as you would a diary. Blogs often contain
links to webpages users have read and/or agree/disagree with.

The blog module adds a user blogs navigation link to the main navigation menu (the link must be
enabled), which takes any visitor to a page that displays the most recent blog entries from all the
users on the site. The navigation menu has a create content link (which takes you to a page with a
link to a submission form) and a my blog link (which displays your blog entries as other people
will see them). The blog module also creates a recent blog posts block that can be enabled.

You can

read your blog via your user profile at my account.
post a blog at create content >> personal blog entry.
administer blog at administer >> settings >> content types >> blog entry.
administer blog api at administer >> settings >> blogapi.
enable the "recent blog posts" block at administer >> blocks to show the 10 most recent blog
posts.

HOWTO: Configure user blogs
To implement user blogs on your Drupal site, turn on the blog module and enable permissions:

1. Go to administer » modules and check the box in the status column to the right of blog.
2. Under administer » access control, check the edit own blog box for each role you wish to
maintain blogs.

233
Drupal Handbook 3 Aug 2007

Aftewards, once logged in, each user with the permission to maintain a blog will be able to click
create content » personal blog entry and will see my blog (which displays blog entries as other
people will see them) in the user navigation block. At the top of each individual blog post, the
original blog author will find an edit tab.

To add instructions for users on creating their blogs and set workflow options such as published,
promoted to the front page, etc.:

1. Select administer » content » configure » content type, then the "configure" link next to
"personal blog entry
2. Enter your instructions in the available text field.
3. Set workflow options.
4. Use the Minimum number of words in a blog entry setting to specify a minimum length for all
blog posts.

Most recent blog post block
Note that the block displaying "recent blog posts" cannot be easily customized to display fewer
than 10 items. You have to modify the source code, the number is hard wired. There is a forum
discussion on this limitation. See:
http://drupal.org/node/15635

Navigate throught categories inside a blog
It’s very useful knowing how to make the general taxonomy system fits with the needings of a
multiblog site. If in our web there are many blogs independent, but the share the same
vocabulary, there would be a problem when navigate using taxonomy links in a post.

There a interesting post titled "Blogs categories" very useful: http://drupal.org/node/20260 .

I’ll write here the code to make a term link go to a view with two arguments (the user id, and the
term id).

Soon.

What is a blog or weblog?
Drupal’s blog module allows all registered users to maintain a personal weblog on site. Blogs are
easily- and frequently-updated websites usually written in an informal and conversational style.
They are ordered reverse-chronologically (that is, the most recent entry is at the top) and have
archives of past entries. Each individual entry has a permanentâthat is to say, stableâURL
linking directly to that item. Blogs typically have comments for each entry so that readers can
participate in the discussion, and they usually have RSS feed to be syndicated elsewhere or read
in an desktop aggregator. Each entry usually contains one idea, with a link to the source of the
original item being discussed. Blogs can be (and are) written about any subject, from daily
personal life to technology to politics to knitting to sports to a company’s products.

234
3 Aug 2007 Drupal Handbook

From a more practical standpoint, blogs can be seen as a means of personal knowledge
publishing, a place for researchers or enthusiasts to build and share knowledge about their
interests. Or in project oriented sites, as a workspace for project members to post ideas for
commenting by others in a group.

For a more complete definition of blogging with links to resources and examples, see George
Siemens’ The Art of Blogging - Part 1 and The Art of Blogging - Part 2.

Making user blogs more accessible
Drupal provides a number of ways to make user blog posts accessible. You’ll need to decide
which ones work best for how your Drupal site is configured:

A link in the navigation bar: After activating the blog module, most Drupal themes will
include a Blogs link in the header navigation bar. The user blog listing contains the most
recent blog posts by all site users. If the site is using xtemplate, you’ll need to create the link
yourself. Go to site configuration » themes » xtemplate and add in the HTML to create the
URL (to find the URL, switch your site theme momentarily to Marvin and the link will be
present in the navigation header).
Making user blog listings the default home page: Click administer » settings and type in
the word "blog" (without quotes) for Default front page.
Promoting individual blog posts: If "node" is the Default front page setting, administrators
can elect to promote any user blog posts to the front page. Click onto the blog post you want
to promote, then the edit tab and then check Promoted to Front Page.
Promoting individual blog posts automatically: Click administer » content » configure »
content type, then the "configure" link next to "personal blog entry, and check the Promoted
front page box in the "Default options" group. (This will work if "node" is the Default front
page in administer » settings.
Links to recently-updated blogs on the sidebar: Drupal also makes available a Most recent
blogs block under administer » blocks.

Additional features
Blog it: Users with blogs will see a "blog it" link in the form of a linked image i.e. when
viewing posts in the news aggregator. Other news listings, such as RSS blocks, will have an
icon in place of the textual blog it link. When the blog it option is selected, the user will be
taken to the blog entry form, with the title, a link to the item, and a link to the source
already entered in the text input field, ready for the user to add explanation.
User Blog RSS syndication: each individual user blog has their own RSS feed, allowing
other sites to syndicate their content or allowing readers to read the individual blog in an
aggregator. To find the RSS feed for a user, view their personal blog (in their personal
information, which you can get to by clicking on their username, select view recent blog
entries). Then look for the XML icon at the bottom of their blog page.

235
Drupal Handbook 3 Aug 2007

BlogApi: post from blog tools
The blog API module enables a post to be posted to a site via external GUI applications. Many
users perfer to use external tools to improve their ability to read and post responses in a
customized way. The blog api provides users the freedom to use the blogging tools they want
but still have the blogging server of choice.

When this module is enabled and configured you can use a variety of programs to create and
publish posts from your desktop. Blog API module supports several XML-RPC based blogging
APIs such as the Blogger API, MetaWeblog API, and most of the Movable Type API.

For more information on using software with the BlogAPI, see the Creating New Content section
of the End User Guide.

This module also allows site administrators to configure which content types can be posted via
the external applications. So, for instance, users can post forum topics as well as blog posts.
Where supported, the external applications will display each content type as a separate "blog".

You can

view the XML-RPC page.
administer >> settings >> blogapi.

Book: structured document publishing
A book is a set of pages tied together in sequence, perhaps with chapters, sections, subsections,
and so on. You can use books for manuals, site resource guides, Frequently Asked Questions
(FAQs), or whatever you’d like.

Users who have permission can create a book and write, review, modify, or rearrange the pages.
Many users can work together on a book. You can allow or disallow collaboration, to whatever
extent you want.

At the bottom of book pages, Drupal automatically provides links for moving to the previous
page and the next, and a link labeled up that leads to the level above in the structure. A contents
page is also automatically created.

You can provide your users a menu that helps them find their way around inside your books.
You do this by enabling the book navigation block on the blocks page (administer >> blocks). (Users
will see the menu only when viewing the book.)

Apart from this, you can also add a books link to any of your menus. This link will take users to a
list of your books. You add the link by enabling the books menu item on the menus page
(administer >> menus). You’ll find this item there under "Navigation." You can also add this link
to any menu you want. (Click "add menu item," and when you fill in the "path" field on the
dialogue page just enter "book.")

236
3 Aug 2007 Drupal Handbook

The "books" link takes users to your books. The "book navigation" block helps users move around
inside your books.

You can also let users generate a printer-friendly display of a book page and all its subsections.
They do this by selecting the link for printer-friendly version at the bottom of any book page.

On the books administration page (administer >> content >> books), administrators can view a
list of all the books on your site. For each book there’s a link to an outline, from which to edit or
delete pages or sections, change their titles, or change their weight (thus putting them in a
different order).

When you edit a page or section, you can also move it to a different level in the hierarchy by
changing the "parent" to which it belongs. So you can move things around however you like.
You can also check for orphan pages (pages that have become disconnected from the rest of the
book).

On the access control page (administer >> access control) you can assign to users with various
roles the permission to create book pages, to create new books, and to edit their own book pages
or the pages of others.

When users you allow create a post of the type Book page, Drupal automatically prompts them to
add their page at the level of their choice in a book, or to start a new book (by defining its
"parent" as "top-level").

You can also give permission to outline posts in books. Users with this permission can take any
other type of existing content on your site and add it to a book. When viewing a post they’ll see
an outline tab, and by clicking it they’ll come to an interface that lets them move the post into a
book.

You can:

create new book pages: create content >> book page.
administer individual books (choose a book from list): administer >> content >> books.
set workflow and other global book settings at administer >> settings >> content types >>
book page.
enable the book navigation block: administer >> block.
control who can create, edit, and maintain book pages at administer >> access control.

Customising the book navigation menu
By default, the navigation menu block for a book appears only on pages that are part of the book
hierarchy- that is, the top-level book page (www.example.com/books/book-name) and its child
pages (www.example.com/books/book-name/child-page). This is because the code in the block
is not an actual menu- it just simulates a menu, and so will never appear on the menu page at
..admin/menu.

237
Drupal Handbook 3 Aug 2007

This means that you can’t make the book navigation block appear permanently on the front page
(if you are using the book module to create a static hierarchical structure for example), or in any
other place on the site except the book pages.

This seems like a major limitation, but fortunately a snippet is available that will create a book
navigation menu that can be placed anywhere on your site and not just when navigating a book.

Maintaining a FAQ using a collaborative book
Collaborative books let you easily set up a Frequently Asked Questions (FAQ) section on your
web site. The main benefit is that you don’t have to write all the questions/answers by yourself -
let the community do it for you!

In order to set up the FAQ, you have to create a new book which will hold all your content. To
do so,

1. Click on the create content » book page link.
2. Give it a thoughtful title. A title like "Estonia Travel - FAQ" is nice.
3. Set the Parent to <top-level> to make this page the beginning of a new book
4. Add in the text of the book page into the Body textarea.
5. Leave the log message blank for now.
6. Use the weight field to position this book in the list on the book module page.

After you have submitted this book page, you are ready to begin filling up your book with
questions that are frequently asked.

Creating new pages for your FAQ. The process for creating new pages in your FAQ is very similar
to above. When choosing the Parent option, select the FAQ book page that you already created to
add it to the book.

Adding existing non-book pages to your FAQ. Whenever you come across a post which you want to
include in your FAQ,

1. Click on the outline tab at the top of the page.
2. Place the relevant post wherever is most appropriate in your book by selecting a Parent.

Notes:

Books are quite flexible. They can have sections like Flying to Estonia, Eating in Estonia and
so on. As you get more experienced with the book module, you can reorganize posts in your
book so that it stays organized.
Any comments attached to those relevant posts which you designate as book pages will also
be transported into your book. This is a great feature, since much wisdom is shared via
comments. Remember that all future comments and edits will automatically be reflected in
your book.
You may wish to edit the title of posts when adding them to your FAQ. Clear titles improve
navigability enormously.

238
3 Aug 2007 Drupal Handbook

Book pages may come from any content type (blog, story, page, etc.). If you are creating a
post solely for inclusion in your book, then use the create content » book page link.
If you don’t see the edit link or outline tab , then you probably have insufficient permissions.

Categories (taxonomy): A way to organize your
content
The categories module lets you classify content into categories and subcategories, thus
organizing the content on your site. For example, you could classify music by genre: classical,
jazz, rock. And you might further classify "classical" into concertos, sonatas, symphonies, and so
on. When your users create new content, you can let them classify it (or even require them to do
so) right when they create it.

When users view a post to which a category has been assigned, along with the post your theme
will generally show the name of the category (or categories) to which the post belongs. Each
category’s name appears as a link. And clicking on that link will bring users to a page showing
the other posts of the same category.

You can enable the categories module on the modules page (administer >> site building >>
modules).

The categories module is also sometimes called the taxonomy module. Taxonomy means
"division into ordered groups or categories." Taxonomy also refers to the science or principles of
classification. In the language of taxonomy, groups of categories are called "vocabularies," and
the categories themselves are called "terms."

With the categories module you can define groups ("vocabularies") of categories ("terms") by
which to classify content.

Each vocabulary consists of a set of terms.
You can have as many vocabularies as you want and for each create as many terms as you
want.
You can order your terms into hierarchies.
You can also have "free vocabularies," in which users creating new content don’t have to
classify it with terms from a "controlled vocabuary," one you’ve defined. Instead they can
freely define their own terms, or "tags." (This is sometimes called "free tagging.")
When you create a term, you can also tie it to related terms. (Think of "See also" in a
dictionary.)

You can allow users to classify each piece of content they create--each story, blog item, or
whatever--using one term or many.

For simple implementations, you might create a set of categories without subcategories (like
Slashdot’s "sections"). For more complex implementations, you might use subcategories too,
thus organizing things into a hierarchy.

239
Drupal Handbook 3 Aug 2007

To further organize your site, you can have groups of categories intersect. For example,
intersecting your musical genres you might have a set of categories indicating times: seventeenth
century, eighteenth century (perhaps with subcategories like "early eighteenth century" and "late
eighteenth century"). So, using our "genre" vocabulary we might call an item by the term
"sonata," and using our "times" vocabulary we might call it by the term "early eighteenth
century." If we add a vocabulary for "composers," we might categorize the item three ways--as
an "early-eighteenth-century" "sonata" by "Bach"--and locate it by any of these three terms.

Working with vocabularies

On the categories page (administer >> content management >> categories) you can create, view and
manage your categories. You’ll see a list of the vocabularies you’ve created, and you can edit
each one.

You can add new vocabularies, using the add vocabulary tab at the top of the page. Or you can
edit an existing vocabulary by clicking the edit vocabulary link next to its name (in the
"Operations" column).

You choose a name for your vocabulary.
You can give each one a description, which modules may use in different ways. (For
example, when users hover over a link that displays this vocabulary, they may see your
description.)
You can tie your vocabulary to particular "content types"--"story," "book page," or whatever.
Then when users create content of a particular type, they’ll see a list of your vocabulary
terms that go with it. Users can then categorize their post by choosing from the list. (You
can also give your vocabulary a help text to help your users choose.)
You can make choices about the hierarchies for your vocabularies. If you want all the terms
to be on only one level, choose "disabled." To allow your terms to have one (but only one)
level of terms below them, choose "single." And if you want to allow still further levels,
choose "multiple."
You can allow "related terms."
If you allow "free tagging," when your users create content they can make up their own
terms as they go along, instead of having to choose from a list.
By choosing "multiple select," you can allow your users to put a post into more than one
category at once by tagging it with more than one vocabulary term.
Also, if you like, you can require that when your users create content of a certain "content
type" they assign at least one of this vocabulary’s terms.
You can decide the order in which your vocabulary will appear in lists by assigning to it a
"weight."
Finally, if you like you can delete the vocabulary altogether, thereby also deleting all its
terms.

Working with terms

To view or manage the terms of each vocabulary, click on its list terms link. On the list terms page
you can edit each term by clicking the edit link. Now, on the edit term page you have several
kinds of choices.

240
3 Aug 2007 Drupal Handbook

If you’ve allowed this vocabulary to have a hierarchy, you can put the term in its place in
the hierarchy by choosing the term’s "parent."
You can select from this vocabulary one or more terms with which you’d like your term to
be related. (You can select multiple terms by using the standard conventions of your
operating system, like shift-click and control-click.)
You assign your term a name. (You have to do it. There’s no such thing as a "nameless
term.")
You can list synonyms for your term. (In taxonomy lingo, you’re creating for your
vocabulary a "thesaurus.")
You can decide the order in which your term will appear in lists by assigning it a "weight."
Or, finally, if you like you can delete a term altogether.

To add new terms to your vocabulary, click its add terms link. (The list terms page also has an add
terms link that does the same thing.) When you add new terms you have the same options as
when you edit them.

Using categories in menus

The menus on your site can call for items that match specific taxonomy terms--that is, terms
you’ve named your categories. Here’s how.

When you create a new term, Drupal assigns it a number. And you can call up all the items
categorized under that term by calling for its number.
To see your term’s number, go to the categories page, choose list terms for the category to
which your term belongs, and now hover over your term’s name in the list. You’ll see the
number.
Now, on the menus page (administer >> site building >> menus) you can create a menu item
for your term. Select add item, and when you fill in the path field you add your category like
this:

taxonomy/term/1

If your category "sonatas" is term 1, this would call for all the nodes of that category.

If your category "Bach" is term 2, you could call for only those sonatas written by Bach:

taxonomy/term/1,2

Or if Brahms is term 3 and you want to call for everything that has to do with either Bach or
Brahms, you’d do it this way:

taxonomy/term/2+3

Several contributed modules make powerful use of the categories (taxonomy) module,
exploiting and extending what it can do.

241
Drupal Handbook 3 Aug 2007

You can

enable the categories module at administer >> site building >> modules.
administer categories at administer >> content management >> categories.
decide who else can administer categories at administer >> user management >> access
control.
add a vocabulary at administer >> content management >> categories >> add vocabulary.

Modules that do more with categories
Categorization is useful for three main purposes on a website.

Manage categories: Challenges include user’s ability to suggest new categories, sharing
common categories across sites, and re-organizing categories.
Taxonomy_otf
Taxonomy_xml
Organizing content by category: Challenges include understanding hierarchies, getting
users to apply categories, automatic default categorization by node type or other, automatic
defaults, pulling or subscribing to content that is automatically categorized.
Action_feed
Taxonomy_defaults
Taxonomy_image
Taxonomy_multi_edit
Taxonomy_redirect
Taxonomy_similar-not stable
Taxonomy_theme
Inserting Taxonomy Images into nodes
Seperating free tagging from categories
Use categories for navigation: Challenges include menus, blocks, layouts, lists of titles and
teasers.
Taxonomy_association
Taxonomy_block
Taxonomy_browser
Taxonomy_context
Taxonomy_dhtml
Taxonomy_hide
Taxonomy_html
Taxonomy_links
Taxonomy_menu
Taxonomy_ticker
Related_nodes

242
3 Aug 2007 Drupal Handbook

Action_feed-you to receive and classify incoming e-mails from many organizations
taxonomy_assoc The taxonomy_assoc module lets you display a node - along with the usual
node listing for that term - when you view a taxonomy term. The node can be used instead of (or
as well as) the description that taxonomy_context outputs. Unlike raw descriptions, however,
nodes can be commented on, can have filters applied to them, and can be used in a number of
other ways.
taxonomy_block This is a simple module to create blocks based on taxonomy. It displays listings
of recently posted nodes based on taxonomy definitions. You can create as many blocks as you
like.
taxonomy_browser Think of this as a ’build your own category view’ page. Users select the
terms they want to see, and are redirected to the right URL (e.g. taxonomy/term/3,4,5), which
displays the matching content.
taxonomy_context The taxonomy_context module enables you to display several useful types of
information drawn from taxonomy terms. By default in Drupal, when you bring up a taxonomy
term you get a list of "node" (stories, static pages, books, etc.) associated with that term--but
nothing to describe the term itself. But for organizational websites one often wants to display
information like a title and description of the current section. So this module includes several
methods for displaying information about taxonomy terms:
* breadcrumbs
* the current term
* listings of sub-terms of the current term
taxonomy_defaults This module provides the ability to set default taxonomy terms per node
type.
taxonomy_dhtml A page listing recent nodes on your site, organized by taxonomy term. Also
provides a block for each vocabulary, listing terms and their node counts. Finally, a box is
exported to the syndication.module main page.
taxonomy_hide This module enables to setup list of vacabularies which terms will not be listed
in reference term list during node view. It enables also grouping terms by vocabulary as well.

taxonomy_html This module adds an HTML representations of site’s taxonomy. This is useful
for enabling users to browse your site according to topics of their own interest ... Specifically,
this module an Overview page listing all terms and vocabularies. Node counts for each term are
also shown beside each term link or in a help tip (aka title attribute).
taxonomy_image The taxonomy_image module allows site administrators to associate images
with taxonomy terms. With the association created, an admin can then make a call to
’taxonomy_image_display()’ from their theme or other PHP code
to display the appropriate image.

The module allows the admin to create a one-to-one term-to-image relationship. With image
display recursion, it is also possible to create a many-to-one relationship. This is useful if
creating taxonomy hierarchies in which an entire tree of terms will use the same image. With
recursion enabled, you only need to associate an image with the tree parent, and all children will
automatically inherit the same image.

taxonomy_menu The taxonomy menu module adds links to the navigation menu for taxonomy
terms. This is useful when the community is focused on creating content that is organized in a
taxonomy. The taxonomy menu administration interface allows taxonomy terms to be enabled

243
Drupal Handbook 3 Aug 2007

to show in the navigation menu. You can also select whether a term’s descendents subterms are
displayed.
taxonomy_multi_edit A mass category editor. quickly manage the taxonomy terms associated
with your nodes.
taxonomy_otf This module provides a mechanism for adding taxonomy terms on-the-fly. Users
who are granted permission can specify new categories while creating or editing their post.
taxonomy_redirect This module allows the administrator to change the destination of Taxonomy
Term links. Ordinarily these links go to taxonomy/term/TERMID but that is not
always desirable. Using this module, you could redirect these links to custom content, or content
generated by the Views module.

Due to the way the taxonomy module handles these redirects, they are available only on a
by-vocabulary basis; you cannot redirect them for individual terms.
taxonomy_similar taxonomy_similar will display a "similar tags" screen anytime content has
been created or updated with tags from a "Free tagging" vocabulary.
taxonomy_theme The taxonomy_theme module allows you to change the theme on a given node
based on the value of a taxonomy term for that node.
taxonomy_ticker Provides a block displaying titles of nodes in a scrolling news ticker.
taxonomy_xml This module makes it possible to import and export vocabularies and taxonomy
terms via XML. It requires taxonomy.module.
Taxonomy_links It looks up the taxonomies associated with the node, and then picks up all the
link entries associated with nodes belonging to those taxonomies.
Inserting Taxonomy Images into nodes These snippets allow you to insert Taxonomy images
into your nodes, when using the taxonomy_image.module.
Separate ’free tagging’ terms from normal taxonomy termsseparates Free tagging terms from
normal ones for separate theming.
Related_nodesuses taxonomy terms to find lists of nodes similar to the currently displayed one.

Content Management System comparison focused on
Taxonomy
This paper that compares Drupal with other CMS and why the taxonomy module sets it apart.

Taxonomy - some guidelines for effective design of
taxonomies
(I wrote this as a comment and was told to make it a page, so I have).

In most small sites taxonomy is obvious, but in larger sites, especially those where the expertise
of the readership may not be that of the authors, taxonomy design can make the difference
between a site being good or bad.

VIEWS Module - with it’s powerful taxonomy based Filters - makes taxonomy design even more
important than before.

244
3 Aug 2007 Drupal Handbook

General Rules

1) Unless a Vocab is well known to all anticipated users, and alphabetical (e.g. Countries of the
World), try and keep them below 30-40 Terms.

2) If your Vocab has Parent-Child structures, think about dividing it up because it’s likely to be
going to get too big, and is probably badly designed.

Example (sort from an online arts shop) - Traditional Arts Single Select

Europe
-Lapp
-Sami
-Celtic
Australia
-Aboriginal

This represented the way the shop classified their items.

But as such it prevents some clients saying "show me European Art".

Multiple Select is an option but much better to have two Vocabs - one for Region and one for
Culture, make them both multi and a collector could say "What have you got which is Lapp, or
Celtic or Chinese?"

3) Too Many Terms

"Perfect" taxonomies are always too complex and you need to fight to make them more
manageable. (Esp if you have just cut up a few Parent Child vocabs into several smaller ones
each...)

The advantage of VIEWS is that the multiple taxonomy terms start to build context, and that can
be captured by views.

There are not many sites that ever need to show more than 3-4 filters to users, even if there are
5-6 more hidden ones .

Plus building them into structure adds even more granularity.

Eg a site for ALL the small towns of America, where people are interested in their little towns
stuff, using Book for basic structure:-

Top level - States - 50 items
Off each State - Counties
Off each County - settlements

Click the named settlement and a get a VIEWS screen with filters for News, Culture,
Announcements.

245
Drupal Handbook 3 Aug 2007

(Hidden filters in the Views filter by State/County/Settlement)

Highly non scary - any users can use that to get what they need.

4) Clients are not experts on taxonomy, not even their own

Taxonomy is a communications issue and if there is a budget for the site it’s always worth
running it past an outsider - but note that they will need to get to understand the purpose of the
site and also to an extent the jargon of the subject.

This normally requires a least one decent face to face meeting to force the client to decide what is
important, and what can be cut out. (Trust me, these decisions will have to be made, and if they
are not, then people are probably not thinking carefully enough.)

5) Taxonomy creates Legacy issues - SO GET IT RIGHT

Once you have a load of tagged data, it’s hard to make changes to taxonomy structures (apart
from adding terms) without rendering existing nodes much harder to find. Trust me, NO ONE
will go back and edit existing data, not in real life, unless there is massive funding for that
purpose.

6) Taxonomy is trial and error.

It should be the first thing you do on a site, but by adding test data you’ll find flaws, and refine
and eventually go live with something that works. In between times you solved the CSS and
templating...

I once spent 3 days testing different ways to classify cars for one site - the makes/models
complexity of past 20 years is a nightmare, and which there are several ways ot do it, all of
which work, some are more userfriendly than others!

Hope this helps.

Ian Dickson - community specialist with a sideline in taxonomy because its the buidling block
for EFFECTIVE social software... .

Taxonomy Garden: Managing Categories
Manage categories: Challenges include user’s ability to suggest new categories, sharing common
categories across sites, and re-organizing categories.

Taxonomy_otf
Taxonomy_xml

Taxonomy On The Fly

246
3 Aug 2007 Drupal Handbook

This module provides a mechanism for adding taxonomy terms on-the-fly. Users who are
granted permission can specify new categories while creating or editing their post.

Taxonomy XML

This module makes it possible to import and export vocabularies and taxonomy terms via XML.

Taxonomy Garden: Navigation by category
Challenges include menu’s, blocks, layouts, lists of titles and teasers.

Taxonomy_association
Taxonomy_block
Taxonomy_browser
Taxonomy_context
Taxonomy_dhtml
Taxonomy_hide
Taxonomy_html
Taxonomy_links
Taxonomy_menu
Taxonomy_ticker
Related_nodes

247
Drupal Handbook 3 Aug 2007

Taxonomy Association

The taxonomy_assoc module lets you display a node - along with the usual node listing for that
term - when you view a taxonomy term.

The node can be used instead of (or as well as) the description that taxonomy_context outputs.
Unlike raw descriptions, however, nodes can be commented on, can have filters applied to them,
and can be used in a number of other ways. Taxonomy association allows you to assign terms to
nodes as seen in the picture below.

248
3 Aug 2007 Drupal Handbook

Taxonomy block

This is a simple module to create blocks based on taxonomy. It displays listings of recently
posted nodes based on taxonomy definitions. You can create as many blocks as you like.

249
Drupal Handbook 3 Aug 2007

Taxonomy browser

Think of this as a ’build your own category view’ page. Users select the terms they want to see,
and are redirected to the right URL (e.g. taxonomy/term/3,4,5), which displays the matching
content.

250
3 Aug 2007 Drupal Handbook

Taxonomy context

The taxonomy_context module enables you to display several useful types of information drawn
from taxonomy terms. By default in Drupal, when you bring up a taxonomy term you get a list
of "node" (stories, static pages, books, etc.) associated with that term--but nothing to describe the
term itself. But for organizational websites one often wants to display information like a title and
description of the current section. So this module includes several methods for displaying
information about taxonomy terms:

breadcrumbs
the current term
listings of sub-terms of the current term

251
Drupal Handbook 3 Aug 2007

Taxonomy dhtml

A page listing recent nodes on your site, organized by taxonomy term. Also provides a block for
each vocabulary, listing terms and their node counts. Finally, a box is exported to the
syndication.module main page.

252
3 Aug 2007 Drupal Handbook

Taxonomy hide
This module enables to setup list of vacabularies which terms will not be listed in reference term
list during node view. It enables also grouping terms by vocabulary as well.

Taxonomy menu

The taxonomy menu module adds links to the navigation menu for taxonomy terms. This is
useful when the community is focused on creating content that is organized in a taxonomy. The
taxonomy menu administration interface allows taxonomy terms to be enabled to show in the
navigation menu. You can also select whether a term’s descendents subterms are displayed.

253
Drupal Handbook 3 Aug 2007

Taxonomy ticker

Provides a block displaying titles of nodes in a scrolling news ticker.

Taxonomy Garden: Organize content by category
Challenges include understanding hierarchies, getting users to apply categories, automatic
default categorization by node type or other, automatic defaults, pulling or subscribing to
content that is automatically categorized.

Action_feed
Taxonomy_defaults
Taxonomy_image
Taxonomy_multi_edit
Taxonomy_redirect
Taxonomy_similar-not stable

254
3 Aug 2007 Drupal Handbook

Taxonomy_theme
Inserting Taxonomy Images into nodes
Seperating free tagging from categories

Taxonomy multi-edit

Edit the taxonomy designations of multiple nodes at once, without having to select each node
individually. Simplifies changing a large number of nodes from one taxonomy classification. In
admin/categories, a tab is added to "assign categories." Every node with at least one taxonomy
designation is displayed in a table, with the first column being and the remaining columns being
the available categories.

255
Drupal Handbook 3 Aug 2007

Taxonomy_image

Attach an image to each node in specified taxonomies based on terms. Child terms can have
parent images if no images are designed for child terms.

In admin/settings/taxonomy_image, admins can set the basic settings for the module. In
admin/categories an additional tab is added to allow users to upload one image per taxonomy
term. After inserting appropriate function calls to display_taxonomy_image() in the theme,
images will be displayed with nodes.

256
3 Aug 2007 Drupal Handbook

Taxonomy_theme

In one taxonomy, each term can be mapped to a theme that will display when the node is
display on its own. In an admin/settings submenu, the module can be enabled or disabled. One
taxonomy can be selected. Each term can be mapped to a theme. If it is not mapped, it gets the
site default theme.

257
Drupal Handbook 3 Aug 2007

Views

The views module is a query building module that can display a listing or table of results. Views
can include filters to limit results by a variety of criteria. This module does not specifically
organize nodes, but allows retrieval of pre-categorized nodes.

In admin/views, users can create a view entering appropriate values into a form. The form has
the following subsections: display, block, table, URL, arguments, filters, and sorting. If a URL is
specified, a menu item can be added for later retrieval. The view can be stored for later use, or
use by other modules. Views can be displayed directly as well.

258
3 Aug 2007 Drupal Handbook

Taxonomy_default

This module automatically tags posts for which the taxonomy is not activated (in the categories
admin section). For posts where the taxonomy is active, the tags are simply preselected.

In admin/settings/taxonomy_defaults, a section is created for each content type. Each content
type can set preselected tags in any vocabulary. For enabled vocabularies, the word "active" is
not italicized. For non-enabled vocabularies, the word active is italicized. When entering a node,
in-active vocabularies are not shown, but the term(s) are automatically added to nodes. For
active vocabularies, the terms are pre-selected. In either case, the terms are visible when the
node is rendered.

259
Drupal Handbook 3 Aug 2007

The taxonomy module for Drupal 4.x
The taxonomy module is one of the most popular features because users often want to create
categories to organize content by type. Users also use categories to help in site navigation. The
taxonomy module can automatically classify new content, which is very useful for organizing
content on-the-fly. A simple example would be organizing a list of music reviews by musical
genre.

Taxonomy is also the study of classification. The taxonomy module allows you to define
vocabularies (sets of categories) which are used to classify content. The module supports
hierarchical classification and association between terms, allowing for truly flexible information
retrieval and classification. The taxonomy module allows multiple lists of categories for
classification (controlled vocabularies) and offers the possibility of creating thesauri (controlled
vocabularies that indicate the relationship of terms) and taxonomies (controlled vocabularies
where relationships are indicated hierarchically). To delete a term choose edit term. To delete a
vocabulary, and all its terms, choose edit vocabulary.

260
3 Aug 2007 Drupal Handbook

A controlled vocabulary is a set of terms to use for describing content (known as descriptors in
indexing lingo). Drupal allows you to tag each piece of content (blog, story, etc.) using one or
many of these terms. For simple implementations, you might create a set of categories without
subcategories, similar to Slashdot’s sections. For more complex implementations, you might
create a hierarchical list of categories.

Sites can also use folksonomies. By checking the "Free tagging" option when creating a
vocabularly, users can create and enter their own tags for their content.

You can

add a vocabulary at administer >> categories >> add vocabulary.
administer categories at administer >> categories.

Understanding categories for new users
Drupal’s Category, also known as ’Taxonomy’, system can sound daunting, but it doesn’t have
to be. When all the fancy language is stripped away, Taxonomy is about one thing: organizing
your site by attaching descriptive terms to each piece of content.

Those terms might describe what section of your site a particular page belongs to. They might
describe what topics are discussed in a given blog post, or what region of the country a
photograph was taken in. These terms are organized in separate ’Vocabularies’ so that recipe
ingredients don’t get mixed up with cities in Texas when you’re trying to find out what
travel-logs were written in Houston, or what soups use potatos.

Setting up these Vocabularies, and the descriptive terms that belong to them, is the first step in
organizing your Drupal site. There are different kinds of vocabularies, and understanding how
they differ can help you decide the best way to categorize your content.

1. Lists of pre-defined terms -- a ’flat’ vocabulary
2. Hierarchies of pre-defined terms -- a ’tree’ vocabulary
3. Buckets full of terms -- a ’free-tagging’ vocabulary

For example, let’s say you’re setting up a photo portfolio, and using Taxonomy to keep things
organized. First, you might create a ’flat’ vocabulary for basic organization called ’Photo Type.’
To that vocabulary, you would add the terms ’Portrait,’ ’Stop-Action,’ ’Landscape,’ and so on.
Next, to keep track of where the photographs were taken, you might create a hierarchial
vocabulary called ’Location.’ To it, you could add terms like ’Europe’ and ’United States.’ In a
hierarchial vocabulary, each of those terms can also have sub-terms like ’France’ and ’Illinois.’
This makes it possible to tag a photo once with the term ’London’ and retrieve it later with a
broader request like ’Show me all the photos taken in Great Britain.’ Finally, to capture notes
about each photograph that would be hard to plan in advance, you could add a ’free tagging’
vocabulary called ’Keywords.’ Rather than defining the terms in advance, a free tagging
vocabulary lets you enter in new terms each time you post a piece of content. If two pieces of
content share a term, they’yer automatically connected to each other.

261
Drupal Handbook 3 Aug 2007

With those three vocabularies in place, any new photograph you post to your site can be quickly
categorized. Whenever you post a new image, Drupal offers you a list of the available terms in
the ’Photo Type’ and ’Location vocabularies AND a place to type in terms for your ’Keywords’
vocabulary. When posting a photo of your brother’s wedding, you might select a Photo Type of
’Portrait,’ a Location of ’Paris’ (if that’s where he was married, naturally!) and type in ’wedding’
and ’brother’ as keywords.

If you’re used to other CMS or blogging systems, these different vocabulary types might be
familiar as ’categories’ or ’sections’ or ’keywords.’ It’s important to note that nothing requires
you to use these different Drupal vocabularies, and different kinds of content can use different
vocabularies when it makes sense. News articles and Images might share ’Keywords’, but ’Photo
Type’ obviously only makes sense for one.

Mixing and matching these techniques in Drupal allows you to create the organizational system
that best suits your needs. Getting used to it can be tricky at first, but if you take the time to
think through your site’s organization, the results are worth it.

Using taxonomy to organize content
http://drupal.org/node/73694

-->

http://digitalsolutions.ph/couchkamotereviews/power_drupal_categories

-->
http://drupal.org/node/118525 -->

Drupal Taxonomy: the power to organize and reorganize

Adapted from benc’s
http://digitalsolutions.ph/couchkamotereviews/power_drupal_categories

The Drupal Taxonomy module (and the contributed module Categories) is one of its most
powerful features. Combined with its hooks, Drupal allows administrators to organize and
reorganize content easily, giving more flexibility for knowledge sharing in an organization that
continuously discovers better ways to share knowledge.

This tutorial has two purposes:

In particular: To show content managers and web developers how web content can be
organized and reorganized by using Drupal’s taxonomy module.
In general: To show the power of Drupal for rapid organization and reorganization and
dynamic taxonomy management; these are qualities that make Drupal a good tool to
facilitate knowledge sharing.

262
3 Aug 2007 Drupal Handbook

System requirements: You need an installation of Drupal 4.7 with admin permissions.

Basic terminology:

Taxonomy: The name of Drupal’s core (included) module for classification.
Category: The label used in the Administer area for configuring taxonomy. Also, the name
of a contributed (add-on) module for classification.
Vocabulary: A group of taxonomy terms.
Term: A label (of a taxonomy vocabulary) that can be applied to an item.
Labels, Tags: other words that are sometimes loosely applied to mean the same thing as
"Term."

Scenario: Starting a news web site

You have been asked to create a web site for a news company. They want to organize web
content according to the topic of the story. The topics are Politics, Technology, Business, and
Lifestyle. Stories may be about just one topic, or they may be about more than one. For instance,
a story may be about both technology and business.

Step 1: Plan your content structure.

How will you organize content in the web site? In our scenario, our client wants to categorize
stories as Politics, Technology, Business, and Lifestyle.

Step 2: Create a vocabulary.

After logging in to Drupal, go to (administer > categories) and click the "add vocabulary" tab. In
the add vocabulary screen, type "Topic" as the Vocabulary name.

Next, you need to tell Drupal that the vocabulary "Topic" will be used by the Story content type.
To do this, check the story checkbox under Type. This step is called binding a vocabulary to a
content type.

Next, click the checkbox called Multiple select. This allows selecting more than one taxonomy
term for each story.

At this point, you will see many other options. Ignore them for now and play around with them
later.

Step 3: Add terms under your vocabulary.

We now need to tell Drupal what labels are available under the Topic vocabulary. To the right of
the categories screen, click add terms. In the screen that follows, type a Term name (e.g.: Politics)
and click submit. Repeat this for each of the terms under Topic.

You can now review your vocabulary. To the right of your Topic, click list terms. You will see
something like this:

263
Drupal Handbook 3 Aug 2007

Topic
--Business
--Lifestyle
--Politics
--Technology

This gives you an idea of the content structure so far.

Step 4: Now try it out by creating a story.

In the administer menu, click create content > story. Now you see the newly created Topic tags
near the top of the form. Type a Title, choose Technology as the Topic, and write some text in the
Body field. Click Submit.

You have just uploaded content (a story) and tagged it as Technology.

Upload three other stories and multi-tag them according to the plan below. (To multi-tag, just
Ctrl-Click one item after another.)
1 story - Business, Technology
1 story - Lifestyle, Technology, Politics
1 story - Business, Politics

Now you’re seeing a bit of the power of Drupal.

Step 5: Exploit Drupal’s linking system.

Now you’ll get more glimpses of Drupal’s power. Go back to the categories screen (administer >
categories) and click list terms for Topic. Each of your terms is still listed and are actually links,
too. Mouse over "Business" and look at the status bar of your browser; it’ll show something like
www.example.com/taxonomy/term/555. (Note that the number 555 will be different in your
case.)

The link above tells you that "Business" is term number 555. And, get this, you can show all
stories that have been tagged as Business by just invoking the link
www.example.com/taxonomy/term/555 (using "taxonomy/term/555" will give the same
results). Go ahead, try it on your browser. Type that link or just click on "Business" to see the
stories that were tagged under Business.

What does this mean? First, without having to reprogram, you can create different ways of
displaying content by invoking the taxonomy term numbers. You can create a directory page for
your website, similar to Yahoo, simply by creating a story, typing the topics and linking them to
the term number. You can even create custom menus using this technique.

You have seen how organizing content is easy in Drupal through its taxonomy module. You also
saw that multi-tagging is easy to do in Drupal. Finally, you got a taste of Drupal’s power by
exploiting term numbers. That’s the end of this scenario of our tutorial.

264
3 Aug 2007 Drupal Handbook

Meanwhile, you can play around with the taxonomy module further. Try out the other options
and test the results by creating different stories. When you are ready, go to Scenario 2 (coming
soon), which will teach you to harness more power from vocabularies.

References to other beginning-level taxonomy pages (in order):

Understanding categories for new users
Advanced taxonomies: using hierarchies
More about Taxonomy

Using vocabularies for navigation
When displaying nodes, both in teaser listings on the Drupal home pages and in full,
single-node view, many Drupal themes display the categories applied to the node. If the user
selects any category term, Drupal will then display a browsable listing for all nodes tagged with
that term.

Examine the Taxonomy URL for one such category listing. The end of the URL should look
something like this:

taxonomy/term/1

And another Taxonomy URL, for a different term, something like this

taxonomy/term/2

Note that Taxonomy URLs always contain one or more Term IDs at the end of the URL. These
numbers, 1 and 2 above, tell Drupal which categories to display.

Now combine the Term ID’s above in one URL using a comma as a delimter

taxonomy/term/1,2

The resulting listing represents the boolean AND operation. It includes all nodes tagged with
both terms. To get a listing of nodes using either taxonomy term 1 OR 2, use a plus sign as the
operator

taxonomy/term/1+2

Want to combine more categories? Just add more delimeters and numbers. Know that you can
use the taxonomy section in Drupal site administration to find out any Term ID. Just place the
cursor over any edit term and look to the status bar at the bottom of the browser. Then substitute
the new Term ID’s found there to create a different category listing.

In addition to displaying Drupal nodes by category on site, Drupal has category specific RSS
feeds for other sites to access your site content. See how the URL format for the RSS feed is very
similar to the Taxonomy URL:

265
Drupal Handbook 3 Aug 2007

taxonomy/term/1+2/0/feed

Building individual Taxonomy URL’s is not the most user friendly way to provide site users
access to browseable listings. Nor do administrators necessarily want to build custom blocks for
users with links to each category listing. To extend the means of accessing nodes by category,
download and install the optional taxonomy_dhtml and syndication modules from the Drupal
downloads page.

Vocabularies and terms
Each category group, or vocabulary, can contain multiple category entries, or terms, for tagging
content.

For example, a web-based discussion community might have a vocabulary Topics with terms
such as

Technology
Politics
Education
Religion
Sports

An administrator might also choose to create multiple vocabularies for use with the same node
type. Consider another vocabulary for use alongside of Topics, one which classifies nodes in
another way:

Content with terms

News
Reviews
Announcements
Opinions

New vocabularies can also be created or added to at any time, with as few or as many terms as
the administrator may need. And do not worry. Long before reaching Drupal’s limits at
handling very large classification schemes, users would find large vocabularies and terms
unwieldy to use and maintain.

NOTE: When creating terms for a new vocabulary, administrators might want to provide users
with a catchall term, such as Miscellaneous. Administrators can then review nodes tagged with
Miscellaneous to see if a need exists for new terms. Once new terms are created, ambitious
administrators can also update nodes with the new tag and remove the catchall category tag.

266
3 Aug 2007 Drupal Handbook

Creating a vocabulary
When setting up a vocabulary, Drupal will prompt for:

Vocabulary name (Required) -- A name for this vocabulary; for example, Topics.
Description (Optional) -- A description of the vocabulary (this item may be used by some
modules and feeds).
Types (Required) -- A vocabulary may be associated with or more node types. So, an
administrator might declare that a particular vocabulary is to be associated with stories and
blogs, but not book pages. If an expected node type is unavailable, check and make sure that
the module for the specific node type has been activated.
Hierarchy (Optional) -- Allows a tree-like taxonomy (see Using Hierarchies below).
Related terms (Optional) -- Allows relationships between terms within this vocabulary.
Think of these as "see also" references (this item is not used by many Drupal modules).
Freetagging (Optional) -- Users create terms as they go by typing comma-separated lists of
the terms they want to apply to content instead of selecting from a pre-existing list of terms.
Freetagging vocabularies will present users with a text input that will autocomplete with
matching terms if they exist.
Multiple select (Optional) -- Allows users to categorize nodes by more than one term.
Useful for cross-indexing content. Nodes may then appear on multiple taxonomy pages.
Required (Optional) -- Requires a user to select a term in this vocabularly in order to submit
the node. Otherwise, when creating a node, users will be offered a none option as the default
for each vocabulary.
Weight (Optional) -- Allows the administrator to set the priority of this vocabularly when
listed with other vocabularies. When vocabularies are left with the default weight of zero,
Drupal displays multiple vocabularies in alphabetical order. Increasing a vocabularies
weight with respect to other vocabularies will cause it to appear after them in lists.
Conversely, lighter vocabularies will float nearer the top of lists. Useful for specifying which
vocabulary a user sees first when creating a node.

Creating terms
Once you have finished defining the vocabulary, you may populate it with terms. When creating
a term, note that the available options may depend on what was selected for related terms,
hierarchy and multiple select when creating the vocabulary:

Term name (Required) -- The name for this term. Example: Technology.
Description (Optional) -- Description of the term (this item may be used by some modules
and feeds).
Parent (Required) -- Select the term under which this term is a subset -- the branch of the
hierarchy that this term belongs under (only required when heirarchy is enabled for the
vocabulary).
Synonyms (Optional) -- Enter synonyms for this term, one synonym per line. Synonyms can
be used for variant spellings, acronyms, and other terms that have the same meaning as the
added term, but which are not explicitly listed in this thesaurus, i.e. unauthorized terms
(this item not used by many Drupal modules).

267
Drupal Handbook 3 Aug 2007

Weight (Optional) -- The weight is used to sort the terms of this vocabulary (see explanation
of weight above).

Advanced taxonomies: using hierarchies
For many users needing simple classification schemes, the examples above may be the only
structure necessary for tagging site content. For more elaborate classification needs, consider the
hierarchy option when creating vocabularies. Hierarchies allow the creation of sophisticated
taxonomies with categories and subcategories in a tree structure, much like Yahoo categories or
subject classifications used by libraries.

For example, the vocabulary Food could include the following categories and subcategories:

Dairy
Milk
Drink
Alchohol
Beer
Wine
Pop
Milk
Meat
Beef
Chicken
Lamb
Spices
Sugar

Note that the term Milk appears within both Dairy and Drink. This is an example of multiple
parents for a term. Just select both parents when creating the term Milk.

Don’t forget that that the order of term siblings (e.g. Beef, Chicken, Lamb) can be controlled with
the weight option.

More about Taxonomy
Taxonomy is more than just a module in Drupal. It is also the study of classification and a
research area of information science in the digital age. Drupal admnistrators who want to push
the limits of the Drupal taxonomy system might want to read how it applies to Drupal
taxonomy module development.

The taxonomy module is one of Drupal’s strongest and most popular features because it makes
our lives easier and brings goodwill to all. This is because the taxonomy module allows
authorized users to (1) tag content using custom labels (aka terms), and (2) automatically classify
new content based on this taxonomy. This makes for truly flexible information classification and
retrieval.

268
3 Aug 2007 Drupal Handbook

How is it done? There’s a technical and a storytelling explanation. Let’s begin with the technical
explanation:

The taxonomy module allows you to define vocabularies which are simply a collection of terms
(similar to Gmail "labels" or Flickr "tags"). You can define 2 kinds of relationships between terms:

* Hierarchical: indicates a parent-child (vertical) relationship like cat and dog are children of
mammals)

*Assocation: indicates a "similar to" (horizontal) relationship like mammals is similar to
animals.

Using these relationships, the taxonomy module allows multiple lists of categories for
classification (or controlled vocabularies) and offers the possibility of creating thesauri (terms
with horizontal relationships) and taxonomies (terms with hierarchical relationships). To delete a
term choose edit term. To delete a vocabulary, and all its terms, choose edit vocabulary. {comment: The
emphasized sentence actually sounds out of place here. Please suggest how it can be
reorganized.}

{factor next para into the main text}A controlled vocabulary is a set of terms to use for describing
content (known as descriptors in indexing lingo). Drupal allows you to describe each piece of
content (blog, story, etc.) using one or many of these terms. For simple implementations, you
might create a set of categories without subcategories, similar to Slashdot’s sections. For more
complex implementations, you might create a hierarchical list of categories. {/factor}

Still confused? The story below will show some examples of what the taxonomy module can
help you do:

Case 1 (simple example). Abel sets up a website that contains his music reviews (posted as
stories). Abel uses the taxonomy module to create two terms called Reviews and New
Releases. Under Reviews, he creates the following child terms: Jazz, Folk, Classical. He then
binds these terms to the story node. Now, when Abel posts each of his reviews, he gets a
taxonomy dropdown box that prompts him to classify his review. If Abel classifies a review
as Jazz, the story automatically gets displayed in the website’s "Jazz" category.

Case 2 (intermediate example): Yoyo Ma, a classical cellist, releases an album where he
combines Jazz with Classical styles. Abel now cannot decide whether to classify his album
review as Jazz or Classical. Abel fires up the taxonomy module and modifies the taxonomy
-- now, instead of allowing only one-to-one tagging, he allows multi-tagging. Abel now tags
his review as both Jazz and Classical and everyone, including Yoyo Ma, is happy.

Case 3 (complex): Abel’s music website grows and it now contains stories, blogs and forum
discussions. Beth and Ching are both contributors to Abel’s site. As they post content, they
are also asked to tag their contributions. {to be continued}

It’s Case 3 that I am most interested in.

269
Drupal Handbook 3 Aug 2007

I’m developing a site using Drupal which will rely heavily on stories, essays, and articles
submitted by a number of different users. These folks will want to just write their stuff and post
it. They can use the menu navigation feature of the submission/posting process to determine to
which menu (custom ones previously created by me and/or authorized moderators) the piece
should be associated. [The default behavior is to list unsorted menu items in alpha order, a
perfectly acceptable practice. Myself and moderators can further modify the order of menu items
by assigning them weights.]

So why should our contributors be further required to "classify" their material using terms I have
created? Why put them (and me, who would have to spend time creating vocabularies and
terms) through an unnecessary workload hassle?

So far all I have read are excuses like "well, you can and it’s cool", "it will help people search for
things later" (assumes an otherwise poor search facility is all that is available ), or "you either get
it or you don’t". This last one being the worst response. A typical refuge of
communication-impaired people who like to think themselves more powerful and wise through
possession of secret knowledge. Are we expected to embrace a system simply because a system
can be constructed?

I picked Drupal after trying other CMS approaches because it puts forward clean, nice-looking
pages fairly easily and contains a nice set of optional features (unlike Mambo and Nuke systems
which seem to assume everybody screamingly wants to know what’s hot, what’s not, who’s
popular, and the latest gossip). But I am not convinced Drupal developers must also buy into the
theology or dialectic of the supremacy of taxonomies. Could it be something as simple as
because a Drupal-type CMS is based on a database application (like MySQL), a taxonomy-based
approach is the easiest way of making the system rational and more humanly understandable?

Cheerily Yours,
Tim O’Laguna

Creating a Block with links belonging to certain taxonomy
terms
Question

war_boar wrote:

how to have a block of links to all terms which match taxonomy like Reviews: Anime Or
Reviews: Movies without doing it manually

it should be titled, Reviews and underneath all blogs or stories which matched.

Answer

You might want to use the Taxonomy dhtml module.

270
3 Aug 2007 Drupal Handbook

You will need to create a new Block of type=php. You will then want to paste in the code
below, and customize the ’Physicians’ subject and the $tax array. $tax the list of tids that you are
inetrested in. The third element, named ’operator’, can be and or or. So in your case, assuming
the term ID for movies is ’3’ and the term ID admin/taxonomy/edit/term/3 for Anime is ’6’
admin/taxonomy/edit/term/6, you want:

<?php
// paste this code into a custom block of type=php
// customize the $tax array and the $subject as needed
$tax = array(3, 6);
$operator = "or";
$result = taxonomy_select_nodes($tax, $operator);
while ($obj = db_fetch_object($result)) {
$node = node_load(array(’nid’ => $obj->nid));
$items[] = l($node->title, "node/". $node->nid);
}
return theme(’item_list’, $items);
?>

A Block that returns the first 5 terms for a taxonomy

<?php
$taxo_id = 3;
$sql = "SELECT node.title, node.nid FROM node INNER JOIN term_node ON
node.nid = term_node.nid WHERE term_node.tid = $taxo_id LIMIT 5";
$output .= "<ul>";
$result = db_query($sql);
while ($anode = db_fetch_object($result)) {
$output .= "<li>".l($anode->title, "node/$anode->nid")."</li>";
}
$output .= "</ul>";
return $output;
?>

Taxonomy terms on a page
I have a page with a table where each cell should list nodes that are at the intersection of two
keywords. In order to accomplish this I have modified Moshe’s code slightly. Here it is:

$content = "Some text";
$content .= getnodes (1,2);
$content .= "Some text";
$content .= getnodes (3,4);
print $content;
function getnodes($id1, $id2) {
$tax = array ("str_tids" => "$id1, $id2", "tids" => array ($id1, $id2),
"operator" => "and");

271
Drupal Handbook 3 Aug 2007

$result = taxonomy_select_nodes(array2object($tax), 0);
while ($node = db_fetch_object($result)) {
$output[] = l($node->title, "node/". $node->nid);
}
return (theme_item_list($output));
}

Comment: allow comments on content
The comment module creates a discussion board for each post. Users can post comments to
discuss a forum topic, weblog post, story, collaborative book page, etc. The ability to comment is
an important part of involving members in a communtiy dialogue.

An administrator can give comment permissions to user groups, and users can (optionally) edit
their last comment, assuming no others have been posted since.

Attached to each comment board is a control panel for customizing the way that comments are
displayed. Users can control the chronological ordering of posts (newest or oldest first) and the
number of posts to display on each page.

Comments behave like other user submissions. Filters, smileys and HTML that work in nodes
will also work with comments. The comment module provides specific features to inform site
members when new comments have been posted. On sites with active commenting from users,
the administrator can turn over comment moderation to the community.

You can

control access for various comment module functions through access permissions
administer >> access control.
administer comments administer >> comments >> configure.
enable the recent comments block: administer >> block

Detailed comment documentation
When enabled, the Drupal comment module creates a discussion board for each Drupal node.
Users can post comments to discuss a forum topic, weblog post, story, collaborative book page,
etc. An administrator can give comment permissions to user groups, and users can (optionally)
edit their last comment, assuming no others have been posted since.

User control of comment display
Attached to each comment board is a control panel for customizing the way that comments are
displayed. Users can control the chronological ordering of posts (newest or oldest first) and the
number of posts to display on each page. Additional settings include:

272
3 Aug 2007 Drupal Handbook

Threaded â Displays the posts grouped according to conversations and subconversations.
Flat â Displays the posts in chronological order, with no threading whatsoever.
Expanded â Displays the title and text for each post.
Collapsed â Displays only the title for each post.

When a user chooses save settings, the comments are then redisplayed using the user’s new
choices. Administrators can set the default settings for the comment control panel, along with
other comment defaults, in administer » comments » configure. NOTE: When comment
moderation is enabled, users will have another control panel option to control thresholds (see
below).

Additional comment configurations
Comments behave like other user submissions in Drupal. Filters, smileys and HTML that work
in nodes will also work with comments. Administrators can control access to various comment
module functions through administer » access control » permissions. Know that in a new
Drupal installation, all comment permissions are disabled by default. The choice of which
permissions to grant to which roles (groups of users) is left up to the site administrator. The
following permissions:

Access comments â Allows users to view comments.
Administrate comments â Allows users complete control over configuring, editing and
deleting all comments.
Moderate comments â Allows users to rate comment postings (see more on moderation
below).
Post comments â Allows users to post comments into an administrator moderation queue.
Post comments without approval â Allows users to directly post comments, bypassing the
moderation queue.

Notification of new comments
Drupal provides specific features to inform site members when new comments have been
posted.

Drupal displays the total number of comments attached to each node, and tracks comments read
by individual site members. Members which have logged in will see a notice accompanying
nodes which contain comments they have not read. Some administrators may want to
download, install and configure the notify module. Users can then request that Drupal send
them an e-mail when new comments are posted (the notify module requires that cron.php be
configured properly).

The tracker module, disabled by default, displays all the site’s recent posts. There is a link to the
recent posts page in the navigation block. This page is a useful way to browse new or updated
nodes and comments. Content which the user has not yet read is tagged with a red star (this
graphic depends on the current theme). Visit the comment board for any node, and Drupal will
display a red "new" label beside the text of unread comments.

273
Drupal Handbook 3 Aug 2007

Comment moderation
On sites with active commenting from users, the administrator can turn over comment
moderation to the community.

With comment moderation, each comment is automatically assigned an initial rating. As users
read comments, they can apply a vote which affects the comment rating. At the same time, users
have an additional option in the control panel which allows them to set a threshold for the
comments they wish to view. Those comments with ratings lower than the set threshold will not
be shown. To enable moderation, the administrator must grant moderate comments
permissions. Then, a number of options in administer » comments » configure must be
configured.

Moderation votes
The first step is to create moderation labels which allow users to rate a comment. Go to
administer » comments » configure » moderation votes. In the vote field, enter the textual
labels which users will see when casting their votes. Some examples are

Excellent +3
Insightful +2
Useful +1
Redundant -1
Flame -3

So that users know how their votes affect the comment, these examples include the vote value as
part of the label, although that is optional. Using the weight option, you can control the order in
which the votes appear to users. Setting the weight heavier (positive numbers) will make the
vote label appear at the bottom of the list. Lighter (a negative number) will push it to the top. To
encourage positive voting, a useful order might be higher values, positive votes, at the top, with
negative votes at the bottom.

Moderator vote/values matrix
Next go to administer » comments » configure » moderation matrix. Enter the values for
the vote labels for each permission role in the vote matrix. The values entered here will be used
to create the rating for each comment. NOTE: Comment ratings are calculated by averaging user
votes with the initial rating.

Creating comment thresholds
In administer » comments » configure » moderation thresholds, you’ll have to create some
comment thresholds to make the comment rating system useful. When comment moderation is
enabled and the thresholds are created, users will find another comment control panel option for
selecting their thresholds. They’ll use the thresholds you enter here to filter out comments with
low ratings. Consequently, you’ll probably want to create more than one threshold to give users
some flexibility in filtering comments.

274
3 Aug 2007 Drupal Handbook

When creating the thresholds, note that the Minimum score is asking you for the lowest rating
that a comment can have in order to be displayed. To see a common example of how thresholds
work, you might visit Slashdot and view one of their comment boards associated with a story.
You can reset the thresholds in their comment control panel.

Initial comment scores
Finally, you may want to enter some initial comment scores. In administer » comments »
configure » moderation roles you can assign a beginning rating for all comments posted by a
particular permission role. If you do not assign any initial scores, Drupal will assign a rating of 0
as the default.

Aggregator comments
Comments for aggregator items has been added to aggregator2 module.

Contact: a way for users to get in touch
The contact module helps people get in touch with one another and with you or the people
running your site.

Through personal contact forms users can send one another e-mail. And through site-wide contact
forms users can send e-mail to the people in charge of your site.

With either form, users can specify a subject, write their message, and also have a copy of their
e-mail sent to their own address.

Through contact forms, users allow themselves to be contacted yet keep their own e-mail
addresses private.

You can enable the contact module on the menus page (administer >> menus).

Users (in their account settings) can turn their personal contact forms on or off. When their form
is turned on, a contact tab appears in their user profile, for everyone to see. (Privileged users such
as site administrators can contact even users who have turned their forms off.)

When users view their own profiles they won’t see their contact tab. Only other users will see it,
if it’s turned on.

Your navigation menu can show a link to your site-wide contact form. Just enable the "contact"
link on your menus page (administer >> menus). You can add that link to any other menu as
well. (Click "add menu item," and when you fill in the "path" field on the dialogue page just
enter "contact.")

On the contact administration page (administer >> contact form) you can set up "categories" of
site-wide contact you’d like to receive. For example, one category might be "website feedback,"
and another might be "product information."

275
Drupal Handbook 3 Aug 2007

For each category, you can specify whom you’d like to have receive your user’s e-mail. The mail
could go to one person or many. You can also specify whether or not the user will receive an
automatic reply.

The settings portion of the contact administration page offers you other options. You can specify
what message you’d like to show on your site-wide contact page. And you can limit how many
times a user can contact you in an hour.

You can

view user profiles.
let each user enable a personal contact form in my account.
administer contact at administer >>contact.

Make your site wide contact form look prettier
Drupal ships with a sitewide contact form since version 4.7 that you can use to allow site visitors
to send feedaback. As mentioned in the help text on the contact form settings page, you can also
use the body area just above the form to give site visitors your postal address or share any other
information.

However, because you can’t specify an input format for the contact form page, the additional
information you add will display without linebreaks or paragraph breaks and look pretty ugly.

There is a simple workaround for this. Just put <br> and <p> tags where you want the
linebreaks and paragraphs to appear and you will have a nice looking contact page. Experiment
with the line break and paragraph break tags until you are satisfied with the appearance of your
contact page.

Drupal: Drupal sites directory server
The Drupal module uses the XML-RPC network communication protocol to connect your site
with a directory server.

Enabling the Drupal module will:

allow members on all sites using the Drupal module to login to your site without registering
using their distributed identification and vice versa.
allow members to login to any other site which uses the Drupal module, using a login name
which looks much like an email address for your site: username@example.com

The Drupal module administration page allows you to set the xml-rpc server page. The listing of
your site in a site directory will occur shortly after your sites next cron run.

You can

276
3 Aug 2007 Drupal Handbook

run your cron job manually at your sites cron page.
view the XML-RPC page.
administer Drupal administer >> settings >> drupal.

Old page
The "Drupal" module features a capability whereby other drupal sites may call home to report
their existence. In turn, this enables a pod of Drupal sites to find, cooperate and advertise each
other.

Currently, the main application of this feature is the Drupal sites page. By default, fresh Drupal
installations can use drupal.org as their directory server and report their existence. This reporting
occurs via scheduled XML-RPC pings.

Drupal administrators should simply enable this feature to get listed on the Drupal sites page.
Just set your site’s name, e-mail address, slogan and mission statement on the administer »
settings page. Then make sure that the field called Drupal XML-RPC server on the administer »
settings » drupal page is set to http://www.drupal.org/xmlrpc.php, and enable this feature
using the dropdown directly below.

The listing of your site will occur shortly after your site’s next cron run. Note that cron.php
should be called using the domain name which you want to have listed at drupal.org. For
example, don’t kick off cron by requesting http://127.0.0.1/cron.php. Instead, use a publicly
accessible domain name such as http://www.example.com/cron.php.

Also note that your installation need not use drupal.org as its directory server. For example, this
feature is perfectly capable of aggregating pings from all of your departmental drupal
installations sites within an enterprise.

Filter: Input formats for user content
The filter module allows you to configure formats for text input for your site. For example, you
may want a filter to strip out malicious HTML from users’ comments.

Despite the name "filter," the module not only lets you keep out text you don’t want but also lets
you enhance the text you let in. So, for example, you can use a filter to turn ordinary line breaks
into HTML paragraph tags.

When users create or edit content, they can choose between the input formats you make
available. You can configure which formats are available to which user roles, as well as choose a
default input format. You can also create new input formats. And you can configure each input
format to use your choice of filters.

You can

277
Drupal Handbook 3 Aug 2007

administer input format permissions and settings at administer >> input formats.
add a new input format at administer >> input formats >> add input format.

Forum: create threaded discussions
The forum module lets you create threaded discussion boards, called forums, on your site. This is
similar to a message board system such as phpBB. Forums are very useful because they allow
community members to discuss topics with one another, and the discussions are archived for
future reference.

Topics, or threaded discussions, are posted to a forum. Each topic is comprised of an initial post
and replies, or comments. Forum topics can have their own URLs.

Multiple forums are often set up for different areas of discussion. Forums can also be placed
inside other forums for a discussion area that is a subset of the parent forum, in which case they
are often called child boards or forums.

Containers can also be created to hold a group of forums. However, topics cannot be posted to
containers, unlike a parent forums. Both containers and forums can be placed inside other
containers and forums. By planning the structure of your containers and forums well, you make
it easier for users to find a discussion area of interest to them.

Forums module requires Taxonomy and Comments modules to be enabled.

You can

administer forums at administer >> forums.
set workflow and other global forum settings on the forum configuration page: administer
>> settings >> content types >> forum .
control who can create, edit, and administer forum posts with administer >> access control
or taxonomy access control.
move forum topics to a different forum board using the edit tab; a copy can be left in the
existing forum by selecting leave a shadow copy.
enable the required comment and taxonomy modules at administer >> modules.
style with flatform theme and add features with the quote, subscription, bbcode, and
comment mover modules. Add private message with privatemsg module and extend user
profile information with the profile module.
read about the comment module at administer >> help >> comment.
read about the taxonomy module at administer >> help >> taxonomy.
The forum module, like Drupal itself, can be extended with different modules depending on
the needs or your site. What features you choose to implement are in your control.

278
3 Aug 2007 Drupal Handbook

HOWTO: Create a forum
Users can post topics to forums. Forums can appear below other forums in a hierarchy, or can
appear in containers.

1. Click administer » forums.
2. Click the add forum tab.
3. Type in a forum name.
4. Type in a forum description. This will show up below the forum name when users visit the
forum section.
5. Select a parent.
You can choose either a forum or a container to be a ’parent’ for a forum. If there are no
containers or existing forums to choose from, you will only see <root> as the option,
meaning it will be at the top of the forum hierarchy.
6. Select a weight. Higher numbers means the container will sink down in the list, lower
numbers mean the container will rise up.
7. Click the "Submit" button.

HOWTO: Create forum containers
Containers are ’parents’ for forums (discussion boards); they are used to group forums. Users
cannot post topics to containers; users post to the forums in the container(s). A site with only a
few forum discussion boards may not need any containers.

1. Click administer » forums.
2. Click the add container tab.
3. Type in a container name.
4. Type in a container description. This will show up below the container name when users
visit the forum section.
5. Select a parent. If there are no containers or existing forums to choose from, you will only
see <root> as the option, meaning it will be at the top of the forum hierarchy.
6. Select a weight. Higher numbers means the container will sink down in the list, lower
numbers mean the container will rise up.
7. Click the "Submit" button.

Help: context-sensitive guidance
The help module displays context-sensitive help.

Administrators cannot alter the help system. But module authors can make informative use of it.
And modules can make help texts available to other modules.

279
Drupal Handbook 3 Aug 2007

More about the help module
All user help should be presented using the help module. Some examples of help:

The name of a module (unused, but there).
The description found on the admin/system/modules page.
The module’s help text, displayed on the admin/help page and through the module’s
individual help link.
The help for a distributed-authorization module (if applicable).
The description of a post type (if applicable).

The text of the help topics listed on administer >> help are maintained on drupal.org in the
Drupal modules section. Additional help is often available in sub pages of that section.

Legacy: remapping of old-style URLs
The legacy module provides legacy handlers for upgrades from older installations. These
handlers help automatically redirect references to pages from old installations and prevent page
not found errors for your site.

The legacy module handles legacy style taxonomy page, taxonomy feed, and blog feed paths. It
also handles URL upgrades from Drupal 4.1. It rewrites old-style URLs to new-style URLs (clean
URLs).

Example Mappings:

taxonomy/page/or/52,97 to taxonomy/term/52+97.
taxonomy/feed/or/52,97 to taxonomy/term/52+97/0/feed.
blog/feed/52 to blog/52/feed.
node/view/52 to node/52.
book/view/52 to node/52.
user/view/52 to user/52.

Legacy module has no configurable options and does not need to be enabled for new Drupal
sites.

Locale: multi-language support
The locale module allows you to present your Drupal site in a language other than the default
English. You can use it to set up a multi-lingual web site or replace given built-in text with text
which has been customized for your site. Whenever the locale module encounters text which
needs to be displayed, it tries to translate it into the currently selected language. If a translation
is not available, then the string is remembered, so you can look up untranslated strings easily.

280
3 Aug 2007 Drupal Handbook

The locale module provides two options for providing translations. The first is the integrated
web interface, via which you can search for untranslated strings, and specify their translations.
An easier and less time-consuming method is to import existing translations for your language.
These translations are available as GNU gettext Portable Object files (.po files for short).
Translations for many languages are available for download from the translation page.

If an existing translation does not meet your needs, the .po files are easily edited with special
editing tools. The locale module’s import feature allows you to add strings from such files into
your site’s database. The export functionality enables you to share your translations with others,
generating Portable Object files from your site strings.

You can

administer localization at administer >> localization.
manage strings for the localization: administer >> localization >> manage strings.
add a locale language: administer >> localization >> add language.
download translation files from the Drupal translations page.

Adjusting your php.ini settings for importing .po files
Gettext portable object files sometimes are big enough to require you to adjust the settings of
you php.ini at least to be able to import the translated strings into your Drupal installation.

For example, the es.po (Spanish localization) for Drupal 4.6.4 is a 400K+ text file containing
1800+ translated strings. You might very well need to adjust the relevant php.ini settings for this
file to get imported.

PHP defaults to this values:

; Maximum execution time of each script, in seconds
max_execution_time = 30

; Maximum amount of time each script may spend parsing request data
max_input_time = 60

; Maximum amount of memory a script may consume (8MB)
memory_limit = 8M

You’ll more likely have to adjust the memory_limit to 16M (your mileage may vary) to have the
import process complete.

If you’re getting a blank page with no indication that the import process has been completed (or
has failed) you’re most probably having trouble with PHP’s defaults. Make sure by checking the
messages in your webserver’s error log.

If it’s the upload what is taking too much time go adjust max_input_time to a higher value. If it’s
the time the script is taking to complete the process what’s taking too much time you’ll have to
adjust max_execution_time.

281
Drupal Handbook 3 Aug 2007

There should be no need to leave this values that way once you’ve imported a big .po file. If
you’re confident the new settings won’t hurt your webserver’s performance or security just
leave them that way. Otherwise return them to the previous settings (even when it’s highly
iikely that you’ll need to readjust them whenever you perform an upgrade or reinstall)

Editing text for translation
Translating text via the Drupal interface can be pretty tedious to say the least. This is not so
much because of Drupal, but because of page reloads every time a string is updated. There is a
much better way to translate strings into a different language, namely editing PO files with a PO
editor, and then importing them into Drupal.

A full guide on how to translate Drupal Core or modules, using the above-mentioned technique,
can be found here.

How to create Drupal site in Marathi (Devnagari)
I read a few posts asking guidelines on creating a Drupal site in Marathi (Devnagari) - a
language spoken in western part of India. As there is neither standard Marathi translation nor
any Marathi language specifc help is available, I thought of writing a small set of steps /
guidelines for creating a Drupal based website in Marathi language ( rather any Indian
Language for which Unicode fonts are available)

Although I have created Marathi websites using Drupal 4.7 & 5.1, this article applies to Drupal
5.1 only.

To create a Drupal site in Marathi, you may follow these steps:

- Install Drupal!
- Create first (Admin) user account
- Login as administrator to the newly created site
- Go to Administer > Site Building > Modules (/admin/build/modules)
- Enable Locale module
- Go to Administer > Site Configuration > Localization (/admin/settings/locale)
- Click on add language tab
- From the drop down of languages, select Marathi & click on Add language button
- On the Languages list page, you will now see mr (Marathi) as a language, enable it & make it
default

Now you might expect that suddenly the entire site will appear in Marathi, but nothing like
this will happen! Now you will need to ’translate’ default English ’Strings’ to Marathi one by
one.

- To do so, go to Manage Strings Tab on the localization page
(admin/settings/locale/strings/search)
- Enter the string / text you wish to translate to Marathi (e.g. Log in)
- If the string is found, a list of all the places where this string is used in Drupal site is displayed.

282
3 Aug 2007 Drupal Handbook

- In that list, go to the row which you want to translate to Marathi, click on edit
- In the next page enter your own Marathi translation of the string using unicode marathi font &
save the string (e.g. Log In = यà¥à¤£à¥à¤¯à¤¾à¤à¥ नà¥à¤à¤¦ )

Follow these steps for all the labels / strings which are appearing on your site’s interface and
you are done!!

To avoid this painful process, there is an option of Importing a translation scheme (so we can
actually import entire Marathi translation of Drupal interface in a single click). However,
unfortunately, there is no standard Marathi Translation of Drupal interface available yet! So we
have to wait for someone to write it or follow this string by string translation process!

If you need a Marathi Transliteration Typing interface for your site (so that your users can type
in Marathi using normal English keyboards), you may try a module called as UniSaraswati
(http://drupal.org/project/unisaraswati) specifically written for this purpose

If you need generic help about computing in Marathi, you may get it on Marathi Wikipedia -
http://mr.wikipedia.org

You may find the examples of marathi sites created using Drupal at:

www.sadha-sopa.com (Drupal 4.7)
www.marathigazal.com (Drupal 5.1)
www.miloonsaryajani.com (Drupal 5.1)

Prasad Shirgaonkar

How to install a different language
To install a locale, simply enable the locale module. Then, go to admin/localization and import a
.po file that you downloaded from http://drupal.org/project/Translations. You should select
the right language code in the popup menu. That’s it !

You can now let user switch languages, or not, by activating more than one. Also, you could
look in the tab "translate srtings" in the localization module.

See Locale or internationalization support for more.

HOWTO: Creating a customized language set to replace
Drupal terminology
1. Enable the locale module on the administer » modules page
2.
administer > access control
give yourself (and any other roles that should have it) permission to access locale
3. Go to the administer » localization page.
4. Select the add language tab .

283
Drupal Handbook 3 Aug 2007

5. Assuming English, create a custom language by adding en-US in the Language code text
field.
6. Give your language a name, such as custom-English (be sure not to use spaces in your
language name), and add the language.
7. This will return you to the main localization page. Set your new language as enabled and as
the default.
8. Save the configuration.
9. Then disable the original English language set (that is, unless you would like users to be
given the option to choose between the two in their account area).

Now, any time you visit a page with Drupal hard-coded content, it will be added into your
language set database.

Once you have visited a page that you wish to change the content:

1. Go to the manage strings page (admin/locale/string/search) of the localization section.
2. Enter in the string you wish to search for.
3. Edit the result and enter your replacement text.

HOWTO: Use a customized language set to change Drupal
text and terminology
Depending on your particular application, you may find that the default text or terminology
used in the Drupal core or a contributed module doesn’t suit your style or need. Customizing
this text with the locale module is fairly simple and is portable if you create an additional site up
upgrade your version of Drupal or a contributed module.

As simple examples, you might wish to change the "Search" button to say "Find", or you might
wish that comments were shown as being "Posted by" rather than "Submitted by" a particular
user. As a more advanced possibility, you might wish that the things described by Drupal as
"forums" were instead called "bulletin boards", and that you could change this in every context
where the word "forum" is used.

The locale module is a well-developed system for handling this situation. While described as a
system for making translations, it will also efficiently substitute your prefered terminology for
the default Drupal terminology. You should first read the instructions for Creating a customized
language set to replace Drupal terminology. After following the steps outlined there to create
your custom language, this page is intended to provide additional step-by-step and detailed
instructions for those new to Drupal.

Again, before proceeding, follow the instructions in the first section at
http://drupal.org/node/24593 to enable the locale module, create a customized language, and
make it the default language. If you are not user #1, a user with appropriate access will need to
go to the access control page at administer >> access control and enable "administer locales" for
your user role.

284
3 Aug 2007 Drupal Handbook

Next, rather than searching for individual strings through the interface at administer >>
localization, you’ll probably find it easier to use a template file and then import the "translated"
strings. So, download the translation templates from the appropriate version of Drupal. Some
contributed modules will also include a translation template in a "po" directory.

In the downloaded directory of templates, you will see numerous template files ending in ".pot".
The file "general.pot" contains strings that are reused in several modules. Open this in a text
editor and look it over. Following through on the simple examples above, we can find these
strings in the file in the following form:

#: includes/locale.inc:327;346 modules/search.module:142;996
modules/system.module:1198 modules/user.module:1958
msgid "Search"
msgstr ""

Edit the file so as to specify a replacement text, such as:

#: includes/locale.inc:327;346 modules/search.module:142;996
modules/system.module:1198 modules/user.module:1958
msgid "Search"
msgstr "Find"

Similarly, we can change the text shown by each comment by making a change to this entry:

#: themes/engines/phptemplate/phptemplate.engine:250;273
msgid "Submitted by %a on %b."
msgstr "Posted by %a on %b."

Note that the text following the "#:" is for information only and does not affect the outcome of
this process.

From here, save your edited file somewhere handy (you might keep it together with your local
copy of your customized theme). Now go back to administer->localization and choose "import"
from the top tabs. Browse and choose your edited translation file, and then import it into your
customized language. Voila, you should see that the name of the Search box it changed to "Find",
etc.

For a more sweeping change, you could open the "forum-module.pot file", and provide an
alternate term every place the word "forum" is used. For example, you could edit the following
entry as shown:

#: modules/forum.module:51;110;216
msgid "forum topic"
msgstr "bulletin board subject"

Additional help and techniques for using the locale module and generating substitute text can be
found in the Translator’s guide.

285
Drupal Handbook 3 Aug 2007

Note for the curious
If you look in the PHP code for a module, you’ll find (for example) in the search.module:

<?php
$form[’basic’][’inline’][’submit’] = array(’#type’ => ’submit’,
’#value’ => t(’Search’));
?>

’Search’ is a t-ified string, which means it can be replaced by using the locale module.

Menu: customize site navigation
The menu module lets you customize your menus. Menus appear in blocks on your site and
help visitors and users find their way around. The main menu for navigation is by default called
"Navigation."

On the administer menu page administrators can ’’’edit’’’ to change the title, description,
parent or weight of a menu item. Under the ’’’operations’’’ column, click on
’’’enable/disable’’’ to toggle a menu item on or off. Disabled menu items are not deleted but
merely made no longer visible on your site. The default menu items generated by the menu
module cannot be deleted, only disabled.
Use the ’’’add menu’’’ tab to submit a title for a new custom menu. Once submitted, the new
menu will appear in a list toward the bottom of the administer menu page underneath the
main navigation menu.
Use the ’’’add menu item’’’ tab to create new links in either the navigation menu or a
custom menu. Select the parent item to place the new link within an existing menu
structure. For top-level menu items, choose the name of the menu in which the link is to be
added.
To turn off the navigation menu block, administer the block page.

You can

administer menus at administer >> menus.
turn menus blocks on and off in the administration >> block.
add a menu at administer >> menus >> add menu.
add a menu item at administer >> menus >> add menu item.
reset all menu customizations back to the Drupal default at administer >> menus >> reset
menus.

Using named anchors with menus
Users who have tried using ânamed anchors,â also known as âjump links,â in the menu system
can run into problems with them not to working. For clarification, a named anchor looks like
this:
<a name="anchor"></a>

286
3 Aug 2007 Drupal Handbook

The expected behavior is that when a link that points to this named anchor is clicked, the user’s
browswer should jump to a to the anchor tag on the html page, making it appear at the top of
the user’s browser window.

This desired behavior can be accomplished by adding the following function to your theme’s
template.php file:

function phptemplate_menu_item_link($item, $link_item) {
// Convert anchors in path to proper fragment
$path = explode(’#’, $link_item[’path’], 2);
$fragment = !empty($path[1]) ? $path[1] : NULL;
$path = $path[0];
return l(
$item[’title’],
$path,
!empty($item[’description’]) ? array(’title’ =>
$item[’description’]) : array(),
!empty($item[’query’]) ? $item[’query’] : NULL,
$fragment,
FALSE,
FALSE
);
}

Node: the content
All content on a Drupal website is stored and treated as "nodes." A node is any posting, such as
a page, poll, story, forum text, or blog entry. Comments are not stored as nodes but are always
tied to one.

Treating all content as nodes allows the flexibility of creating new types of content. It also allows
you to painlessly apply new features or changes to all content.

Behind the scenes, the nodes module manages these nodes. This module is what lets you

list, sort through, and manage all the content on your site
set norms for how all posts are displayed
list and configure the "content types" for your site, and create new ones

Offering "content types" is a way Drupal allows you to have different kinds of nodes for
different purposes. For example, a "story" is one kind of node, a "book page" another, and a
"blog entry" yet another. You can also create new content types of your own.

You can

287
Drupal Handbook 3 Aug 2007

search for content at search.
administer all nodes at administer >> content management >> content.
administer workflow and other default settings for individual node types at administer >>
content management >> content types.
configure the number of nodes to display on the main page and the length of trimmed posts
at administer >> content management
>>post settings.
set access permissions for various node types at administer >> user management >> access
control.

Page: post static pages
The page module allows users to create static pages, which are the most basic type of content.
Pages can be collected in books via the book module. Users should create a page if the
information on the page is static. An example would be an "about" page.

When a page is created, a user can set authoring information, configure publishing options,
whether readers will be able to post comments. They can also select the content type of the page
(e.g., full HTML, filtered HTML, php).

As an administrator, you can set the publishing default for a page (in its workflow): you can
specify whether a page is by default published, sent to moderation, promoted to the front page,
sticky at the top of lists, and whether revisions are enabled by default. You can set the
permissions that different user roles have to view, create, and edit pages.

You can

read the node administration help at administer >> help >> node.
read the page administration help at administer >> help >> page.
read the story administration help at administer >> help >> story.
create a page at create content >> page.
set workflow and other global page settings at administer >> settings >> content types >>
page.

Difference between page and story
Many people ask what the difference is between the "page" node type and the "story" node type.
In terms of basic functionality, there is no difference. However, as they are processed within
Drupal as two different node types, one can theme them differently, so that page nodes and
story nodes have differing looks. You can also make a distinction when using various node
access modules.

Note that as of Drupal 5.x a few default differences have been introduced:

288
3 Aug 2007 Drupal Handbook

A page doesn’t post author information, timestamps or comments by default.
A story does post author information, timestamps or comments by default.

It is still possible to configure a story and a page to be exactly the same. Drupal core now also
allows administrators to edit the names of page and story to anything you want and create your
own different types of content that suit the needs of a specific site.

Specify page by title
You can specify a page by using the URL format node.php?title=text

Path: readable URLs
The path module lets you create aliases for Drupal URLs. That is, instead of a technical-looking
web address like www.example.com/?q=node/67, your users will see, for instance,
www.example.com/?q=news.

This makes more sense for your users and may help make your site show up better in internet
searches. (And with Drupal’s "clean URLs" feature you can get rid of the "?q=":
www.example.com/news.)

Some examples of URL aliases:

user/login => login
image/tid/16 => store
taxonomy/term/7+19+20+21 => store/products/whirlygigs
node/3 => contact
node/10 => products/merchandise/cups
node/10 => cups
node/11 => products/merchandise/coffeemakers

You can use slashes however you like. So, for example, suppose a page is called
www.example.com/taxonomy/term/7+19+20+21. You could also give it both of these new addresses:

www.example.com/store/products/whirlygigs
www.example.com/timesavers/whirlygigs

You can enable the path module on the modules page (administer >> modules). Then when users
with the right permissions create or edit posts, they’ll see a field for "URL path settings." That’s
where they can enter an alias of their choice.

On the URL aliases page (administer >> url aliases) you’ll see a list of all the URL aliases on your
site. There you can edit them, and add new ones. You can assign more than one alias to a page
(just use the add alias tab again for each new alias).

289
Drupal Handbook 3 Aug 2007

On the access control page (administer >> access control) you can decide who can create aliases
and who can administer the list of them.

The path module also lets you define many URL aliases at once. This is useful if you wish to use
URLs uniformly different from those assigned by default. For example, you may want to show
your URLs in a different language. To do this sort of thing, you need to dig a bit into Drupal’s
source code.

You can

set the path for a post with the path module.
add a URL alias: administer >> url aliases >> add alias.
administer the list of URL aliases: administer >> url aliases.
read how to configure clean URLs for your webserver.
enable Clean URLS to remove the =? at administer >> settings in the General settings area.
automate URL alias creation by installing and using the pathauto module.

Mass URL aliasing
Drupal also comes with user defined mass URL aliasing capabilities. You might like to see
completely different URLs used by Drupal, or even URLs translated to the visitors’ native
language, in which case this feature is handy. Only an administrator with access to the website
source code can set up this kind of aliases. You can define a function somewhere in your code
(even in settings.php), following this example:

<?php
// Example for Drupal 4.6.x
function conf_url_rewrite($path, $mode = ’incoming’) {
if ($mode == ’incoming’) { // URL coming from a client
return preg_replace(’!^display/(\d+)$!’, ’node/\1’, $path);
}
elseif ($mode == ’outgoing’) { // URL going out to a client
return preg_replace(’!^node/(\d+)$!’, ’display/\1’, $path);
}
}
?>
<?php
// Example for Drupal 4.7.x and up
function custom_url_rewrite($type, $path, $original) {
// This path was already aliased, skip rewriting it
if ($path != $original) {
return $path;
}
if ($type == ’source’) { // URL coming from a client
return preg_replace(’!^display/(\d+)$!’, ’node/\1’, $path);
}
elseif ($type == ’alias’) { // URL going out to a client

290
3 Aug 2007 Drupal Handbook

return preg_replace(’!^node/(\d+)$!’, ’display/\1’, $path);
}
}
?>

This function will shorten every node/$node_id type of URL to display/$node_id.
Individual URL aliases defined on the browser interface of Drupal take precedence, so if you
have a ’contact’ page alias for example, then the display/3 alias will not be effective when
outgoing links are created. Incoming URLs however always work with the mass URL aliased
variant. Only two modes are supposed to be supported by your custom function.

You cannot only use this feature to shorten the URLs, or to translate them to you own language,
but also to add completely new subURLs to an already existing module’s URL space, or to
compose a bunch of existing stuff together to a common URL space. You can create a news
section for example aliasing nodes and taxonomy overview pages falling under a ’news’
vocabulary, thus having news/15 and news/sections/3 instead of node/15 and
taxonomy/term/3. You need extensive knowledge of Drupal’s inner workings and regular
expressions though to make such advanced aliases.

Ping: notify services of changes
The ping module is useful for notifying interested sites that your site has changed. It
automatically sends notifications (called "pings") to the pingomatic service to tell it that your site
has changed. In turn pingomatic will ping other services such as weblogs.com, Technorati,
blo.gs, BlogRolling, Feedster.com, Moreover, etc.

The ping module requires cron or a similar periodic job scheduler to be enabled.

You can:

enable or disable the ping module at administer >> modules.
run your cron job at your sites cron page.
read about configuring cron jobs.

Write a custom module to ping a set of sites
If the sites that you want to notify don’t use ping-o-matic you can use the following update.

Copied from here: http://drupal.org/node/29704

Replace ping.module:ping_ping with the following. Compatible with drupal 4.6.3

/**
* Implementation of hook_ping().
*
* Notifies pingomatic.com, blo.gs, and technorati.com of changes at
this site.

291
Drupal Handbook 3 Aug 2007

*/
function ping_ping($name = ’’, $url = ’’) {
$result = xmlrpc(’http://rpc.pingomatic.com’, ’weblogUpdates.ping’,
$name, $url);
if ($result === FALSE) {
watchdog(’directory ping’, t(’Failed to notify pingomatic.com
(site).’), WATCHDOG_WARNING);
} else {
watchdog("directory ping", t(’successfully notified pingomatic.com
(site).’), WATCHDOG_NOTICE);
}
unset($result);
$result = xmlrpc(’http://rpc.technorati.com/rpc/ping’,
’weblogUpdates.ping’, $name, $url);
if ($result === FALSE) {
watchdog(’directory ping’, t(’Failed to notify technorati.com
(site).’), WATCHDOG_WARNING);
} else {
watchdog("directory ping",t(’successfully notified technorati.com
(site).’), WATCHDOG_NOTICE);
}
unset($result);
$result = xmlrpc(’http://ping.blo.gs’, ’weblogUpdates.ping’, $name,
$url);
if ($result === FALSE) {
watchdog(’directory ping’, t(’Failed to notify blo.gs (site).’),
WATCHDOG_WARNING);
} else {
watchdog("directory ping", t(’successfully notified blo.gs
(site).’), WATCHDOG_NOTICE);
}
unset($result);
}

- David Herron - http://7gen.com/

Poll: community voting
The poll module lets you create simple polls. You ask a question, provide possible answers, and
let your users vote. Drupal then keeps a running tally of the results.

When you create a poll, you can also specify the "base" vote counts (how many votes an item has
at the start) and decide how long the vote will run.

292
3 Aug 2007 Drupal Handbook

You can enable the polls module on the modules page (administer >> modules).

The poll item in the navigation menu will take you to a page where you can see all the current
polls, vote on them (if you haven’t already) and view the results.

On the access control page (administer >> access control) you can decide which users have
permission to vote, to see the voting results, and to create polls of their own.

You can see some sample polls on Drupal.org.

You can

view the polls page.
administer >> settings >> content types >> poll.

Profile: extending user account information
The profile module lets your users share information about themselves. You set up forms for
them to fill in. Users tell about themselves by filling in your forms on the edit tab of their "My
Account" page. And what each user tells will be visible to the rest of the users on your site, to the
extent you choose when you design the forms.

You can enable the profile module on the modules page (administer >> modules).

When you set up the forms for user profiles (at administer >> settings >> profiles), you can define
custom fields (for example, for name, age, and country). To do this, you can make use of fields of
the following types:

single-line textfield
Example: You want to ask your user’s name
multi-line textfield
Example: You want to ask an open-ended question: "What would you most like to do to
make this a better community?"
checkbox
Example: You want to say, "Please tick this box if you’ve ever been to Brazil."
list selection
Example: You want to ask, "Which of these colors do you most prefer--red, blue or green?"
freeform list
Example: You want to ask your user for a list--"What languages do you speak?"
URL
Example: You want to ask, "What is the address of your personal website?"
date
Example: You want to ask, "When were you born?"

You can have as many fields as you want, using any of these types as many times as you want.
And you can put each field into the order you want by specifying its "weight."

293
Drupal Handbook 3 Aug 2007

Each time you add a field, you are asked to specify its "category." This allows you to divide each
user’s profile into more than one section. For example, you might divide the profile into two
sections, one on "Community interests," the other on "Professional skills." So as you define each
field, you assign it to one of these two categories. Drupal will then typically display each user’s
profile page with two separate sections--one for "Community interests," another for
"Professional skills"--each with its own set of information, derived from the fields you have
defined and your user has filled in.

You can mark a field as being required ("The user must enter a value"). And you can specify that
when new users register, a field be shown for them to fill in.

If both the profile module and the menu module are enabled, from the Menus page (administer
>> menus) you can enable on the Navigation Menu the item User list. This will take people to a
page where they can see a list of your users. A person who has permission can click on the name
of any user in the list to view that user’s profile.

The option to show this menu item may be disabled by default, but you can enable it. (And you
can rename "User list" to whatever you wish.) You can also place a link to the User list among
your site’s primary and secondary links, or on any other menu as well. (Click "add menu item,"
and when you fill in the "path" field on the dialogue page just enter "profile.")

On the permissions page (administer >> access control) you can decide who is normally allowed to
view the user profiles. (You’ll find the permissions for profiles under "user module.") In any
case, the profiles are always accessible to your site administrators.

Contributed modules can also deploy the fields in user profiles to do much more with them. Such
modules, for example, can help community-based sites identify and organize users through their
profile fields.

You can

view user profiles.
administer profile settings: administer >> settings >> profiles.

Enabling user pictures (avatars)
Note that user pictures (or avatars) or pictures are part of the user.module, not the profile
module.

1. Navigate to the administration area for user module configuration page under administer »
users » configure
2. In the Pictures

settings, for Picture support, select Enabled (Enable picture support.)

Note: you must write in your directory name. Make sure the directory is created and make
sure you have that directory has write permissions (that is, chmod to 755).
Click ’save configuration’

294
3 Aug 2007 Drupal Handbook

Drupal 4.7 allows you to enable avatars at administer » settings » users
(admin/settings/user).

HOWTO: Create new profile fields
1. Enable the profile module:
2.
In administer » modules select in the ’Enable’ column where you see:
profile | Support for configurable user profiles.
3. Create new fields or edit existing ones:
4.
Navigate to the administration area: administer » settings » profiles
Select a form field type under ’Add new field’
Follow onscreen instructions for configuring this field, and ’save field’.

HOWTO: Make a field part of the registration process
This information is pertaining to Drupal 4.6.3.

To make a field part of the registration, perform the following steps:

1. Go to: administer >> settings >> profiles.
2. Create the profile field if it doesn’t exist yet, and as follows:
3.
Under the ’add new field’ section, choose the type of field you want to create by
clicking its link.
Provide the particulars for the field, namely category, title, form name, explanation,
weight, visibility and page title.
Now check whether the field may or may not be left empty.
To make it appear on the registration page, make a checkmark in the ’Visible in user
registration’ checkbox.
4. Click on the ’Save field’ button.

Your new field will now appear on the registration page.

Form Validation in plugin
check for $type="validate" in plugin
set errors via form_set_errors() to validate the required fields in registration form

HOWTO: Create a ’country’ profile field
This page describes how to create a ’country’ field in your users’ profiles, similar to the one on
Drupal.org, that lets you easily find users in any country.

295
Drupal Handbook 3 Aug 2007

1. Create a new profile field.
2. Go to the profile settings page (administer > settings > profiles ?q=admin/settings/profile)
3. Select the ’list selection’ type of form field.
4.
Category (required): It can be a category you already have or a new one. (Suggested:
Personal Information)
Title (required): Anything is OK. (Suggested: Country)
Form name (required): Anything is ok, as long as it is unique. (Suggested:
profile_country)
Explanation (optional): Usually, country is self explanatory, but you may want to write
a note here to your users about this field.
Selection options: Copy the list from the attached file here. This file is from Wikipedia
(http://en.wikipedia.org/wiki/List_of_countries May 2006)
Weight: Select whatever you like (this is the weight in the category selected above).
Visibility: Select one of the ’Public Field’ options.
Page title (required): You must put something here. (Suggested: People who live in)
Check boxes: Check ’the user must enter a value’ to make this field required. Check
’visible in user registration form’ to make it part of user registration.
5. Click on ’Save field.’

CiviCRM: Tags, Profiles, Groups, advanced community
member management
CiviCRM’s Profile functionality allows you to integrate and extend Drupal User screens with
your contact management requirements. It also gives you tools for collecting and sharing contact
information with community members and visitors.

You can:

configure user registration forms to include standard and custom CiviCRM fields
allow users to maintain some or all of their own contact data and find other contacts with
shared characteristics
make a subset of CiviCRM data available for searchable listings
create custom ’sign-up’ forms to collect contact information from site visitors

More information:

CiviCRM Quickstart - Website Integration
Configuring CiviCRM Profiles

296
3 Aug 2007 Drupal Handbook

Search: an internal site search system
The search module lets users search for specific content on your site. You can search both for
users and for particular words.

With a regular search, if you enter more than one search term the search module will look for
content that has all the terms you’ve entered. If instead you want either one term or another, join
your terms with "or." If you’re looking for an exact phrase, enclose it in quotation marks.

With Advanced Search you can also look for "any of these words" or "this phrase," or both, you
can rule out words you don’t want, and you can choose content types within which to confine
your search.

You can enable the search module on the modules page (administer >> modules).

Drupal’s search engine indexes the text of your site and the names of your users. You can tweak
the way it does this.

The search engine does its indexing at intervals you choose by setting "cron runs." Cron (which
stands for chronograph) is not a part of Drupal. It’s a scheduler that resides on your server and
runs tasks (called "cron jobs") at intervals, which you specify. The jobs can run weekly, daily,
hourly, or whatever you like.

What you want to do is schedule a "cron job" that has a browser on your server regularly visit
your "cron page." For instance, if your site were www.example.com your cron page would be
http://www.example.com/cron.php. (This page is automatically set up for you when you install
Drupal.)

Whenever such a visit occurs, the search engine will take up the work of indexing. You need to
set up those cron runs before your search engine will work.

For a modest personal site to which you post now and then, you might set up such a cron job to
run once a day. For a more active site you’d likely want to run that job more often--perhaps
every few hours or every hour.

With Linux or Unix you can schedule your cron jobs by setting up what’s called a "crontab."
(You might rely on helper programs like C-Panel to make setting up your cron jobs easier.)

For further guidance on cron you can see Drupal’s handbook page configuring cron jobs (or, if
your server is running Windows, configuring Windows cron jobs). Your hosting company may
also help guide you.

On your settings page for Search (administer >> settings >> search) you can limit how many items
should be indexed in a single cron run. This can help keep your system from getting overloaded
with work. (If you get a message that cron is timing out or PHP is running out of memory, lower
the number of items to index per run.) You also have a few more search settings you can choose.

297
Drupal Handbook 3 Aug 2007

If both the search module and the menu module are enabled, from the menus page (administer >>
menus) you can enable on the Navigation Menu the item Search. The option to show this menu
item may be disabled by default, but you can enable it. (And you can rename "Search" to
whatever you wish.)

You can also place a link to Search among your site’s primary and secondary links, or on any
other menu as well. (Click "add menu item," and when you fill in the "path" field on the dialogue
page just enter "search.")

On your blocks page (administer >> blocks) for most themes there’s also a Search form you can
enable, and you can choose where you want it to display.

On your access control page (administer >> access control) you can decide who can do searches and
who can administer the search settings.

A technical note: To use the search module the database user needs the create temporary table
permission. If you seem not to have it, ask your systems administrator to make sure it’s granted
to you.

You can

read about how your site uses cron in the administer >> help >> system.
run your cron job manually at your sites cron page.
read about configuring cron jobs.
configure search at administer >> settings >> search.

Add searching to your custom module
In order to have a custom module be searched the module must support the search hook. Read
the Drupal API for the hook_search.

Statistics: tracking referrers, page hits, etc.
The statistics module keeps track of numerous statistics of site usage. It counts how many times,
and from where each of your posts is viewed. The statistics module can be used to learn many
useful things about how users are interacting with each other and with your site.

Statistics module features

Logs show statistics for how many times the site and specific content on the site has been
accessed.
Referrers tells you from where visitors came from (referrer URL).
Top pages shows you what’s hot, what is the most popular content on your site.
Top visitors shows you the most active visitors for your site and allows you to ban abusive
visitors.
Recent hits displays information about the latest activity on the site.

298
3 Aug 2007 Drupal Handbook

Node count displays the number of times a node has been accessed in the node’s link
section next to # comments.

Configuring the statistics module

Enable access log allows you to turn the access log on and off. This log is used to store data
about every page accessed, such as the remote host’s IP address, where they came from
(referrer), what node they’ve viewed, and their user name. Enabling the log adds one
database call per page displayed by Drupal.
Discard access logs older than allows you to configure how long an access log entry is
saved, after which time it is deleted from the database table. To use this you need to run
cron.php
Enable node view counter allows you to turn on and off the node-counting functionality of
this module. If it is turned on, an extra database query is added for each node displayed,
which increments a counter.
Display node view counters allows you to globally disable the displaying of node view
counters.

You can

administer statistics administer >> setttings >> statistics.
access statistics logs administer >> logs.
view recent hits administer >> logs >> recent hits.

Story: post static pages
The story module is used to create a content post type called stories. Stories are articles in their
simplest form: they have a title, a teaser and a body. Stories are typically used to post news
articles or as a group blog.

The story administration interface allows for complex configuration. It provides a submission
form, workflow, default view permission, default edit permission, permissions for permission,
and attachments.

You can

post a story at create content >> story.
set workflow and other global story settings at administer >> settings >> content types >>
story.
control who can create and edit stories at administer >> access control.

System: cron and caching
The system module provides system-wide defaults for running jobs at particular times, storing
(caching) web pages to improve efficiency, and performing other essential tasks. The module
also keeps track of various preferences you give for how you want your system to behave.

299
Drupal Handbook 3 Aug 2007

Some of Drupal’s modules require regularly scheduled actions. The statistics module
periodically cleans up logfiles. The aggregator module periodically updates feeds. Ping
periodically notifies services of new content on your site. Search periodically indexes your site’s
content. All of these services rely on cron.

Cron (which stands for chronograph) is not a part of Drupal. It’s a scheduler that resides on your
server and performs tasks (called "cron jobs") at intervals, which you specify. The jobs can run
weekly, daily, hourly, or whatever you like.

What you want to do is schedule a "cron job" that has a browser on your server regularly visit
your "cron page." For instance, if your site were www.example.com your cron page would be
http://www.example.com/cron.php. (This page is automatically set up for you when you install
Drupal.) This regular visit to your cron page will help keep your system running smoothly.

For a modest personal site to which you post now and then, you might set up such a cron job to
run once a day. For a more active site you’d likely want to run that job more often--perhaps
every few hours or every hour.

With Linux or Unix you can schedule your cron jobs by setting up what’s called a "crontab."
(You might rely on helper programs like C-Panel to make setting up your cron jobs easier.)

For further guidance you can see Drupal’s handbook page configuring cron jobs (or, if your
server is running Windows, configuring Windows cron jobs). Your hosting company may also
help guide you.

The system module’s caching mechanism stores dynamically generated web pages in a cache--a
stockpile--and reuses them. The pages on your site, rather than being never-changing sets of text
and images, are all (or nearly all) likely to use elements pulled together "on the fly" from various
parts of your database. Such pages are said to be "dynamically generated."

By caching such pages, the system module keeps them ready to use again, instead of having to
create them again each time someone wants to view them. This way, displaying a page takes
only one database query instead of several. Queries take time and system power, so caching
lightens the load on your system and lets it respond more quickly.

Only pages requested by anonymous users are cached. To reduce server load and save
bandwidth, the system module stores and sends cached pages compressed.

You can

run your cron job manually at your site’s cron page.
read about configuring cron jobs.
administer cache settings in administer >> settings in the Cache settings area.

300
3 Aug 2007 Drupal Handbook

Configuring cron jobs
Some modules require regularly scheduled actions, such as cleaning up log files. You can make
these happen automatically by using cron.

Cron, which stands for chronograph, is not a part of Drupal. It’s a command scheduler that
resides on your server and executes commands at intervals, specified in seconds. You can use it
to control the execution of daily, weekly or monthly jobs (or anything with a period measured in
seconds). These tasks are called "cron jobs."

What you want to do is schedule a "cron job" that tells a web browser on your server, such as
lynx or wget, to regularly visit your "cron page." For instance, if your site were www.example.com,
your cron page would be http://www.example.com/cron.php. (This page is automatically set up for
you when you install Drupal.) This regular visit will automatically tell Drupal to perform its
periodic tasks, and this will help keep your system running smoothly.

For a modest personal site to which you post now and then, you might set up such a cron job to
run once a day. For a more active site you’d likely want to run that job more often--perhaps
every few hours or every hour.

With Linux or Unix you schedule your cron jobs by setting up what’s called a "crontab." (You
might rely on helper programs like C-Panel to make setting up your cron jobs easier.)

Your crontab might look like this:

45 * * * * /usr/bin/lynx -source http://example.com/cron.php

or

45 * * * * /usr/bin/wget -O - -q http://example.com/cron.php

This would have a browser (lynx or wget) visit your cron page 45 minutes after every hour. (At
the start of the hour your site may receive a lot of traffic from other sites aggregating your
content via RSS. So running your cron job earlier helps the job avoid that traffic.)

To set up a cron job on Windows read configuring Windows cron jobs.

Suppose your hosting company doesn’t allow you to set up crontab entries.

You can ask the company to let you. Sometimes that’s all you need to do.
You can ask someone else with access to the internet to set up an entry for you. After all,
virtually any Unix/Linux machine with access to the internet can set up a crontab entry to
regularly visit http://example.com/cron.php.
You can use a webcron service (for example, http://www.webcron.org) to set up cron jobs
through a web interface.
If you can’t run cron yourself or find someone to do it for you, consider the poormanscron
module.

301
Drupal Handbook 3 Aug 2007

Cron doesn’t guarantee your commands will run at the specified interval. But Drupal will try its
best to come as close as possible. The more you visit cron.php, the more accurate cron will be.

Some guidelines of a more technical nature:

Take a look at the example scripts in the scripts directory. Make sure to adjust them to fit
your needs. For example, the cron-lynx.sh file contains the line:

/usr/bin/lynx -source http://example.com/cron.php > /dev/null 2>&1

Enter:

whereis lynx

from your shell to make sure lynx is located at /usr/bin/lynx (if not, adjust the path as needed).
Also change http://example.com/cron.php to the location of your Drupal installation (for
instance, http://www.example.com/drupal/cron.php).

A good crontab line to run this cron script once every hour would be:

00 * * * * /home/www/drupal/scripts/cron-lynx.sh

Note that it is essential to access cron.php using a browser on the web site’s domain; do not
run it using command line PHP directly and avoid using localhost or 127.0.0.1 or some of
the environment variables will not be set correctly and features may not work as expected (for
example, the Drupal module).

If your host doesn’t give you permission to use a browser such as wget or lynx, there is also a
script in Drupal’s /scripts/ directory called cron-curl.php which uses curl instead. It’s also
possible to write a simple PHP script which simulates a browser accessing your website’s
cron.php (using curl, fopen, or similar), and write a cron configuration which calls that instead.

Configuring cron jobs on DreamHost
I culled this info from the Dreamhost knowledgebase:

How do I set up a cron job?

Via the "crontab" command from the shell.

crontab -l will show you your currently set up cron jobs on the server.
crontab -r will delete your current cron jobs.
crontab -e will allow you to add or edit your current cron jobs by using your default text
editor to edit your "crontab file".

Your crontab includes all the cron jobs you’d like, with one cron entry per line. A cron entry
looks like this:

302
3 Aug 2007 Drupal Handbook

45 2 * * * /home/user/script.pl

The first number is the minute of the hour for the command to run on.
The second number is the hour of the day for the command to run on.
The third number is the day of the month for the command to run on.
The fourth number is the month of the year for the command to run on.
The fifth number is the day of the week for the command to run on.

Here are some examples to help you learn the syntax for the numbers:

32 * * * * : will be run every hour on the 32nd minute.
12,42 * * * * : will be run twice an hour on the 12th and 42nd minutes.
*/15 */2 * * *: will be run at 0:00, 0:15, 0:30, 0:45, 2:00, 2:15, 2:30, ...
43 18 * * 7: will be run at 6:43pm every Sunday.

You can also edit crontab on a local file. Upload it to a directory and run:

crontab YourFileName

It’ll replace your crontab with what’s on the text file, without having to edit it online. This is
useful if you’re using a telnet client which doesn’t support ANSI control codes (such as the
Windows’ one) and can’t understand what the heck is going on on the editors.

In my own experience, I found that only by entering one cron command per line worked (one
line each for :10, :20, :30, etc.). I could not get crontab to take the "*/15" argument, so I worked
around it. Also, if you have ANY character after the last command (space, CR, whatever) the file
will not take.

I like this file-load approach because I have a basic command file to edit or call up again if
needed. Afterwards, running crontab -l will confirm that the job did take.

I hope this helps people making new installations.

--

Cron Job configuration line by line
1. start your shell.

2. type crontab -l to see current jobs for site.

3. verify if lynx was set up on your server under /usr/bin

4. edit scripts/cron-lynx.sh putting in the direct address of your cron.php file.

5. create and edit a new text file cron.txt with your settings:

303
Drupal Handbook 3 Aug 2007

e.g.,

55 23,5,11,17 * * * /home/accountname/public_html/drupal/scripts/cron-lynx.sh

(a cron run every 11:55pm, 5:55am, 11:55am, 5:55pm)

6. import this script into crontab by typing crontab cron.txt

7. type crontab -l to see your new jobs for site.

Voila, much easier than I thought!

Cronjobs without wget/lynx or curl
Some of you might have trouble getting lynx or wget to work. This may be the case if "localhost"
is not permitted.
Then wget, lynx or curl won’t work on the local machine. If you are not willing to depend on
others to perform cronjobs and you dislike poormans cron, try this script.
touch ~/scripts/cron-php.sh
chmod 700 ~/scripts/cron-php.sh
vi ~/scripts/cron-php.sh

#!/bin/bash
#
# Simple cron script for those who cannot
# use wget, lynx or curl because the host
# closed the localhost loop.
#
# Usage:
# - put this file in the ~/scripts dir
# - add a cronjob pointing to this script
#
# Copyright OCS - 2006
# This script is provided under the GPL.
#
# v 0.1 original release
#
#############################
# CONFIGURATION OPTIONS
#############################
# Complete local path
#
# Set the complete local path
# to where the cron.php file
# is (ie the root path)
# Default is /var/www/html/
root_path=/var/www/html/
# Complete php path

304
3 Aug 2007 Drupal Handbook

#
# Set the complete path
# to the php parser if
# different from standard
parse=/usr/bin/php
##############################
# END OF CONFIGURATION OPTIONS
##############################
cd $root_path
if [ -e "cron.php" ]
then
$parse cron.php
if [ "$?" -ne "0" ]
then
echo "cron.php not parsed."
else
echo "cron.php has succesfully been parsed."
fi
else
echo "cron.php not found."
exit
fi
exit
and then the crontab itself:
crontab -e
* * * * * ~/scripts/cron-php.sh > /dev/null 2>&1

where ~ is the directory where your drupal install is (the script defaults to /var/www/html/
but your professional hosting company will probably use /home/your.domain.tld/www

Configuring cron jobs on Windows
To setup a Windows machine to run cron.php at a specific time follow the specific instructions
below. This can be useful if you are not familiar with Linux/Unix, or if your web host does not
offer the ability to run cron jobs; you can run them remotely from your own computer.

Note: These instructions were written for Windows XP but should be similar in other versions of
Windows.

Creating a Scheduled Task

1. Open Scheduler
2. Go to Start > Programs > Accessories > System Tools > Scheduled Tasks
3. Double-click Add Scheduled Task
4. The Scheduled Task Wizard will appear. Click Next.
5. Select the program to run. Choose your browser from the list (for example, Internet Explorer
or Mozilla Firefox). Click Next.

305
Drupal Handbook 3 Aug 2007

6. Give the task a Name, such as Drupal Cron Job, and choose the Frequency with which to
perform the task (for example, Daily)). Click Next.
7. Choose specific date and time options (this step will vary, depending on the option selected
in the previous step). When finished, click Next.
8. Enter your password if prompted. Change the username if required (for example, you’d
like the task to run under a user with fewer privileges security reasons). Click Next.
9. On the final page, select the checkbox Open advanced properties for this task when I click
Finish and click Finish.

Configuring the task

1. Go to the task’s setting page either by checking the checkbox at the end of the last step, or
by double-clicking on the task.
2. In the Run box, after the text that is there now (for example,
C:\PROGRA~1\MOZILL~1\firefox.exe), enter a space and then type the address to your
website’s cron.php page in double quotations (for example,
C:\PROGRA~1\MOZILL~1\firefox.exe http://www.example.com/cron.php
3. To set a frequency more often than Daily (for example, hourly), click the Schedule tab, then
click Advanced. Here you can set options such as Repeat task, every 1 hour for 23 hours.
Click Ok when finished.
4. Change the start time on the task to one minute from the current time. This will allow you
to test the task and make sure that it is working.
5. When all settings have been configured to your liking, click Apply and OK (note: you may
be prompted for your password)

Command-line version

Another way to perform the above commands is by using the schtasks (or at in Windows 2000)
command from the command line. To duplicate the example above, which runs Firefox hourly
to execute http://www.example.com/cron.php, open a command prompt (Start > Programs >
Accessories > Command Prompt) and enter:

schtasks /create /tn "Drupal Cron Job" /tr
"C:\PROGRA~1\MOZILL~1\firefox.exe http://www.example.com/cron.php" /sc
hourly

Enter your password if prompted.

Throttle: congestion control
The throttle module provides a congestion control throttling mechanism for automatically
detecting a surge in incoming traffic. If the site gets linked to by a popular website, or otherwise
comes under a "Denial of Service" (DoS) attack, your webserver might become overwhelmed.
This mechanism is utilized by other modules to automatically optimize their performance by
temporarily disabling CPU-intensive functionality. For example, in the site theme, you might
choose to disable pictures when the site is too busy (reducing bandwidth), or in modules, you

306
3 Aug 2007 Drupal Handbook

might choose to disable some complicated logic (reducing CPU utilization).

The congestion control throttle can be automatically enabled when the number of anonymous
users currently visiting the site exceeds the specified threshold. The congestion control throttle
can be automatically enabled when the number of authenticated users currently visiting the site
exceeds the specified threshold.

You can

enable throttle for modules at administer >> module.
enable throttle for blocks at administer >> block.
administer throttle at administer >> settings >> throttle.

When to use the throttle module?
The throttle is useful to sites that have limited resources and usually are not that busy. It is
actually less useful to consistently high-traffic sites, as by necessity they will already have the
required infrastructure to survive high loads.

The throttle works well for a website that’s on a shared host with limited CPU and bandwidth,
that usually only gets a handful of visitors, and then is suddenly Slashdotted. Of course, it will
only help in that case if it has been enabled and properly configured.

Tracker: viewing new and updated content
The tracker module displays the most recently added or updated content to the website allowing
users to see the most recent contributions. The tracker module provides user level tracking for
those who like to follow the contributions of particular authors.

The "recent posts" page is available via a link in the navigation menu block and contains a
reverse chronological list of new and recently-updated content. The table displays the content
type, the title, the author’s name, how many comments that item has received, and when it was
last updated. Updates include any changes to the text, either by the original author or someone
else, as well as any new comments added to an item. To use the tracker module to watch for a
user’s updated content, click on that user’s profile, then the track tab.

You cannot administer this module. There are no configuration options.

You can

view the most recent posts.
view user profiles and select the track tab.

307
Drupal Handbook 3 Aug 2007

Upload: collaborate with files
The upload module allows users to upload files to the site. The ability to upload files to a site is
important for members of a community who want to share work. It is also useful to
administrators who want to keep uploaded files connected to a node or page.

Users with the upload files permission can upload attachments. You can choose which post
types can take attachments on the content types settings page. Each user role can be customized
for the file size of uploads, and the dimension of image files. Note: you must first give a user role
upload permissions before you can customize some of these settings.

You can

enable/disable uploads for individual content types at administer >> settings >> content
types.
administer storage location of uploaded files at administer >> settings in the File system
settings area.
configure file size, number of files, and other user role defaults at administer >> settings >>
upload.
control who can upload and view attached files at administer >> access control.

The maximum upload size is controlled by your PHP environment. The standard PHP default is
2 MB. If you need to alter this, see the handbook page on how to Increase upload size in your
php.ini.

User: access and management settings
The user module allows users to register, log in, and log out. Users benefit from being able to
sign on because this associates content they create with their account and allows various
permissions to be set for their roles.

The user module supports user roles, which can be set up with fine-grained permissions
allowing each role to do only what the administrator permits. Each user is assigned one or more
roles. By default there are two roles: anonymous (a user who has not logged in) and authenticated
(a user who has signed up and been authorized).

Users can use their own name or handle and can fine tune some personal configuration settings
through their individual my account page. Registered users need to authenticate by supplying
either a local username and password or a remote username and password, such as a
DelphiForums ID or an ID from a Drupal-powered website.

A visitor accessing your website is assigned a unique ID, the so-called session ID, which is
stored in a cookie. For security’s sake, the cookie does not contain personal information but acts
as a key to retrieving the information stored on your server.

308
3 Aug 2007 Drupal Handbook

You can

view your user page.
administer users at administer >> user.
create new users at administer >> user >> add user.
configure user registration, user email, and user picture settings at administer >> settings
>> user.
allow users to select themes from their user account by enabling themes in administer >>
themes.
read user profile help at administer >> help >> profile.
configure access permissions at administer >> access control.

Access Permissions reference
(This page is a work in progress. If you know what some of these do, please add a comment and
I’ll fold it in.)

block module
administer blocks
use PHP for block visibility

filter module
administer filters

menu module
administer menu

node module
access content
Allows the user to view content. This should be enabled for all users, unless you want a
private site.
administer content types
Allows the user to edit and add content types at /admin/content/types.
administer nodes
Allows the user to create, edit, and delete nodes of all types. This overrides all the
create/edit own/edit options for specific content types below. This also exposes the
’Publishing options’ section when editing nodes, allowing users to promote content to the
front page, publish and unpublish, make sticky, and create new revisions.
create [TYPE] content
Allows the user to create content of this type. This permission exists for page and story and
each additional content type defined on the site. Overridden by the ’administer nodes’
permission.

309
Drupal Handbook 3 Aug 2007

edit own [TYPE] content
Allows the user to edit content of this type that they have created. This permission exists for
page and story and each additional content type defined on the site. Overridden by the
’administer nodes’ permission.
edit [TYPE] content
Allows the user to edit all content of this type. This permission exists for page and story and
each additional content type defined on the site. Overridden by the ’administer nodes’
permission.
revert revisions
view revisions

path module
administer url aliases
allows users the ability to administer the url aliases (modify, add, remove)
create url aliases
allows users to create url aliases

user module
access user profiles
Can see user profiles; users without this set don’t see links on user names.
administer access control
Get the admin menu items Access control, Access rules, Roles added to navigation and able
to make changes there.
administer users
Get the admin menu item Users -- can list all users, activate accounts, but NOT set roles.
change own username
what it says on the tin

system module
access administration pages
allows users access to the admin path
administer site configuration
allows users to access the site configuration area of the admin panel
select different theme
allows users to change the theme from their profile.

Access rules (email filters)
Some of us know about a few CMS’s where the administrator can filter the incoming email
registrations. For instance, you could register with your@institution.edu, but not with
your@gmail.comor your@yahoo.com.Here’s how you do it:

310
3 Aug 2007 Drupal Handbook

Add an ACCESS RULE by going to ADMINISTER -> ACCESS CONTROL-> ACCESS RULES
[for Drupal 4.7.4].

Then add 2 email address rules:

Deny %@% (which should block everyone) and Allow %@allowed.com(which will allow people
with anyone@allowed.com). That’s pretty much all there is to it. Have fun with Drupal!

Managing access control with permissions and user roles
Roles, a way of assigning specific permissions to a group, allow you to fine tune the security, use
and administration of Drupal. Users assigned to the role, or group, are granted those
permissions assigned to the role. Common examples of roles used with which you may be
familiar include: anonymous user, authenticated user, moderator, and administrator.

By default, Drupal automatically defines two roles as a part of site installation:

anonymous user -- readers of the site who are either do not have an account or are not
logged in.
authenticated user -- the role assigned to new accounts on a Drupal site.

The anonymous user role should typically have the least access to the site of all roles.
Authenticated users, because they took the time to register, might be given more permissions,
such as the ability to create some types of content. If administrator approval is required for new
users, or if they match certain criteria (such as having a company email address), you may be
able to grant more permissions that way.

The first Drupal account created on a new installation, sometimes referred to as the "root user",
always has full permissions for all Drupal activities, including administration and content
creation, editing and removal.

More trusted users might be granted special privileges through an administrator-created role,
and must be manually added to that role through the user administration interface. To create
new roles:

1. Click administer >> access control >> roles tab.
2. Enter a label for the new role in the available text field at the bottom of the current list of
roles.
3. Once you’ve added the role, select the permissions tab.
4. Your new role will be listed as a new column in the permission matrix. Grant permissions to
the new role.
5. To add users to this role you will need to edit individual user accounts. Click administer >>
users and the edit link for the user you wish to add to the role. Then you can add this user to
your new role under the Roles section of the user edit page.

311
Drupal Handbook 3 Aug 2007

Note: Although all roles you create yourself receive any permissions you give to authenticated
users automatically, neither roles you create yourself nor the authenticated user role receives
permissions given to anonymous users. If you check any of the permissions boxes for
anonymous users in the access control page, you should almost always also check the equivalent
box for authenticated users to avoid odd site behavior.

Assigning permissions and users to roles
Access to almost all Drupal modules can be controlled by either enabling or disabling
permissions for a given role. As a security precaution, the anonymous and authenticated users
are configured with very minimal permissions during a site install. You’ll have to consider
which permissions to enable.

Go to the permissions administration page (administer >> access control >> permissions tab to
begin enabling or disabling permissions. Consider the following descriptions of permissions:

Administer -- Administer permissions, such as administer content and administer users, are
usually reserved for the most trusted site users. These administration privileges grant users
extensive control of the specific module(s) described by the permission title. For example,
when administer permissions are granted on modules associated with specific node types,
the user will be able to edit and delete all content for that node type on the entire site.
Reminder: you’ll have to assign access administration pages rights to any role which also
needs to configure site options in the administration menu.
Access -- Permissions which grant access allow users read-only rights or general use of
specific site modules, without any significant configuration privileges. Typically, these roles
do not permit the creation of content. Most access permissions are safe to assign to any user
role, although giving access administration should generally be reserved for the most trusted
users.
Create -- Allows users to create, but not necessarily edit later, the specified type of content.
Generally applies to node types.
Maintain -- These permissions generally enable a user to create content, as well as allowing
the author of the submitted content to edit their own content. If you want to allow new site
members to keep a weblog or work on the collaborative book, you’ll need to enable
maintain permissions for the authenticated user.

Taxonomy_access: Restrict user roles to access specific categories
only
Access to content can be restricted by category using the Taxononmy Access:
http://drupal.org/project/Modules/taxonomy_access

Adjusting permissions after adding modules
Whenever a module is enabled, even if it is merely turned off and on, permissions for that
module are unassigned to all roles. As a security precaution, an administrator always needs to
assign permissions to roles any time a module is enabled.

312
3 Aug 2007 Drupal Handbook

User authentication
Registered users need to authenticate by supplying either a local username and password, or a
remote username and password such as a jabber, Delphi, or one from another Drupal website.
See distributed authentication for more information on this innovative feature.

The local username and password, hashed with Message Digest 5 (MD5), are stored in your
database. When you enter a password it is also hashed with MD5 and compared with what is in
the database. If the hashes match, the username and password are correct.

Once a user authenticated session is started, and until that session is over, the user won’t have to
re-authenticate. To keep track of the individual sessions, Drupal relies on PHP’s session support.
A visitor accessing your website is assigned an unique ID, the so-called session ID, which is
stored in a cookie. For security’s sake, the cookie does not contain personal information but acts
as a key to retrieve the information stored on your server’s side. When a visitor accesses your
site, Drupal will check whether a specific session ID has been sent with the request. If this is the
case, the prior saved environment is recreated.

Make a Drupal site use Basic Auth/ldap instead of the normal login
block
This is a module I wrote for Drupal 5.0 to take care of authenticating, where the webserver has
already done the user authentication via Basic Auth. In my case the user logged in via Basic
Auth is also available as a user in Ldap so I can pull the ’cn’ name and user thier real name as
thier Drupal name. Also auto populate the email address and keep the id the same as my
corporate assigned user id.

Enabling this module without first creating a user with admin priv with the same uid number
as assigned via ldap will result in you locking yourself out of your site as the normal login
block is totally bypassed by this module and becomes unavailable.

To speed things up, I also added a row into the users table that directly maps to my user id
obtained from basic auth. Also prevents users in large orgs with multiple John Smiths from
being assigned the same account.

Once again, this module totally bypasses the normal login block within Drupal substituting
existing webserver based basic authentication. For those interested in doing ldap authentication
WITHIN the Drupal login block, this module is not for you. Instead consider:
http://drupal.org/project/ldap_integration for this.

If you need to support Basic Auth, but don’t have hooks for ldap, considrer using this:
http://drupal.org/project/securesite or this http://drupal.org/project/httpauth

Some wierdness present. Users on first visit to site get the basic auth prompt twice, and the user
shows up as logging in twice in the logs.

313
Drupal Handbook 3 Aug 2007

I also commented out the "Log out" button in my application in user.module as it doesn’t do
anything other than adding extra lines into the logs after turning on this module.

This module works as is for me, and perhaps it will save someone attempting to do the same
thing as me some time. A good familarity with basic auth, ldap, and directly modifying the
’users’ table is probably a must.

<?php
/*
ldap_auth module
hook_init is run EVERY page load. We need to handle our own
consumption of resources or spiral to death.
*/
function ldap_auth_init() {
# if global $user has a uid already, bail as we are already logged
in.
global $user;
if ($user->uid > 0) { return; }
$user_tid=strtolower(trim($_SERVER[’LDAP_USER’]));
require_once ’./includes/common.inc’;
require_once ’./includes/theme.inc’;
$result = db_fetch_object(db_query(’SELECT u.uid,u.name FROM {users}
u WHERE u.tid = \’%s\’’,$user_tid));
# User doesn’t exist in database. Retrieve user info and add user.
if (! $result->uid) {
$ldap_server = ’directory.appl.yourcompany.com’;
$ds=ldap_connect($ldap_server);
if ($ds) {
$r=ldap_bind($ds);
$sr=ldap_search($ds, "o=yourcompany.com", "(uid=$user_tid)");
$info = ldap_get_entries($ds, $sr);
$user_mail = $info[0][’mail’][0];
$user_name = $info[0][’cn’][0];
$user_number = trim($info[0][’personalnumber’][0]);
# Use replace instead of insert to avoid errors in the event the
uid has been added ahead of time, such as in the case of the
administrators...
db_query("REPLACE INTO {users} (uid,tid,name,mail,status,created)
VALUES (%d,’%s’,’%s’,’%s’,1,%d)",
$user_number,$user_tid,$user_name,$user_mail,time());
ldap_close($ds);
} else {
drupal_set_message(t(’Unable to contact Ldap server %name.’,
array(’%name’ => check_plain($ldap_server))));
return;
}
} else {

314
3 Aug 2007 Drupal Handbook

# User exists in database. Set user info from there.
$user_name = $result->name;
$user_number = $result->uid;
}
# Log in, updating logs and redirecting to where the user requested,
or home. Good stuff stolen from persistent login module.
drupal_set_message(t(’Authenticated via Ldap. Welcome %name.’,
array(’%name’ => check_plain($user_name))));
$l = array(’ldap_auth_login’ => 1,’name’ => $user_name,’uid’ =>
$user_number);
drupal_load(’module’, ’user’);
$user = user_load(array(’uid’ => $l[’uid’]));
user_login_submit(’ldap_auth_login’,$l);
drupal_goto(substr(drupal_get_destination(), 12));
}
?>

NTLM Authentication
NTLM is a proprietary (and not so good) protocol for deploying Single Sign On in
predominantly Windows oriented networks (our company network also). NTLM sits on top of
HTTP, so users who are logged on to the Windows Active Directory network can transparently
log-on to web services using their Microsoft Windows credentials (and thereby having Single
Sign On). Getting IIS servers working with NTLM is easy (it should be), but traditionaly Apache
servers have had problems in doing this.

This document explains how to get NTLM authentication working in Drupal in Linux + Apache
boxes.

There are various methods for getting NTLM authentication working in Apache.

mod_ntlm - This is an Apache module which will add NTLM support to Apache. However,
this module is not very actively maintained, and getting it compiled and running in various
Apache versions ( and various distributions ) is a herculean task. To top it, the compilation
throws out a lot of warnings, and one tends to feel uncomfortable with it.
mod_ntlm_winbind - for boxes that have Winbind ( 1, 2 ) configured, this module can be
configured to provide NTLM authentication for Apache. However, this module is still
under development and is not well tested.

However, for the help of people working in such unfriendly conditions, there is an excellent perl
module that provides good support for NTLM authentication.

Follow the steps given below for getting NTLM authentication working.

1. Install/Configure mod_perl under Apache - (and get it working of-course)
2. Download the following files for doing NTLM authentication (the following files worked
for us)

315
Drupal Handbook 3 Aug 2007

For Fedora Core systems download the module from
http://search.cpan.org/~speeves/Apache2-AuthenNTLM-0.02/AuthenNTLM.pm
For Debian Linux systems, download the module from
http://search.cpan.org/~speeves/Apache-AuthenNTLM-2.10

Install the module
tar xvfz Apache*AuthenNTLM*.tgz
cd Apache*AuthenNTLM*
perl Makefile.PL
make
make test
make install
Edit the Apache configuration and enable KeepAlive
KeepAlive On
Restart your Apache server.
Configure apache to do the authentication. For eg in .htaccess add.
# Enable the Authentication module
PerlAuthenHandler Apache2::AuthenNTLM
# Do NTLM and basic authentication
AuthType ntlm,basic
# The name that should be displayed in the Auth box, if NTLM fails
AuthName OurCompany
# Ask for a valid user.
require valid-user
# domain pdc bdc
# Domain : Your windows domain
# pdc : Primary Domain Controller
# bdc : Backup Domain controller.
#
# Note : Multiple domains can be specified.
PerlAddVar ntdomain "OURDOMAIN domainpdc domainsdc"
# What should be the default domain
PerlSetVar defaultdomain OURDOMAIN
# The user names are in the form "OURDOMAIN\user_name". Let us split
it.
PerlSetVar splitdomainprefix 1
# Set the debug variables
PerlSetVar ntlmdebug 0
PerlSetVar ntlmauthoritative off

More documentation is available in the accompanying README file in the tarball or the
following link

Once this is done, the domain user is populated as REMOTE_USER in the http server
variables, which can be picked up by any application for doing authentication.

316
3 Aug 2007 Drupal Handbook

Now we need to enable Drupal to pick up this user id and automatically create a user. Once
we have NTLM authentication working, the user id is available as REMOTE_USER. The
WebServer Auth module can use this variable to automatically log the user in.

Download, install, enable and configure the Webserver auth module and you should have a
Drupal setup which can seamlessly integrate into Windows AD based networks.

User preferences and profiles
Each Drupal user has a profile, and a set of preferences which may be edited by clicking on the
my account link. Of course, a user must be logged into reach those pages. There, users will find a
page for changing their preferred time zone, language, username, e-mail address, password,
theme, signature, homepage, and distributed authentication names. Changes made here take
effect immediately. Also, administrators may make profile and preferences changes administer
» users on behalf of their users.

Module developers are provided several hooks for adding custom fields to the user view/edit
pages. These hooks are described in the Developer section of the Drupal Handbook. For an
example, see the jabber_user() function in /modules/jabber.module.

Using distributed authentication
Distributed authentication
One of the more tedious moments in visiting a new website is filling out the registration form.
Here at drupal.org, you do not have to fill out a registration form if you are already a member of
Drupal. This capability is called distributed authentication, and Drupal, the software which
powers drupal.org, fully supports it.

Distributed authentication enables a new user to input a username and password into the login
box, and immediately be recognized, even if that user never registered at drupal.org. This works
because Drupal knows how to communicate with external registration databases. For example,
lets say that new user ’Joe’ is already a registered member of Delphi Forums. Drupal informs Joe
on registration and login screens that he may login with his Delphi ID instead of registering with
drupal.org. Joe likes that idea, and logs in with a username of joe@remote.delphiforums.com
and his usual Delphi password. Drupal then contacts the remote.delphiforums.com server behind
the scenes (usually using XML-RPC, HTTP POST, or SOAP) and asks: "Is the password for user
Joe correct?". If Delphi replies yes, then we create a new drupal.org account for Joe and log him
into it. Joe may keep on logging into drupal.org in the same manner, and he will always be
logged into the same account.

Drupal
Drupal is the name of the software that powers drupal.org. There are Drupal websites all over the
world, and many of them share their registration databases so that users may freely log in to any
Drupal site using a single Drupal ID.

317
Drupal Handbook 3 Aug 2007

So please feel free to log in to your account here at drupal.org with a username from another
Drupal site. The format of a Drupal ID is similar to an e-mail address: username@server. An
example of a valid Drupal ID is mwlily@drupal.org.

Watchdog: monitor your site
The watchdog module monitors your system and records system events in a log you can review.
This helps you get a quick overview of activity on your site. Since the log records events in
sequence, it can also be useful for debugging site errors.

The watchdog log records errors, warnings, usage data, performance data, and operational
information. You can filter the entries ("Filter by message type") to view only a particular type of
message.

You should check the watchdog report regularly to make sure your site is working properly.

You can

view watchdog logs at administer >> watchdog.
configure the length of time logs are archived at administer >> settings in the Error handling
area.

318
3 Aug 2007 Drupal Handbook

End user guide
Welcome! This guide describes how to get started using (as opposed to administrating) a
Drupal-powered web-site. This naturally includes Drupal.org, as well as most other Drupal web
sites. The guide covers basic topics such as registering for an account, logging in, changing your
account settings, and creating content.

Drupal is a content management system. Its goal is to help users compose and present web-site
content such as articles, photos, and other content types. Drupal is a "dynamic" system; rather
than forcing users to specify a fixed, pre-declared arrangement of content, Drupal takes care of
the details of how information is arranged and presentated, and lets users focus on the actual
content to be displayed.

Most of the content on a Drupal-based site (the text of this page, for example) is stored in a
database. Text and images are submitted by filling in forms via a web browser. When visitors
view a page, Drupal gets the relevant bits of content from the database and composes all of the
components of the page in a template. This makes it easy to quickly add or change content,
without requiring knowledge of HTML or other web technologies on the part of the person
providing the content.

Depending on the configuration of the Drupal site and the user-roles you play with respect to
that site, you may be allowed to contribute or edit content. Fortunately, Drupal is designed to
make this relatively easy. Very little technical knowledge is assumed. Though details may vary
with a site’s configuration, the basic process involves these steps:

register with the site
log in by typing the user name and password supplied you in the registration step, and
create content such as articles and stories

This user guide will explain these steps and familiarize you with the basic information you need
to use Drupal successfully.

This section can also serve as a foundation for a set of instructions customized to your site’s
specific needs.

Registering as a user
To add or edit content on a Drupal site, usually you have to first be registered as a user.
(Sometimes the site administrator has chosen to enable "anonymous" posts of things like
comments, in which case you can post them without registering.)

In some cases, a site administrator will add you as a user. If so, they will send you a user name
and password that you can use to log on.

319
Drupal Handbook 3 Aug 2007

Otherwise, look for a small form called âUser loginâ on the main page of the site you want to
register with (usually on the right or the left of the page). Click the link that says "Create new
account".

The next page that comes up will generally have some information on the site’s policies for
registration. After reading them, to register, enter a user name of your choice and an email
address to which you have access and hit "submit". Then check your email account. Within a few
minutes, you should get an automatically-generated email confirming your registration and
giving you an initial password to use. Now you’re ready to log in.

Logging in
Before you can add or edit content, you usually need to log in. If you haven’t already done so,
register as a user, see above (or, if applicable, request that your site administrator register you).
Then hit the main page of the site you’re wishing to use and look for a "User login" form. This
will typically be on the left or right side of the page (it is a "block" in Drupal talk). Enter your
user name and password and hit "submit".

Assuming everything’s working as planned, when the new page loads it will include a new
block with your user name at the top. This is the menu you use to start entering and editing
content.

Changing your account settings
Once you have registered with a Drupal-based site, you can change settings to control
information about yourself and also your use and experience of a Drupal site. To see what
tweaks you can make to your account, log in and then click on my account in the navigation block
(that’s the one titled with your user name). Click on the edit tab.

Account Settings. You may see a different collection of settings than is presented here,
depending on what features have been enabled on your site.

password
Enter in a new password in both fields to set it. Drupal sends you a default password that is
often hard to remember, so it is recommended that you change your password to something
you can easily remember.
block configuration
The site administrator may make some blocks (chunks of content that are usually displayed
in a left and/or right column) optional. You can enable and disable the display of these
blocks by checking and unchecking the boxes next to them.
signature
If comments are enabled, you will be able to set a default signature. This will be copied into
new comments for you automatically, but may still be edited.
time zone
Your site administrator may allow users to set their time zone. This will cause all dated
content on the site to display in local time, according to the offset you enter here.

320
3 Aug 2007 Drupal Handbook

theme
A "theme" is the basic look and feel of a Drupal site. Sometimes a particular site will have
more than one theme installed. If the site administrator has made more than one theme
available, you will be able to select what you would like the default theme to be for your
account.

As mentioned earlier, different site-settings will cause different fields to be displayed on your
user account page. See the documentation for individual modules for instructions on how to use
these additional options.

Additional Information. Aside from the account settings tab, you may also see additional tabs,
titled according to the information they contain. Some examples might include "Personal
Information", "Workplace", etc. These are controlled by the profile module, and allows you to
enter more information about yourself. Please see the profile module for more information on
this.

Creating new content
Once you have logged-in, you’re ready to start posting content.

At the top of your personal menu, you’ll find a link called "create content". Click this and you’ll
see a list of the types of content you can create. This list reflects the privileges assigned to your
user account or to the group ("role") your account is part of.

There are several contributed modules which can assist with more complex content creation
within this framework, such as spell checking, image embedding, and file attachment uploading.

A step-by-step example
We will assume that you have selected create content and chosen "story" as a content type.

You should be looking at a form with the title "Submit story". From here, it is just a matter of
filling in the form and posting it.

Administrative options

At the top of the form you may see some administrative options. For example, there is a box
with the heading User comments. Drupal supports discussion/comments on postings--but
such comments are not always appropriate. If your article is one that could be usefully
commented on, keep the default settings: "Read/write". Otherwise, choose "Disabled".

Title

The title is straightforward enough. Try to be descriptive and catchy.

321
Drupal Handbook 3 Aug 2007

Topic: (may not be visible if you do not have categories defined)

Next comes the "Topic" menu. This is the section your article will go in--or in the technical
language of Drupal, its ("taxonomy categories"). This list presents all the sections available
on the website, with their structure. So, choose the appropriate section or sections for your
story and continue down the form to supply the body of your text.

Body

The "body" field is where you put the main content of the page. If you’ve typed this into a
word processor or HTML editor, just copy and paste it into this field. Alternately you can
just type straight in. For the most basic page, just type and leave a blank line (i.e., hit "enter"
twice) at the and of each paragraph.

You can optionally format your entry in friendly old HTML. But hey, if you’re a novice,
don’t worry--it’s not as difficult as it sounds. Here’s a quick primer:

If you want something to be bold, just enclose it in <b> or <strong> tags, like this:

<b>This text is bold</b>

<strong>This text is bold</strong>

Note that there is always an opening tag (no forward slash) and a closing tag (a forward
slash before the tag name, indicating that you are "turning it off").

To make something italic, put it in <i> or <em> tags:

<i>This is in italics</i>

<em>This is emphasized</em>

There is considerable debate about the semantic nature of the <b></code and
<code><i> tags versus the <strong> and <em> tags.

To put things nicely in paragraphs, enclose them in <p> tags:

<p>This is a paragraph.</p>

To make a bulleted list, first open a list with a <ul> tag (that stands for "unordered list"),
then put each list item in <li> (yes, for "list item") tags. Don’t forget at the end to close off
your list with a closing </ul> tag. Here’s how it looks:

<ul>
<li>This is the first bulleted item</li>
<li>This is the second bulleted item</li>
</ul>

322
3 Aug 2007 Drupal Handbook

The result is displayed below:

This is the first bulleted item
This is the second bulleted item

To add a link to you need to use the <a> (anchor) tag.

<a href="http://www.example.com">Example.com</a>

To add links to other pages within your Drupal site you do not need to add the full URL,
you can simply refer to the node like so:

<a href="/?q=node/1222">My node</a>

Note the "/" at the beginning. Also the above example is using non-clean URLs. If your site
has clean URLs enabled you can remove the ?q= so that you just have <a
href="/node/1222">My node</a>.

That wasn’t too painful, was it?

Decide where you want the "teaser" (the part of the main text used in links to the article) to
end. If you do nothing, Drupal will choose a breaking point for you -- but it’s better to
decide yourself, to make sure the breaking point is appropriate. You do this by typing in a
<!--break--> where the teaser is to end. (Your default break point is controlled by Post
Settings, found in 4.7 at administer > settings > posts and in 5 at administer > content
management > post settings.)

And you’re set! You can preview the page you’ve prepared by hitting "Preview"
(recommended, and sometimes required) or you can bravely or recklessly just go ahead and
publish it by hitting "Submit".

Controlling Teaser Location
In Drupal, you can cause the teaser to end at the point of your choosing by adding the following
to your content body:
<!--break-->

Everything above this tag will appear in the teaser (unless you place it beyond the point at
which Drupal automatically breaks the content).

Notes

Make sure there are no spaces in the tag or it will be ignored.
You can place the tag in the middle of a paragraph. The full text will not notice the tag so
the paragraph will look normal, but the paragraph will be cut short in the teaser

323
Drupal Handbook 3 Aug 2007

How to add a page to the Handbook
Depending on how Drupal is configured, different users can add book pages, such as to the
Documentation handbooks at drupal.org. The ability to create book pages is normally assigned
to "roles" in the administration area. At drupal.org, all logged-in users have the role
"authenticated user" and are allowed to add book pages.

It’s very easy to add a page. When you feel like writing a piece of documentation about a topic
that hasn’t already been addressed, just click on "Create content" link in the block under your
user name. Then click the "Book page" link. Type away in the Body. Depending on
administration settings at a web site, you may have various formatting options. Here on
drupal.org, by default you will have "filtered HTML" capability.

Give your page a short, descriptive Title.

You will have to set the correct parent to page, select it from the Parent drop-down menu.

Optionally you can add a log message to explain why you wrote the documentation.

Give your page a weight. Pages with a less heavy weight will stay at the top within the parent
section while pages with heavy weights will sink deeper.

Then preview and finally submit.

Types of content
There are various types of content that you can post using Drupal. Many of these are organized
into what are called "nodes". Basically, you can think of a node as the content of a page. This
might be, for instance, an article. Content is added or updated through web page forms. So to
add an article, you bring up a form, enter text into it (like the title and content of an article), and
hit a button to submit the form.

Topics, categories and terms
Content on Drupal websites is usually organized using categories through a system called
"taxonomy". A taxonomy has different "terms" that are used as categories for articles. When
you’re adding an article, you might find a drop-down list of topics. By selecting one, you choose
where on the site to categorize your article. If this seems hard to relate to, you can think of topics
as being like folders on your hard drive--they help to organize content, so that you can find
similar things in the same place.

Permissions
What types of content you can create or edit depends on the privileges assigned to the "role" or
user group that you’re a member of. In general, to find out what you can do:

324
3 Aug 2007 Drupal Handbook

On your user menu (the collection of links that has your user name as a title), look for a link
that says "create content". Click this to get a listing of the types of content you have
permission to post.
On a particular page, look for links at the bottom of an article. These links say things like "12
comments" (if there are comments that have been made on the article) and "read more" (if
you’re looking at a short version of an article). If one of these links say "administer" or
something like "edit this page", you have permissions to edit that type of content.

Moderation and the submission queue
Some Drupal sites are set up so that when you submit content it goes into a "submission queue".
Content in this queue is read by other users who have a moderator role on the site. They will
review the content and, if it is accepted, "publish" your contribution.

Note that moderation has been removed from core as of Drupal 5 and can be accomplished with
modules such as modr8.

Creating comments
Comments allow users to interact with the content on a site, to respond to an article, offer their
own ideas, make additions, or supply a critique.

Leaving comments

When you bring up an article to read, look for comment-related links at the bottom of the
article. If you’re not logged in, this might read "login or register to post comments". When
you do log in, you should see something like "Add new comment". Click on the link and
you’re ready to comment away.

Etiquette

Comments can be a great way of enriching a community site--but they can also lead to
unfriendly, even harassing exchanges. As with any communication, it’s important to try to
ensure that your comments are respectful and constructive.

"Threaded" comments

Comments on a Drupal web-site are "threaded". This means you can comment directly on
an article--or you can reply to an existing comment. If you reply, your comment will be
indented to show that it is part of that discussion.

Alternative ways to enter content
Drupal’s built-in form-based content editing approach is fine for many applications, but if you
have a lot of text to create, or you wish to convert existing content, or if you are using a
specialized content type such as a blog, it may be more convenient to use other approaches to
enter content into your Drupal-based site.

325
Drupal Handbook 3 Aug 2007

Preparing your content offline suggests some ways to use familiar software on your computer to
create or edit content before submitting it to Drupal.

Depending on what’s available on your site, you might even be able to enter new articles
without ever logging on to the site.

Drupal includes functionality for "blogging"--creating "blogs" or web-based journals with the
BlogAPI module. If this functionality is enabled on your site, you may be able to input and edit
content using one of a number of desktop "blog" software packages. These allow you to simply
type in content, hit a "post" button, and have your content automatically loaded onto your site.

In fact, blogging software can be used for more than blogs--it can allow you to post content
easily and quickly to almost any part of a website. Some examples of software you can use are:

Examples of applications that work with Drupal from the desktop include the following:

Ecto - Windows/Mac
MarsEdit - Mac
MS Word 2007 - Windows

In addition to desktop blogging tools, other services like Flickr’s "post to blog", Firefox plugin
Scribefire and Google Docs should work with your Drupal site.

Before trying out one of the blogging programs, you might want to check with your site’s
maintainer to make sure it accepts blog posts. The key question to ask is: "Is the BlogAPI
enabled?" If the answer is yes, you’re ready to roll. If not, you could request that it be enabled to
allow you quick updates.

HOWTO: Posting and editing blog entries with TextMate
Textmate is an editor for Apple Macintosh computers. The included Blogging bundle let you
post and edit blog entries in your Drupal blog.

As of writing to use the Blogging bundle you need to have the latest "cutting edge" release of
Textmate (Version 1.5.2 (1112)). Get it by choosing "Cutting-Edge" in the TextMate menu
TextMate > Preferences > Software Update and pressing "Check now".

1. Setup the Blogging bundle for your blog: Open a blank window and select Bundles >
Blogging > Setup Blogs. Enter the URL of your blog. Insert your username and append
xmlrpc.php to the URL, for example
http://user@yourdomain/yourpath/xmlrpc.php. Save the file.
Note: You are able to insert more than one blog entry.
2. Test the blog setup: Bundles > Blogging > Fetch post. TextMate will ask you for your Drupal
password first time you connect to the blog. It will be saved in the keychain so you have to
enter it only once. Next Textmate will present you with the last 20 blog entries you may
choose from.
3. New blog entry: File > New From Template > Blogging > Weblog Post. Write your text and
select Bundles > Blogging > Post To Blog to finally post the blog entry.

326
3 Aug 2007 Drupal Handbook

4. Choose Input Filter: the "Format:" header correlates to the Drupal Input Filters. Put a 3 there
and the blog entry will use the third Input Filter.
5. Trimmed version (Teaser): Insert <!--break--> where you want to end the trimmed version
of the blog entry.

For a longer explanation have a look at the screencast at Blogging from Textmate.

Problems so far:

Image files: insert image files into your text by dropping them in the TextMate window.
They will instantly uploaded to the blog and referenced in the text. Alas they do not appear
at the blog entry, at least not at the authors blog.
Taxonomy and vocabulary terms: It seems there is no way to insert vocabulary terms in the
blog entry yet.

Posting and editing content with w.bloggar
w.bloggar is a gratis software for Windows designed for "blogs" (web-based journals).

If you’ve confirmed that blog support is enabled, here’s some steps to get going:

Download the software from http://www.wbloggar.com/ and install.
Set up a new account. This is explained in the w.bloggar help files.

When it comes time to set the "Blog Tool" selection, choose "MovableType" (and not
"Drupal"). This is because (at time of writing) the Drupal support in w.bloggar is
outdated.
For "Host" put the domain of the website you’re using, then for "Path" put the rest of
the address, if any, followed by "/xmlrpc.php". So if the address was
"http://www.gworks.ca/site/" you would put "www.gworks.ca" for host and
"site/xmlrpc.php" for Path. The "xmlrpc.php" part is the Drupal file that handles the
blogging input.

Now you’re ready to start posting. In doing so, you can take advantage of the text formatting
functionality w.bloggar offers. When correctly set up, posting a web page from w.bloggar is as
simple as opening the program, typing in some text, selecting a category (the "taxonomy term"
to use) and hitting post.

update
It has been reported using 4.00.0193 (Mozilla version)

Configuration notesâa departure from the original postingâ¦

In w.bloggar, I selected âDrupalâ as my blogging tool
in the account setup dialog.

327
Drupal Handbook 3 Aug 2007

In Drupal, you must enable the blogger.api module.
You don’t necessarily require blog module. I’m only
using âstoryâ nodes, so I didn’t enable blog module.
After enabling blogger.api, go to settings >> blogger.api and:
check off the content type you wish to
edit via the API. In my case, it’s âstoryâ.
change the XML-RPC engine to âMetaWeblogâ.

Posting content with mailhandler
If the BlogAPI doesn’t meet your needs you should consider using the contrib mailhandler
module to submit content.

Preparing content offline
Before posting directly to a site, you may want to start in a word processing program. Potential
advantages include:

Saving time online. This is a particular consideration if you’re on dial-up.
Access to spell-check and other editing features.

Depending on how much formatting you wish to do, you could also consider using an HTML
editor. These include, for instance, the "composer" that comes with Mozilla and Netscape. Here
are the steps involved:

Type or copy and paste your text into the HTML editor.
Apply formatting as desired (e.g., bold, italics).
Bring up the HTML (encoded) view of the text.

This HTML is what you’ll copy and paste into Drupal’s input form, to have formatted copy.

Editing and deleting content
To edit or delete existing content, log in and then bring up the page you wish to edit. Look on
the page for an "edit" tab. Depending on your user permissions, you might see this on all pages
or only on certain ones. For example, on Drupal.org, you should see the edit tab for those pages
that you submitted.

Clicking the edit tab will bring up a page with a form for changing the page. Here you can
change the text and settings. Once you have the text and settings in a suitable form, click on the
"Submit" button on the bottom of the form. Note that certain sites may be set up to require you
to "Preview" the page before you can submit your changes.

If you wish to delete the page (and you have appropriate permissions), click on the "delete"
button near the bottom of the form. You’ll get a second chance to confirm that you wish to delete
the page, or to change your mind!

328
3 Aug 2007 Drupal Handbook

Note: Because Drupal is very configurable, there may be additional ways of editing and
managing content. Please check the documentation for your installation, ask the Drupal
administrator, or consult with another user for details.

Search
The search facility is turned on or off by your site administrator. If it is on, you will see a box for
entering your search terms and a button labelled "Search". it will be on the header of the page, or
in one of the blocks on either side of the page.

Like most search facilities, enter a word or words you want to search for and click the button.

The wild card * performs the usual function of searching for âeverything that starts withâ

Multiple words are searched as A or B, i.e. it returns pages that have one or more of the words.
There is no search only for pages that have both A and B.

The search engine gives greater weight to words used in headings or highlighted. It does this by
assigning weights (multipliers) for scores of words inside certain HTML tags.

Header h1 => 21
Header h2 => 18
Header h3 => 15
Header h4 => 12
inside a link => 10
Header h5 => 9
Header h6 => 6
underlined, bold, italics => 5

You can only search on individual words, not phrases in quotes. There is no sorting by date or
other parameters.

When searching for numerical data such as dates, IP addresses or version numbers, it considers
a group of numerical characters separated only by punctuation characters to be one piece. This
also means that searching for e.g. ’20/03/1984’ also returns results with ’20-03-1984’ in them.

The dot, underscore and dash are simply removed. This allows meaningful search behaviour
with acronyms and URLs.

With the exception of the rules above, search considers all punctuation, marks, spacers, etc, to be
a word boundary.

You might also consider using Google. Start your query with "site:example.com", so you would
enter
site:example.com my search query
or use the "Search this site" button on the Google toolbar.

329
Drupal Handbook 3 Aug 2007

Beyond the basics
Drupal is designed to support many different types of website. Many changes to a Drupal site’s
functionality, appearance, and modes of interaction are easy to make via Drupal’s configuration
and extension mechanisms.

Drupal is highly configurable. The administrator of a site can enable different capabilities and
change many settings that affect the look and functionality of a site.
Drupal has a system of privileges that makes it possible to create different user roles - for
instance, member, staff, partner. Each type of user can see and do different things on the
site.
Drupal is designed to be easily extended through modules. A module is just a fancy term for
additional software you can activate or "plug in" to your web site to provide extra features
and functions. For example, you might activate the poll module to let users easily create
web-based polls. Some modules, called "core" modules, come pre-packaged with every
Drupal installation. Third party modules, called "contributed" modules, can be downloaded
separately from the Drupal website and installed on your server.
The look and feel of a Drupal site can be changed through different "themes". As with
modules, there are both core and contributed themes.

Hence, what you see on a particular Drupal site, and what you can do there, depends to a high
degree on what the site administrator(s) have chosen to present. If you require more in-depth
information about changing the way in which information is presented or how its appearance
may be configured, please see the Administrator’s guide at http://drupal.org/handbook and the
Drupal forums.

330
3 Aug 2007 Drupal Handbook

Sports
football
“is david beckham the greatest footballer ever in england??”

331
Drupal Handbook 3 Aug 2007

Best practices guidelines
If you are going to invest in the time to setup a CMS, then you should make sure you protect
your investment with some simple best practices guidelines. These guidelines are only
suggestions on things that need to be considered when managing a web site or CMS. It is up to
you to decide what is appropriate for you to implement for your sites.

Of all the guidelines, being able to successfully backup and restore your website is probably the
most important.

Back up your Drupal site
Backups are a mandatory part of running a content management system. They are your
responsibility to perform regularly and flawlessly. Here’s what you need to know about backing
up your Drupal site:

Inquire about your ISP or web host’s backup policies. Most good web hosts have a backup
plan that kicks in every 24 hours. If yours does not, it’s up to you to back up your site daily,
or find a host who will. It cannot be stressed enough that if a site’s data does not exist in
three places, it doesn’t exist at all.
In addition to your web host’s backups, do it yourself. Periodically run a separate backup
monthly, weekly, daily or whatever fits your site’s needs. Gauge the backup cycle by how
much of your user’s data you can afford to loose without all the users revolting and starting
a riot. Even if you tell yourself, "It’s no big deal", it is, and you do not want to lose content.
Date your backups. Save each one into a directory that’s titled with the date of the backup.
You do not want to be guessing which backup is the most recent one when you are trying to
recover your failed site. Panic is not conducive to a good recovery process. Save a copy of
each backup in a different location than your webserver. Remember, if data doesn’t exist in
three places, it doesn’t exist at all. If your webserver crashes, then all the backup files might
be gone too (see earlier reference to panic).

Backing up the database
Backing up and restoring a MySQL database using the command line is covered in the MySQL
Reference Manual, section 5.10. Note that the Reference Manual cited is based on MyISAM
tables. If you use InnoDB tables in your database, please pay particular attention to MySQL
Reference Manual, section 14.2.8

Backups can also be performed with a graphical utility such as PHPmyAdmin. There’s also a
FAQ on that site called "How can I backup my database or table."

Another alternative solution is to install the Database Administration module. It has the option
to backup the database tables from within Drupal itself. Note: Be careful with the permissions.

332
3 Aug 2007 Drupal Handbook

If you are using a database other than MySQL, that vendor’s documentation should have
backup information. For a list of even more methods, consult the Handbook pages in the
Upgrade Guide as well.

Backing up the core files
The root directory of your installation contains all the files that make Drupal do its magic. Sure,
you *could* go get these files from Drupal.org again if you ever needed them, but having your
own copies of the core files is so much faster and efficient. If you’ve edited anything in the core
files for your specific website, having a copy of the core files becomes mandatory, since the site’s
changelog is part of the root directory too.

As a suggestion, everything in the root directory should be backed up monthly, but always back
up the core files before an upgrade. It’s been said before in other sections of the Handbook, but Best
Practices means that backups of the core should be a regular habit. Do this every month as
suggested, and when disaster strikes, you won’t be wondering whether you’ve made any
changes recently that have been lost forever.

Backing up the non-core files
Contributed modules and their associated third-party files should be backed up monthly as well.
If you are adhering to the Best Practices outlined in the previous section above, your contributed
modules will be part of the core files backup by default, since they exist inside a directory of the
root Drupal installation. If you do not have the bandwidth or storage resources to back up your
entire root directory each month, you must backup the /sites/all/modules/ (version 5.x) or the
/sites/example.com/modules/ (version 4.7 and lower). Failure to do this may leave you with
no clear example of which modules you had, and what versions they were. Imagine trying to
restore your site right now without knowing which versions of modules to download from
Drupal.org. Could you do it?

There are also files that are not part of the database, the core, or the contributed modules that are
important to your site. The directory you specified in Administer > Site Configuration > File
System holds uploaded pictures, user’s icons, and other stuff that you don’t want to loose. If you
are running your site in ’private’ file transfer mode, chances are good that this /files/ directory
is not inside your root Drupal installation, and therefore won’t get backed up by the procedure
outlined in "Backing Up The Core Files" above.

The /sites/ directory is another one that you should take note of, since it holds lots of things
relating to your site such as logos and embedded images. Custom themes are also stored here.

Make sure that you back these two directories up weekly, or any changes made by your users
might get lost forever. On high traffic sites, make daily backups of these two, and save the last 8
backups for safekeeping. If something goes wrong by accident, and you can bring your site back
to the same way your users left it, you will have garnered their loyalty, increased
word-of-mouth traffic for your site, and become their newest idol. You might even make it into
their blog. Yes, backups can do this for you.

333
Drupal Handbook 3 Aug 2007

Test your backups
Document and test your backup and restore procedure before you need it. The forums and IRC
chat are full of people who want help recovering from some unforeseen fatal error, and if they
knew how to restore their site using the backups they’d created, they would be in business and
making money rather than waiting for help from a Drupal volunteer.

Backup and restore using bash shell scripts
The two Bash shell scripts presented here work together automating the Drupal backup and
restore process. They work "as is" for simple installations and can be customized for multisite or
non-standard installations.

The scripts have two uses:

1. Creating Drupal backups which can be restored to their original location
e.g., restore from a failed upgrade attempt or recover from a disk failure
2. Staging data between Drupal configurations
e.g., backup a production instance and restore to a test instance

These scripts have been used successfully on and between Linux systems and on Windows
systems using Cygwin.

Functional Overview
A full Drupal backup requires data backups from both the database and file system. These two
backups must then be tied to each other.

The backup script performs a file system backup using the tar command and a database backup
using the mysqldump utility. The two backups are then combined into a single tar file. The tar is
compressed and its file name includes the backup date.

The restore script reverses the process by unpacking the file and database backups from the
container tar file and applying them to their respective targets.

The Drupal instance backed up or restored is specified by variables defined in the backup and
restore scripts.

Usage notes and cautions
Detailed usage notes are provided for each script. The following points bear highlighting:

The restore script has no safeguards against accidental restore. If you don’t understand
how it can destroy your system you are encouraged NOT to use it.
The backup script backs up every file and directory in the Drupal root directory. If you have
a hosted site with subdomain websites contained in subdirectories a backup of the main
website directory will include the subdomain websites. For backups this will only bloat

334
3 Aug 2007 Drupal Handbook

your backup file. For restores this could be disastrous, since you would restoring the file
systems for ALL of the website. If you have this kind of configuration you must customize the
tar command to make a selective backup.
These scripts make no provision to lock out users while the backup or restore is in progress.
This script does not understand Drupal multisite configurations
The backup script requires read access to all files/directories and the restore script requires
read/write access. This is sometimes a problem in hosted configurations.
Because the backup and restore is done in stages enough temporary space must be available
for the intermediate files
Some commands used in the scripts will vary between operating systems. You may have to
tailor commands for your operating system.

Site backup script
To use the script modify the variables in the Configuration block to specify the instance being
backed up.

The script will default the backup file name to value of tarnamebase appended with the date.
The default value of tarnamebase is fullsitebackup. e.g.: fullsitebackup-2006-04-14.tgz. This name
can be overridden by specifying a filename in parameter P1.

The script is run using the normal Bash script invocation for your system. e.g.:
$ sh fullsitebackup.sh
$ bash fullsitebackup.sh

You will be prompted for the database password. The backup file is placed in the same directory
the script is run from.

If multiple sites are hosted on the same system, create a copy of the script for each instance and
rename it to reflect the backup it will perform. For example, for a site named mys