Professional Documents
Culture Documents
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
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
iv
3 Aug 2007 Drupal Handbook
v
Drupal Handbook 3 Aug 2007
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
viii
3 Aug 2007 Drupal Handbook
ix
Drupal Handbook 3 Aug 2007
x
3 Aug 2007 Drupal Handbook
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
xiii
Drupal Handbook 3 Aug 2007
xiv
3 Aug 2007 Drupal Handbook
xv
3 Aug 2007 Drupal Handbook
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:
2
3 Aug 2007 Drupal Handbook
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:
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.
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.
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
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".
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
6
3 Aug 2007 Drupal Handbook
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
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
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
11
Drupal Handbook 3 Aug 2007
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.
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.
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:
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
Take note of the username, password, database name and hostname as you create the database.
You will enter these items in 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:
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.
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.
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
session.cache_limiter none
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
First, you must create a new database for your Drupal site:
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:
where
19
Drupal Handbook 3 Aug 2007
flush privileges;
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";
$base_url = "http://www.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
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
5. CONFIGURE DRUPAL
You can now launch your browser and point it to your Drupal site.
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.
22
3 Aug 2007 Drupal Handbook
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.
Development environment:
Server: LAMP
SSH/Telenet Client: PuTTY
Server Interface: WHM
Must have root access.
10 minute Install:
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.]
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:
24
3 Aug 2007 Drupal Handbook
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
Done!
Tarek : )
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
#
#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.
; 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
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.
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:
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
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
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
Downloaded the latest MySQL installer from dev.mysql.com. I chose the Mac OS X Installer
Package for 10.3.
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
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:
31
Drupal Handbook 3 Aug 2007
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.
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/
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:
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.
32
3 Aug 2007 Drupal Handbook
Now I paused to rejoice. MySQL was installed and ready for Drupal. Now it was time to install
Drupal itself.
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:
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:
Now it was time to create all the database tables that Drupal needs:
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.
$db_url = ’mysql://drupaldbuser:fuffy@localhost/drupal’;
$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:
#AddModule mod_php4.c
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.
36
3 Aug 2007 Drupal Handbook
37
Drupal Handbook 3 Aug 2007
38
3 Aug 2007 Drupal Handbook
39
Drupal Handbook 3 Aug 2007
40
3 Aug 2007 Drupal Handbook
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
43
Drupal Handbook 3 Aug 2007
44
3 Aug 2007 Drupal Handbook
45
Drupal Handbook 3 Aug 2007
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
48
3 Aug 2007 Drupal Handbook
49
Drupal Handbook 3 Aug 2007
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’);
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;
10. Now browse this virtual folder with its alias name in IE example
http://localhost/"aliasname"
Have a look at one of the pretty clean theme implementation in drupal - ENJOY . . .
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
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.
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
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:
54
3 Aug 2007 Drupal Handbook
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:
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.
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:
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".
Procedure for allowing php.ini configuration for a website (shows changing file upload max)
This directory will be hosting your copy of php and your php.ini file.
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
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
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:
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
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
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.
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.
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
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.)
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.
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.
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:
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.
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...
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
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
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
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
65
Drupal Handbook 3 Aug 2007
66
3 Aug 2007 Drupal Handbook
DrupalCon site
design contest entry over at the DrupalCon site and become immortal in the Drupal community.
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
This book explaines how I’ve enabled Drupal hosting for my customers.
I hope it is helpfull for other Drupal hosters...
Environment
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:
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.
Requirements: http://drupal.org/node/80472
Solution overview: http://drupal.org/node/90144
69
Drupal Handbook 3 Aug 2007
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)
$ 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
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
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:
70
3 Aug 2007 Drupal Handbook
Introduction
On this page I will explain in general what solutions are provided for the different requirements
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.
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.
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
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.
Navigation
As the book seems to order the sub pages by date, I list here the order of further reading:
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
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".
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
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’);
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.
75
Drupal Handbook 3 Aug 2007
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.
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:
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.
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.
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.
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.
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’;
$base_url = ’http://www.example.com’;
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:
79
Drupal Handbook 3 Aug 2007
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.
6.
NOTE: Do not delete old site until you are 200% sure new site is ok.
Export:
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
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)
Click the âGOâ button and you will soon see a pop-up asking you where to save file.
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.
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.
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
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.
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
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).
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.
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.
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.
That’s it! You have now copied, moved, migrated, synchronized or duplicated your mySQL
database. Well Done!
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
85
Drupal Handbook 3 Aug 2007
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.
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
Update Cron
If you set up Cron on your old installation, make sure you update it to point to your new
installation.
Test that everything is working in your new installation. If so, it is now safe to delete the
files in your old Drupal directory.
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:
# 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......
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).
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.
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.
Edit your .htaccess file in a text editor. [Note: Be sure to save the file in "UTF-8" format.]
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]
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.
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"
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.
http://sourceforge.net/project/showfiles.php?group_id=61776&package_id=6...
#wget http://kent.dl.sourceforge.net/sourceforge/xampp/xampp-linux-1.5.3a.tar....
$su -
#/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.
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
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.
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
Starts XAMPP.
stop
Stops XAMPP.
restart
startapache
92
3 Aug 2007 Drupal Handbook
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
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
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
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
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.
opt/lampp/bin/ - The XAMPP commands home. /opt/lampp/bin/mysql calls for example the
MySQL monitor.
93
Drupal Handbook 3 Aug 2007
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
Stopping XAMPP
#/opt/lampp/lampp stop
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
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.
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).
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.
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:
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
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.
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".
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).
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
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.
102
3 Aug 2007 Drupal Handbook
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:
Apache2Triad
Apache Friends - XAMPP
104
3 Aug 2007 Drupal Handbook
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.
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.
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.
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.
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
=========
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";
$base_url = "http://testsite1";
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
127.0.0.1 localhost
127.0.0.1 testsite1
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
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"
Then go back and rerun the final part of the database.pgsql file - where the "greatest" function is
created.
110
3 Aug 2007 Drupal Handbook
2) Create the new drupal database owned by the user created in 1) above
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).
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:
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
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
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)
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).
Stephen Winters
Winters Sewing
Winters Sewing: Upholstery Information Website
115
Drupal Handbook 3 Aug 2007
1. leech
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
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/node/19813 vs taxonomy
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:
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.
118
3 Aug 2007 Drupal Handbook
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
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.
Here we go:
[/]# cd /var/www
"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
119
Drupal Handbook 3 Aug 2007
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
[/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
[/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
[/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.
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:
(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).
121
Drupal Handbook 3 Aug 2007
.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
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.
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’ );
?>
9. Go to your subdomain. Drupal will install the tables necessary to run 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
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.
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.
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 -
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.
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
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.
- 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
Drupal 5
One database on MySQL
Linux-based server
Also:
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
DB name: drupal_db
DB username: druser
Password: twosites
Access right: SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER,
CREATE TEMPORARY TABLES, LOCK TABLES
$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’;
$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
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_’.
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
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.
$ 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.
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.
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:
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.
131
Drupal Handbook 3 Aug 2007
$ 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.
You want to create more than one Drupal site using the same codebase (the same basic set
of Drupal files, uploaded into one location).
Some definitions:
Affected files:
settings.php (sites/default/...)
132
3 Aug 2007 Drupal Handbook
database.mysql
www.example.com: the MAIN site, where the codebase has already been uploaded,
and settings.php has been properly configured.
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_
$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:
# $conf = array(
# ’site_name’ => ’My Drupal site’,
# ’theme_default’ => ’pushbutton’,
# ’anonymous’ => ’Visitor’
# );
$db_prefix = ’sub1_’;
$base_url = ’http://sub1.example.com’;
$conf = array(
’site_name’ => ’My SUB1 Drupal Site’,
’theme_default’ => ’pushbutton’,
’anonymous’ => ’Visitor’
);
$db_prefix = ’sub2_’;
$base_url = ’http://www.example.com/sub2’;
$conf = array(
’site_name’ => ’My SUB2 Drupal Site’,
’theme_default’ => ’fancy’,
’anonymous’ => ’Anonymous’
);
$db_prefix = ’sub3_’;
$base_url = ’http://www.sub3example.com’;
$conf = array(
’site_name’ => ’My SUB3 Drupal Site’,
’theme_default’ => ’marvin’,
’anonymous’ => ’Guests’
);
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!
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.
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.
/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
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.
137
Drupal Handbook 3 Aug 2007
There are several themes which you can download from the Drupal web site which should get
you started.
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
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
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".
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.
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
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.
143
Drupal Handbook 3 Aug 2007
This code was taken from the boost.module and modified just a little bit.
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.
#
# 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 $
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
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...)
# a2enmod rewrite
# /etc/init.d/apache2 restart
#
# 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
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
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
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>
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
First, from the linux command line, I enabled the rewrite module for apache like this:
a2enmod rewrite
/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
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.
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:
Here are the steps in letting this method apply to your setup.
151
Drupal Handbook 3 Aug 2007
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.
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.
153
Drupal Handbook 3 Aug 2007
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.
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.
and
#AddModule mod_rewrite.c
154
3 Aug 2007 Drupal Handbook
AddModule mod_rewrite.c
Oskar Calvo.
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.
# 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;
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.
REQUEST_FILENAME
The full local filesystem path to the file or script matching the request.
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.
<?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.’),
?>
<?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);
?>
(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
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.
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
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
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.
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.
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
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).
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:
You can then use CSS to theme your DIVs however you like.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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:
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 once a week at 1:00 am every saturday (you can see that saturday is
represented by 0):
Run cron.php task on the first day of every month at 12:00 am (midnight) :
I hope this is helpful for beginners who have installed Drupal and are wondering how to setup
Cron.
167
Drupal Handbook 3 Aug 2007
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.
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.
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.
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
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.
# 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.
also, a little off-topic, but don’t forget to Disable PHP’s session use_trans_sid for cleaner search
engine listings.
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).
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
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.
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>
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.
The administration menu has changed in 4.7, so the config screen for this has moved.
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
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.
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
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.)
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
<^(?!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
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)>
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)
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).
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)
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.
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
You will need to experiment with the value that is right for you.
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
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
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.
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...
);
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:
185
Drupal Handbook 3 Aug 2007
The prefix must be removed from the index and constraint name--that is they must be changed
to:
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:
to:
An alternate approach
Here’s what you need to do if you want to solve it this way:
<?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;
}
?>
$db_url = ’pgsql://user:password@+tmp/dbname.schemaname’;
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’);
<?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
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:
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
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.
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!
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!
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.
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
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.
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". stance on the sites directories,
read Setup of /sites directory for multi-site.
194
3 Aug 2007 Drupal Handbook
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:
Close phpMyAdmin.
Go to the www/Drupal/sites directory.
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").
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.
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.
<p>Sorry! The page you were looking for no longer exists. We redesigned
our site and many of the pages have changed.</p>
<p> </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> </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> </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> </p>
<p>If you are not a member, you need to <a href="/join_us">join
us</a>.</p>
<p> </p>
<p>If you have any questions about our site or group, please feel free
to <a href="/contact">contact us</a>.</p>
<p> </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.
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.
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.
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).
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
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.
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.
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.
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
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:
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.
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.
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.
If the blog is a diary, you probably want to use the date for the title.
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.
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.
206
3 Aug 2007 Drupal Handbook
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.
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.
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.
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.
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.
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.
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."
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.
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.
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 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.
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).
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">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>
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.
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.
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.
221
Drupal Handbook 3 Aug 2007
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.
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
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.
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.
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.
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
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.
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
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:
NOTE: Enable your site’s XML syndication button by turning on the Syndicate block in
administer » blocks.
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
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.
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.
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:
Module blocks
Module blocks are available when modules are enabled. These blocks can be administered in
block administration.
232
3 Aug 2007 Drupal Handbook
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
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
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.
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.
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.
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
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
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:
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.
In order to set up the FAQ, you have to create a new book which will hold all your content. To
do so,
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,
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.
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.
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.
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).
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.
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.
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
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.
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
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?"
"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 .
Eg a site for ALL the small towns of America, where people are interested in their little towns
stuff, using Book for basic structure:-
Click the named settlement and a get a VIEWS screen with filters for News, Culture,
Announcements.
245
Drupal Handbook 3 Aug 2007
Highly non scary - any users can use that to get what they need.
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.)
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.
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!
Ian Dickson - community specialist with a sideline in taxonomy because its the buidling block
for EFFECTIVE social software... .
Taxonomy_otf
Taxonomy_xml
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_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
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.
259
Drupal Handbook 3 Aug 2007
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
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.
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.
-->
http://digitalsolutions.ph/couchkamotereviews/power_drupal_categories
-->
http://drupal.org/node/118525 -->
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.
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:
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.
How will you organize content in the web site? In our scenario, our client wants to categorize
stories as Politics, Technology, Business, and Lifestyle.
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.
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
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.
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’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.
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.
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:
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).
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.
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)
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}
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
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
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);
?>
<?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;
?>
271
Drupal Handbook 3 Aug 2007
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
272
3 Aug 2007 Drupal Handbook
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).
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.
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.
Aggregator comments
Comments for aggregator items has been added to aggregator2 module.
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
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.
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
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.
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.
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.
You can
278
3 Aug 2007 Drupal Handbook
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
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.
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.
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
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.
; Maximum amount of time each script may spend parsing request data
max_input_time = 60
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)
A full guide on how to translate Drupal Core or modules, using the above-mentioned technique,
can be found here.
Although I have created Marathi websites using Drupal 4.7 & 5.1, this article applies to Drupal
5.1 only.
- 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.
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:
Prasad Shirgaonkar
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.
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:
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.
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 ""
#: 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
<?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.
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
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:
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
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.
Note that as of Drupal 5.x a few default differences have been introduced:
288
3 Aug 2007 Drupal Handbook
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.
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.)
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
<?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
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.
The ping module requires cron or a similar periodic job scheduler to be enabled.
You can:
/**
* 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);
}
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
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
1. Navigate to the administration area for user module configuration page under administer »
users » configure
2. In the Pictures
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
295
Drupal Handbook 3 Aug 2007
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:
296
3 Aug 2007 Drupal Handbook
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.
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.
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
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
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
300
3 Aug 2007 Drupal Handbook
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.)
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.)
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.
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:
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.
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:
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.
--
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
#!/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
Note: These instructions were written for Windows XP but should be similar in other versions of
Windows.
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.
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:
306
3 Aug 2007 Drupal Handbook
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
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.
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 can
307
Drupal Handbook 3 Aug 2007
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.
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
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
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.
310
3 Aug 2007 Drupal Handbook
Add an ACCESS RULE by going to ADMINISTER -> ACCESS CONTROL-> ACCESS RULES
[for Drupal 4.7.4].
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!
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:
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.
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.
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
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.
315
Drupal Handbook 3 Aug 2007
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.
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.
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.
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
318
3 Aug 2007 Drupal Handbook
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:
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.
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.
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
321
Drupal Handbook 3 Aug 2007
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:
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").
<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.
<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
<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:
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>.
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".
Everything above this tag will appear in the teaser (unless you place it beyond the point at
which Drupal automatically breaks the content).
Notes
323
Drupal Handbook 3 Aug 2007
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.
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.
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.
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.
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.
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.
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.
If you’ve confirmed that blog support is enabled, here’s some steps to get going:
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)
327
Drupal Handbook 3 Aug 2007
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.
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
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
Of all the guidelines, being able to successfully backup and restore your website is probably the
most important.
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).
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.
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.
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
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.
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.
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 mysite1, create a
copy of fullsitebackup.sh named mysite1fullbackup.sh. You should also modify the tarnamebase
variable to be more description of the site.
This 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
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.
This script does not understand Drupal multisite configurations
This script does not lock out users while the backup is in progress
Read access is required on all files and directories (this is sometimes a problem in hosted
configurations)
The mysqldump utility uses the --add-drop-table option so that a restore automatically
replaces tables. You may wish to modify this to add an element of safety to your restore
335
Drupal Handbook 3 Aug 2007
process. (e.g., tables must be manually dropped, script will not replace)
Commands may need to be modified for your operating system (e.g., The default tar
command in Solaris does not support compression)
Because the backup is done in stages enough temporary space must be available to build the
backup files
fullsitebackup.sh
Copy this text to a file named fullsitebackup.sh. Please ensure that special characters, such as
backtick ("‘") and quotes, are saved correctly.
#!/bin/bash
#
# fullsitebackup.sh V1.0
#
# Full backup of website files and database content.
#
# A number of variables defining file location and database connection
# information must be set before this script will run.
# Files are tar’ed from the root directory of the website. All files
are
# saved. The MySQL database tables are dumped without a database name
and
# and with the option to drop and recreate the tables.
#
# Parameters:
# tar_file_name (optional)
#
# Configuration
#
# Database connection information
dbname={DB Name} # (e.g.: dbname=drupaldb)
dbhost=localhost
dbuser={DB Username} # (e.g.: dbuser=drupaluser)
# Website Files
webrootdir={Directory Path} # (e.g.:
webrootdir=/home/user/public_html)
#
# Variables
#
# Default TAR Output File Base Name
tarnamebase=sitebackup-
datestamp=‘date +’%Y-%m-%d’‘
# Execution directory (script start point)
startdir=‘pwd‘
# Temporary Directory
tempdir=tmpbckdir$datestamp
336
3 Aug 2007 Drupal Handbook
#
# Input Parameter Check
#
if test "$1" = ""
then
tarname=$tarnamebase$datestamp.tgz
else
tarname=$1
fi
#
# Banner
#
echo ""
echo "fullsitebackup.sh V1.0"
#
# Create temporary working directory
#
echo " .. Setup"
mkdir $tempdir
echo " done"
#
# TAR website files
#
echo " .. TARing website files in $webrootdir"
cd $webrootdir
tar cf $startdir/$tempdir/filecontent.tar .
echo " done"
#
# sqldump database information
#
echo " .. sqldump’ing database:"
echo " user: $dbuser; database: $dbname; host: $dbhost"
cd $startdir/$tempdir
mysqldump -p --user=$dbuser --host=$dbhost --add-drop-table $dbname >
dbcontent.sql
echo " done"
#
# Create final backup file
#
echo " .. Creating final compressed (tgz) TAR file: $tarname"
tar czf $startdir/$tarname filecontent.tar dbcontent.sql
echo " done"
#
# Cleanup
#
echo " .. Clean-up"
cd $startdir
337
Drupal Handbook 3 Aug 2007
rm -r $tempdir
echo " done"
#
# Exit banner
#
echo " .. Full site backup complete"
echo ""
Updated fullsitebackup.sh
#!/bin/bash
#
# fullsitebackup.sh V1.1
#
# Full backup of website files and database content.
#
# A number of variables defining file location and database connection
# information must be set before this script will run.
# Files are tar’ed from the root directory of the website. All files are
# saved. The MySQL database tables are dumped without a database name and
# and with the option to drop and recreate the tables.
#
# ----------------------
# March 2007 Updates
# - Updated script to resolve minor path bug
# - Added mysql password variable (caution - this script file is now a security risk - protect it)
# - Generates temp log file
# - Updated backup and restore scripts have been tested on Ubunutu Edgy server w/Drupal 5.1
#
# - Enjoy! BristolGuy
#-----------------------
#
## Parameters:
# tar_file_name (optional)
#
#
# Configuration
#
338
3 Aug 2007 Drupal Handbook
# Website Files
webrootdir="/var/www/drupal" # (e.g.: webrootdir=/home/user/public_html)
#
# Variables
#
# Temporary Directory
tempdir=$datestamp
#
# Input Parameter Check
#
#
# Begin logging
#
echo "Beginning drupal site backup using fullsitebackup.sh ..." > $logfile
#
# Create temporary working directory
#
echo " Creating temp working dir ..." >> $logfile
mkdir $tempdir
#
# TAR website files
#
echo " TARing website files into $webrootdir ..." >> $logfile
cd $webrootdir
tar cf $startdir/$tempdir/filecontent.tar .
339
Drupal Handbook 3 Aug 2007
#
# sqldump database information
#
echo " Dumping drupal database, using ..." >> $logfile
echo " user:$dbuser; database:$dbname host:$dbhost " >> $logfile
cd $startdir/$tempdir
mysqldump --user=$dbuser --password=$dbpw --add-drop-table $dbname > dbcontent.sql
#
# Create final backup file
#
echo " Creating final compressed (tgz) TAR file: $tarname ..." >> $logfile
tar czf $startdir/$tarname filecontent.tar dbcontent.sql
#
# Cleanup
#
echo " Removing temp dir $tempdir ..." >> $logfile
cd $startdir
rm -r $tempdir
#
# Exit banner
#
endtime=‘date‘
echo "Backup completed $endtime, TAR file at $tarname. " >> $logfile
To use this script modify the variables in the Configuration block to specify the instance where
the data will be restored.
To restore a site run the script specifying the backup file in parameter P1. e.g.:
$ sh fullsiterestore.sh fullsitebackup-2006-04-14.tgz
$ bash fullsiterestore.sh fullsitebackup-2006-04-14.tgz
You will be prompted for the database password and may be prompted for permission to delete
a file if it is permitted read-only.
If multiple websites are hosted on the same system create a copy of the script and rename it to
reflect the restore it will perform. For example, for a site named mysite1, create a copy of
fullsiterestore.sh named mysite1fullrestore.sh.
340
3 Aug 2007 Drupal Handbook
The backup script uses the mysqldump --add-drop-table option. On a restore this allows the
database tables to be removed and recreated. No prompt is given before this happens.
Write access is required on all files and directories (this is sometimes a problem in hosted
configurations)
Enough file space must be available to allow unpacking of the backup file
This script does not lock out users while the restore is in progress
This script does not understand Drupal multisite configurations
Commands may need to be modified for your operating system (e.g., The default tar
command in Solaris does not support compression)
If restoring over top of a Drupal instance that contains modules that are not in the backup
there will be "orphaned" module tables. Depending on the situation, you may wish to drop
and recreate the database before doing the restore.
When restoring to a different server the file permissions may require updating
No Drupal configuration is required if restoring a backup to the same location it was backed up
from.
fullsiterestore.sh
Copy this text to a file named fullsiterestore.sh. Please ensure that special characters, such as
backtick ("‘") and quotes, are saved correctly.
#!/bin/bash
#
# fullsiterestore.sh v1.0
#
# Restore of website file and database content made with full site
backup.
#
# A number of variables defining file location and database connection
# information must be set before this script will run.
# This script expects a compressed tar file (tgz) made by
fullsitebackup.sh.
# Website files should be in a tar file named filecontent.tar, and
database
# content should be in a sqldump sql file named dbcontent.sql. This
script
# expects the sql to drop the table before readdding the data. In other
words,
# it does not do any database preparation.
#
341
Drupal Handbook 3 Aug 2007
# Parameters:
# tar_file_name
#
# Configuration
#
# Database connection information
dbname={DB Name} # (e.g.: dbname=drupaldb)
dbhost=localhost
dbuser={DB Username} # (e.g.: dbuser=drupaluser)
# Website Files
webrootdir={Directory Path} # (e.g.:
webrootdir=/home/user/public_html)
#
# Variables
#
# Execution directory (script start point)
startdir=‘pwd‘
# Temporary Directory
datestamp=‘date +’%Y-%m-%d’‘
tempdir=tmpbckdir$datestamp
#
# Banner
#
echo ""
echo "fullsiterestore.sh v1.0"
#
# Input Parameter Check
#
# If no input parameter is given, echo usage and exit
if [ $# -eq 0 ]
then
echo " Usage: sh fullsiterestore.sh {backupfile.tgz}"
echo ""
exit
fi
tarfile=$1
# Check that the file exists
if [ ! -f "$tarfile" ]
then
echo " Can not find file: $tarfile"
echo ""
exit
fi
# Check that the webroot directory exists
if [ ! -d "$webrootdir" ]
then
echo " Invalid internal parameter: webrootdir"
342
3 Aug 2007 Drupal Handbook
343
Drupal Handbook 3 Aug 2007
Updated fullsiterestore.sh
#!/bin/bash
#
# fullsiterestore.sh v1.1
#
# Restore of website file and database content made with full site backup.
#
# A number of variables defining file location and database connection
# information must be set before this script will run.
# This script expects a compressed tar file (tgz) made by fullsitebackup.sh.
# Website files should be in a tar file named filecontent.tar, and database
# content should be in a sqldump sql file named dbcontent.sql. This script
# expects the sql to drop the table before readdding the data. In other words,
# it does not do any database preparation.
#
# ----------------------
# March 2007 Updates
# - Updated script to resolve minor path bug
# - Added mysql password variable (caution - this script file is now a security risk - protect it)
# - Generates temp log file
# - Updated backup and restore scripts have been tested on Ubunutu Edgy server w/Drupal 5.1
#
# - Enjoy! BristolGuy
#-----------------------
#
# Parameters:
# tarfile # name of backup file to restore
#
#
# Database connection information
dbname="drupal" # (e.g.: dbname=drupaldb)
dbhost="localhost" #
dbuser="" # (e.g.: dbuser=drupaluser)
dbpw="" # database user password
# Website location
webrootdir="/var/www/drupal" # (e.g.: where you keep your drupal directory structure)
#
# Variables
344
3 Aug 2007 Drupal Handbook
# Temporary Directory
datestamp=‘date +’%Y-%m-%d’‘ # uses US format
tempdir=$datestamp
#
# Begin logging
#
echo "Beginning drupal site restore using \’fullsiterestore.sh\’ ..." > $logfile
#
# Input Parameter Check
#
tarfile=$1
#
# Create temporary working directory and expand tar file
#
echo " Creating temp working dir ..." >> $logfile
mkdir $tempdir
cd $tempdir
echo " unTARing db and file tgz files ..." >> $logfile
tar xzf $startdir/$tarfile
345
Drupal Handbook 3 Aug 2007
#
# Remove old website files
#
echo " Removing old files from $webrootdir ..." >> $logfile
rm -r $webrootdir/*
#
# unTAR website files
#
echo " unTARing website files into $webrootdir ..." >> $logfile
cd $webrootdir
tar xf $startdir/$tempdir/filecontent.tar
#
# Load database information
#
cd $startdir/$tempdir
echo " Restoring database ..." >> $logfile
echo " user: $dbuser; database: $dbname; host: $dbhost" >> $logfile
echo "use $dbname; source dbcontent.sql;" | mysql --password=$dbpw --user=$dbuser
--host=$dbhost
#
# Cleanup
#
echo " Cleaning up ..." >> $logfile
cd $startdir
sudo rm -r $tempdir
#
# Exit banner
#
endtime=‘date‘
echo "Restoration completed $endtime for $tarfile. " >> $logfile
346
3 Aug 2007 Drupal Handbook
These are some simple guidlines for setting up Drupal in an Apache Virtual host that provides a
fair amout of security for the rest of your system.
php.ini Configuration
# increase php’s memory limit to avoid the white screen of death when
# you add a few modules.
memory_limit = 16MB
ServerName example.com
#wildcard server alias helps direct all traffic to your end users site
#and simplifies using drupal’s multisite configuration for subdomains.
ServerAlias *.example.com
# This path will vary depending on your system, If you are using debian
# make sure you drop the default images alias it can be very annoying
# to users on shared servers.
DocumentRoot /var/www/example.com/public_html
# Place the log where your end users can see them, and make sure they
# are at the least readable to an end user.
#
# performance option:
# You can move the apache logs to another partition or drive to
# get some small increases in disk i/o on heavily loaded servers.
# You can symlink the log files to /var/www/example.com/logs/
# to keep the persistent user interface, however it doesn’t work in
# chroot environments.
ErrorLog /srv/www/example.com/logs/error.log
CustomLog /srv/www/example.com/logs/access.log combined
347
Drupal Handbook 3 Aug 2007
#Go ahead and give users access to manipulate their vhost to their
#hearts content.
AllowOverride All
//Tweaking performance
my.cnf
#big ol mysql.querycache(128M) (be aware of your systems memory limitations)
query_cache_size = 134217728
#boost mysql max connections (min = (20*number of drupal sites))
set-variable=max_connections=512
eacclerator
prod site: the live, production website where all your web visitors go
test site: a copy of your live site, at a different URL, where you can make experimental changes
without affecting your prod site
Drupal and its modules are in pretty constant development. So things are changing pretty fast
and sometimes not completely documented. In practice, that means making a change or
adding/removing a module on your prod site can have rather surprising results - surprises
you’d rather your visitors didn’t have to live with. That’s why I recommend making all changes
to a test site, and if they work out, promote the changes to your prod site.
Here’s how I built a completely parallel site on my hosted, shared server account.
First I need to mention some things about my site, so the rest of this article makes sense:
348
3 Aug 2007 Drupal Handbook
All of this is pretty standard stuff, but you may have to make a few changes to this process if
your site is set up differently. My test/prod workflow looks generally like this:
So how to actually do all this? Don’t worry, it’s not that hard once you have the right commands
handy. Really, I do steps 1-4 in about 2 minutes. This document is long only because I wanted to
be verbose enough for all skill levels!
The first thing I did was ask my hosting provider to create a new directory, /home/user/test
and then set up apache and their DNS servers so that http://test.yoursite.com and
http://www.test.yoursite.com would point to this new test directory. It was important to ask
them to make a new VirtualHost entry in the apache configurations, NOT just set up a rewrite
rule. They should know what you mean by this - and they might charge you extra for it. Mine
didn’t, but even if this costs you a couple of extra bucks, it’s worth it. Trust me when I say that
using a rewrite rule or subdirectory of your existing site will make the rest of this much harder
to do.
When this is complete your directory structure will look something like:
|-home
|-username
|
|-public_html
| |
| |-database
| |-files
| |-includes
| |-misc
349
Drupal Handbook 3 Aug 2007
| |-modules
| |-scripts
| |-sites
| |-themes
| |-(drupalfiles)
|
|-test
|
|(empty because we haven’t put anything here yet)
You’ll also need a second mySQL database to house your test site’s data.
to create my database and set the permissions. The I broke a single mysql command into the last
two lines because drupal.org wasn’t printing it all as a single line. If you are restricted from
doing so, you may need to create the empty database via cPanel, Plesk, or whatever control
panel your provider gives.
mkdir ~/temp
mysqldump -uuser -ppassword --add-drop-table mydb_prod > ~/temp/prod-db
mysql -uuser -ppassword mydb_test < ~/temp/prod-db
rm ~/temp/prod-db
Above you see the commands I enter. You’ll need to change things user and password to your
username and password; also mydb_prod should be replaced with the mySQL database name for
your prod site. Knowing that, I bet you’ve already figured out that you need to replace mydb_test
with the name of your newly-created test database.
The first line just creates a directory to hold our temporary dump file.
The second line, starting with mysqldump, is where we dump the entire prod database to a
textfile. We use the --add-drop-table option because this essentially creates a script we’ll run
later; this option makes sure that script will erase old data before importing new data. Note that
you need to supply the proper username and password for your production database. I specify
the database name mydb_prod - you will need to change this to the name of your prod site’s
350
3 Aug 2007 Drupal Handbook
database. The textfile created by this command is actually a full script which will create tables
and populate them with data.
The third line, starting with mysql, is where we do that. Again, be sure and replace the italicized
parts with the username, password, and database name you set up in step 1.
Finally I delete the dump file (~/temp/prod-db); it’s not needed anymore now that we have
loaded it into mySQL.
rm -rf ~/test
cp -R ~/public_html/. ~/test
Here I remove the test directory, then recreate it, and copy everything from ~/public_html into
it. I remove the test directory and all contents because I may copy of the test site in there, and I
don’t want it to pollute my fresh new exact replica of my prod site.
nano ~/test/sites/default/settings.php
This starts the nano editor (or use whatever you like) and loads drupal’s settings file. Here you
will need to change two lines:
$db_url = ’mysql://user:password@localhost/mydb_test’;
$base_url = ’http://test.yoursite.com’;
These lines are not together in the file. Set the database connection line, pointing to the test
database you created in step one and populated in step 2. (in other words, you need to replace
the words user, password, and mydb_test with information that’s correct for your test database.)
The base_url line sets the URL you will point your browser at to use the site. Save the changes.
Now, in your web browser, navigate to the site - it should be working fine. But I also change the
Name field at administer --> settings to TEST.yoursite.com (all caps) so its easy for me to
remember I am looking at the test site.
This is where you make you changes. Change settings, add/remove modules, muck with the
code - it’s up to you. Remember you are working in a copy of your site - one that users don’t
know about - so you don’t have to worry that you are creating problems for the users.
Killes has written a very nice and very quick way of testing your site at node/11521
And if you don’t like the changes, or if you mess up your test site
completely - no worries! Just re-do steps 2-4 to bring a new copy of your
production site and database into your test environment.
351
Drupal Handbook 3 Aug 2007
Now that you have your test site the way you want it, you really have two choices.
Method 1: You can re-make all the same changes manually on your production site.
Method 2: You can basically migrate the test site into production, with a very brief outage for the
users.
I usually use method 2, but have been known to do it both ways. To use method 2, I’m
essentially doing everything mentioned above, but this time copying the test site into the
production location. So I’ll skip over it more quickly this time around:
1.
mysqldump -uuser -ppassword --add-drop-table mydb_test >
~/temp/test-db
mysql -uuser -ppassword mydb_prod < ~/temp/test-db
rm -rf ~/temp/test-db
rm -rf ~/public_html/*
cp -R ~/test/. ~/public_html
2. nano ~/public_html/sites/default/settings.php (here you’ll edit the db_url
and base_url to the prod-site settings)
3. Also be sure to open the prod site, navigate to administer // settings and change the name
back to the way it should be for the prod site.
You should probably test your site again using the Killes method linked in step 5.
There are a couple of additional cleanup steps I do, once I know my site is in good shape:
rm -rf ~/test/* (just cleaning out test dir for next time)
rm ~/bash_history(because it has my database password in it)
Remove the test database (if space is a concern)
1. For Drupal 5.x only: a new feature/best practice. For a normal (single site) installation, you
should put all non-core modules or themes in the sites/all/modules or
sites/all/themes folders. For a multi-site installation, put modules or themes in
sites/all that you wish to have available for all sites.
2. For 4.7 and prior: Create a sub directory in modules for each contributed module you
install. This helps you track contributed modules vs included core modules. This is fairly
important when preparing for a Drupal version upgrade and a good idea in general.
For example: a module named foo.module would go in a sub directory of modules; modules/foo Be
sure not to include the space if the module name is multiple words.
3. Multisite setups allow you to have a modules directory specific to the site in the
sites/www.example.com/modules directory. You can still put modules in directories off
352
3 Aug 2007 Drupal Handbook
the main /modules directory if you want them available to all sites.
4. Leave the CHANGELOG.txt file in your root directory as it has the Drupal version
information in it. If you manage more then one site, consider putting a version.txt file in the root
of your drupal directory with the Drupal version, date and modules you are using. If you only
manage a few sites you will probably remember them all, but if you set them up for other
people, these reminders can help you if you are asked back to do additional work. Also, it can
help the next site admin if you move on.
5. Rename update.php if you want. There are protections for it in the update script in that you
have to be logged in with UID1. As of 4.7 update.php is now required for various module
installations and other tasks so if you move/rename it for whatever reason do not forget to put it
back to it’s original state before module installs/updates.
Other Tips
Modules that are not part of core may or may not be supported by their contributor for a
Drupal version upgrade.
Avoid spaces in any directory name.
Test Sites
Set up a test site using your live data. You do not want to have to ask in the forums how to save
your site. You have worked hard to build it, it would be a shame to lose it.
1. Never do development or testing on your live production site. Drupal is fast and easy to
install. Always test on a test site first.
2. Test that your backups work and that you know how to do a restore of your site. The test
system can be your local desktop, just edit your conf.php (4.5 or earlier) file or settings.php
(4.6) to localhost. You do not want to discover the hard way that you forgot a file or did not
know how to do this when your site is down.
3. Test your site upgrade procedure before risking your live site and document the steps you
take. Documentation aids repeating the process if necessary. Testing can be done with
Simpletest.
For more information on installing test sites, please see the Installing Drupal section. There are
some specific examples of copying a production site to a test/development environment in the
Special Cases subsection under Installation.
353
Drupal Handbook 3 Aug 2007
1. Read the Best Practices on test sites and don’t do it first on your live site.
2. Make sure that all the contrib modules you are using have an update path or you are
willing to upgrade them yourself or abandon them.
3. Create a new database and restore your live site to it, files and all.
4. Disable all contrib modules.
5. Set your site to the default theme Blue Marine (for Drupal 4.7.x) or Garland (for Drupal 5.x).
Doing so will complicate, make difficult or near impossible site updates due to Security and
bug fixes
You will make it difficult for those that come after to maintain the site
You could possibly leave your site vulnerable to exploits
Are there exceptions to this rule? Sure, but this is generally for specific sites or implementations
by people who are extremely familiar with the Drupal code base, development practices and
security model. Those who properly document their changes and practice proper revision
control with their code. If you have to ask, chances are you shouldn’t.
354
3 Aug 2007 Drupal Handbook
Security
Security is an important consideration when running your web site. If you maintain your own
server you should be aware of any announced vulnerabilities for your operating system, php,
and web server. Be sure to follow up with the appropriate patches or updates as needed. Sign up
for the security mailing list so that you can be aware of any announced vulnerabilities and how
to correct them.
Fortunately, there is a very simple and easy solution. Instead of writing and testing your code
inside the administer > blocks page, go to create content and create a new story or page node.
Use PHP input format, write the code, and the Preview to debug your code. When you are
happy and your code is working, copy and paste the code into the block.
Thank you to Heine for this tip in the #drupal-support IRC channel.
355
Drupal Handbook 3 Aug 2007
Another place to look for issues or bugs in contributed modules is: Module downloads page.
Click on "Bugs and feature requests" under your specific module to see if someone has already
addressed the issue. The next place to go is to the forums.
The Forums
Another great resource is the forums where you can ask your question to anyone, typically in
the "How do I..." section. Be courteous, and please search for your answers first. Don’t be
dismayed if you can’t find it right away. Chances are, someone else has already asked and
answered your question, but that doesn’t mean the search will find it right away. Some people
use Google to do a website search by typing in "site:www.drupal.org" in the search box.
Advanced customization
If your answer was not anywhere listed above, the next step may be to customize your install of
Drupal by changing the code. Now, you’ve entered the realm of developing Drupal, or
customizing the code to suit your needs. Look at the Contributer’s Guide to start, and you may
end up with something we all can benefit from. There is a Module developer’s guide and a
Theme developer’s guide. Also very helpful is the: API, or application program interface. The
API is an interactive repository of information on all the functions, modules, constants,
variables, etc that are used in the core Drupal code, and it’s very useful if you want to
understand the relationships and purpose of different parts of Drupal. You may eventual find
that your new function, module, phpcode snippet, etc. can benefit the Drupal community at
large. There are several ways to do that - post it in the forums, add it to PHP page snippets, or
apply for CVS (concurrent version system) access and add it there.
356
3 Aug 2007 Drupal Handbook
1. Locate the directory where you installed the Image module. It’s most likely in
/sites/default/modules/image or /sites/all/modules/image. Open the image folder and
look for a file called ’image.imagemagick.inc’. Copy (don’t move) that file to /includes/.
That’s a Drupal core directory, BTW.
2. After the file has been copied to your /includes/ folder on the server, surf your way to
Administer > Site Configuration > Image Toolkit. There, you will find a second entry under
"Select an image processing toolkit". Enable the Imagemagick library there, and click ’Save
Configuration’.
3. Set the proper path to Imagemagick’s Convert binary. This is usually /usr/bin/convert, but
it can be in other places too. If you installed Imagemagick on your own server, you’ll know
where to look. If you’re using a hosting company who provides it as a package, ask them
*after* you try and see if the default /usr/bin/convert works or not.
You’re done! If there are any questions or problems relating to this HowTo, post a comment
here. If you found a bug, or something doesn’t work right and you know it should, file a bug
report for image.module. Full documentation on the Image module can be found in Contributed
Modules > Image handbook.
357
Drupal Handbook 3 Aug 2007
PLAY B-I-N-G-O!
Want to help Drupal? Like random games of chance? Why not combine both of these interests in
one fell swoop and participate in: Patch Bingo: http://drupal.org/patch-bingo and Bug Bingo:
http://drupal.org/bug-bingo. These links will take you to a random issue in the Drupal queue.
Test out bugs to see if they’re still an issue, try out patches to see if they work and comment on
whether or not they’d be useful. You’ll both add some wacky adventures to your life, and help
Drupal at the same time!
E-COMMERCE
Check out this nice ecommerce module for Drupal: http://drupal.org/project/ecommerce.
While I wouldn’t recommend it to start an entire store, it has everything you need to make your
own little gift shop and sell t-shirts, coffee mugs and more. Plus, it integrates nicely, so your
store looks just like the rest of your website.
You can get more tips from Bryght’s "Best Practices" section at
http://support.bryght.com/taxonomy/term/8.
Commentator array
Lately on my website, which runs Drupal 4.7.4, I have been getting serious performance
problems. In one hand I have a lot of modules installed. In the other hand I have a lot of
personal code I have wrote to make my site more attractive.
One of these things was to show user’s profile data on every comment, just below user’s image.
Data like location, country and a nice country flag.
Well, the only way I could imagine to do this was either loading user’s profile or querying DB on
comment.tpl.php. That means I had to repeat this operations on every comment. Of course this
was totally redundant if the same user was commenting more than once in the same thread,
having nodes were I was loading some user’s profiles even more than 20 times. This of course is
a bad practice and makes your site pretty slow.
So today I was thinking it would be cool to load all commentators information before displaying
the comments. And here is how I made it.
1. On node.tpl.php file, after node has been closed, add this php code:
if ($node->comment) {
global $commentators;
$commentators = mystuff_getcommentators($node->nid);
}
358
3 Aug 2007 Drupal Handbook
function mystuff_getcommentators($nid) {
$result = db_query("select distinct uid from {comments} where uid > 0
and nid = $nid");
while ($u = db_fetch_object($result)) {
profile_load_profile($u);
$commentators[$u->uid] = $u;
}
return $commentators;
}
Of course, on this function you can add other stuff to the user object besides user’s profile.
global $commentators;
if ($picture) { print theme(’user_picture’, $comment, ’comment’);
}
if ($comment->uid) {
print $commentators[$comment->uid]->profile_location_city .
"<br/>";
print $commentators[$comment->uid]->profile_location_state .
"<br/>";
print $commentators[$comment->uid]->profile_location_country .
"<br/>";
}
(Profile fields must be set on profile settings page)
And that’s it! I love to do stuff without touching a line of Drupal’s or modules code.
PS: I have been looking for some kind of solution for this on the forum, but haven’t found
anything so I did it myself.
Need more flexibility in creating content? Are the simple page and story content types not
enough for your site’s needs? Do you wish you could create content types on the fly by just
filling in a few fields? Try the Flexinode http://drupal.org/project/flexinode module. Once
installed, you can go to administer->content->content types and create custom content types. For
each content type, you can specify a set of fields that can be filled out by the content
contributors. Once you set up all the fields, you can easily add content by selecting the new
content type from the create content menu.
359
Drupal Handbook 3 Aug 2007
WYSIWIG EDITORS
Writing rich content in Drupal is sometimes a hassle. You either write the page in a separate
WYSIWIG editor and copy it into Drupal or code HTML in the tiny textarea. However, it is
possible to easily integrate one of the many inline
WYSIWIG editors into Drupal. You can choose from TinyMCE
http://drupal.org/project/tinymce, FCKEditor http://drupal.org/node/16118 and HTMLArea
http://drupal.org/project/htmlarea. Install one of these modules and within minutes, you can
create diverse content right from your browser.
Is your content rampaging all over the place? Organize it and make it easy to locate. Drupal
ships with a power organization module called Taxonomy
http://drupal.org/handbook/modules/taxonomy. Taxonomy allows you to define sets of
categories called
"vocabularies". This makes it extremely easy to organize and group content and make your
website more navigable.
QUICK SUPPORT
Feeling a little lost? Need some quick support with Drupal? Get an IRC client and pop into
#drupal-support on irc.freenode.net. Someone could be there to help you out.
Remote authentication
If you want to use remote authentication against your site, then create a role with no
permissions and put a user under this role. So it’s nopermissionuser@my.drupal.site.
360
3 Aug 2007 Drupal Handbook
Let us take as an example the project named "shazamgallery": Visit the link
http://drupal.org/cvs?file=/modules/shazamgallery/ to see the latest commits to that project.
The /modules/shazamgallery/ in the url can be replaced by anything of your interest. You can even
track changes to one file. For example,
http://drupal.org/cvs?file=/modules/shazamgallery/shazamgallery.mysql lets you track
changes to the database file only.
The most interesting part, however, is the RSS feed that comes with that
at http://drupal.org/cvs?rss=true&file=/modules/shazamgallery/
Use this to track your own contribs (to see if some other contributor
slips in features, or bugs, by accident). Or to track changes of the
projects you use on your drupal site.
Module Linking
Contributed by Heine Deelstra
361
Drupal Handbook 3 Aug 2007
-->
Overview
While implementing a website planning is very important. I have learned this the hard way. I
wrote this document while planning my family website. This will be my second complete site
redesign for this site that has been up for about five years. Although this is a fairly simple site
the same planning process would apply to any site. The most important thing I have learned
was that the lack of planning in the first two attempts significantly limited the end site. Many of
the limitations, or headaches, could have easily been solved during the planning phase. I am not
a programmer although I manage eight production web sites from e-commerce to purely
informational to just for fun. Some of this may seem obvious to those with programming
experience but for the do it yourselfers I hope this will help get you started.
Requirements
Gathering requirements is key and really needs to be the first step in the Website
implementation process. If you are like me it is also the hardest to force myself to do. On my last
attempts once I had some idea about what I wanted I tried out a couple of CMSes and then
loaded one and started adding content. This time is different. One thing about the requirements
below to keep in mind is this is not a totally serial process. During each step I am continually
adding to each proceeding step. As I go through the process more and more things come to
mind.
The first thing I considered is: What will the website publish or do? For a store this might be
selling products, handling RMAs, selling advertising space, or hosting forums about your
products. You also need to think about things like: What languages will you site need to
support? Will it need to be able to handle transaction processing? Will it need to talk to other
sites? If it talks to other sites, what standards are out there that you will need to comply with?
Do you need to secure access? Basically anything else you can think of that is important to how
you want your site to function.
For my family site I came up with the following requirements: I need various people to be able
to publish content. We need to be able to publish pictures, videos, audio clips, wish lists, blogs,
and stories. We need a way to secure some of our content yet other content will be open to the
Internet. We need a shared calendar that allows for event scheduling. We would like a place to
document our genealogy. The site needs to be easy enough for my grandmother to use. None of
the users are programmers so it needs to be easily deployed with a minimum of coding. We
would like to easily change the look and the feel of the site during different seasons or whenever
we feel like it. There is no income so I need to keep the costs down. The content needs to be easy
to search. I need to be able to get the majority of the content out if I decide to restart again some
day. We would like the ability to be able to comment on content. We would like the ability to
have polls. We publish a bunch of pictures to it should be easy to publish pictures especially and
keep them very organized.
362
3 Aug 2007 Drupal Handbook
The second thing I consider is: Who will be using the website? It is best to break your users into
groups, even if a group will only have one person in it for now. This is especially important if
there is any possibility for growth. The user groupings should be broken into functional groups
that will change based on the site. For a store site you might have customers, site administrators,
vendors, and your accountant.
For my family site I am able to break the users into the following
groups:
The next thing I consider is: How will the content be accessed? What are some possible work
flows? For a store I might want to make sure that I can link to vendors. I would want to make
sure that vendors could update content but that I would have approval of any changes. I would
want to make sure that putting an item on sale is access controlled. I would want my highest
profit, best selling items right up front. I want to make sure a search works well enough to
return just a handful of items.
For my family site I want easy and simple entry of content and simple viewing of content. The
users inserting content are trusted so I would like for them to have options about where their
content is published. I would like the users to handle the content so that I don’t have to get
involved every time someone adds or changes something. Users should have a way to pull up
specific content easily. They should be able to sort by date, subject, category, and content type.
Our current site ended up with a huge amount of unorganized content. It was a great site for
current news or pictures but finding an old audio clip was next to impossible. It would be best if
all the content could be organized using the same organizational structure. Our current site we
ended up with a totally different sorting system and access method for each type of content
since we used somewhat unrelated modules. The new one I want people to be able to pull all
content types of a certain subject when they want to.
Based on what you are trying to do you could take this further but this was enough for me to use
as a base set of requirements.
363
Drupal Handbook 3 Aug 2007
Now that I have an idea of what I want the system to do it was time to start looking at the
options. Based on my budget and eagerness for a system that could be tailored to my needs GPL
was obvious. I looked into all the popular CMSes and some not so popular ones. When it came
down to it, for what I wanted Drupal was hands down the best choice. I could go through the
others ones but I will skip to what I liked about Drupal. I really like the everything is a node
idea. I also like the way taxonomy was implemented. From a work flow stand point those two
parts made Drupal stand out above the rest. Not knowing the system I assumed it might take me
a little more work to get it setup but in the end it would be a seamless website with the ability to
eventually, if not immediately, meet all of my requirements.
Once I picked Drupal I spent a bunch of time looking at modules. There seems to be at least one
module for everything I wanted that was not included in the base. I wrote down all of the
possibilities and worked out in my head how it would all come together. I won’t go through all
of the modules here but basically this step was just a bunch of reading.
Next I went right to setting up the site. I installed the Drupal base and just started playing. While
I really like Drupal on virtual paper for me it was not final until I saw how it worked. I was
pleasantly surprised. It took me a little while to really get the whole picture but once I did it all
clicked. It was very slick and really was the seamless base I wanted.
I tried a ton of modules. Based on my requirements it was very important to me that everything
worked with the base in a productive way. I did not want to end up having to pull up a picture
in a different way than I had to pull up a video. I can’t say I have everything i want but you can’t
always get everything you want and I did get much closer than expected. I ended up with
image, image_pub, quotes, wishlist, video, and audio. I am still looking for a few odds and ends
but for the most part I was able to get all of these installed and working.
Once I had this worked out I started working on taxonomy. For me this was the most difficult to
decide and also the most important. Producing a ton of unusable content would have made the
rest of this useless. Drupal has a bunch of articles on taxonomy which helped a bunch. I tried on
paper a whole bunch of things and then would talk to he users. They would provide feedback
and I would take another stab. Some of the items listed below may not be considered taxonomy
because it is not set up as a category in Drupal but is already part of the system. Although this
might still change some currently we have the following vocabulary:
364
3 Aug 2007 Drupal Handbook
After this, I put up a test site, got everything working, and had the real users have a go at it.
Although I knew a little they are really the only ones that can make it break and have to use it. I
administer the family site I rarely add any content. I will tell you that on first pass the site is
much better than I expected. We have along way to go for the perfect site but the combination of
Drupal and a good plan is a fantastic starting point.
Profile your site’s performance loading: bandwidth, anonymous page views (general reads),
concurrent number of users (unique reads), concurrent number of user posts (writes) are all
important in building your sites profile.
365
Drupal Handbook 3 Aug 2007
your site by configuring incorrectly. Be careful and back up configurations before making
changes.
1. Understanding LAMP performance. This LAMP performance study revealed that Apache is
bandwidth limited, PHP is CPU limited, and MySQL is memory limited and disk I/O
bound. Be sure to compile your stack natively for maximum performance. You can also read
Optimize high traffic servers.
If there are other applications running on your server such as (mail, ssh, anti-virus, spam
checking, web services, custom applications, etc) that are consuming contrained resources
you might need to move them to a new server.
3. Bad guests consuming too many resources: Crawlers, Aggregators, Spammers. Search
engines may crawl your site and cause a performance degradation, although if they crawl as
an anonymous user then they should recieved cached pages which consume less resources.
Slow down the robots crawling your site by adding a robots.txt line like this:
User-Agent: *
Crawl-Delay: 10
Disallow: /archive
Here 10 is the delay in seconds between page requests. Disallow robots from sections of
your site that do not need indexing. See Controlling what gets indexed -- the robots.txt file.
Some RSS clients are set to check for aggregator feed updates too frequently. Check your logs for
aggressive reads of feeds from a specific IP address. Spammers have many ways of consuming
your sites resources, be sure your site has a spam blocking strategy. Drupal 4.7 includes a check
to ensure that that forms originated on the site. This is to prevent spammers from creating large
amounts of comment and trackback spam remotely.
Apache performance Apache is usually bandwidth limited so you should be aware how
much bandwidth your server has access to. You can ask your hosting provider how much
bandwidth you have or you can use a tool like lperf. The mod_rewrite module for Apache
can consume resources if the directives are included in local directories through .htaccess
files. If you have control of the Apache configuration then these directives should be moved
to httpd.conf. You can also configure Apache to handle more connections with
MaxSpareServers, ServerLimit, MaxClients. CGI is slow. mod_php is popular and fast,
FastCGI is fast and secure. Read this tutorial on configuring Apache for Configuring
Apache for maximum performance.
366
3 Aug 2007 Drupal Handbook
PHP tuning: CPU consumption and optimizers:Use a PHP optimizer such the upcoming
Alternate PHP Cache, Zend Optimizer, eAccelarator a development of mmcache PHP. You
can also read Optimizing PHP.
The number of modules enabled on your site may effect performance but should be
measured using the techniques outlined above. If the module has slow query times look at
tuning the tables with schema changes and using the the MySQL optimization tools, such as
ANALYSE and EXPLAIN. Other areas for analysis are theme resource consumption if you
theme has a lot of PHP calls.
There are several known performance issues in Drupal 4.6.5 including the URL alias table is
loaded into memory frequently and the use of Path and PathAuto modules will lead to an
increase in the number of aliases in the table (fixed in 4.7 and higher). Recent improvements to
session handling for anonymous users and a proposed file cache that bypasses Drupal’s page
loading mechansims offer significant performance improvements for anonymous users.
Configuring Drupal for performance: Cron jobs such as aggregating lots of feeds can be
resource intensive. If the cron jobs are set too frequently there can be a consistent drain on server
performance. Drupal has a cache that is very effective for pages served to anonymous users. It
can be found at administer >> settings
Server architectures for scalability and performance: separate web server and database
server, MySQL replication topologies, clustering servers.
This page was authored by Kieran Lal, from CivicSpace Labs. If you would like to
contribute or edit this page please contact me. If you would like to fund performance
improvements for Drupal please contact Kieran as well.
By design, Drupal is defined as the 404 handler for all instances in the .htaccess file. That
code is:
367
Drupal Handbook 3 Aug 2007
Drupal (and other php-based CMS systems) do this so that index.php handles all URI
requests and can generate the right page.
The problem is that using Drupal as the 404 handler invokes a full bootstrap load for any
missing file.
Adding the following code to .htaccess eliminates some of this, by telling Apache to handle
certain types of 404 errors:
# This overrides the Drupal 404 handler for files that should never
be handled by Drupal
<FilesMatch "\.(gif|jpe?g|png|s?html|css|js|cgi)$">
ErrorDocument 404 default
</FilesMatch>
This elminates the following file types from invoking Drupal if a 404 is encountered:
- gif
- jpeg
- shtml and html
- css
- js
- cgi
Doing so avoiding invoking Drupal’s bootstrap in order to look for missing files. This
procedure minimizes database load and helps boost site performance.
-- WARNING --
There is a known issue that occurs if you block .png files with this method. It affects the
system_test() function in system.module, which relies on a phantom .png call to the directory
’/system/test/’.
If you block Drupal’s 404 handling for .png files and do not allow this exception, you lose
the ability to configure the site for clean_urls.
368
3 Aug 2007 Drupal Handbook
Here’s my scaling tree. As you progress up the tree, you will find that time, money,
maintenance, headaches will all increase.
I found that using APC speeds up Drupal by a lot, 3 to 5 times the pages view per second.
This was _literally_ a 5 minute install (on FreeBSD) for a 300% to 500% performance
improvement. I think at that point it was my dev servers SATA HDDs were the bottle neck. It
sits beside me and when I hit it with ab, I can hear the HDDs wrrrrr like crazy.
The benefits of this are amazing, considering the minimal effort it takes to implement. If
doesn’t matter if it takes Drupal 0.002 seconds to generate a 40K of html, if it takes like 1 to 2
seconds for a client to download it (more if using a modem). mod_gzip usually gives a 10% to
80% compression depending on the size of pages. Amazing results for 10 minutes of work.
3. Get a faster DB server. I’m thinking of 3x15K SCSI (raid 5), dual way xeon mysql server
from freebsdsystems.com for my next installation. These things rip . Expensive (~$5K to $7K)
but fast. An average Drupal dev charges like $100USD these days right? A super fast db server is
still more bang for your buck than 50 to 70hrs of code performance tuning.
4. Get faster (or more) Web Servers. Maybe not the same specs as above, but fast anyways.
5. Get a load balancer, or a reverse HTTP proxy (squid) to distribute the load
6. Do MySQL replication
Squid Caching
Squid is a fully-featured, open-source web-content caching system. In accelerator mode,
squid can be used in between your users and your web-server to cache objects and reduce
requests against your web server(s) and database server(s).
Usually, Drupal has very dynamic content (nodes gets comments and so on, the pages look
different from one user to the other) and it has its own cache so Squid caching Drupal content is
neither really desired nor really feasible. Drupal does supply the necessary headers which tells
369
Drupal Handbook 3 Aug 2007
Squid not to cache its pages. However, images and other static content can be cached by Squid
and usually it really helps.
Am not sure if these tips do any good for someone on a shared hosting plan or not (do
shared plans have access to a my.cnf file?). Also, I can only confirm these setting for MySQL
4.0.2 thru the latest 4.0.x version, but I think it would work for 5.x (maybe someone can confirm
this and leave a comment...). Actually, it will work for below 4.0.2 I think as long as you add
set-variable = before each line (see this page for more on set-variable)
1. Get this script, upload it, unzip it, and install it in your /etc folder (at the root of your
server, not your Drupal install, right). Then run it from the command line by entering sh
/path-to-file/tuning-primer.sh
The script will run and what you’ll be left with is an output with some info and suggestions
about your MySQL settings. Was shocked to learned that on my VPS the cache was not even
enabled - very helpful to know!
2. Next open your my.conf file in pico or some kind of proper code/text editor:
Depending on the memory resources you have available you’ll want to paste in something
like these examples (adjust up or down depending on how your system differs, of course):
For a setup with 500mb or ram paste this in your my.cnf file:
[mysqld]
max_connections = 800
max_user_connections = 800
key_buffer = 36M
myisam_sort_buffer_size = 64M
join_buffer_size = 2M
read_buffer_size = 2M
sort_buffer_size = 3M
table_cache = 1024
thread_cache_size = 286
interactive_timeout = 25
wait_timeout = 1800
connect_timeout = 10
max_allowed_packet = 1M
max_connect_errors = 999999
query_cache_limit = 1M
query_cache_size = 16M
370
3 Aug 2007 Drupal Handbook
query_cache_type = 1
tmp_table_size = 16M
[mysqld]
max_connections=500
max_user_connections = 500
key_buffer = 16M
myisam_sort_buffer_size = 32M
join_buffer_size = 1M
read_buffer_size = 1M
sort_buffer_size = 2M
table_cache = 1024
thread_cache_size = 286
interactive_timeout = 25
wait_timeout = 1000
connect_timeout = 10
max_allowed_packet = 1M
max_connect_errors = 999999
query_cache_limit = 1M
query_cache_size = 16M
query_cache_type = 1
tmp_table_size = 16M
3. Save your my.cnf file and restart mysql. This can be done via WHM or the command line
(not sure what that command is - sorry)
Your new settings are now active and you can see run the script from above again and see
the difference in your results. After some experiementing I’ve found that it is useful to look at
the script results right after making a change just to see if your modifications were recognized by
the system and get the early returns from whether things were improved or not - but - to get a
truly accurate reading from the script you should check back in 24-48 hours after rebooting
mysql (this is actually noted at the top of the script itself, but it doesn’t really explain why). Also,
I’ve found that the way I’ve got Drupal set up it is particularly demanding in the tmp_table_size
and table_cache areas (e.g., you may want to bump up the number for both of these areas in the
settings above)
If you’d like to read up on more about mysql tuning I suggest taking a look at these
resources:
MySQL variables
371
Drupal Handbook 3 Aug 2007
Tuning PHP
1. If you have CPU cycles to spare, or if bandwidth is a more constrained resource than
CPU cycles, you can add the following to php.ini:
output_handler = ob_gzhandler
372
3 Aug 2007 Drupal Handbook
"You can redirect all of the output of your scripts to a function. For example, if you
set output_handler to ’ob_gzhandler’, output will be transparently compressed for
browsers that support gzip or deflate encoding. Setting an output handler
automatically turns on output buffering."
Additional resources:
But there are times when PHP should be configured to disallow persistent connections
to the database.
Each apache process can potentially obtain a persistent connection to each database the
server is hosting. If there are lots of apache processes and lots of databases it is common
to see the database throwing "too many connections" errors.
Increase the number of available connections the database will allow. If most
connections are idle most of the time, this is a viable solution.
Disable pconnect via the XXsql.allow_persistent = Off attribute in your
php.ini. The performance hit from this setting is very slight.
PHP caches
PHP is a scripting language. Each time a PHP script is run to generate a webpage with
Drupal, your web server must compile the PHP script into an executable format. This
results in an obvious amount of overhead each time a page is generated.
A PHP cache can be installed to save and re-use compiled PHP scripts, thus greatly
reducing the amount of overhead required for Drupal to display a web page.
PHP Accelerator
After Burner
Zend Accelerator
373
Drupal Handbook 3 Aug 2007
APC is a free and open PHP op-code cache that can significantly speed up PHP
applications in certain cases.
Here are instructions on how to install PHP APC on Ubuntu Dapper (and Debian?)
eAccelerator
From what I can tell eAccelerator is the best free php accelerator.
Here are my notes on how to set the control variables (in php.ini):
;linux 2.6 has 32meg limit. If you have the memory and lots of modules try to set even
higher e.g to 64
eaccelerator.shm_size="32"
; people have suggested that putting this directory on a fast separate disk will help
; you shouldn’t be generating that much activity on this disk anyway because of the
shared memory configured above
eaccelerator.cache_dir="/Applications/MAMP/tmp/eaccelerator"
eaccelerator.enable="1"
eaccelerator.optimizer="1"
; You can set this to 0 for production sites. 1 means checks modification times so you
don’t need to restart web server
; if you are editing your php. You aren’t editing php scripts on live sites are you?
eaccelerator.check_mtime="1"
eaccelerator.debug="0"
eaccelerator.filter=""
eaccelerator.shm_max="0"
eaccelerator.shm_ttl="3600"
eaccelerator.shm_prune_period="0"
; set this to 1 if you want to just use the memory cache: good if you have configured a
large one
eaccelerator.shm_only="0"
eaccelerator.compress="1"
eaccelerator.compress_level="9"
Turck MMCache
The Turck MMCache has been confirmed to work well with Drupal. Installation is quite
simple, resulting in a quick and noticeable performance increase.
374
3 Aug 2007 Drupal Handbook
Overview:
According to the project’s home page:
"Turck MMCache is a free open source PHP accelerator, optimizer, encoder and
dynamic content cache for PHP. It increases performance of PHP scripts by caching
them in compiled state, so that the overhead of compiling is almost completely
eliminated. Also it uses some optimizations to speed up execution of PHP scripts.
Turck MMCache typically reduces server load and increases the speed of your
PHP code by 1-10 times."
Compatibility:
The Turck MMCache runs on Linux and Windows, working with Apache 1.3 and
Apache 2.0, compatible with PHP 4.1 and later.
The following versions of MMCache have been tested successfully with Drupal 4.1+:
2.3.15, 2.3.23, 2.4.6.
Installation:
Step-by-step installation instructions can be found here. Once properly installed, you
should immediately notice an improvement.
CPU Utilization:
The sar utility from the sysstat collection gathers system activity numbers over time.
The following sar snapshot taken from a dedicated Drupal server shows how the
installation of MMCache can help reduce system load on even a heavily-optimized web
server (MMCache was installed around 12:00PM):
375
Drupal Handbook 3 Aug 2007
99.29
12:50:00 PM all 0.44 0.00 0.11
99.45
Troubleshooting:
An easy way to tell if MMCache is working properly after following the installation
instructions is to see if temporary files are being created in ’/tmp/mmcache’, or wherever you
told them to be written with the ’mmcache.cache_dir’ directive. If no files are appearing,
something is wrong.
First, be sure that PHP has properly loaded mmcache. Create a short script on your web
browser called ’phpinfo.php’ as follows:
<?php
phpinfo();
?>
Load that file in your browser to find a wealth of useful information. Search for any
occurances of the word ’MMCache’. If it’s not there, then MMCache is not loaded. Double check
your ’Configuration File (php.ini) Path’ on that same page, and be sure that you modified the
correct ’php.ini’ file. Verify that you installed ’mmcache.so’ into the directory specified by the
’extension_dir’ directive. Also, try restarting your web browser to be sure the latest
configuration changes have been made. Finally, be sure to look in your web server’s error log to
see if there are any hints there. (Note that the phpinfo() function call reveals a _lot_ of
information about your system. For security reasons it is very unwise to make this information
available to the general public. If you created ’phpinfo.php’ in a public place, be sure to remove
it when you’re finished troubleshooting.)
Additional resources:
For people who are setting up servers, or who are interested in learning more about how
Drupal can run more efficiently, this article is a good read.
376
3 Aug 2007 Drupal Handbook
The configuration file is in etc/mysql4; or if you followed the above instructions for
installing MySQL, it should go in /usr/local/mysql but is not there by default. You can put it
there by copying it in:
sudo cp /usr/local/mysql/support-files/my.large.cnf
/usr/local/mysql/my.cnf.
Restart MySQL for the new settings to take effect.
To view the current variable settings for MySQL, from the terminal command line client
type: mysqladmin -uroot -p variablesI opted for the "my.large.cnf" settings and
halved the sql query times.
You can monitor MySQL through a pleasant user interface using MySQL Administrator,
though it seems to expect my.cnf at /etc/my.cnf (it will still work, you just can’t view the conf
file).
I also discovered that I could roughly halve page load times by using Apache 2 instead of
the stock Apache on Tiger.httpd -v to see what version you are running. I downloaded
the php and Apache 2 from ServerLogistics: http://serverlogistics.com/downloads.php.
I am not sure I can recommend this for production sites as I do see some error diagnostics I
haven’t resolved yet. I didn’t expect such a big difference with Apache2. Measurements with a
system call profiler show that it does about half the read(2) system calls as Apache 1.3.
The overall impression I have from my benchmarking is that drupal pages require a lot of
disk I/O to synthesize. Anything you can do to speed up or miminize (e.g. caching) is going to
help. MySQL already has plenty of caching if a my.cnf files is being used. For the Apache/PHP
part busy sites will need a php accelerator.
377
Drupal Handbook 3 Aug 2007
Please note that comments are not meant to address problems you found during installation. For
problems with installation, please address your questions at proper places. Note that Drupal
versions prior to 4.6.3 are now known to have security vulnerabilities and therefore you should
upgrade to the latest version of Drupal. After upgrading Drupal core you might need to convert
custom modules and convert custom themes.
NOTE: One of the most IMPORTANT things to do BEFORE you upgrade, is to backup your
sites files and database. See this node for an example of an automated backup script.
Introduction to upgrading
Every few months, a new version of Drupal is released. In order to fix security issues and take
advantage of many new features, upgrading your Drupal site to the latest version is
recommended. Upgrading your Drupal site involves three basic steps:
However, to make your update run as smoothly as possible, there are various preparations that
experienced Drupal users do to guarantee the least frustrating upgrade and minimal
interruption to their users. These best practices are represented in this full tutorial along with the
basic steps.
NOTE: You should check to see if the contributed modules you rely on have been upgraded as
well. Old versions of modules will not run on an upgraded version of Drupal (e.g 4.7 modules
do not work on a Drupal 5.x site).
Command line. Via SSH terminal access, you can connect to the server, enter commands
directly, and complete all the steps in the upgrade.
GUI. You can use phpMyAdmin, a browser-based MySql interface, to do anything you
need on your database. And you can use any FTP client, such as SmartFTP, to transfer the
files for your Drupal site from your desktop to the server.
378
3 Aug 2007 Drupal Handbook
Once you have determined whether you will use the GUI or command-line version (or a bit of
both), you’re ready to prepare to upgrade by following the instructions given in the links below.
Login as USER 1, the root user, the very first account created when Drupal was installed. If
you cannot login as the root user, you will need to modify the update.php script once you
load the new files for your site.
Turn off all modules that are not core modules:
administer >> modules
Also, switch your theme back to the default theme (’BlueMarine’ in 4.7 and lower, ’Garland’
in 5.x):
administer >> themes
Drupal 5 and later will also alert you to run update.php if it is detected that your database is no
longer up to date. The alert will appear on the Administration page (admin) and the status
report (admin/logs/status).
Choose either the GUI or command-line method for backing up your site.
379
Drupal Handbook 3 Aug 2007
cp -r . backup/.
Where the directory ’drupal_site’ is a the path to your live site. If you are upgrading a test site,
this would be your test site directory. Go ahead and back up your test site files to a new
directory.
Make sure the .htaccess file gets copied to the ’backup’ directory as well.
a) Navigate to your live site directory, and download a special script to your Drupal site folder
which will backup your database to a file called ’backup.sql’. Put the backup in your ’backup’
directory.
cd drupal_site/
wget
http://cvs.drupal.org/viewcvs/*checkout*/drupal/contributions/sandbox/dr...
chmod +x drupalsqldump.sh
If you are upgrading a test site, the path ’drupal_site’ would be the path to your test site.
b) The following command will look at your Drupal settings file, automatically connect to the
database, and make a backup of it.
If you are running a version of Drupal that is 4.6 or newer, then enter the following:
If you are running a version of Drupal 4.5 or older, run the following:
380
3 Aug 2007 Drupal Handbook
If you are upgrading a test site, the path ’drupal_site’ would be the path to your test site.
Remember where you saved this backup.sql in case there is an error during the upgrade.
If you choose not to create a test site, skip forward to Downloading Drupal and installing the
files. Otherwise, choose either the GUI or command line method for Copying your live site to a
test site.
Make sure you have already completed the steps for backing up your site.
$db_url = mysql://user:pass@localhost/test_site_db’;
(test-site database login & password, URL location of the test-site database. "localhost" usually
works by default.)
381
Drupal Handbook 3 Aug 2007
$base_url = ’http://www.example.com/test_site’;
(This is where you want to move Drupal. You can install Drupal to a subdirectory such as
http://www.example.com/test-site. This is what we want.)
$db_prefix = ’’;
(Sometimes your database tables will have a prefix. Ask your webhosting company for help if you
think this is causing a problem. Otherwise leave it blank.
II. Upload the backed-up Drupal files to a test-site folder on your server
First, create the subfolder "test_site" first. Right-click in SmartFTP and click
"New"...."Folder". Other FTP clients may have slightly different methods.
Using an FTP client such as SmartFTP, upload all the backed-up Drupal files to the
directory:
http://www.example.com/test_site
V. Get ready for the basic steps.The basic steps will repeat some of the work you just did such
as backing up your live site and database. You can skip those steps in the basic steps
instructions.
Make sure you have already completed the steps for backing up your database.
cp -R /path/to/drupal/path/to/drupal_backup
Make sure the .htaccess file gets copied to the test_site directory as well.
382
3 Aug 2007 Drupal Handbook
(Where ’dba_user’ is an example MySQL user which has the CREATE and GRANT privileges.
Use the appropriate user name for your system.)
b) MySQL will prompt for the ’dba_user’ database password and then create a blank test_site
database. Next you must login and set the access database permissions:
mysql -u dba_user -p
c) Again, you will be asked for the ’dba_user’ database password. At the MySQL prompt, enter
following command:
flush privileges;
$db_url = ’mysql://user:pass@localhost/testsite_db’;
(test-site database login & password, URL location of the test-site database. "localhost"
usually works by default.)
$db_prefix = ’’;
(Sometimes your database tables will have a prefix. Ask your webhosting company for help if you
think this is causing a problem. Otherwise leave it blank.)
$base_url = ’http://www.example.com/test_site’;
(This is where you want to move Drupal. You can install Drupal to a subdirectory such as
http://www.example.com/test_site. This is what we want.)
IV. Insert the backup.sql file into the test_site database Now that you have a new blank
test_site database, you must take the backup.sql file created by the live site database and run it.
This will create a copy of the live site database on the new test site database.
383
Drupal Handbook 3 Aug 2007
cd test_site
b) Get the database insertion script, and set permissions on the script. You database may a limit
on the size of file it can import. Use the --max_allowed_packet option for mysql to increase the
size of db import.
c) Now execute the script which will create all the Drupal tables needed on the test_site
database:
If you are running a version of Drupal 4.6 or newer, then enter the following:
If you are running a version of Drupal 4.5 and older, run the following:
If you setup a test site, you are going to be updating it instead of your existing, live site.
384
3 Aug 2007 Drupal Handbook
.htaccess
sites/default/settings.php (*** see note below!)
the ’files’ directory
any other files you need from the ’backup’ directory
*** If you are upgrading from a version of Drupal that is older than Drupal 4.5, you will have to
look in your ’backup’ directory for a file called:
<strong>includes/conf.php</strong>
Then using a plain text editor such as jEdit, copy the following three lines as they appear in your
conf.php file:
<strong>$db_url = mysql://user:pass@localhost/drupal_db’;
$base_url = ’http://www.example.com’;
$db_prefix = ’’;</strong>
And paste them over the appropriate lines in your new Drupal file on your server, located here:
<strong>sites/default/settings.php</strong>
It’s simply a matter of overwriting the above three lines in settings.php with the lines in
conf.php.
These settings are responsible for connecting your Drupal to the database and to the files it
needs. The file name and location was changed from Drupal 4.5 to 4.6, hence the magical dance
involved.
1. Navigate to your Drupal directory and move all the old files using the standard Unix ’mv’
command. If you are upgrading a test site, this means move all the test site files. Move these
to a backup directory.
2. Download and untar the new Drupal files to your Drupal directory:
cd drupal_site/
wget
385
Drupal Handbook 3 Aug 2007
http://ftp.osuosl.org/pub/drupal/files/projects/drupal-4.7.3.tar.gz
tar -xzvpf drupal-4.7.3.tar.gz
If you are upgrading a test site, the path ’drupal_site’ would be the path to your test site.
.htaccess
sites/default/settings.php (*** see note below!)
the ’files’ directory
any other files you need from the ’backup’ directory
*** If you are upgrading from a version of Drupal that is older than Drupal 4.5 , then you will
have to look in your ’backup’ directory for a file called:
includes/conf.php
Then using your favorite text editor, copy the following three lines as they appear in your
conf.php file:
$db_url = mysql://user:pass@localhost/drupal_db’;
$base_url = ’http://www.example.com’;
$db_prefix = ’’;
And paste them over the lines in your new Drupal file located here:
sites/default/settings.php
It’s simply a matter of overwriting the above three lines in settings.php with the lines in
conf.php.
These settings are responsible for connecting your Drapal to the database and to the files it
needs. The file name and location was changed from Drupal 4.5 to 4.6, hence the need to move
these lines to the new file.
Running update.php
If you have previously determined that you do not need to update your database, you may skip
the following step. However, it does not hurt to run the update.php script just to verify whether
or not a database update is necessary. Just make sure that you have made a backup of your
database first.
If you setup a test site, you are going to be running update.php on it instead of your existing,
live site.
386
3 Aug 2007 Drupal Handbook
editor. Otherwise, you will not be permitted to update the database. Change TRUE to FALSE for
the $access_check statement like so:
$access_check = FALSE;
After you complete the upgrade, be sure to CHANGE the update.php file BACK TO IT’s
ORIGINAL STATE if you have made this change. Otherwise, anyone would be able to run the
update.php file on your site.
http://www.example.com/update.php
or
http://www.example.com/test_site/update.php (if you are upgrading a
test site)
The update script should only be run once, it will complete all the updates at once. If prompted
for which version, choose the closest starting version that makes sense for you.
This will update the default Drupal and contributed module database tables automatically
(versions prior to 4.7 will require manual upgrade of the contributed modules). Once the script
has stopped loading, be sure to scroll to the bottom to look for errors.
387
Drupal Handbook 3 Aug 2007
If you are moving from Drupal 4.4 to Drupal 4.5 then you need to change the path table to
replace node/view/number and book/view/number to node/number. Users path changed
from /user/view/number to /user/number. You should also enable legacy module to do
handle URL requests of the old type.
We recommend you upgrade to the latest release which takes care of all known database issues
at this time.
Post-upgrade steps
Congratulations! You have completely upgraded your Drupal installation.
You should now go to your adminster >> modules page and enable new modules from your
upgrade. Be sure to then go to adminster >> access to get enable permissions to use that module
for different roles. Make sure anonymous users don’t have too many permissions.
The last step in an upgrade is to delete or move the following files from your site:
install.php
update.php
CHANGELOG.txt
INSTALL.txt
LICENSE.txt
MAINTAINERS.txt
UPGRADE.txt
If you have upgraded a test site and are satisfied with the results, you will now need to copy the
test site to a live site.
If you have more questions, please consult the Troubleshooting FAQ guide and please don’t
hesitate to Ask for Help in the Forums.
For a more thorough review we recommend you review the administration help in your site at
administer >> help. Each page of help documentation has links to the most important pages for
each module.
388
3 Aug 2007 Drupal Handbook
From a command line on a computer connected to the Internet run wget with the following
options:
The cookie this command is referring to is the cookie downloaded from your browser when you
last logged into your Drupal site as an admin.
-r to recursively crawl the site. --delete-after, --cookies=off tells the crawler not to use a cookie.
--header=’Cookie: PHPSESSID=XXXX’ tells the Drupal site that session information will be
passed in the http header. This should be repeated 2 more times; once for a regular userid, and
once for an anonymous userid. After the link check is done check your Drupal admin logs and
your webserver error logs. Look in your browser preferences to see what cookies you have for
your url.
389
Drupal Handbook 3 Aug 2007
cp live_site/.htaccess backup/.
Make sure the .htaccess file gets copied to the ’backup’ directory as well.
II. Copy your test site files to your live site directory
1. Delete all your live site files with the Unix ’rm’ command. You made a backup, right?
2. Copy the contents of your test site directory to your live site directory
cp test_site/.htaccess live_site/.
Make sure the .htaccess file gets copied to the test_site directory as well.
$base_url = ’http://www.example.com/’;
(This is the address of your live site directory. This tells Drupal where to look for the Drupal files to
connect with.)
There is no need to change the database settings. Just take note that your test site database is now
being used as the live site database.
390
3 Aug 2007 Drupal Handbook
$base_url = ’http://www.example.com/’;
(This is the address where you will upload your live site directory. This tells Drupal where to look for the
Drupal files to connect with.)
There is no need to change the database settings. Just take note that your test site database is now
being used as the live site database.
III. Upload the test site Drupal files to your live site directory
Using an FTP client such as SmartFTP,
1. Download all your live site files to a backup folder on your desktop.
2. Delete all your live site files on your server. You made a backup, right?
3. Upload all the test site files to the directory:
http://www.example.com/
"DO NOT attempt to go from 4.7.6 to 5.1 direct. You MUST upgrade to 5.0 first, else update.php will
fail. there are database changes at 5.0 and 5.1 and they need to be done in sequence. this useful fact is not
documented anywhere but it is hinted at here http://drupal.org/drupal-5.1
391
Drupal Handbook 3 Aug 2007
"DO NOT attempt to go from 4.7.6 to 5.1 direct. You MUST upgrade to 5.0 first, else update.php will
fail. there are database changes at 5.0 and 5.1 and they need to be done in sequence. this useful fact is not
documented anywhere but it is hinted at here http://drupal.org/drupal-5.1
392
3 Aug 2007 Drupal Handbook
);
CREATE TABLE locales_meta (
locale varchar(12) NOT NULL default ’’,
name varchar(64) NOT NULL default ’’,
enabled int4 NOT NULL default ’0’,
isdefault int4 NOT NULL default ’0’,
plurals int4 NOT NULL default ’0’,
formula varchar(128) NOT NULL default ’’,
PRIMARY KEY (locale)
);
<?php
// Connecting, selecting database
$link = mysql_connect(’host’, ’dbuname’, ’dbpw’)
or die(’Could not connect: ’ . mysql_error());
echo ’Connected successfully’;
mysql_select_db(’dbname’) or die(’Could not select database’);
// Performing SQL query
$query = "CREATE TABLE users_roles (uid int(10) unsigned NOT NULL
default ’0’, rid int(10) unsigned NOT NULL default ’0’,PRIMARY KEY
(uid, rid))";
$result = mysql_query($query) or die(’Query failed: ’ . mysql_error());
$query = "CREATE TABLE 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))";
$result = mysql_query($query) or die(’Query failed: ’ . mysql_error());
// Closing connection
mysql_close($link);
?>
It takes about an hour and a half to complete and it is important to follow each step carefully to
avoid glitches or gremlins appearing at a later stage.
393
Drupal Handbook 3 Aug 2007
Make a backup of your Drupal MYSQL database and the Drupal 4.5 files & folders on your
server, so you can recover your complete site in case anything should go wrong during the
upgrade.
394
3 Aug 2007 Drupal Handbook
user.module
watchdog.module
=================
395
Drupal Handbook 3 Aug 2007
downloading a 4.6 version of the modules. Some of the more complex modules will usually have
a unique module-update.php file included, to ease the process. Check the readme.txt or
install.txt in the module folder as you download them to check for upgrading instructions.
1. Go to ADMINISTER -->> SETTINGS -->> SEARCH. It will indicate how much of your
upgraded site is being indexed.
2. If your site search index is not 100%. Type www.example.com/cron.php in your
browser.
3. Wait for a minute (longer if you have a very large site) and press the back button to bring
you back to the SETTINGS/SEARCH page.
4. If your site is still not 100% indexed and/or you received an error message when running
CRON.PHP adjust the settings accordingly and type www.example.com/cron.php again.
5. Repeat the process until your site is 100% indexed
Blocks
There are a lot of improvements in how BLOCKS are built in Drupal 4.6.x. If you had block
paths configured on the block administration page in your Drupal 4.5 site, you’ll have to
reconfigure these after the upgrade.
Permissions
Please note that permissions screen has moved to ADMINISTER -->> ACCESS CONTROL in
Drupal 4.6.x. To ensure your permission settings match those set on your Drupal 4.5 site, follow
these steps:
396
3 Aug 2007 Drupal Handbook
Forums
After upgrading, you need to re-associate the category terms you used in Drupal 4.5.x to
FORUM TOPIC node types. The reason is that there is a change in how FORUMs are managed
between version 4.5.x and 4.6.x including the new FORUM configuration screen that makes it
easier to manage your FORUMS.
There also appears to be a bug in the update.php script dealing with forums that registers every
LAST POST in each category to Anonymous.
Worth checking the Upgrade Poblems Forum in case someone else has worked out what’s
wrong.
Images
Upgrading a site with the image.module installed also appears very problematic. I didn’t have
the image.module in the site I upgraded so I can’t help with any tips. Best to follow the forum
discussions in the Upgrade Problems Forum
Events
Upgrading a site with the event.module installed also appears very problematic. The
events.module comes with a special update-event.php script, which appears to work when
you run it, but, I have tried it on a few occasions and it doesn’t seem to upgrade properly.
I ended up spending so long trying to work out what’s wrong it was quicker for me to copy and
paste each event from the old site into the new site by hand. There maybe a better solution in the
Upgrade Problems Forum
397
Drupal Handbook 3 Aug 2007
Tip for beginners who want to back up the database: If you are unfamilir with PHP MYADMIN or
other MYSQL database management tools it’s worth downloading and installing the Database
Administration Module (dba.module) for Drupal. It allows you to backup your site database from within
Drupal very simply and easily.
1. Once you have made a backup, check to make sure you are upgrading from the correct
version of Drupal.
(Using a text editor like notepad.exe or other, open the CHANGELOG.TXT file from the root (main)
folder of your Drupal installation and check the very first few lines. That indicates the version of
Drupal you are using.)
398
3 Aug 2007 Drupal Handbook
Tip for beginners who want to back up the database: If you are unfamilir with PHP MYADMIN or
other MYSQL database management tools it’s worth downloading and installing the Database
Administration Module (dba.module) for Drupal. It allows you to backup your site database from within
Drupal very simply and easily.
1. Once you have made a backup, check to make sure you are upgrading from the correct
version of Drupal.
(Using a text editor like notepad.exe or other, open the CHANGELOG.TXT file from the root (main)
folder of your Drupal installation and check the very first few lines. That indicates the version of
Drupal you are using.)
399
Drupal Handbook 3 Aug 2007
If you have previously had trouble finding such one time configuration options such as work
flow for content types or post length, check for them in admin >> settings menu.
In your local Drupal (4.7) site, if you have the help module turned on you have admin >> help
That takes you to this page ?q=admin/help
Let’s pick a common one, taxonomy ?q=admin/help/taxonomy
For more information please read the configuration and customization handbook
Taxonomy page.
If you click on the link, you are brought back to Drupal.org. If anyone has provided additional
information to that module since release, they will now get the updated text and and additional
material people have seen fit to contribute as child pages.
Drupal 4.7 allows you to easily create context sensitive menus using primary and secondary
menus.
To enable this behavior, in admin >> settings >> menu you must set both Menu containing
primary links: and Menu containing secondary links: to the same menu.
Contributed modules that come with an .install file should be kept enabled. The .install
file is not only used to do setup tasks, it also includes instructions to perform updates. If the
module is enabled when running update.php, these instructions can be automatically executed
400
3 Aug 2007 Drupal Handbook
during the Drupal update process. This of course requires that the module’s old files are
replaced by the new ones before the update.
If such modules are disabled before the update process, database error messages are likely to
appear when they are enabled again. Also performing the module’s update afterwards is a
rather cumbersome task.
A .install file is run the first time a module is enabled, and is used to do setup required by
the module. The most common task is creating database tables and fields (which prior to version
4.7 was done manually).
.install files are also used to perform updates when a new version of a module needs it.
More information for module developers can be found in the developers handbook here.
The short answer for site admins is that if a contributed module uses this new method, you will
no longer need to manually load SQL tables into the database.
The migration script attempts to successfully migrate your existing links but you will need to
verify if it is successful.
The Nmoderation project has been updated to 4.7 compatability. It now uses the VotingAPI for
its storage and calculation, so in the coming months it will also benefit from the increasing
integration with actions.module and views.module that is being added to the API.
401
Drupal Handbook 3 Aug 2007
This will change the way in which relative links are encoded by hand in a Drupal site.
Previously, to link to a Drupal node such as
http://example.com/drupal/node/1000
<href="node/1000">
Now, with the absence of the base href statement, the relative link is written relative to the
domain name like this
<a href="/drupal/node/1000">
When updating from 4.6 to 4.7, update.php will fix relative links in previously existing content
in
nodes
comments
custom blocks
node submission guidelines
user registration guidelines
Site administrators will want to check HTML code with relative links that they have added in
other places (such as content managed by contributed modules).
Developers creating new Drupal sites for move to a different location when production ready
should be aware. If you build a site in
http://example.com/drupal/
all of the relative URL’s that the content might include have to be expressed in terms
"/drupal/..." (see above). If you then move the site to another folder location or a root domain,
the URL’s cease to function. It is recommended that if you plan to move the site to a root
domain, then construct it in a subdomain so that the relative URL is preserved. Or developers
may choose to borrow from update.php to create a script to update their tables (perhaps
someone will share such a script).
402
3 Aug 2007 Drupal Handbook
To get around this new limitation, in your page.tpl.php file you can replace print $mission
with include ’mission.tpl.php’. Create a file mission.tpl.php with your mission
statement and it will be called by your page.tpl.php.
403
Drupal Handbook 3 Aug 2007
Troubleshooting FAQ
If you are installing Drupal for the first time, or you are trying to configure some part of your
existing installation, chances are your problem has been asked and answered countless times
already. Use this list of Frequently Asked Questions as your initial problem-solving helper. If
you don’t find your answer here, search the entire Drupal site. Failing that, you can ask for help
in the Support forum.
DO NOT simply post a Support Forum request without at least making an effort to find the
answer yourself. Yes, we know its tempting, but the answer you seek has been found by
someone else before you.
1.
2.
.htaccess config problems - "Internal server error" - Error 500 directive not allowed here
Memory problems Fatal error: Allowed memory size of 8388608 bytes exhausted
Misbehaving javascript - modules/troublesome/utility.js 404 file not found
3.
404
3 Aug 2007 Drupal Handbook
5.
405
Drupal Handbook 3 Aug 2007
search.
Take care to leave out pathnames (but filenames are probably useful). Try different
permutations of quotes around what seem to be discreet parts of the message.
Try searching both with and without arguments. Strings input by the user won’t help much
when searching for the problem elsewhere.
6.
406
3 Aug 2007 Drupal Handbook
9.
To answer a question like "how is my sites rss.xml created?", a troubleshooting process may
be:
All dynamic pages can be debugged by starting like this. Look at the URL, identify the
module that serves that URL, trace the callback through the code.
407
Drupal Handbook 3 Aug 2007
The popular distribution from CivicSpace requires 24MB of memory so you may have to
experiment with what memory value works for your needs.
All fatal errors can result in a blank modules page. If you want to be sure if the memory limit is
causing this problem, you should check your web server error logs. Hunt for a line that looks
like:
Always keep in mind that generally, "Less is More." The less memory your installation
consumes, the faster it is, and the more people can visit your site at one time.
You may have to restart Apache for the configuration changes to take effect.
Drupal 4: http://www.example.com/?q=admin/block
Drupal 5: http://www.example.com/?q=admin/build/block
Note: Use the literal word user, not your username or user id.
You are probably using MySQL 4.1 or higher and need to reset the password to pre 4.1 style.
408
3 Aug 2007 Drupal Handbook
Unfortunately there is usually a knowledge gap between the Drupal installation documents and
the exact environment a new user is confronted with when attempting to install and configure
Drupal. For more experienced users that have a little Unix and Apache (a typical webhost setup)
knowledge under their belts, bridging the gap between their webhosting environment and the
general purpose Drupal installation guide is no problem. Things are more confusing for less
experienced users though. The following info is intended to help newbies come to grips with the
documentation and their webhosts environment.
There are a wide range of web site configuration tools (eg CPanel, Plesk, webmin etc) and near
infinite number of ways a webhost could configure a webserver. What this means is that a lot of
the general Drupal docs you read will have to use the lowest common denominator (ie Unix
shell commands) to describe configuration steps.
Less experienced users will not fully understand what these commands do or why they should
do them, and definitely won’t know when to deviate from them. To make matters worse most
webhosts don’t even offer shell access, so the instructions need to be ’translated’ to whatever
control panel they offer.
The following topics will hopefully provide just enough insight into Apache and Unix that new
users will be able to better understand the installation documentation and ’tune’ their sites for
running Drupal without too much pain. As a new user you might also gain an understanding of
why most of the docs are written the way they are.
Note: There are webhosts that offer Drupal specific hosting for those without the time or
inclination to do it themselves. See http://drupal.org/services and
http://drupal.org/forum/34 for more info.
Every program that runs on a Unix machine runs as a specific user account. This includes the
webserver itself, any command line shell you are running, and whatever software you use to
access the servers filesystem and admin interfaces (eg FTP software, CPanel interface etc). When
you log in with a username and password through an FTP client or a control panel you are now
operating on the server using that user account.
409
Drupal Handbook 3 Aug 2007
Note: this doesn’t include any Drupal user accounts you have set up. They only exist in your
Drupal database, not as any operating system user accounts.
All files on a Unix server have an owner and a group assigned to them. Whenever a file is
created on the server it is automatically owned by the user account running the program that
created it. Each user account also has a primary group associated with it, and this group also
gets assigned to the files group.
Each file and directory also has a set of permission ’bits’ assigned to it as well. These permission
bits determine what access various users get to a file. The owner of a file is allowed to change
these permissions, but all other users can’t change them (with the exception of the root user).
The file permission bits are arranged into three sets: ’user owner’, ’group owner’, and ’other’.
These three sets can also be referred to as ’user’, ’group’ and ’world’ respectively. ’world’ or
’other’ refers to the permissions that apply for any user that isn’t the owner and isn’t in the files
group. Each of these can have its own combination of three basic permissions.
The three basic permissions are ’read’, ’write’, and ’execute’ and are abbreviated as ’rwx’. When
you see dashes replacing a letter that means that the permission is absent eg ’r--’ means that only
read access is present.
When all three sets of permission bits are combined you get a setting like ’rwxr-xr-x’ which
represents ’rwx’ for the owner, ’r-x’ for the group, and ’r-x’ for everyone else.
You will also see permissions represented as a numerical shorthand eg 755 or 644 etc. In this case
the value of ’r’ = 4, ’w’ = 2, and ’x’ = 1, and the digits are determined by adding up these
numbers for each set.
examples:
755 is shorthand for ’rwxr-xr-x’. Translation: full access for the owner, everyone else has
read and execute access
664 is shorthand for ’rw-rw-r--’. Translation: the owner and the group get read and write
access, all other users get read access.
For files these permissions settings are quite straight forward. ’read’ allows accessing the
contents of a file, ’write’ allows the file to be changed or deleted, and ’execute’ allows the file to
be run as a program from the command line shell. Note that the execute bit isn’t really required
for PHP files as they don’t generally get run from the shell.
Permissions on directories are a little different from those on files. ’read’ allows the contents of a
directory to be listed, ’write’ means that you can add or delete files in the directory, and
’execute’ allows direct access to files in the directory (if you already know their names). On most
directories read and execute bits tend to go together ie typically directories will either have both
bits set or neither set.
410
3 Aug 2007 Drupal Handbook
If you have something to add to this list, please post a comment, and one of the document
maintainers will add it for you, then erase your comment.
If you (or your ISP) are running Drupal under an operating system which has SELinux installed
and enabled, you may find that certain operations fail mysteriously. Symptoms include, for
example, files not being written or read though the webserver has permissions; communications
operations such as sending mail or attempting XMLRPC operations failing, although firewall
permissions are OK, etc.
411
Drupal Handbook 3 Aug 2007
You can confirm that SELinux is causing the problem by turning SELinux off temporarily (run
the command setenforce 0 as root) and try the operation. If it succeeds, likely SELinux is the
culprit. (I’m assuming that this is a development setup, not a production machine - SELinux is
designed to protect your system, so turning it off on a production machine is not to be done
lightly). You can get more information about exactly why SELinux is shutting you down by
looking in the log files that it generates, for example, in /var/log/audit/audit.log on FC4.
Look for ’avc’ (access vector cache) messages.
Once you have tracked down exactly what aspect of SELinux policy is causing your operation to
fail, you can modify the SELinux configuration to fix the problem. This may be as easy as
turning on a boolean configuration setting in a configuration file, or as complicated as writing a
new snippet of SELinux policy.
Using the avc messages, the supplied SELinux administration tools and a little bit of help from
Google, the SELinux FAQs/tutorials on the web, and folks on the various the SELinux mailing
lists, you should be able to find your way around configuring additional policy to get Drupal to
do what you need.
I highly encourage you to bite the bullet and run with SELinux enabled, though it does involve a
rather steep learning curve.
The default permissions on these files usually won’t allow other users to write to them for
obvious reasons.
On most servers by default, the webserver runs under a different user account. eg on a Debian
Linux server, Apache usually runs as the www-data user. Some webhosts though might have
installed Apache modules that switch the webserver to run as the owner of the files it is serving
up.
Note: To find out what user the webserver is running as, you can use the phpinfo() function.
There are various ways of doing this - you can upload your own php file to do so, or that
functionality might already be built into tools you already have available like phpmyadmin.
Most documents or people answering forums tend to assume that the webserver is running as a
different user account. The explanations get a bit too fiddly and convoluted otherwise. But if
your server does run the webserver as your own account, keep that in mind when reading other
docs or answers - they might be aimed at the case where it runs as a different user.
How the web server is set up determines which permissions get used to control access to your
files. If the webserver runs under your user account, then Unix uses the file owners permissions
to provide access to your files. If the webserver runs as a different user, then Unix uses either the
’group’ or ’other’ permissions to determine access depending on whether or not the webserver
412
3 Aug 2007 Drupal Handbook
There is a workaround though. You can create a small PHP script containing the commands you
want to carry out and upload it to the server. Once uploaded, you can run it from your web
browser by entering the URL for it. The script will run as the user account the webserver runs as.
Be sure to remove the script after you have used it though.
With these techniques you should be able to get the webserver to do anything the Unix shell can
do.
Take care doing this though. These are the kind of tasks where it pays to practice them on your
test instance first - you do have a test instance right?
You may wonder why you would want to know what these Unix commands do, but once you
have a better idea of what they do you can then translate them to the functionality provided by
your control panel or FTP client etc.
413
Drupal Handbook 3 Aug 2007
cp
copies files and directories. The ’-p’ (for preserve) option switch also copies permissions and
ownerships etc. The ’-r’ (for recursive) option switch also copies subdirectories and files as
well. The ’-a’ (for archive) option switch includes both -r and -p options.
mkdir
creates a directory.
ln
creates a filesystem link. The main kind you will see mentioned is a ’symbolic link’ (using
the ’-s’ option switch) which behaves a bit like a shortcut in windows. You can create a link
to a file or directory located somewhere else and it will behave just like a copy of that file or
directory. But because they are linked rather than just copied, changes to one are reflected in
the other.
wget
a command to download web pages or files off the net and save them to disk.
tar
a zipping and unzipping utility. eg the Drupal download is what’s called a tarball. tar is
used to ’unzip’ the tarball into a subdirectory.
mysql and mysqladmin
command line utilities for connecting to and managing a MySQL database. Just about
anything they can do can also be done by phpmyadmin.
Special characters:
/
the Unix directory separator (just like with URLs) and also represents the root directory.
When a path starts with / it is an absolute path ie it starts with the root directory. A path
ending in / is an optional way of explicitly referring to a directory rather than a file.
..
refers to the parent directory (just like in Windows). A path starting with this is relative to
the current directory. Can be chained together eg ../.. refers to the parent of the parent
directory.
.
like ’..’ but refers to the current directory.
*
wildcard that matches any number of characters (like in Windows)
?
wildcard that matches just one character (like in Windows)
414
3 Aug 2007 Drupal Handbook
Most of the time, any files you upload should end up with the correct permissions to run a basic
Drupal site. Your webhost will have set the default permissions so they will be able to be read by
the webserver.
Where things get trickier is with the infamous ’files’ directory. If you install or enable modules
that upload files or images, they get stored under this directory. To do this, the webserver will
need write access to this directory. What this also means is that any files you upload will be
owned by the webserver user account and may not be able to be moved or deleted any more by
your FTP client or control panel as you might not have enough permissions. In most cases don’t
worry about this too much, but if you really have to delete some of these files manually there are
ways around the problem by uploading your own PHP scripts for the webserver to run and
change the permissions.
All the Drupal files (eg .php, .module, .css, .theme and images etc) will need to be able to be read
by the webserver account. The ’files’ is generally the only directory will need to be writable by
the webserver account.
If you get error messages complaining about missing files, or not being able to open/read a file
etc and you know that the file really is there - chances are that the webserver doesn’t have read
permissions for it. Recheck the permissions on subdirectories etc.
Ideally your settings.php file won’t be world readable as it contains your database connection
string (with password). But sometimes you can’t avoid it if making it world readable is the only
way your webserver can read it.
Along similar lines, ideally for security reasons you won’t have to make anything world
writable. But on a lot of webhosts it is hard to avoid having to make the ’files’ directory world
writable. What ever you do don’t go making anything other than the ’files’ directory world
writable. That makes it easy for other users to overwrite your Drupal files.
If it is possible through your admin interface it can be useful to assign the group ownership of
the ’files’ directory to the group the webserver runs as, and allow group write access. This
improves security a bit by not requiring the directory to be world writable.
Quite often you will hear people talk about setting permissions to 777 which is no restrictions at
all. While that is a good way to isolate any permissions issues when troubleshooting, you should
try to tighten the permissions back again afterwards if possible. Preferably you wouldn’t need to
use 777 permissions anywhere.
Another thing to keep in mind is that a permission setting only tells part of the story about
access - when troubleshooting it is also important to know who the owner and group are, and
well as which user the webserver runs as.
415
Drupal Handbook 3 Aug 2007
With standard HTML only Drupal configuration, Drupal is not creating any files on the web
servers filesystem. When in that mode it runs like a standard web site - all the web server needs
to do is read the files, it doesn’t need to write anything. All the content you submit to the site is
going into the database not the filesystem.
But to be able to upload files or images through the Drupal interface, now Drupal needs to be
able to write files to the filesystem on the server.
This gets tricky because most of the time you don’t want the webserver to be able to write files
into your site directory. Just think what would happen if someone exploited a vulnerability in
someone else’s website on that server - they could now overwrite any of your website files very
easily. Just think what you could get up to just by uploading PHP files if other peoples sites had
wide open write access - no don’t try this.
So generally web servers aren’t allowed to write files in peoples websites. If you do want to
Drupal to be able to write files into a subdirectory - you will have to manually weaken the
filesystem security to make it work.
This isn’t a Drupal issue - any code (eg PHP, Perl, Python etc etc) run by the web server will
need those permissions weakened if they are to be able to write files to part of your web
directory.
You may also run into upload filesize problems that require changing settings like:
memory_limit, post_max_size, upload_max_filesize etc. These settings are there to limit what
any one website can do to overload the server. If these are too high, it allows one site to
completely tie up the server causing trouble for all the other sites.
Its all just the nature of sharing a server with lots of other people. There will be security and
resource limits put in place to stop a badly behaved user causing trouble for the others.
Your webhost is trying to strike a balance between ease of use and security. Different webhosts
will draw the line in different places - that is why it is impossible to write detailed docs that
cover all situations.
If this error is not the first error message on the page, then it is most likely a ’avalanche effect’ of
previous errors and you may ignore it. Instead, focus on fixing the errors before it. When you fix
the first error message(s), the "headers already sent" error(s) will most likely disappear.
416
3 Aug 2007 Drupal Handbook
However, if you get an error "headers already sent" as the first error, especially when trying to
log in and it tells you the error is near the end of a file (check which file "output started at" points
to), that probably means that there are extra spaces or lines after the closing ?> php tag. Just
delete them, and everything should work fine.
The extra whitespace being added probably is caused by a bad unpacking program and / or a
windows editor adding it.
When you installed Drupal, you created a database and a database user. This error is caused by
that database user not having a certain privilege over your database.
When you come across this problem, first, double check that you have granted all privileges to
your user. You can try to grant the LOCK tables privilege by executing the following query:
If the GRANT command does not seem to have any effect on MySQL, you may need to follow it
by "FLUSH PRIVILEGES." If you still get this problem, and you are using shared hosting, it is
very likely that your host does not usually let users have the kind of permission required. For
reference, you may want to read these forum posts. You need to contact your host (e-mail seems
better than live support for this) and ask (if you are using mySQL 4) for global LOCK TABLES
privilege for your user in that database.
Although there are fixes in the forums, these are not recommended. If your host denies your
request, they may not be an appropriate place for your Drupal site.
417
Drupal Handbook 3 Aug 2007
This is caused by the way Drupal handles unauthorised access to items. There is an easy fix to
this problem. The following line should be added to the end of the .htaccess file in the
subdirectory you are trying to access (NOT THE DRUPAL .HTACCESS FILE).
Doing this rewrites the default 401 error so that it is not intercepted by Drupal.
Many porno and online poker sites have robots that are sending "fake" referrer strings, claiming
they entered your site via their own site. When you would have a block displaying these
referrers, they would get more hits from people clicking these displayed referrer URL’s. So it is a
good thing that Drupal doesn’t display these referrers, apart from the referrer logs admin page.
Often, the robots sending these referrers do this via a so-called zombienetwork, thousands and
thousands of misconfigured or hacked PC’s which are "open proxys". You can’t really block this
referrer spam, the robots are sending real user-agents, are using many URL’s and there are so
many zombie IP addresses that are changing fast, that you can’t block these.
There is some work underway to block bad behaving robots and users from within Drupal. This
will probably be part of Drupal 4.7. Until that time, the only way to block the referrer spam it by
looking at your referrer log and look for often used word in the fake referrer URL’s, like
"online-poker".
Now you can block these words in your .htaccess file. Say you want to block the referrers
"internet-poker" and "viagra" as well as all user-agents that contain "looksmart"
First localize your .htaccess. This file is most likely in your Drupal document root. You can use
vi, pico, notepad or another editor. Now go to the end of the file and just before the last line add:
418
3 Aug 2007 Drupal Handbook
RewriteRule .* - [F]
You don’t have to restart your webserver, these settings take place immediately. When you look
at your logs, you will still see the spamming robots with the fake referrer URL’s. But you will see
that these clients now get a 404 error, this means that they are not allowed to access that (or any
other) page.
If the robot that is sending this referrer spam is a "smart" robot, it will know sending the fake
URL didn’t work. Now it wont stop all the bad guys, they will probably try to send another
URL. Or the will go to another site to spam there. But there is a chance you will make it a better
world. Try it.
Here is a list already made available to use, which blocks several spams.
419
Drupal Handbook 3 Aug 2007
order deny,allow
deny from env=BadReferrer
420
3 Aug 2007 Drupal Handbook
The likely problem (short form): At some point, the sequence table in your Drupal database
was not updated.
The solution
1. Access your database. Check the affected table. In this case, the error tells us that it is the
node table (query: INSERT INTO node). This also happens with other tables, modify these
instructions accordingly.
2. This is the node table, so the problem is the node id (nid). Each node has a unique id. Look at
your table, and find the highest node id (nid). If you have many nodes, it may help to sort
your table by nid to find the highest one.
3. Go to your sequences table. Change the node id in the sequences table to a number higher
than the id you found in step 2.
The ’key’ in a table is a column where every entry has to be unique. For example, in the users
table, every UID (user id number) must be unique. You don’t want two users with the same id!
Drupal keeps track of what is the highest ID value separately, in the sequences table. When a
new user is created, Drupal checks the sequences table to find out what the next UID should be.
Presumably this is more efficient than checking the user table itself. Drupal then creates the new
user, updates the user table with the new user information, and updates the sequences table with the
new UID. The same thing happens for the node table, comment table, really, a whole bunch of
tables.
Sometimes, for some reason, Drupal does not update the sequence table. The number there
becomes out of date. So let’s say that in the node table the highest NID is 300, but somewhere,
something went wrong, and in the sequences table, the NID is only 297. The next time Drupal
makes a node, it will check the sequences table, and try to make a node with a NID of
298...whoops! That already exists.
421
Drupal Handbook 3 Aug 2007
The error itself can tell us a lot. Let’s divide it into 3 parts:
The error:
Duplicate... meaning the ’24’ is the same as something else in the table, something where no two
things can be the same. Which table? Which column?
The query:
INSERT INTO [tablename] tells us which table produced the error. What follows is a list of
column names.
The values:
The values we tried to insert into columns of the NODE table... We already know ’24’ was the
problem, we see here it is the LAST value, corresponding to the LAST column, the nid, or node
id.
So the problem is, we tried to insert 24 into the nid column of the node table, when that value
already existed (duplicate entry!).
Why? Because the sequence table was not updated, and told Drupal the wrong nid. The solution
is to enter a value for nid into the sequence table that is higher than ANY nid in the node table.
To find the highest nid in the node table, access your database, however you do it. Find the node
table, and sort it by nid. Write down the highest value. Let’s say for this example that the highest
number is 68.
Go to the sequences table, and find the row that has nid in it. Replace the number there with
ANY number higher than the highest value in the node table. For this example, the highest value
was 68. 69 would work, so would 70, 90, and 201. ANY NUMBER higher than 68 would work in
this example.
Additional point: 99% of the time, the solution is in the sequence table, but this error will come
up ANY time you try to insert duplicate data into a column where every value has to be unique.
422
3 Aug 2007 Drupal Handbook
If you continue to have problems, the use the "user_mail_wrapper" option included with
Drupal.
You can now hook up your own custom SMTP library to Drupal instead of using the default
PHP mail() function. For more people mail() will work just fine, but for others this is a major
problem and it does not work properly. If you just want to get started you will have to
download a custom wrapper function from the Drupal contrib repository. If you already
have a favorite SMTP function you want to use you will have to create your own wrapper
function.
Customize smtp.inc from the repository above to ensure that the proper settings for your SMTP
server are being used.
The following are steps that I used to get Drupal 4.6.x running on Apache with PHP 4.3.10-15 to
successfully relay mail to an external mail gateway without using the php_mail() function. I
have tested this on Postfix and Exchange server mail gateways successfully.
$this->host = ’localhost’; Change localhost to the IP address of your mail gateway. You may
also use the FQDN instead of the IP address if you have DNS set up correctly to something
like yourmailgateway.yourdomain.com.
$this->helo = ’localhost’; Change localhost to reflect the hostname (FQDN) of your external
423
Drupal Handbook 3 Aug 2007
$conf["smtp_library"] = "includes/smtp.inc";
6. Finally be sure to add the IP address of the mail gateway to the [mail function] section in your
php.ini file and restart your web server.
Good Luck! I hope this saves you the hours of researching it took me to get it running.
When you use the file database/database.mysql to create a drupal database, MySQL reports the
following error:
error 1364 (hy000) line 803: field ’page’ doesn’t have a default value.
You may have additional problems when working with Drupal. Sidebars will be absent and
posting content results in an error:
Cause
424
3 Aug 2007 Drupal Handbook
MySQL 5.0 and higher have a strict mode that is currenty incompatible with a number of queries
in Drupal. The Windows Installer from MySQL.com enables this strict mode by default.
Workaround
MySQL needs to be restarted before changes in my.ini have an effect. My.ini can be found in the
MySQL installation directory or the Windows directory, depending on your configuration.
Note: After switching MySQL mode you have to recreate your Drupal database or your site will
not function properly.
On Step 3 of INSTALL.txt - RUN THE INSTALL SCRIPT you do not arrive at the Database
Configuration page, but are greeted with the following warning(s) instead:
Followed by one or more warnings concerning headers that have already been sent:
This happens if you have already edited the $db_url variable in settings.php. The installer
will no longer be automatically invoked, because Drupal assumes installation has already been
completed.
425
Drupal Handbook 3 Aug 2007
The popular distribution from CivicSpace requires 24MB of memory so you may have to
experiment with what memory value works for your needs.
This is most often seen in form functions -undefined function: form_*() but could result from any
missed upgrade step listed in the module developers upgrade notes which lists the deprecated
functions, but most likely means you have installed the wrong version of the module (or that a
compatable version doesn’t exist yet).
You may find that turning on legacy.module will support a few of the older (deprecated)
functions that the troublesome module is trying to call.
This error usually occurs on the modules settings page, but also on other module pages
containing forms.
Most likely cause: the module is specific for Drupal version 4.6.
The way forms are created changed completely in version 4.7. This new forms API means that
all former form_* functions such as form_checkbox, form_select and form_submit, are no longer
available.
Solution: You need to download a 4.7 specific version of the module in question. If the module
isn’t available for 4.7 you might want to try the version marked as "CVS". If that one does give
the same error you should try to update it yourself. For easy forms you can use
426
3 Aug 2007 Drupal Handbook
http://lullabot.com/formupdater
If you succeed in converting the module you should send it to the author so that he can upload it
for others to download.
You may also get this error if you use php snippets in pages or blocks that display forms.
Disable such snippets before upgrading.
If you (or someone) tried making their own module by copying an existing directory (which is
the correct step 1) but failed to rename every function inside the files to their new theme name
(which is the neccessary step 2) you’ll get this error.
Go in and physically remove/move the module/theme files you don’t use out of the
modules/themes directory.
Try to "find in files" for that funcname listed in the errors and see where the dupe is.
Even just having a backup called "Copy of troublesome.module" Is illegal, as the dir scan
returns it as another available theme. It gets evaluated, then conflicts with the original.
Rename it to troublesome.module.bak instead
This error can also arise if two different module installs choose to use and bundle the same third
party library. This is pretty rare. Do the find-in-files to identify the problem, and enquire with
the respective module projects.
427
Drupal Handbook 3 Aug 2007
When the forum module is first enabled, it creates a vocabulary of its own (called Forum) where
it stores half its structure.
If for any reason this vocabulary is deleted (like you decide you don’t want forums yet, or you’re
working on an unstable development site) re-enabling the module will not correctly re-create
the needed vocab again
Thus, you end up with only half a working forum. It seems you can post topics, but the indexing
and overview pages are a bit scrambled, and don’t list anything useful.
The Fix
... is to tell the forum module to forget its old invalid vocabulary id and make a new one.
<?php
variable_del(’forum_nav_vocabulary’);
?>
I use the devel.module, which provides a console where I popped this line, and a variable
viewer which showed me what happened, but another quick way is:
the php code will execute, although you won’t see anything yet.
discard the node, don’t need to save it.
visit admin/forums
this triggers the forum code to check if its parameters are correct.
they are not so it will create the Forum vocab as needed
428
3 Aug 2007 Drupal Handbook
continue, create a new forum or container. The pages should work again as they are
supposed to.
This will disable the module so that you can access your administration panel again.
The theme: example, Internet explorer, Netscape, Opera, Lynx has two Navigation block that
look like this (assuming you have managed to
add link ’Mypage’ there by defining a ’page’):
will show:
* Navigation
* home
* news feeds
* archives
* blogs
* books
* forums
* My Page
* polls
429
Drupal Handbook 3 Aug 2007
* search
but also:
Navigation
* create content
* recent posts
* news aggregator
Where the second one (create content etc.) changes its name to name of the user after the user
logs in.
Themes: marvin and unconed have no generic navigation block but has the same links in the
menu on the top of the page.
Other themes do not have any version of generic navigation block.
In the poast drupal used to have a , what I call "functional navigation". Each module -each
function- could add a link to a general list of links. That list could then be displayed anywhere in
drupal. The list has only one level. so sub-elements were not possible.
For most of the CMS powered sites a functional navigation is the best method of navigation:
forums, blogs etc all have their own specific content-display and content navigation, based on
their function.
But as of drupal 4.3 people started inventing all sorts of navigation modules. These modules
would use tabs, blocks, or even hardcoded (D)html to make the navigation easy.
So in drupal 4.4 there was a general, standard "navigation" block introduced. But this one was
not configurable. Only modules could add items in that block.
So as of 4.5RC JonBob together with lots of others came up with a nice menu system, fully
configurable, with permissions and of course multi-levelled (as was the previous too).
Q: I like the first, generic Navigation block but most of the themes do not display it, even after I
enable Navigation block in the configuration of blocks.
A: The links list is still present in drupal, even in 4.5. You can print a list of linkes using for
example:
<?php
$output .= theme("links", link_page(), " " :: " );
?>
the list will then be something like blogs :: forum :: mypage :: weblinks
Not all themes use this function. In fact, nowadays only very few do. So you will need to add
this manually somwhere.
430
3 Aug 2007 Drupal Handbook
<?php
return $output .= theme("links", link_page() "<br />" );
?>
Please refer to the documentation on drupal.org about printing vs returning in blocks. This is
different in some releases of drupal!
Q: What does the Navigation block in block config refer to? (which block displayed above is
THE navigation block?)
A: That is the default drupal navigation blok. It offers multi-levelled navigation. It is also a place
where some modules place their navigation too (event.module for example).
You can disable this block, but you will then not be able to get into your adminstration, other
than typing in the urls by hand. So be carefull!
Q: Where is the first (generic) Navigation block defined? What to look for if I want to add it to
my theme? I like xtemplate so far so that’s where I would like to have the generic navigation
block.
A: That is an implementaion of
<?php
print $output .= theme("links", link_page() "<br />" ); //Or something
very similar
?>
To fix this, you either need to (1) promote something or (2) change your front page.
(1) Edit a node (or create a new node) and click the arrow next to "Publishing Options" to
expand that section. There is a checkbox labled "Promoted to front page". If you check that and
(re)submit the node it will show up on the front page and the welcome message will disappear.
(2) By default, the front page of your site is ’node’, which is a list of all nodes that have been
promoted to the front page as explained in (1). If you don’t like this, you can change your front
page to any page you like. To do this, go to www.yourdomain.com/admin/settings and click
the arrow next to ’General settings’ to expand that section. Towards the bottom, you will see
’Default front page’. If it’s still at the default, it will be ’node’. Change this to the page you would
like to be your front page. That is, the page that loads when you go to www.yourdomain.com.
For example, if you want people to go straight to the blogs, you would put ’blog’ in that setting.
431
Drupal Handbook 3 Aug 2007
This message is hard coded into the program files so, at this time, it is not possible to have your
front page set to ’node’, have no nodes promoted, and not have this message without changing
the source code. A work-around can be found here:
http://drupal.org/node/30816#comment-53200 .
Clean urls are those fancy looking addresses: instead of www.example.com/?q=/foo/bar you
see www.example.com/foo/bar with clean urls.
Problem is that you cannot set it back, because you cannot browse to the specific page anymore.
NOTE: Drupal 4.6 has added the ability to detect whether your site is capable of running with
clean url’s. If the option to turn them on is greyed out, then you will be unable to activate it until
you resolve the underlying issue.
432
3 Aug 2007 Drupal Handbook
Once you have turned your site off-line using admin » settings » site
maintenance(admin/settings), you can log back in by visiting:
http://example.com/?q=user
Note: Use the literal word user, not your username or user id.
You need to enter the username and password of an account with permission to administer site
configuration. User 1 has this ability as a safety net, should you not have this turned on in other
administrator account(s).
If you attempted to login with a username that does not have the "administer site configuration"
permission you will be stuck in that user account until you clear the browser’s cookies. Simply
instruct your browser to delete cookies for the site and visit the referenced URL above again.
You can also use another browser to access the URL.
If you are truly desperate you can try the following database queries to restore access:
433
Drupal Handbook 3 Aug 2007
You should now have a fresh copy of the missing or corrupted file.
Installation/configuration
406 Error when XMLRPC is used
Some hosting providers (at least one!) may disable xmlrpc.php scripts to plug security holes in
older versions of the XMLRPC libraries. If you’ve installed Drupal and enabled the BlogAPI
module or the Drupal login module on such a provider, you’ll get "406 errors" when you try to
use the features.
One possible solution (aside from convincing your provider to turn the relatively ineffective
security measure off) is to rename the xmlrpc.php file in drupal’s main directory. While this is
bad and will make upgrading a bit of a hassle, it can get you up and running.
You’ll have to alter blogapi.module to point to the newly renamed file, as well as any other
modules that point to xmlrpc.php. In the case of blogapi.module, the reference can be found on
line 560:
When visiting your Drupal site for the first time you see what looks like code output, instead of
the expected theme:
Cause:
Changes made after 4.6.x was released in PHP 5.0.5+/5.1.1+ and the template engine XTemplate
are incompatible.
Before you can change the theme you’ll need to be logged in. Either create the first account or
login at http://www.example.com/?q=user.
434
3 Aug 2007 Drupal Handbook
Make sure to disable all XTemplate themes to prevent visitors from using them. Drupal 4.6
comes with two XTemplate themes included: Bluemarine and Pushbutton. A PHPTemplate
version of Bluemarine is available. Primary/Secondary links configured in the theme general
settings will not carry over to PHPTemplate. You will need to re-configure any
Primary/Secondary links in the PHPTemplate configuration of the theme.
http://example.com/?q=user
The alternative http://example.com/user will only work when clean URLs are enabled.
Note: Use the literal word user, not your username or user id.
Cookies
Make sure cookies are enabled in your browser.
Cache Problems
It seems that sometimes the cache doesn’t get updated when logging into a site so even after
logging in the user is still shown the cached version of the site: not logged in. The source of this
problem (browser, webserver, Drupal settings) is not completely understood.
One solution seems to be to disable the Drupal cache of the site, though that has the undesired
side effect of increasing the load on your site.
Another workaround is for the users to hit the browser refersh button which seems to work
fairly well, but has the drawback of not being easily discoverable and is a hassle for every user of
the site. On a site where only one or two users login, this is not a problem. On a community site
it is a bigger problem.
435
Drupal Handbook 3 Aug 2007
For the next version of Drupal - the problem is fixed as a result of this issue.
While the example has always been to remove the www, the problem and this solution can be
reversed for adding www.
This second issue has been fixed for the "next" version of Drupal in this issue
This problem occurs due to the way PHP handles objects in session handlers. It effects all Drupal
versions upto Drupal 4.7.4 and Drupal 5-beta 1.
The best method of fixing this for Drupal 4.7.4 (and below) users is to upgrade to Drupal 4.7.5
which fixes this problem.
For those wishing not to do a full upgrade yet but need in "instant fix", a patch for Drupal 4.7.4 is
available on http://drupal.org/node/93945#comment-155161. See Patches » HOWTO: Apply
patches for help on applying the patch.
For Drupal-5 beta testers; this has been resolved since the Beta-1 release.
First, please Validate your page and fix all the problems you can. Use the web developer toolbar
to validate local pages.
More on validation below.
436
3 Aug 2007 Drupal Handbook
The content is too wide for the space it’s been given
What’s a poor robot to do?
If you tell a robot to push 1130 pixels into a bag that only holds 1000 - something’s gonna break.
Overlap or overflow are the only things the page renderer can do. (There is currently no
supported ’shrink to fit’ option, and ’expand to fit’ isn’t available in current versions of CSS.)
This is often seen in pages that embed tables, objects (like Flash) or large images that are of
fixed-width and end up making the content column (plus sidebars) wider than the available
screen space.
With percentage-width themes, the available space will depend on browser window size, which
you cannot control.
CSS work-arounds abound, but the first solution is to shrink your content if at all possible.
This is especially easy if you’ve pasted in a fixed-with table. Just remove the width attribute.
You can try #content{min-width:450px;} and similar fixes, but you’ll need to
browser-test. Any suggestions on getting this right are welcome.
Last resort - if you would rather the page always expand to fit your content - and trigger
browser scroll bars at lower resolution - is switch to an old-fashioned table-based layout. If CSS
is too hard for you, you may have to give up on tableless design.
OTOH, if you are keen, alternative fixes are always being proposed over at alistapart.com and
CSS3 apparently will make this dilemma solvable.
Validation Woes
While validation is The Right Thing to do, some warnings/errors are important, some less so. In
general:
437
Drupal Handbook 3 Aug 2007
For more CSS troubleshooting, try the instructions for using the CSS inspector to find the active
styles and go from there.
This behaviour is most likely caused by the Apache module mod_security. Depending on its
filter settings, phrases that trip the module include
lynx, perl, mother, select from, table, cc:, and many more.
Not all hosts will allow this, so you may need to contact your hosting provider.
438
3 Aug 2007 Drupal Handbook
This means that Drupal needs write access to create (and later access) the files and files/tmp
directories. One way to solve this is to give the webserver write access in the directory. Another
common solution seems to be granting everybody write access to the "files" directory. Both
solutions has the drawback that somebody else is able to write files into that directory. [if you
know a better solution, please mention it here]
Solution 1 (recommended)
In the drupal root directory:
mkdir -p files/tmp
chown -R www files
Note: you may need to substitute www with the user id of your webserver process.
Solution 2
In the drupal root directory:
mkdir -p files/tmp
chmod -R 777 files
If the above conditions have been met, you may use the following SQL queries to reset the
node_access table. You can run these from the command line or in phpmyadmin by clicking on
the SQL tab of your right hand pane and pasting the querries into the text area, then clicking go.
Warning: the following SQL queries will reset the entire node access table:
TRUNCATE node_access;
This query deletes all access rules. The next query grants the ’view’ permission to all nodes.
439
Drupal Handbook 3 Aug 2007
* For example: taxonomy access, organic groups, nodeprivacy by role, simple access
phpinfo
On occassion it is useful to see what your php settings are. You can create a php page using
phpinfo() function from within your own Drupal install if you can create php type content. This
is probably not a page you want to leave permanently but can be useful for finding specific
information.
http://us3.php.net/phpinfo
Create a page of php content type and copy and paste the following line in it.
<?php
phpinfo();
?>
1) You are trying to use a theme that is not active. This can happen when you have set the
default theme in settings.php but that theme has not yet been added or configured. It can also
occur when did not switch back to the default theme before upgrade. To fix that issue, go to
admin > build > themes and select the default theme (Garland in 5.x and Bluemarine in 4.7 and
4.6).
2) Your $base_url setting (in your settings.php file) is misconfigured. The $base_url
setting is what gets prepended to all paths for extra resources like stylesheets, images, javascript
includes and form handlers. If the browser can’t find those resources on that path, then they will
be missing from the rendered HTML you see in your browser.
example:
When developing and testing on a local Drupal version you might use localhost in your
$base_url. This works fine when using the browser on the development computer, but
when you access Drupal from another computer all these extra resources are missing. What
is happening is that browser on the other computer is trying to access these extra resources
from localhost and failing to find them there. The solution is to change $base_url to
use a hostname that points to Drupal from both computers (ie not localhost).
440
3 Aug 2007 Drupal Handbook
ServerAdmin webmaster@example.com
# DocumentRoot /home/example/http
DocumentRoot /home/example/drupal
Options +FollowSymLinks +Includes
ServerName old.example.com
ServerAlias www.old.example.com
ErrorLog /var/log/apache/old.lexample.com-error.log
CustomLog /var/log/apache/old.example.com-access.log common
AllowOverride All
RewriteEngine on
NOTE: the change to the last rule above. Without it you may get odd results similar to what is
reported in http://drupal.org/node/54417. Do read the handbooks too.
441
Drupal Handbook 3 Aug 2007
Now we have to find out how to remove the new theme and switch back to an old one. We are
lazy people, moreover our site is big, with lots of content, so reinstalling is not an option. I tested
this with mysql, so these hints are for mysql only.
Dump your database first, and save it somewhere safe so we have a backup. We are going to
edit the dumped records, and reinsert the database. I used this method because using my
favourite editor is way easier and safer than using mysql shell (anyway we shouldn’t edit a live
site database).
The theme name is registered in the following tables in your database: system, variables and block.
After many tries I realised I have to clear the cache manually, meaning to remove all the
INSERT INTO ‘cache_‘ lines in order to see results. Change the ’default_theme’ value in
‘system‘, where note that ’s’ stands for string length, so be sure you put the string length after
the ’s:’. Also make sure you change the value to an existing theme (available themes listed in
‘system‘). And remove, or rename your troublemaker theme.
The change in ‘block‘ is imperative, otherwise the blocks will not appear. Drop your old
database from the sql server and insert the edited one. Voila, we have recovered from a theme
crash.
-->
442
3 Aug 2007 Drupal Handbook
A: Most likely, you need to assign a taxonomy vocabulary to the content type.
You’ve just created a taxonomy and filled it with a perfect array of terms. But there’s no category
menu on the post submission page! What gives?
Go to (administer > categories > edit vocabulary) and look under the "Types" heading. There you
can assign your taxonomy to any content types you want. Save your configuration here, and try
to submit a post. Your taxonomy should now be available to you.
Miscellaneous
How can I change Drupal’s character encoding? (UTF-8 and
Unicode)
Several people have asked how to specify the character encoding that Drupal uses. The short
answer is: you can’t, but you don’t have to.
Drupal uses UTF-8 for encoding all its data. This is a Unicode encoding, so it can contain data in
any language. You no longer need to worry about language specific encodings for your website
(such as Big5, GB2312, Windows-1251 or 1256, ...). Also, when Drupal imports external XML
data (such as RSS or XML-RPC), it is automatically converted into UTF-8 (iconv support for PHP
will be required for most encodings).
If you really want to change Drupal’s encoding, you will experience a lot of troubles, because of
the various ways Drupal can receive and send out data (web, e-mail, RSS, XML-RPC, etc).
443