Professional Documents
Culture Documents
Drupal Handbook
Table of Contents
Installation and configuration . . . . . . . . . . . . System requirements . . . . . . . . . . . . . . Client System Requirements . . . . . . . . . . . Javascript . . . . . . . . . . . . . . . CSS . . . . . . . . . . . . . . . . . RSS . . . . . . . . . . . . . . . . . Browser Specifics . . . . . . . . . . . . . Browser Popularity . . . . . . . . . . . . . Known Problems . . . . . . . . . . . . . Validation . . . . . . . . . . . . . . . Caveats . . . . . . . . . . . . . . . . HOWTO: Server requirement recommendations for your consulting clients Message to the Client . . . . . . . . . . . . Benchmark . . . . . . . . . . . . . . . What Drupal.org runs on . . . . . . . . . . . Requirements - older versions . . . . . . . . . . . Installing Drupal, modules and themes . . . . . . . . . Installing Drupal . . . . . . . . . . . . . . Formatted Drupal 5.x Installation instructions for better readability . Installation . . . . . . . . . . . . . . Changes . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . Optional Requirements . . . . . . . . . . . Installation . . . . . . . . . . . . . . Drupal Administration . . . . . . . . . . . Customizing your theme(s) . . . . . . . . . . Multi-site configuration . . . . . . . . . . . More Information . . . . . . . . . . . . . Formatted Drupal 4.7.x Installation instructions for better readability . Installation . . . . . . . . . . . . . . REQUIREMENTS . . . . . . . . . . . . . SERVER CONFIGURATION . . . . . . . . . . . OPTIONAL COMPONENTS . . . . . . . . . . . INSTALLATION . . . . . . . . . . . . . 1. DOWNLOAD DRUPAL . . . . . . . . . . . 2. CREATE THE DRUPAL DATABASE . . . . . . . 3. LOAD THE DRUPAL DATABASE SCHEME . . . . . . 4. CONNECTING DRUPAL . . . . . . . . . . 5. CONFIGURE DRUPAL . . . . . . . . . . . 6. CRON TASKS . . . . . . . . . . . . . DRUPAL ADMINISTRATION . . . . . . . . . . CUSTOMIZING YOUR THEME(S) . . . . . . . . . UPGRADING . . . . . . . . . . . . . . MORE INFORMATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 3 3 4 4 4 4 4 4 4 5 5 6 6 6 8 8 13 13 14 14 14 14 16 16 16 17 17 17 18 18 18 19 19 19 20 20 21 22 22 22 23 23
Drupal Handbook
3 Aug 2007
10 minute install using PuTTY SSH/Telnet client . . . . . . . . . How I installed Drupal: The Eightfold Way . . . . . . . . . . Installing virtual hosts for Drupal sites and subsites . . . . . . . . Mac OS X-specific guidelines . . . . . . . . . . . . . . Important notes for MySQL install: . . . . . . . . . . . . HOWTO: Create a local server environment for drupal using MAMP . . . . HOWTO: Installing PostgreSQL and MySQL on the same Mac OS X machine . . Installing Drupal on Mac OS X 10.4 Tiger . . . . . . . . . . Installing and Configuring MySQL . . . . . . . . . . . Sending mail . . . . . . . . . . . . . . . . . Creating the Drupal Database and Database User . . . . . . . . Installing using CVS repository . . . . . . . . . . . . Prefixed database.mysql for search and replace . . . . . . . . . . Setup Drupal on Windows XP Pro using IIS . . . . . . . . . . Basic /sites directory setup . . . . . . . . . . . . . . Special cases . . . . . . . . . . . . . . . . . . Compilation failed: this version of PCRE is not compiled with PCRE_UTF8 support Configure .htaccess to allow awstats to work with clean URLs . . . . . Configuring .htaccess to ignore specific subfolders . . . . . . . . Ignoring Subfolders that exist in the DocumentRoot . . . . . . . Ignoring subfolders that are included via Apache Alias directives . . . . Create a custom php.ini . . . . . . . . . . . . . . . How to create a custom php.ini file when nothing else works . . . . . 1. Get and modify your custom php.ini file . . . . . . . . . 2. Creating your CGI script . . . . . . . . . . . . . 3. Modifying your .htaccess file . . . . . . . . . . . . 4. Test your site . . . . . . . . . . . . . . . . Create Drupal database using Plesk . . . . . . . . . . . . Drupal with safe mode enabled and open basedir . . . . . . . . Generic Mass SQL Import into Drupal . . . . . . . . . . . DrupalCon site . . . . . . . . . . . . . . . . How to degrade your Drupal db from MySQL 4.1.X/5.0.X to MySQL 4.0.X . . How-To: Virtual Hosting with Drupal . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . Environment . . . . . . . . . . . . . . . . . Requirements . . . . . . . . . . . . . . . . . Next pages . . . . . . . . . . . . . . . . . How-To: Virtual Hosting with Drupal :: Prepare environment . . . . . Introduction . . . . . . . . . . . . . . . . . The drupal group . . . . . . . . . . . . . . . . The temp directory . . . . . . . . . . . . . . . The reference location . . . . . . . . . . . . . . . Navigation . . . . . . . . . . . . . . . . . How-To: Virtual Hosting with Drupal :: Solution Overview . . . . . Introduction . . . . . . . . . . . . . . . . . Safe mode . . . . . . . . . . . . . . . . . Open Basedir . . . . . . . . . . . . . . . . .
23 . 24 . 25 . 26 . 27 . 28 . 29 . 30 . 30 . 32 . 32 . 33 . 36 . 51 . 52 . 53 . 53 . 54 . 55 . 55 . 55 . 56 . 60 . 60 . 60 . 61 . 61 . 61 . 62 . 65 . 67 . 67 . 68 . 68 . 68 . 69 . 69 . 69 . 69 . 70 . 70 . 70 . 70 . 71 . 71 . 71 . 71 .
ii
3 Aug 2007
Drupal Handbook
Plesk integration . . . . . . . . . . . . . . Managed application . . . . . . . . . . . . . eAccelerator . . . . . . . . . . . . . . . Each individual vhost requirements . . . . . . . . . Navigation . . . . . . . . . . . . . . . HOWTO: copy a site to a local computer using XAMPP . . . . . HOWTO: Copy site to another directory for testing . . . . . . HOWTO: Install Drupal 5.x using cPanel . . . . . . . . HOWTO: Install Drupal using cPanel . . . . . . . . . HOWTO: Site to site transfer with phpMyAdmin and a FTP Client . . Import a MySQL data dump with BigDump . . . . . . . . What is BigDump? . . . . . . . . . . . . . Setting up BigDump . . . . . . . . . . . . . Uploading the sql file and bigdump.php to the webserver . . . . Running BigDump . . . . . . . . . . . . . Installing Drupal behind an Actiontec GT701-WG router . . . . . Installing Drupal in a subdirectory in 4.6 . . . . . . . . . More than one Drupal site on one machine . . . . . . . . General rules for multiple Drupal deployments . . . . . . Moving your Drupal installation to a new directory . . . . . . PCRE_UTF8 solution for VPS servers | FreeBSD . . . . . . . Known causes of PCRE server errors . . . . . . . . . Redirecting specific pages to new URLs (301 redirects in Drupal) . . . How to create 301 redirects in Drupal Apache mod_rewrite . . . The tolerant base URL . . . . . . . . . . . . . Using .htaccess to stop page caching . . . . . . . . . . Linux specific guidelines . . . . . . . . . . . . . Installing PHP, MySQL and Apache under Linux . . . . . . XAMPP for Linux Packages . . . . . . . . . . . . Installing XAMPP in Debian . . . . . . . . . . . Download XAMPP Latest version from the following link . . . . Start XAMPP Server . . . . . . . . . . . . . Windows-specific guidelines . . . . . . . . . . . . How to install Drupal for newbies using FTP and phpMyAdmin . . . Change "/tmp" on your drupal site. . . . . . . . . . Get Drupal ready . . . . . . . . . . . . . . Upload the database . . . . . . . . . . . . . HOWTO: Create an apache sandbox using Windows and Apache2Triad . Before you begin . . . . . . . . . . . . . . Installing Apache2Triad . . . . . . . . . . . . Installing Drupal . . . . . . . . . . . . . . Importing and exporting Drupal databases updated with PHPMyAdmin To export a database with PHPMyAdmin . . . . . . . . To import a database with PHPMyAdmin . . . . . . . . Using bigdump.php to deal with large databases . . . . . . Installing Apache (with PHP) on Windows . . . . . . . . Installing MySQL on Windows . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iii
Drupal Handbook
3 Aug 2007
Installing PHP4 on Windows . . . . . . . . . . . . . 105 . Drupal 4.7 on Windows/IIS Requires PHP in ISAPI mode . . . . . . 105 . Installing PostgreSQL on Windows . . . . . . . . . . . . 105 . Multiple Drupal Sites under Windows . . . . . . . . . . . 106 . Running multiple sites on a local PC (localhost) from a single codebase, using Windows 106 Untar . . . . . . . . . . . . . . . . . . . 108 . Installing Drupal on Windows . . . . . . . . . . . . . 109 . PostgreSQL specific guidelines . . . . . . . . . . . . . 109 . ERROR: DB connect failed . . . . . . . . . . . . . . . 109 . ERROR: language "plpgsql" does not exist . . . . . . . . . . 110 . ERROR: null value in column "uid" violates not-null constraint . . . . . 110 . PostgreSQL support in Drupal 4.7.x . . . . . . . . . . . . 110 . Drupal 4.5 and PGSQL 8 configuration . . . . . . . . . . . 110 . Installing contributed modules . . . . . . . . . . . . . . 111 . HOWTO: Install glossary module . . . . . . . . . . . . . 113 . Where is the Glossary? . . . . . . . . . . . . . . . 113 . What is the purpose of the Glossary Module, and what does it do? . . . . 113 . Installing the Glossary Module . . . . . . . . . . . . . 114 . Configuring the Glossary . . . . . . . . . . . . . . 114 . Adding Full Page Definitions . . . . . . . . . . . . . 115 . Adding Glossary To Menus . . . . . . . . . . . . . . 115 . Leech - automating content addition . . . . . . . . . . . . 116 . Relationships between modules . . . . . . . . . . . . . 116 . Installing new modules (Drupal 4.6 or older) . . . . . . . . . . 117 . Multi-site installation and set-up . . . . . . . . . . . . . . 118 . 10 Minute Multisite Install & Configuration . . . . . . . . . . 119 . Access all multisites with www. only [.htaccess] . . . . . . . . . 121 . Drupal as a library . . . . . . . . . . . . . . . . 121 . Multi-site setup in 5.x using CPanel . . . . . . . . . . . . 123 . Multi-Site, Single Codebase, Shared Database, Shared Sign-on 4.6 . . . . . 124 . Apache (http) Configuration . . . . . . . . . . . . . 124 . Download and Placement . . . . . . . . . . . . . . 124 . SQL Setup . . . . . . . . . . . . . . . . . . 125 . Individual Site Configuration & Theming . . . . . . . . . . 126 . Some things which can be improved: . . . . . . . . . . . 127 . Multi-Site, Single Codebase, Shared Database, Shared Sign-on 5.x . . . . . 127 . 1. Prepare database and database user . . . . . . . . . . . 128 . 1.1. create a database and user . . . . . . . . . . . . . 128 . 2. create and modify site configuration . . . . . . . . . . . 128 . 2.1. duplicate settings folder . . . . . . . . . . . . . . 128 . 2.2. Modify config files . . . . . . . . . . . . . . . 128 . 2.2.1. provide DB connection detail . . . . . . . . . . . . 128 . 2.2.2. set prefixes for table names . . . . . . . . . . . . 128 . 3. create static links . . . . . . . . . . . . . . . . 129 . 4. install drupal . . . . . . . . . . . . . . . . . 130 . Multiple domains or vhosts using different databases . . . . . . . . 130 . Sharing Drupal tables between databases using MySQL5 Views . . . . . 131 .
iv
3 Aug 2007
Drupal Handbook
Multiple domains using the same database . . . . . . . . . Same codebase, completely different content and users . . . . . . Setup of /sites directory for multi-site . . . . . . . . . . Installing new themes . . . . . . . . . . . . . . Basic site configuration . . . . . . . . . . . . . . Settings . . . . . . . . . . . . . . . . . . General settings . . . . . . . . . . . . . . . Default front page . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . Clean URLs . . . . . . . . . . . . . . . . .htaccess for clean urls on specific shared hosts . . . . . . . 403 Permission denied error . . . . . . . . . . . . A mod_rewrite bug causing occasional corruption of the query string . . Apache 2 configuration of clean URLs on Debian . . . . . . . Apache 2 on Ubuntu . . . . . . . . . . . . . Editing apache2.conf . . . . . . . . . . . . . Editing apache2/sites-available . . . . . . . . . . Clean URL Support in Abyss . . . . . . . . . . . Clean URL support in XAMPP . . . . . . . . . . . Clean URLs in Mac OS X Server . . . . . . . . . . . Clean URLs with different webservers . . . . . . . . . Microsoft Internet Services Server . . . . . . . . . . Lighttpd . . . . . . . . . . . . . . . . Clean URLs with Easyphp. . . . . . . . . . . . . Example Clean URL configuration of httpd.conf for performance . . . Existing URLs for server overwrite Drupal paths . . . . . . . IIS CleanURLs using some of the available ISAPI filters. . . . . . Translating Apaches rewrite rules . . . . . . . . . Pathauto and Localizer . . . . . . . . . . . . . Setting up clean URLs above web document root on virtual private servers reboot vps after making change . . . . . . . . . . Using Clean URLs with IIS . . . . . . . . . . . . Alternate method . . . . . . . . . . . . . . set your sites 403 and 404 Error pages . . . . . . . . . . Configure your sites error reporting . . . . . . . . . . Cache support . . . . . . . . . . . . . . . Primary and secondary links . . . . . . . . . . . . General Information: . . . . . . . . . . . . . Setting Up Your Primary and Secondary Links: . . . . . . . Theming Your Link Menus . . . . . . . . . . . . Set length of trimmed posts and # of posts on front page . . . . . URL Alias Optimization . . . . . . . . . . . . . File system settings . . . . . . . . . . . . . . Download method . . . . . . . . . . . . . . Path settings . . . . . . . . . . . . . . . Date and time settings . . . . . . . . . . . . . . Customizing the interface . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
132 . 132 . 135 . 137 . 139 . 139 . 140 . 140 . 141 . 141 . 143 . 146 . 147 . 147 . 149 . 149 . 150 . 151 . 153 . 153 . 154 . 154 . 154 . 154 . 155 . 156 . 156 . 156 . 157 . 158 . 159 . 159 . 160 . 160 . 161 . 161 . 161 . 161 . 162 . 162 . 162 . 162 . 163 . 163 . 164 . 164 . 164 .
Drupal Handbook
3 Aug 2007
Customizing user login . . . . . . . . . . . . Beginners guide for Cron on a shared hosting provider . . . . Check your filters . . . . . . . . . . . . . Configure user registration . . . . . . . . . . . Creating a menu structure . . . . . . . . . . . Creating a menu . . . . . . . . . . . . . Simplifying the workflow . . . . . . . . . . . Helping search engines and robots.txt . . . . . . . . Controlling what gets indexed -- the robots.txt file . . . . . Add Disallow: /node/ if your setup has aliases for all nodes . Selective Bot Crawling . . . . . . . . . . . Increase upload size in your php.ini . . . . . . . . . Need images etc? - check Filtered HTML . . . . . . . . Set default content options - Stop automatic promotion to the front page Show/hide Submitted by on posts . . . . . . . . . Blocks . . . . . . . . . . . . . . . . Block configuration . . . . . . . . . . . . Restricting blocks to certain pages . . . . . . . . Preventing a block from appearing in Drupal 4.5 . . . . . Custom blocks . . . . . . . . . . . . . Increase memory in your php.ini . . . . . . . . . . Database table prefix (and sharing tables across instances) . . . Share tables across instances . . . . . . . . . . Setup tip for Drupal 5 . . . . . . . . . . . Using schema prefixes with PostgreSQL . . . . . . . Define shared variables for all sites . . . . . . . . Drupal Cookbook (for New Drupallers) . . . . . . . . Purpose . . . . . . . . . . . . . . . . Background . . . . . . . . . . . . . . . Myths . . . . . . . . . . . . . . . . Using the Drupal Web Site . . . . . . . . . . . Typing Convention . . . . . . . . . . . . . Some Preliminary Advice . . . . . . . . . . . Drupal Is Supposed to be Easy? . . . . . . . . . . A. Getting Started . . . . . . . . . . . . . B. Basic Configuration . . . . . . . . . . . . C. Creating Multiple Sites On Your Local Computer . . . . . D. Error Pages . . . . . . . . . . . . . . Page Not Found . . . . . . . . . . . . . Access Denied . . . . . . . . . . . . . E. Accessing Your Test Site(s) . . . . . . . . . . F. Adding Modules and Themes . . . . . . . . . . Installation . . . . . . . . . . . . . . Modules . . . . . . . . . . . . . . . Modules . . . . . . . . . . . . . . This Site . . . . . . . . . . . . . . Themes . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
165 . 166 . 167 . 168 . 168 . 169 . 169 . 169 . 170 . 171 . 171 . 175 . 176 . 177 . 178 . 178 . 178 . 179 . 180 . 182 . 182 . 183 . 184 . 185 . 185 . 187 . 189 . 189 . 189 . 189 . 190 . 190 . 190 . 191 . 192 . 193 . 194 . 197 . 197 . 197 . 198 . 198 . 199 . 199 . 199 . 200 . 200 .
vi
3 Aug 2007
Drupal Handbook
Themes . . . . . . . . . . . . . . . . Logo and Favorite Icon . . . . . . . . . . . . G. Creating Content . . . . . . . . . . . . . . Content Types . . . . . . . . . . . . . . Page . . . . . . . . . . . . . . . . . Story . . . . . . . . . . . . . . . . . Book Page . . . . . . . . . . . . . . . Blog Entry . . . . . . . . . . . . . . . G1. Creating a Page . . . . . . . . . . . . . G2. Creating a Story . . . . . . . . . . . . . Whats a Teaser? . . . . . . . . . . . . . G3. Creating a Book Page . . . . . . . . . . . . G4. Creating a Blog entry . . . . . . . . . . . . H. Custom Blocks . . . . . . . . . . . . . . Address . . . . . . . . . . . . . . . . Last Updated . . . . . . . . . . . . . . . I. Working with the Menu . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . How To Menu . . . . . . . . . . . . . . Textual Menu . . . . . . . . . . . . . . . Tabbed Menu . . . . . . . . . . . . . . . Books . . . . . . . . . . . . . . . . . More . . . . . . . . . . . . . . . . . I2. The Contact Form . . . . . . . . . . . . . Set Up . . . . . . . . . . . . . . . . Make It Accessible . . . . . . . . . . . . . Add "Contact" to the Menu . . . . . . . . . . . Using It In Content . . . . . . . . . . . . . J. URL Aliases . . . . . . . . . . . . . . . K. Moving Entire Drupal Site with Databases . . . . . . . . Backup Process with phpMyAdmin . . . . . . . . . Backup Process with phpMyAdmin . . . . . . . . . . L. Moving Stuff to Your Web Site . . . . . . . . . . M. Setting Up Cron . . . . . . . . . . . . . . N. Categories (Taxonomy) . . . . . . . . . . . . O. Common Problems . . . . . . . . . . . . . P. Links and IMG . . . . . . . . . . . . . . Q. Additional Tips and Tricks . . . . . . . . . . . Q1. Tracking Module Status . . . . . . . . . . . Q2. Making Multiple Site Maintenance a Bit Easier . . . . . . Q3. Controlling User Log In . . . . . . . . . . . How do I disable "Create New Account?" . . . . . . . How do I disable User Log In entirely, and how would I get in if I do? R. Keeping Your Local and Remote Sites Synchronized . . . . . S. More Reading . . . . . . . . . . . . . . . T. Glossary . . . . . . . . . . . . . . . . Taking your site live . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
200 . 200 . 201 . 202 . 202 . 202 . 202 . 203 . 203 . 204 . 204 . 205 . 205 . 206 . 206 . 206 . 207 . 207 . 207 . 208 . 208 . 208 . 209 . 209 . 209 . 209 . 210 . 210 . 210 . 211 . 213 . 213 . 216 . 216 . 217 . 219 . 219 . 220 . 220 . 220 . 221 . 221 . 221 . 222 . 222 . 223 . 226 .
vii
Drupal Handbook
3 Aug 2007
Moving from a temporary location . . . . . . . . Moving Drupal . . . . . . . . . . . . . Redirecting your server . . . . . . . . . . . Excluding paths from Drupal . . . . . . . . . Core modules . . . . . . . . . . . . . . Aggregator: publishing syndicated content . . . . . . Old page . . . . . . . . . . . . . . Open aggregator links in new browser window . . . . User Aggregator:user submitted feeds . . . . . . . What do I need to subscribe to a feed? . . . . . . . Configuring news feeds . . . . . . . . . . Filter feeds by keyword, time, by summary . . . . . Creating categories in the aggregator . . . . . . . Tagging individual items in the aggregator . . . . . . Using the news aggregator . . . . . . . . . RSS feed blocks . . . . . . . . . . . . Block: controlling content in the sidebars . . . . . . . Module blocks . . . . . . . . . . . . Administrator defined blocks . . . . . . . . . Blog: a blog for every user . . . . . . . . . . HOWTO: Configure user blogs . . . . . . . . Most recent blog post block . . . . . . . . . Navigate throught categories inside a blog . . . . . . What is a blog or weblog? . . . . . . . . . . Making user blogs more accessible . . . . . . . . Additional features . . . . . . . . . . . BlogApi: post from blog tools . . . . . . . . . Book: structured document publishing . . . . . . . Customising the book navigation menu . . . . . . Maintaining a FAQ using a collaborative book . . . . . Categories (taxonomy): A way to organize your content . . . Modules that do more with categories . . . . . . . Content Management System comparison focused on Taxonomy Taxonomy - some guidelines for effective design of taxonomies . Taxonomy Garden: Managing Categories . . . . . . Taxonomy Garden: Navigation by category . . . . . Taxonomy Garden: Organize content by category . . . . The taxonomy module for Drupal 4.x . . . . . . . Understanding categories for new users . . . . . . Using taxonomy to organize content . . . . . . . Using vocabularies for navigation . . . . . . . . Vocabularies and terms . . . . . . . . . . Creating a vocabulary . . . . . . . . . . Creating terms . . . . . . . . . . . . Advanced taxonomies: using hierarchies . . . . . . More about Taxonomy . . . . . . . . . . Creating a Block with links belonging to certain taxonomy terms
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
226 . 226 . 226 . 227 . 228 . 228 . 229 . 229 . 229 . 230 . 230 . 231 . 231 . 231 . 231 . 232 . 232 . 232 . 233 . 233 . 233 . 234 . 234 . 234 . 235 . 235 . 236 . 236 . 237 . 238 . 239 . 242 . 244 . 244 . 246 . 247 . 254 . 260 . 261 . 262 . 265 . 266 . 267 . 267 . 268 . 268 . 270 .
viii
3 Aug 2007
Drupal Handbook
Taxonomy terms on a page . . . . . . . . . . . . . Comment: allow comments on content . . . . . . . . . . . Detailed comment documentation . . . . . . . . . . . . User control of comment display . . . . . . . . . . . Additional comment configurations . . . . . . . . . . . Notification of new comments . . . . . . . . . . . . Comment moderation . . . . . . . . . . . . . . Moderation votes . . . . . . . . . . . . . . . Moderator vote/values matrix . . . . . . . . . . . . Creating comment thresholds . . . . . . . . . . . . Initial comment scores . . . . . . . . . . . . . . Aggregator comments . . . . . . . . . . . . . . Contact: a way for users to get in touch . . . . . . . . . . . Make your site wide contact form look prettier . . . . . . . . . Drupal: Drupal sites directory server . . . . . . . . . . . . Old page . . . . . . . . . . . . . . . . . . Filter: Input formats for user content . . . . . . . . . . . . Forum: create threaded discussions . . . . . . . . . . . . HOWTO: Create a forum . . . . . . . . . . . . . . HOWTO: Create forum containers . . . . . . . . . . . . Help: context-sensitive guidance . . . . . . . . . . . . . More about the help module . . . . . . . . . . . . . Legacy: remapping of old-style URLs . . . . . . . . . . . Locale: multi-language support . . . . . . . . . . . . . Adjusting your php.ini settings for importing .po files . . . . . . . Editing text for translation . . . . . . . . . . . . . . How to create Drupal site in Marathi (Devnagari) . . . . . . . . How to install a different language . . . . . . . . . . . HOWTO: Creating a customized language set to replace Drupal terminology . HOWTO: Use a customized language set to change Drupal text and terminology Note for the curious . . . . . . . . . . . . . . . Menu: customize site navigation . . . . . . . . . . . . . Using named anchors with menus . . . . . . . . . . . . Node: the content . . . . . . . . . . . . . . . . Page: post static pages . . . . . . . . . . . . . . . Difference between page and story . . . . . . . . . . . . Specify page by title . . . . . . . . . . . . . . . Path: readable URLs . . . . . . . . . . . . . . . . Mass URL aliasing . . . . . . . . . . . . . . . Ping: notify services of changes . . . . . . . . . . . . . Write a custom module to ping a set of sites . . . . . . . . . Poll: community voting . . . . . . . . . . . . . . . Profile: extending user account information . . . . . . . . . . Enabling user pictures (avatars) . . . . . . . . . . . . HOWTO: Create new profile fields . . . . . . . . . . . . HOWTO: Make a field part of the registration process . . . . . . . Form Validation in plugin . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
271 . 272 . 272 . 272 . 273 . 273 . 274 . 274 . 274 . 274 . 275 . 275 . 275 . 276 . 276 . 277 . 277 . 278 . 279 . 279 . 279 . 280 . 280 . 280 . 281 . 282 . 282 . 283 . 283 . 284 . 286 . 286 . 286 . 287 . 288 . 288 . 289 . 289 . 290 . 291 . 291 . 292 . 293 . 294 . 295 . 295 . 295 .
ix
Drupal Handbook
3 Aug 2007
HOWTO: Create a country profile field . . . . . . . . . CiviCRM: Tags, Profiles, Groups, advanced community member management Search: an internal site search system . . . . . . . . . . . Add searching to your custom module . . . . . . . . . . Statistics: tracking referrers, page hits, etc. . . . . . . . . . Story: post static pages . . . . . . . . . . . . . . System: cron and caching . . . . . . . . . . . . . Configuring cron jobs . . . . . . . . . . . . . . Configuring cron jobs on DreamHost . . . . . . . . . Cron Job configuration line by line . . . . . . . . . . Cronjobs without wget/lynx or curl . . . . . . . . . . Configuring cron jobs on Windows . . . . . . . . . . Throttle: congestion control . . . . . . . . . . . . . When to use the throttle module? . . . . . . . . . . . Tracker: viewing new and updated content . . . . . . . . . Upload: collaborate with files . . . . . . . . . . . . User: access and management settings . . . . . . . . . . Access Permissions reference . . . . . . . . . . . . block module . . . . . . . . . . . . . . . filter module . . . . . . . . . . . . . . . menu module . . . . . . . . . . . . . . . node module . . . . . . . . . . . . . . . path module . . . . . . . . . . . . . . . user module . . . . . . . . . . . . . . . system module . . . . . . . . . . . . . . . Access rules (email filters) . . . . . . . . . . . . . Managing access control with permissions and user roles . . . . . Assigning permissions and users to roles . . . . . . . . Taxonomy_access: Restrict user roles to access specific categories only . Adjusting permissions after adding modules . . . . . . . . User authentication . . . . . . . . . . . . . . Make a Drupal site use Basic Auth/ldap instead of the normal login block NTLM Authentication . . . . . . . . . . . . . User preferences and profiles . . . . . . . . . . . . Using distributed authentication . . . . . . . . . . . Distributed authentication . . . . . . . . . . . . Drupal . . . . . . . . . . . . . . . . . Watchdog: monitor your site . . . . . . . . . . . . . End user guide . . . . . . . . . . . . . . . . Registering as a user . . . . . . . . . . . . . . . Logging in . . . . . . . . . . . . . . . . . Changing your account settings . . . . . . . . . . . . Creating new content . . . . . . . . . . . . . . A step-by-step example . . . . . . . . . . . . . Controlling Teaser Location . . . . . . . . . . . . How to add a page to the Handbook . . . . . . . . . . Types of content . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
295 . 296 . 297 . 298 . 298 . 299 . 299 . 301 . 302 . 303 . 304 . 305 . 306 . 307 . 307 . 308 . 308 . 309 . 309 . 309 . 309 . 309 . 310 . 310 . 310 . 310 . 311 . 312 . 312 . 312 . 313 . 313 . 315 . 317 . 317 . 317 . 317 . 318 . 319 . 319 . 320 . 320 . 321 . 321 . 323 . 324 . 324 .
3 Aug 2007
Drupal Handbook
Topics, categories and terms . . . . . . . . . Permissions . . . . . . . . . . . . . Moderation and the submission queue . . . . . . . Creating comments . . . . . . . . . . . Alternative ways to enter content . . . . . . . . HOWTO: Posting and editing blog entries with TextMate . Posting and editing content with w.bloggar . . . . . Posting content with mailhandler . . . . . . . Preparing content offline . . . . . . . . . Editing and deleting content . . . . . . . . . . Search . . . . . . . . . . . . . . . Beyond the basics . . . . . . . . . . . . Sports . . . . . . . . . . . . . . . . football . . . . . . . . . . . . . . . Best practices guidelines . . . . . . . . . . . Back up your Drupal site . . . . . . . . . . Backing up the database . . . . . . . . . . Backing up the core files . . . . . . . . . . Backing up the non-core files . . . . . . . . . Test your backups . . . . . . . . . . . . Backup and restore using bash shell scripts . . . . . Functional Overview . . . . . . . . . . Usage notes and cautions . . . . . . . . . Site backup script . . . . . . . . . . . Usage notes and warnings: . . . . . . . . fullsitebackup.sh . . . . . . . . . . . Updated fullsitebackup.sh . . . . . . . . Site restore script . . . . . . . . . . . Usage notes and warnings: . . . . . . . . fullsiterestore.sh . . . . . . . . . . . Updated fullsiterestore.sh . . . . . . . . . Accounts and roles . . . . . . . . . . . . Configuring Apache and PHP for Drupal in a Shared Environment Creating a Test Site workflow . . . . . . . . . File and directory management . . . . . . . . . Other Tips . . . . . . . . . . . . . Test Sites . . . . . . . . . . . . . . Version update considerations . . . . . . . . . Do not modify core Drupal . . . . . . . . . . Security . . . . . . . . . . . . . . . Test php before putting it in blocks . . . . . . . . HowTo: The Advanced users guide . . . . . . . . HowTo: enable Imagemagick for the Image module . . . . Tips and Tricks . . . . . . . . . . . . . August 2005: Upgrade, Play B-I-N-G-O!, & E-commerce . . UPGRADE . . . . . . . . . . . . . PLAY B-I-N-G-O! . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
324 . 324 . 325 . 325 . 325 . 326 . 327 . 328 . 328 . 328 . 329 . 330 . 331 . 331 . 332 . 332 . 332 . 333 . 333 . 334 . 334 . 334 . 334 . 335 . 335 . 336 . 338 . 340 . 341 . 341 . 344 . 346 . 347 . 348 . 352 . 353 . 353 . 353 . 354 . 355 . 355 . 356 . 357 . 357 . 357 . 357 . 358 .
xi
Drupal Handbook
3 Aug 2007
E-COMMERCE . . . . . . . . . . . . . . . . . 358 . Commentator array . . . . . . . . . . . . . . . . 358 . June 2005: Custom Content Types, WYSIWIG Editors, Organize Your Content & Quick Support . . . . . . . . . . . . . . . . . . . 359 . September 2005: Newest modules, Change any string, Remote authentication, and tracking project issues . . . . . . . . . . . . . . . . 360 . Get the newest modules -- fast! . . . . . . . . . . . . . 360 . Change any string . . . . . . . . . . . . . . . . 360 . Remote authentication . . . . . . . . . . . . . . . 360 . Keep tabs on project issues . . . . . . . . . . . . . . 361 . Winter 2005/2006: Tracking projects with RSS and Module Linking . . . . . 361 . Planning a web site . . . . . . . . . . . . . . . . . 361 . Server tuning considerations . . . . . . . . . . . . . . . 365 . Identifying Drupal performance goals . . . . . . . . . . . . 365 . Analysing your sites traffic and resource consumption . . . . . . . . 365 . Understanding and configuring your stack for performance . . . . . . 365 . Enable default 404 handling for some file types . . . . . . . . . . 367 . Simple Decision Tree for Drupal Enterprise Scalability . . . . . . . . 368 . Slow contributed modules determined using the developer module . . . . . 369 . Squid Caching . . . . . . . . . . . . . . . . . 369 . Tools, tips, and links on optimizing mysql . . . . . . . . . . . 370 . Tuning MySQL for Drupal . . . . . . . . . . . . . . 372 . Tuning PHP . . . . . . . . . . . . . . . . . . 372 . Persistent database connections . . . . . . . . . . . . . 373 . PHP caches . . . . . . . . . . . . . . . . . . 373 . APC : Alternative PHP Cache . . . . . . . . . . . . . 374 . eAccelerator . . . . . . . . . . . . . . . . . 374 . Turck MMCache . . . . . . . . . . . . . . . . 374 . Useful article on optimizing PHP . . . . . . . . . . . . . 376 . Tuning Drupal on OS X Tiger . . . . . . . . . . . . . . 376 . Upgrading from previous versions . . . . . . . . . . . . . . 378 . Introduction to upgrading . . . . . . . . . . . . . . . 378 . Getting started: Choosing your method and preparing the site . . . . . . 378 . Preparing the site . . . . . . . . . . . . . . . . 379 . Do I need to upgrade my database? . . . . . . . . . . . . 379 . Important! : Backing up the database and existing files . . . . . . . . 379 . Backing up your site (GUI) . . . . . . . . . . . . . . 379 . Back up your site (command line) . . . . . . . . . . . . 380 . Create a test site first or upgrade your existing site? . . . . . . . . 381 . Copy your live site to a test site (GUI) . . . . . . . . . . . 381 . Copying your live site to a test site (command line) . . . . . . . . 382 . Downloading Drupal and installing the files . . . . . . . . . . 384 . Downloading Drupal and installing the files (GUI) . . . . . . . . 384 . Downloading Drupal and installing the files (command line) . . . . . . 385 . Running update.php . . . . . . . . . . . . . . . . 386 . Optional configuration steps . . . . . . . . . . . . . . 387 . Post-upgrade steps . . . . . . . . . . . . . . . . 388 .
xii
3 Aug 2007
Drupal Handbook
Testing Your Newly Upgraded Site . . . . . . . . Copy your test site to a live site . . . . . . . . . Copying your test site to your live site (command line) . . . Copy your test site to a live site (GUI) . . . . . . . Differences from 4.7 to 5.x . . . . . . . . . . . Important note on upgrading from 4.7 to 5.1 . . . . . . Important note on upgrading from 4.7 to 5.1 . . . . . . Version specific upgrades . . . . . . . . . . . Upgrading from Drupal 4.4 to 4.5 . . . . . . . . . Upgrading from Drupal 4.5 to 4.6.3 . . . . . . . . Before you Start . . . . . . . . . . . . . Step-by-step Upgrade from Drupal 4.5 to 4.6.3 . . . . . Finalising your upgrade . . . . . . . . . . . Rebuilding your Drupal Search Index. . . . . . . . Blocks . . . . . . . . . . . . . . . . Permissions . . . . . . . . . . . . . . Forums . . . . . . . . . . . . . . . Images . . . . . . . . . . . . . . . Events . . . . . . . . . . . . . . . Upgrading from Drupal 4.6.3 to 4.6.5 . . . . . . . . Before you Start . . . . . . . . . . . . . Step-by-step Upgrade from Drupal 4.6.3 to 4.6.5 . . . . . Upgrading from Drupal 4.6.4 to 4.6.5 . . . . . . . . Before you Start . . . . . . . . . . . . . Step-by-step Upgrade from Drupal 4.6.4 to 4.6.5 . . . . . Differences from 4.6 to 4.7 . . . . . . . . . . . Block visibility settings . . . . . . . . . . . Configure options centralized . . . . . . . . . . core module help text linked to the handbook now . . . . . Creating context sensitive menus with primary and secondary menus Dont turn off contributed modules that provide an .install file . . Module .install files . . . . . . . . . . . . Primary/secondary links now part of the menu system . . . . queue module removed from core . . . . . . . . . Removal of base href statement from header . . . . . . Some HTML Tags stripped from mission statement . . . . XTemplate engine removed from core . . . . . . . . Troubleshooting FAQ . . . . . . . . . . . . . How to troubleshoot (read this first) . . . . . . . . . Stop and think . . . . . . . . . . . . . Read the errors . . . . . . . . . . . . . Validate your page . . . . . . . . . . . . Read the README . . . . . . . . . . . . Search the right way . . . . . . . . . . . . Identify the source of the problem . . . . . . . . . Dump some diagnostics . . . . . . . . . . . Ask the right questions . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
388 . 389 . 390 . 390 . 391 . 391 . 392 . 392 . 392 . 393 . 394 . 394 . 396 . 396 . 396 . 396 . 397 . 397 . 397 . 397 . 398 . 398 . 398 . 398 . 399 . 399 . 399 . 399 . 400 . 400 . 400 . 401 . 401 . 401 . 402 . 403 . 403 . 404 . 404 . 404 . 404 . 405 . 405 . 405 . 406 . 406 . 407 .
xiii
Drupal Handbook
3 Aug 2007
Identify the module thats giving you problems . . . . . . . . My admin > modules page is blank . . . . . . . . . . . . How do I get the User Login block back . . . . . . . . . . . Client does not support authentication protocol requested by server... . . . . Webhosting issues for new Drupal users . . . . . . . . . . . Brief intro to Unix file permissions . . . . . . . . . . . . Host-specific error messages . . . . . . . . . . . . . SELinux may cause mysterious permission problems . . . . . . . Typical webhosting setups . . . . . . . . . . . . . Using PHP to change files on the webserver . . . . . . . . . What do all those Unix commands mean? . . . . . . . . . . Some Unix command youll see mentioned: . . . . . . . . . Special characters: . . . . . . . . . . . . . . . What permissions does Drupal need? . . . . . . . . . . . Why is this uploading stuff so difficult? . . . . . . . . . . "Headers already sent" error . . . . . . . . . . . . . . "LOCK TABLES sequences WRITE" error . . . . . . . . . . "Method POST is not allowed for the URL /index.htm" error (Error 405) . . . "Page Not Found" error when trying to access a subdirectory . . . . . . Block referrer spam . . . . . . . . . . . . . . . . .htaccess sample list plus domain blocking . . . . . . . . . . Color picker doesnt appear on theme configuration page . . . . . . . Drupal 4.7 Install inserts CGI-BIN in URL . . . . . . . . . . Duplicate entry error . . . . . . . . . . . . . . . E-Mail from Drupal is bouncing or not being sent . . . . . . . . Relay SMTP mail to external mail server using smtp.class . . . . . . Error 1364 upon importing database.mysql with MySQL 5.0+ . . . . . . Error on installation step 3: Warning: Table [database].access doesnt exist [...] . Fatal error: Allowed memory size of X bytes exhausted (tried to allocate Y bytes)... Fatal error: Call to undefined function . . . . . . . . . . . Fatal error: Call to undefined function: form_*() on Drupal 4.7 . . . . . Fatal error: Cannot redeclare blah_function() in ../modules/blah.module . . . Forgotten your Drupal account password . . . . . . . . . . Forum overview stopped working . . . . . . . . . . . . The Fix . . . . . . . . . . . . . . . . . . FTP uploads and file permissions using Transmit . . . . . . . . . Help! I enabled a buggy module and now I cant disable it! . . . . . . How can I adminstrate my navigation on my Drupal site? (version 4.5 or older) . How do I get rid of the "Welcome to your new Drupal website" on the front page? . How do I get the Navigation block back . . . . . . . . . . . How do I unset the clean URLs? . . . . . . . . . . . . . How to login once you have turned your site off-line for maintenance . . . . HOWTO: Download a fresh copy of a missing or corrupted module/image/file . Installation/configuration . . . . . . . . . . . . . . 406 Error when XMLRPC is used . . . . . . . . . . . . Junk {head} {styles} codes as output . . . . . . . . . . . . Login after disabling the User login block . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
407 . 407 . 408 . 408 . 409 . 409 . 411 . 411 . 412 . 413 . 413 . 413 . 414 . 414 . 416 . 416 . 417 . 417 . 418 . 418 . 419 . 420 . 420 . 421 . 423 . 423 . 424 . 425 . 426 . 426 . 426 . 427 . 427 . 428 . 428 . 429 . 429 . 429 . 431 . 432 . 432 . 432 . 433 . 434 . 434 . 434 . 435 .
xiv
3 Aug 2007
Drupal Handbook
Login doesnt work or must be done twice . . . . . . . . . . . Cookies . . . . . . . . . . . . . . . . . . . Cache Problems . . . . . . . . . . . . . . . . . Logging in at www on a site with no www in the baseurl . . . . . . . Login problems on PHP 5.2 . . . . . . . . . . . . . . . My layout collapses - content appears below left column (IE) or overflows over the right (FF) . . . . . . . . . . . . . . . . . . . . . The content is too wide for the space its been given . . . . . . . . Validation Woes . . . . . . . . . . . . . . . . . Mysterious 403, 404, 406 or 500 errors depending on submitted content . . . . Permission denied in includes/file.inc . . . . . . . . . . . . Persistent Welcome to Drupal for anonymous users . . . . . . . . . phpinfo . . . . . . . . . . . . . . . . . . . . Plain unstyled HTML output . . . . . . . . . . . . . . Setting up Clean URLs . . . . . . . . . . . . . . . . unblocking account through SQL . . . . . . . . . . . . . Weird behaviour - module-theme name collision . . . . . . . . . . Where is the taxonomy choice when adding content? . . . . . . . . . Miscellaneous . . . . . . . . . . . . . . . . . . How can I change Drupals character encoding? (UTF-8 and Unicode) . . . .
435 . 435 . 435 . 436 . 436 . 436 . 437 . 437 . 438 . 438 . 439 . 440 . 440 . 441 . 442 . 442 . 442 . 443 . 443 .
xv
3 Aug 2007
Drupal Handbook
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 Microsofts support life cycle it is suggested you use IIS6. To achieve clean_urls 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 shouldnt need to set them explicitly. Note, however, that setting PHP configuration options from .htaccess only works: with Apache (or a compatible web server),
3 Aug 2007
Drupal Handbook
if the .htaccess file is actually read, i.e. AllowOverride is not None, if PHP is installed as an Apache module. See the PHP manual for how to change configuration settings for other interfaces to PHP. 5. A PHP-supported Database Server 6. Recommended: MySQL 4.1 or MySQL 5.0. Drupal will work on v3.23.17 and 4.0 but it is strongly suggested you use 4.1 or 5.0 for future compatibility with Drupal 6 which will drop support for older versions of MySQL. NOTE: Drupal makes use of some features not available on some inexpensive hosting plans so please check that your host allows database accounts with the following rights: SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES Note: If your system/host is running MySQL 4.1 or newer and you receive the error "Client does not support authentication protocol requested by server", address the problem by following the instructions provided by MySQL AB. There is a minor OS issue with some MySQL 5+ installations primarily on Windows but affecting some Unices as well. PostgreSQL, version 7.3 or newer. Note, some of the contributed modules are not as abstracted from MySQL specific code as everyone would like. If you are familiar with PostgreSQL please file issues with those contributed modules as you find them. Currently MS SQL and Oracle are not supported but various efforts are underway to supply schemas. Please see discussions in the Enterprise Group if you are interested in working on this.
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 dont care about particular browsers, only what they support.
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 its 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.
3 Aug 2007
Drupal Handbook
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 jurys out on using persistent connections. There is a need for more case studies like this to be documented on this handbook page
3 Aug 2007
Drupal Handbook
with Apache (or a compatible web server), if the .htaccess file is actually read, i.e. AllowOverride is not None, if PHP is installed as an Apache module. See here for how to change configuration settings for other interfaces to PHP. Using a PEAR-supported Database (see below) requires (of course) PEAR to be installed. A PHP-supported Database Server Recommended: MySQL, v3.23.17 or newer (for our use of INNER JOINs with join_conditions). 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 youll 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.
Drupal Handbook
3 Aug 2007
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.
3 Aug 2007
Drupal Handbook
For more detailed information about Drupal requirements, see "Requirements" (http://drupal.org/requirements) in the Drupal Handbook. Guidelines for setting up a server environment with a variety of operating systems and in special cases are available in the Drupal handbook (http://drupal.org/node/260) OPTIONAL REQUIREMENTS --------------------- To use XML-based services such as the Blogger API, Jabber, and RSS syndication, you will need PHPs XML extension. This extension is enabled by default. - If you want support for clean URLs, youll 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 servers document root or your public HTML directory: mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html 2. CREATE THE DRUPAL DATABASE Drupal requires access to a database in order to be installed. Your database user will need sufficient privileges to run Drupal. Additional information about privileges, and instructions to create a database using the command line are available in INSTALL.mysql.txt (for MySQL) or INSTALL.pgsql.txt (for PostgreSQL). To create a database using PHPMyAdmin or a web-based control panel consult the documentation or ask your webhost service provider. Take note of the username, password, database name and hostname as you
Drupal Handbook
3 Aug 2007
create the database. You will enter these items in the install script. 3. RUN THE INSTALL SCRIPT The install script will set the base URL, connect Drupal to the database, and create tables in the database. To run the install script point your browser to the base url of your website (i.e. http://www.example.com). You will be presented with the "Database Configuration" page. The install script will attempt to write-protect the settings.php after updating it with the information you provide in the installation routine. If you make manual changes to that file later, be sure to protect it again after making your modifications. Failure to remove write permissions to that file is a security risk. The default location for the settings.php file is at sites/default/settings.php, but it may be in another location if you use the multi-site setup, as explained below. 4. CONFIGURE DRUPAL When the install script succeeds, you will be directed to the "Welcome" page. In "step one" click "create the first account" which will become the main administrator account with total control. Login as the administrator and complete the initial configuration steps on the "Welcome" page. Consider creating a "files" subdirectory in your Drupal installation directory. This subdirectory stores files such as custom logos, user avatars, and other media associated with your new site. The sub-directory requires "read and write" permission by the Drupal server process. You can change the name of this subdirectory at "administer > site configuration > file system". 5. CRON TASKS Many Drupal modules (such as the search functionality) have periodic tasks that must be triggered by a cron job. To activate these tasks, call the cron
10
3 Aug 2007
Drupal Handbook
page by visiting http://www.example.com/cron.php --this will pass control to the modules and the modules will decide if and what they must do. Most systems support the crontab utility for scheduling tasks like this. The following example crontab line will activate the cron tasks automatically on the hour: 0 * * * * wget -O - -q http://www.example.com/cron.php More information about the cron scripts are available in the admin help pages and in the Drupal handbook at drupal.org. Example scripts can be found in the scripts/ directory. DRUPAL ADMINISTRATION --------------------A new installation of Drupal defaults to a very basic configuration with only a few active modules and minimal user access rights. Use your administration panel to enable and configure services. For example: General Settings administer > site configuration > site information Enable Modules administer > site configuration > modules Set User Permissions administer > users management > access control Configure Themes administer > site building > themes For more information on configuration options, read the instructions which accompany the different configuration settings and consult the various help pages available in the administration panel. Community-contributed modules and themes are available at http://drupal.org/. CUSTOMIZING YOUR THEME(S) ------------------------Now that your installation is running, you will want to customize the look of your site. Several sample themes are included and more can be downloaded from drupal.org. Simple customization of your theme can be done using only CSS. Further changes require understanding the phptemplate engine that is now part of Drupal. See http://drupal.org/handbook/customization to find out more. MULTISITE CONFIGURATION -----------------------
11
Drupal Handbook
3 Aug 2007
A single Drupal installation can host several Drupal-powered sites, each with its own individual configuration. Additional site configurations are created in subdirectories within the sites directory. Each subdirectory must have a settings.php file which specifies the configuration settings. The easiest way to create additional sites is to copy the default directory and modify the settings.php file as appropriate. The new directory name is constructed from the sites URL. The configuration for www.example.com could be in sites/example.com/settings.php (note that www. should be omitted if users can access your site at http://example.com/). Sites do not have to have a different domain. You can also use subdomains and subdirectories for Drupal sites. For example, example.com, sub.example.com, and sub.example.com/site3 can all be defined as independent Drupal sites. The setup for a configuration such as this would look like the following: sites/default/settings.php sites/example.com/settings.php sites/sub.example.com/settings.php sites/sub.example.com.site3/settings.php When searching for a site configuration (for example www.sub.example.com/site3), Drupal will search for configuration files in the following order, using the first configuration it finds: sites/www.sub.example.com.site3/settings.php sites/sub.example.com.site3/settings.php sites/example.com.site3/settings.php sites/www.sub.example.com/settings.php sites/sub.example.com/settings.php sites/example.com/settings.php sites/default/settings.php If you are installing on a non-standard port, the port number is treated as the deepest subdomain. For example: http://www.example.com:8080/ could be loaded from sites/8080.www.example.com/. The port number will be removed according to the pattern above if no port-specific configuration is found, just like
12
3 Aug 2007
Drupal Handbook
a real subdomain. Each site configuration can have its own site-specific modules and themes in addition to those installed in the standard modulesand 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.
13
Drupal Handbook
3 Aug 2007
Changes
As of Drupal 5.0 installation has been automated by an install script. It is no longer necessary to manually edit the "settings.php" file, and database tables are created automatically.
Requirements
Drupal requires a web server, PHP4 (4.3.3 or greater) or PHP5 (http://www.php.net/) and either MySQL (http://www.mysql.com/) or PostgreSQL (http://www.postgresql.org/). The Apache web server and MySQL database are recommended; other web server and database combinations such as IIS and PostgreSQL have been tested to a lesser extent. When using MySQL, version 4.1 or greater is recommended to assure you can safely transfer the database. For more detailed information about Drupal requirements, (http://drupal.org/requirements) in the Drupal Handbook. see "Requirements"
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 PHPs XML extension. This extension is enabled by default. - If you want support for clean URLs, youll 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 servers document root or your public HTML directory: mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html 2. Create the Drupal database Drupal requires access to a database in order to be installed. Your database user will need sufficient privileges to run Drupal. Additional information about privileges, and instructions to create a database using the command line are available in INSTALL.mysql.txt (for MySQL) or
14
3 Aug 2007
Drupal Handbook
INSTALL.pgsql.txt (for PostgreSQL). To create a database using PHPMyAdmin or a web-based control panel consult the documentation or ask your webhost service provider. Take note of the username, password, database name and hostname as you create the database. You will enter these items in the install script. 3. Run the install script The install script will set the base URL, connect Drupal to the database, and create tables in the database. To run the install script point your browser to the base url of your website (i.e. http://www.example.com). You will be presented with the "Database Configuration" page. The install script will attempt to write-protect the settings.php after updating it with the information you provide in the installation routine. If you make manual changes to that file later, be sure to protect it again after making your modifications. Failure to remove write permissions to that file is a security risk. The default location for the settings.php file is at sites/default/settings.php, but it may be in another location if you use the multi-site setup, as explained below. 4. Configure Drupal When the install script succeeds, you will be directed to the "Welcome" page. In "step one" click "create the first account" which will become the main administrator account with total control. Login as the administrator and complete the initial configuration steps on the "Welcome" page. Consider creating a "files" subdirectory in your Drupal installation directory. This subdirectory stores files such as custom logos, user avatars, and other media associated with your new site. The sub-directory requires "read and write" permission by the Drupal server process. You can change the name of this subdirectory at "administer > site configuration > file system". 5. Cron Tasks Many Drupal modules (such as the search functionality) have periodic tasks that must be triggered by a cron job. To activate these tasks, call the cron page by visiting http://www.example.com/cron.php --this will pass control to the modules and the modules will decide if and what they must do. Most systems support the crontab utility for scheduling tasks like this. The following example crontab line will activate the cron tasks automatically on the hour: 0 * * * * wget -O - -q http://www.example.com/cron.php
More information about the cron scripts are available in the admin help pages and in the Drupal handbook at drupal.org. Example scripts can be found in the scripts/ directory.
15
Drupal Handbook
3 Aug 2007
Drupal Administration
A new installation of Drupal defaults to a very basic configuration with only aw active modules and minimal user access rights. Use your administration panel to enable and configure services. For example: General Settings administer > site configuration > site information Enable Modules administer > site configuration > modules Set User Permissions administer > users management > access control Configure Themes administer > site building > themes For more information on configuration options, read the instructions which accompany the different configuration settings and consult the various help pages available in the administration panel. Community-contributed modules and themes are available at http://drupal.org/.
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 sites 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 modulesand 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. 2. 3. 4. 5. 6. 7. 8.
REQUIREMENTS SERVER CONFIGURATION OPTIONAL COMPONENTS INSTALLATION DRUPAL ADMINISTRATION CUSTOMIZING YOUR THEME(S) UPGRADING 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
These values are set in php.ini and can be overwritten in a .htaccess file; you can print out your local PHP settings with PHPs phpinfo() function.
OPTIONAL COMPONENTS
To use XML-based services such as the Blogger API, Jabber, RSS syndication, you will need PHPs XML extension. This extension is enabled by default in standard PHP4 installations. If you want support for clean URLs, youll need mod_rewrite and the ability to use local .htaccess files. (More information can be found in the Drupal handbook on drupal.org.)
18
3 Aug 2007
Drupal Handbook
INSTALLATION
1. DOWNLOAD DRUPAL
You can obtain the latest Drupal release from http://drupal.org/. Download the current tar.gz format and extract the files: $ wget http://drupal.org/files/project/drupal-x.x.x.tgz $ tar -zxvf drupal-x.x.x.tgz This will create a new directory drupal-x.x.x/ containing all Drupal files and directories. Move the contents of that directory into a directory within your web servers document root or your public HTML directory: $ mv drupal-x.x.x/* drupal-x.x.x/.htaccess /var/www/html
19
Drupal Handbook
3 Aug 2007
If successful, MySQL will reply with Query OK, 0 rows affected to activate the new permissions you must enter the command flush privileges; and then enter \q to exit MySQL.
4. CONNECTING DRUPAL
The default configuration can be found in the sites/default/settings.php file within your Drupal installation. Before you can run Drupal, you must set the database URL and the base URL to the web site. Open the configuration file and edit the $db_url line to match the database defined in the previous steps: $db_url = "mysql://username:password@localhost/drupal"; Set $base_url to match the address to your web site: $base_url = "http://www.example.com"; In addition, a single Drupal installation can host several Drupal-powered sites, each with its own individual configuration. If you dont need to run multiple Drupal sites, you can skip to the next section. Additional site configurations are created in subdirectories within the sites directory. Each site subdirectory must have a settings.php file which specifies the configuration settings. The easiest way to create additional sites is to copy the default directory and modify the settings.php file as appropriate. The new directory name is constructed from the sites URL. The configuration for www.example.com could be in sites/example.com/settings.php (note that www. should be omitted if users can access your site at http://example.com/). Sites do not each have to have a different domain. You can use subdomains and subdirectories for Drupal sites also. For example, example.com, sub.example.com, and sub.example.com/site3 can all be
20
3 Aug 2007
Drupal Handbook
defined as independent Drupal sites. The setup for a configuration such as this would look like the following: sites/default/settings.php sites/example.com/settings.php sites/sub.example.com/settings.php sites/sub.example.com.site3/settings.php When searching for a site configuration (for example www.sub.example.com/site3), Drupal will search for configuration files in the following order, using the first configuration file it finds: sites/www.sub.example.com.site3/settings.php sites/sub.example.com.site3/settings.php sites/example.com.site3/settings.php sites/www.sub.example.com/settings.php sites/sub.example.com/settings.php sites/example.com/settings.php sites/default/settings.php Each site configuration can have its own site-specific modules and themes that will be made available in addition to those installed in the standard modules and themes directories. To use site-specific modules or themes, simply create a modules or themes directory within the site configuration directory. For example, if sub.example.dom has a custom theme and a custom module that should not be accessible to other sites, the setup would look like this: sites/sub.example.com/: settings.php themes/: custom_theme modules/: custom_module NOTE: for more information about multiple virtual hosts or the configuration settings, consult the Drupal handbook at drupal.org.
5. CONFIGURE DRUPAL
You can now launch your browser and point it to your Drupal site. Create an account and login. The first account will automatically become the main administrator account.
21
Drupal Handbook
3 Aug 2007
6. CRON TASKS
Many Drupal modules have periodic tasks that must be triggered by a cron job. To activate these tasks, you must call the cron page; this will pass control to the modules and the modules will decide if and what they must do. The following example crontab line will activate the cron script on the hour: 0 * * * * wget -O - -q http://HOSTNAME/cron.php
More information about the cron scripts are available in the admin help pages and in the Drupal handbook at drupal.org. Example scripts can be found in the scripts/ directory.
DRUPAL ADMINISTRATION
Upon a new installation, your Drupal website defaults to a very basic configuration with only a few active modules, one theme, and no user access rights. Use your administration panel to enable and configure services. For example, set some general settings for your site with "Administration configuration". Enable modules via "Administration - configuration modules". User permissions can be set with "Administration - accounts - permissions". For more information on configuration options, read through the instructions which accompany the different configuration settings and consult the various help pages available in the administration panel. Note that additional community-contributed modules and themes are available at http://drupal.org/.
22
3 Aug 2007
Drupal Handbook
Most themes also contain stylesheets or PHP configuration files to tune the colors and layouts; check the themes/ directory for README files describing each alternate theme.
UPGRADING
1. Backup your database and Drupal directory - especially your configuration file (www.example.com.conf or includes/conf.php). 2. Log on as the user with user ID 1. 3. Remove all the old Drupal files then unpack the new Drupal files into the directory that you run Drupal from. 4. Modify the new configuration file to make sure it has the correct information. 5. Run update.php by visiting http://www.example.com/update.php.
MORE INFORMATION
For platform specific configuration issues and other installation and administration assistance, please consult the Drupal handbook at http://drupal.org/. You can also find support at the Drupal support forum or through the Drupal mailing lists.
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 sites 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.]
24
3 Aug 2007
Drupal Handbook
password). Noted the hostname, e.g., testsite.yoursite.com 4) Using browser, pointed to URL \http://drupal.yoursite.com\ 5) The install.php script automatically installed Drupal 6) Entered information. Database name ("dbname"), username, password 7) Clicked "Advanced options" 8) Entered hostname (e.g., testsite.yoursite.com). Went to testsite.yoursite.com in browser.
25
Drupal Handbook
3 Aug 2007
Activate the sites configuration: a2ensite www.example.com Reload Apaches configuration: /etc/init.d/apache2 force-reload Done! Please post any changes or concerns, Tarek : )
26
3 Aug 2007
Drupal Handbook
You may also need to edit this file to enable the PHP module for Apache. You have to uncomment two lines. First in this section: # # Dynamic Shared Object (DSO) Support # Uncomment this line (around line 235) by removing the #: #LoadModule php4_module Then go below to this section: # Reconstruction of the complete module list from all available modules # (static and shared ones) to achieve correct module execution order. and uncomment this line (around line 278) by removing the #: #AddModule mod_php4.c Drupal goes into /Library/WebServer/Documents/, or ~/Sites. If you use ~/Sites, you may also have to edit the .conf file in /etc/httpd/users that corresponds to your user account. You must AllowOverride in this file for your ~/Sites for clean URLs to work there. After any edits to your .conf files, be sure to restart Apache (as described above). MacZeaolots has a good tutorial on installing Drupal on Mac OS X 10.4. The same tutorial applies to 10.3 as well. While the tutorial talks about Drupal 4.6, the setup of the server environment is the same for any version of Drupal. libexec/httpd/libphp4.so
27
Drupal Handbook
3 Aug 2007
You can instead set this in /etc/my.cnf. #Name of the socket file to use. socket=/var/mysql/mysql.sock Both work, but the second one may make the MySQL preference pane stop working. You may also need to restart apache to have this take effect. Restart from the terminal: $ sudo apachectl restart or restart by disabling and re-enabling personal web sharing.
28
3 Aug 2007
Drupal Handbook
5. Start configuring Drupal! Go to http://localhost:8888/drupal-x.x.x/ and create the first account. Continue with instructions in INSTALL.txt.
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
30
3 Aug 2007
Drupal Handbook
and then start a new Terminal window. Next, we want to make MySQL secure by setting a MySQL root password. Fortunately a handy utility is provided to make that easy. I typed in: mysql_secure_installation Interacting with the script looked like this (note that at the first prompt I just pressed enter since no root password has been set yet: Enter current password for root (enter for none): OK, successfully used password, moving on... Setting the root password ensures that nobody can log into the MySQL root user without the proper authorisation. Set root password? [Y/n] Y New password: zoinks Re-enter new password: zoinks Password updated successfully! Reloading privilege tables.. ... Success! By default, a MySQL installation has an anonymous user, allowing anyone to log into MySQL without having to have a user account created for them. This is intended only for testing, and to make the installation go a bit smoother. You should remove them before moving into a production environment. Remove anonymous users? [Y/n] Y ... Success! Normally, root should only be allowed to connect from localhost. This ensures that someone cannot guess at the root password from the network. Disallow root login remotely? [Y/n] Y ... Success! By default, MySQL comes with a database named test that anyone can access. This is also intended only for testing, and should be removed before moving into a production environment. Remove test database and access to it? [Y/n] Y - Dropping test database... ... Success! - Removing privileges on test database... ... Success! Reloading the privilege tables will ensure that all changes made so far will take effect immediately. Reload privilege tables now? [Y/n] Y ... Success! Cleaning up... All done! If youve completed all of the above steps, your MySQL
31
Drupal Handbook
3 Aug 2007
installation should now be secure. Thanks for using MySQL! I verified that MySQL was running: $ mysqladmin -u root -p status Enter password: zoinks Uptime: 938 Threads: 1 Questions: 16 Slow queries: 0 Opens: 21 Flush tables: 1 Open tables: 0 Queries per second avg: 0.017 It was running fine. Now on to the task of setting up MySQL for Drupal.
Sending mail
Current versions of OS X use Postfix as the mail server but you have to enable it. For a detailed how-to, see: http://www.stepwise.com/Articles/Workbench/eart.index.html Or save yourself lots of frustration and time and spend $10 for Postfix Enabler and get running in a couple of minutes. http://cutedgesystems.com/software/PostfixEnabler/
32
3 Aug 2007
Drupal Handbook
Now we apply the new settings: mysql> flush privileges; Query OK, 0 rows affected (0.19 sec) mysql> \q Bye Now I paused to rejoice. MySQL was installed and ready for Drupal. Now it was time to install Drupal itself.
33
Drupal Handbook
3 Aug 2007
Now I had MySQL running, and had a Drupal database populated by Drupals fields. It was time to tell Drupal how to find that database. In the Finder, I went to /Library/WebServer/Documents/Drupal/sites and duplicated the folder called default, and renamed it localhost. Then inside the new localhost directory I edited the settings.php file, changing line 81 to read: $db_url = mysql://drupaldbuser:fuffy@localhost/drupal; and changing line 90 to read: $base_url = http://localhost/drupal; The reason I duplicated the "default" settings folder was to avoid conflicts when I update CVS in the future, since CVS would have seen the changed settings.php file and tried to merge it with the original one. By keeping my settings file separate, I avoid this. As long as I access my Drupal installation through the URL http://localhost/drupal it will use the settings in the localhost folder. PHP is not enabled by default on OS 10.4. So I enabled it by editing Apaches configuration file. I used BBEdit, but you can use any text editor you want. For example, you could choose Go To Folder from the Finders 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. Heres me opening the file for editing in BBEdit: sudo bbedit /etc/httpd/httpd.conf Then I removed the # from in front of line 240: #LoadModule php4_module and line 284: #AddModule mod_php4.c and line 406: AllowOverride All After changing the configuration file, I stopped, then started the Personal Web Sharing service in the Sharing pane of System Preferences. This forces Apache to reread the configuration file and apply the changes. So now PHP was enabled. Now, with my hands shaking from excitement, I entered http://localhost/drupal into my web browser. I was greeted with Drupals welcome page: libexec/httpd/libphp4.so
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! Dont 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 Ive 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
hostname varchar(128) default NULL, uid int(10) unsigned default 0, timestamp int(11) unsigned NOT NULL default 0, KEY accesslog_timestamp (timestamp), PRIMARY KEY (aid) ) TYPE=MyISAM; --- Table structure for table aggregator_category -CREATE TABLE prefix_aggregator_category ( cid int(10) NOT NULL auto_increment, title varchar(255) NOT NULL default , description longtext NOT NULL, block tinyint(2) NOT NULL default 0, PRIMARY KEY (cid), UNIQUE KEY title (title) ) TYPE=MyISAM; --- Table structure for table aggregator_category_feed -CREATE TABLE prefix_aggregator_category_feed ( fid int(10) NOT NULL default 0, cid int(10) NOT NULL default 0, PRIMARY KEY (fid,cid) ) TYPE=MyISAM; --- Table structure for table aggregator_category_item -CREATE TABLE prefix_aggregator_category_item ( iid int(10) NOT NULL default 0, cid int(10) NOT NULL default 0, PRIMARY KEY (iid,cid) ) TYPE=MyISAM; --- Table structure for table aggregator_feed -CREATE TABLE prefix_aggregator_feed ( fid int(10) NOT NULL auto_increment, title varchar(255) NOT NULL default , url varchar(255) NOT NULL default , refresh int(10) NOT NULL default 0, checked int(10) NOT NULL default 0, link varchar(255) NOT NULL default , description longtext NOT NULL, image longtext NOT NULL, etag varchar(255) NOT NULL default , modified int(10) NOT NULL default 0,
37
Drupal Handbook
3 Aug 2007
block tinyint(2) NOT NULL default 0, PRIMARY KEY (fid), UNIQUE KEY link (url), UNIQUE KEY title (title) ) TYPE=MyISAM; --- Table structure for table aggregator_item -CREATE TABLE prefix_aggregator_item ( iid int(10) NOT NULL auto_increment, fid int(10) NOT NULL default 0, title varchar(255) NOT NULL default , link varchar(255) NOT NULL default , author varchar(255) NOT NULL default , description longtext NOT NULL, timestamp int(11) default NULL, PRIMARY KEY (iid) ) TYPE=MyISAM; --- Table structure for table authmap -CREATE TABLE prefix_authmap ( aid int(10) unsigned NOT NULL auto_increment, uid int(10) NOT NULL default 0, authname varchar(128) NOT NULL default , module varchar(128) NOT NULL default , PRIMARY KEY (aid), UNIQUE KEY authname (authname) ) TYPE=MyISAM; --- Table structure for table blocks -CREATE TABLE prefix_blocks ( module varchar(64) DEFAULT NOT NULL, delta varchar(32) NOT NULL default 0, status tinyint(2) DEFAULT 0 NOT NULL, weight tinyint(1) DEFAULT 0 NOT NULL, region tinyint(1) DEFAULT 0 NOT NULL, custom tinyint(2) DEFAULT 0 NOT NULL, throttle tinyint(1) DEFAULT 0 NOT NULL, visibility tinyint(1) DEFAULT 0 NOT NULL, pages text NOT NULL, types text NOT NULL ) TYPE=MyISAM; --- Table structure for table book --
38
3 Aug 2007
Drupal Handbook
CREATE TABLE prefix_book ( nid int(10) unsigned NOT NULL default 0, parent int(10) NOT NULL default 0, weight tinyint(3) NOT NULL default 0, log longtext, PRIMARY KEY (nid), KEY parent (parent) ) TYPE=MyISAM; --- Table structure for table boxes -CREATE TABLE prefix_boxes ( bid tinyint(4) NOT NULL auto_increment, title varchar(64) NOT NULL default , body longtext, info varchar(128) NOT NULL default , format int(4) NOT NULL default 0, PRIMARY KEY (bid), UNIQUE KEY title (title), UNIQUE KEY info (info) ) TYPE=MyISAM; --- Table structure for table cache -CREATE TABLE prefix_cache ( cid varchar(255) NOT NULL default , data longtext, expire int(11) NOT NULL default 0, created int(11) NOT NULL default 0, headers text, PRIMARY KEY (cid), INDEX expire (expire) ) TYPE=MyISAM; --- Table structure for table comments -CREATE TABLE prefix_comments ( cid int(10) NOT NULL auto_increment, pid int(10) NOT NULL default 0, nid int(10) NOT NULL default 0, uid int(10) NOT NULL default 0, subject varchar(64) NOT NULL default , comment longtext NOT NULL, hostname varchar(128) NOT NULL default , timestamp int(11) NOT NULL default 0, score mediumint(9) NOT NULL default 0, status tinyint(3) unsigned NOT NULL default 0,
39
Drupal Handbook
3 Aug 2007
format int(4) NOT NULL default 0, thread varchar(255) NOT NULL, users longtext, name varchar(60) default NULL, mail varchar(64) default NULL, homepage varchar(255) default NULL, PRIMARY KEY (cid), KEY lid (nid) ) TYPE=MyISAM; --- Table structre for table node_last_comment -CREATE TABLE prefix_node_comment_statistics ( nid int(10) unsigned NOT NULL auto_increment, last_comment_timestamp int(11) NOT NULL default 0, last_comment_name varchar(60) default NULL, last_comment_uid int(10) NOT NULL default 0, comment_count int(10) unsigned NOT NULL default 0, PRIMARY KEY (nid), KEY node_comment_timestamp (last_comment_timestamp) ) TYPE=MyISAM; --- Table structure for table directory -CREATE TABLE prefix_directory ( link varchar(255) NOT NULL default , name varchar(128) NOT NULL default , mail varchar(128) NOT NULL default , slogan longtext NOT NULL, mission longtext NOT NULL, timestamp int(11) NOT NULL default 0, PRIMARY KEY (link) ) TYPE=MyISAM; --- Table structure for table files -CREATE TABLE prefix_files ( fid int(10) unsigned NOT NULL default 0, nid int(10) unsigned NOT NULL default 0, filename varchar(255) NOT NULL default , filepath varchar(255) NOT NULL default , filemime varchar(255) NOT NULL default , filesize int(10) unsigned NOT NULL default 0, list tinyint(1) unsigned NOT NULL default 0, PRIMARY KEY (fid) ) TYPE=MyISAM; --
40
3 Aug 2007
Drupal Handbook
-- Table structure for table filter_formats -CREATE TABLE prefix_filter_formats ( format int(4) NOT NULL auto_increment, name varchar(255) NOT NULL default , roles varchar(255) NOT NULL default , cache tinyint(2) NOT NULL default 0, PRIMARY KEY (format) ) TYPE=MyISAM; --- Table structure for table filters -CREATE TABLE prefix_filters ( format int(4) NOT NULL default 0, module varchar(64) NOT NULL default , delta tinyint(2) DEFAULT 0 NOT NULL, weight tinyint(2) DEFAULT 0 NOT NULL, INDEX (weight) ) TYPE=MyISAM; --- Table structure for table flood -CREATE TABLE prefix_flood ( event varchar(64) NOT NULL default , hostname varchar(128) NOT NULL default , timestamp int(11) NOT NULL default 0 ) TYPE=MyISAM; --- Table structure for table forum -CREATE TABLE prefix_forum ( nid int(10) unsigned NOT NULL default 0, tid int(10) unsigned NOT NULL default 0, PRIMARY KEY (nid), KEY tid (tid) ) TYPE=MyISAM; --- Table structure for table history -CREATE TABLE prefix_history ( uid int(10) NOT NULL default 0, nid int(10) NOT NULL default 0, timestamp int(11) NOT NULL default 0, PRIMARY KEY (uid,nid) ) TYPE=MyISAM; --- Table structure for table locales_meta
41
Drupal Handbook
3 Aug 2007
-CREATE TABLE prefix_locales_meta ( locale varchar(12) NOT NULL default , name varchar(64) NOT NULL default , enabled int(2) NOT NULL default 0, isdefault int(2) NOT NULL default 0, plurals int(1) NOT NULL default 0, formula varchar(128) NOT NULL default , PRIMARY KEY (locale) ) TYPE=MyISAM; --- Table structure for table locales_source -CREATE TABLE prefix_locales_source ( lid int(11) NOT NULL auto_increment, location varchar(255) NOT NULL default , source blob NOT NULL, PRIMARY KEY (lid) ) TYPE=MyISAM; --- Table structure for table locales_target -CREATE TABLE prefix_locales_target ( lid int(11) NOT NULL default 0, translation blob NOT NULL, locale varchar(12) NOT NULL default , plid int(11) NOT NULL default 0, plural int(1) NOT NULL default 0, KEY lid (lid), KEY lang (locale), KEY plid (plid), KEY plural (plural) ) TYPE=MyISAM; --- Table structure for table menu -CREATE TABLE prefix_menu ( mid int(10) unsigned NOT NULL default 0, pid int(10) unsigned NOT NULL default 0, path varchar(255) NOT NULL default , title varchar(255) NOT NULL default , description varchar(255) NOT NULL default , weight tinyint(4) NOT NULL default 0, type int(2) unsigned NOT NULL default 0, PRIMARY KEY (mid) ) TYPE=MyISAM; --
42
3 Aug 2007
Drupal Handbook
-- Table structure for table moderation_filters -CREATE TABLE prefix_moderation_filters ( fid int(10) unsigned NOT NULL auto_increment, filter varchar(255) NOT NULL default , minimum smallint(6) NOT NULL default 0, PRIMARY KEY (fid) ) TYPE=MyISAM; --- Table structure for table moderation_roles -CREATE TABLE prefix_moderation_roles ( rid int(10) unsigned NOT NULL default 0, mid int(10) unsigned NOT NULL default 0, value tinyint(4) NOT NULL default 0, KEY idx_rid (rid), KEY idx_mid (mid) ) TYPE=MyISAM; --- Table structure for table moderation_votes -CREATE TABLE prefix_moderation_votes ( mid int(10) unsigned NOT NULL auto_increment, vote varchar(255) default NULL, weight tinyint(4) NOT NULL default 0, PRIMARY KEY (mid) ) TYPE=MyISAM; --- Table structure for table node -CREATE TABLE prefix_node ( nid int(10) unsigned NOT NULL auto_increment, type varchar(16) NOT NULL default , title varchar(128) NOT NULL default , uid int(10) NOT NULL default 0, status int(4) NOT NULL default 1, created int(11) NOT NULL default 0, changed int(11) NOT NULL default 0, comment int(2) NOT NULL default 0, promote int(2) NOT NULL default 0, moderate int(2) NOT NULL default 0, teaser longtext NOT NULL, body longtext NOT NULL, revisions longtext NOT NULL, sticky int(2) NOT NULL default 0, format int(4) NOT NULL default 0, PRIMARY KEY (nid),
43
Drupal Handbook
3 Aug 2007
KEY node_type (type(4)), KEY node_title_type (title,type(4)), KEY status (status), KEY uid (uid), KEY node_moderate (moderate), KEY node_promote_status (promote, status), KEY node_created (created), KEY node_changed (changed), KEY node_status_type (status, type, nid) ) TYPE=MyISAM; --- Table structure for table node_access -CREATE TABLE prefix_node_access ( nid int(10) unsigned NOT NULL default 0, gid int(10) unsigned NOT NULL default 0, realm varchar(255) NOT NULL default , grant_view tinyint(1) unsigned NOT NULL default 0, grant_update tinyint(1) unsigned NOT NULL default 0, grant_delete tinyint(1) unsigned NOT NULL default 0, PRIMARY KEY (nid,gid,realm) ) TYPE=MyISAM; --- Table structure for table profile_fields -CREATE TABLE prefix_profile_fields ( fid int(10) NOT NULL auto_increment, title varchar(255) default NULL, name varchar(128) default NULL, explanation TEXT default NULL, category varchar(255) default NULL, page varchar(255) default NULL, type varchar(128) default NULL, weight tinyint(1) DEFAULT 0 NOT NULL, required tinyint(1) DEFAULT 0 NOT NULL, register tinyint(1) DEFAULT 0 NOT NULL, visibility tinyint(1) DEFAULT 0 NOT NULL, options text, KEY category (category), UNIQUE KEY name (name), PRIMARY KEY (fid) ); --- Table structure for table profile_values -CREATE TABLE prefix_profile_values ( fid int(10) unsigned default 0,
44
3 Aug 2007
Drupal Handbook
uid int(10) unsigned default 0, value text, KEY uid (uid), KEY fid (fid) ); --- Table structure for table url_alias -CREATE TABLE prefix_url_alias ( pid int(10) unsigned NOT NULL auto_increment, src varchar(128) NOT NULL default , dst varchar(128) NOT NULL default , PRIMARY KEY (pid), UNIQUE KEY dst (dst) ) TYPE=MyISAM; --- Table structure for table permission -CREATE TABLE prefix_permission ( rid int(10) unsigned NOT NULL default 0, perm longtext, tid int(10) unsigned NOT NULL default 0, KEY rid (rid) ) TYPE=MyISAM; --- Table structure for table poll -CREATE TABLE prefix_poll ( nid int(10) unsigned NOT NULL default 0, runtime int(10) NOT NULL default 0, polled longtext NOT NULL, active int(2) unsigned NOT NULL default 0, PRIMARY KEY (nid) ) TYPE=MyISAM; --- Table structure for table poll_choices -CREATE TABLE prefix_poll_choices ( chid int(10) unsigned NOT NULL auto_increment, nid int(10) unsigned NOT NULL default 0, chtext varchar(128) NOT NULL default , chvotes int(6) NOT NULL default 0, chorder int(2) NOT NULL default 0, PRIMARY KEY (chid), KEY nid (nid) ) TYPE=MyISAM; --
45
Drupal Handbook
3 Aug 2007
-- Table structure for table queue -CREATE TABLE prefix_queue ( nid int(10) unsigned NOT NULL, uid int(10) unsigned NOT NULL, vote int(3) NOT NULL default 0, PRIMARY KEY (nid, uid) ) TYPE=MyISAM; --- Table structure for table role -CREATE TABLE prefix_role ( rid int(10) unsigned NOT NULL auto_increment, name varchar(32) NOT NULL default , PRIMARY KEY (rid), UNIQUE KEY name (name) ) TYPE=MyISAM; --- Table structure for table search_index -CREATE TABLE prefix_search_index ( word varchar(50) NOT NULL default , sid int(10) unsigned NOT NULL default 0, type varchar(16) default NULL, fromsid int(10) unsigned NOT NULL default 0, fromtype varchar(16) default NULL, score int(10) unsigned default NULL, KEY sid (sid), KEY fromsid (fromsid), KEY word (word) ) TYPE=MyISAM; --- Table structure for table search_total -CREATE TABLE prefix_search_total ( word varchar(50) NOT NULL default , count int(10) unsigned default NULL, PRIMARY KEY word (word) ) TYPE=MyISAM; --- Table structure for table sessions -CREATE TABLE prefix_sessions ( uid int(10) unsigned NOT NULL, sid varchar(32) NOT NULL default , hostname varchar(128) NOT NULL default , timestamp int(11) NOT NULL default 0,
46
3 Aug 2007
Drupal Handbook
session longtext, KEY uid (uid), PRIMARY KEY (sid), KEY timestamp (timestamp) ) TYPE=MyISAM; --- Table structure for table sequences -CREATE TABLE prefix_sequences ( name varchar(255) NOT NULL default , id int(10) unsigned NOT NULL default 0, PRIMARY KEY (name) ) TYPE=MyISAM; --- Table structure for table node_counter -CREATE TABLE prefix_node_counter ( nid int(11) NOT NULL default 0, totalcount bigint(20) unsigned NOT NULL default 0, daycount mediumint(8) unsigned NOT NULL default 0, timestamp int(11) unsigned NOT NULL default 0, PRIMARY KEY (nid), KEY totalcount (totalcount), KEY daycount (daycount), KEY timestamp (timestamp) ) TYPE=MyISAM; --- Table structure for table system -CREATE TABLE prefix_system ( filename varchar(255) NOT NULL default , name varchar(255) NOT NULL default , type varchar(255) NOT NULL default , description varchar(255) NOT NULL default , status int(2) NOT NULL default 0, throttle tinyint(1) DEFAULT 0 NOT NULL, bootstrap int(2) NOT NULL default 0, PRIMARY KEY (filename) ) TYPE=MyISAM; --- Table structure for table term_data -CREATE TABLE prefix_term_data ( tid int(10) unsigned NOT NULL auto_increment, vid int(10) unsigned NOT NULL default 0, name varchar(255) NOT NULL default , description longtext,
47
Drupal Handbook
3 Aug 2007
weight tinyint(4) NOT NULL default 0, PRIMARY KEY (tid), KEY vid (vid) ) TYPE=MyISAM; --- Table structure for table term_hierarchy -CREATE TABLE prefix_term_hierarchy ( tid int(10) unsigned NOT NULL default 0, parent int(10) unsigned NOT NULL default 0, KEY tid (tid), KEY parent (parent) ) TYPE=MyISAM; --- Table structure for table term_node -CREATE TABLE prefix_term_node ( nid int(10) unsigned NOT NULL default 0, tid int(10) unsigned NOT NULL default 0, KEY nid (nid), KEY tid (tid), PRIMARY KEY (tid,nid) ) TYPE=MyISAM; --- Table structure for table term_relation -CREATE TABLE prefix_term_relation ( tid1 int(10) unsigned NOT NULL default 0, tid2 int(10) unsigned NOT NULL default 0, KEY tid1 (tid1), KEY tid2 (tid2) ) TYPE=MyISAM; --- Table structure for table term_synonym -CREATE TABLE prefix_term_synonym ( tid int(10) unsigned NOT NULL default 0, name varchar(255) NOT NULL default , KEY tid (tid), KEY name (name(3)) ) TYPE=MyISAM; --- Table structure for table users -CREATE TABLE prefix_users ( uid int(10) unsigned NOT NULL default 0, name varchar(60) NOT NULL default ,
48
3 Aug 2007
Drupal Handbook
pass varchar(32) NOT NULL default , mail varchar(64) default , mode tinyint(1) NOT NULL default 0, sort tinyint(1) default 0, threshold tinyint(1) default 0, theme varchar(255) NOT NULL default , signature varchar(255) NOT NULL default , created int(11) NOT NULL default 0, changed int(11) NOT NULL default 0, status tinyint(4) NOT NULL default 0, timezone varchar(8) default NULL, language varchar(12) NOT NULL default , picture varchar(255) NOT NULL DEFAULT , init varchar(64) default , data longtext, PRIMARY KEY (uid), UNIQUE KEY name (name), KEY changed (changed) ) TYPE=MyISAM; --- Table structure for table users_roles -CREATE TABLE prefix_users_roles ( uid int(10) unsigned NOT NULL default 0, rid int(10) unsigned NOT NULL default 0, PRIMARY KEY (uid, rid) ) TYPE=MyISAM; --- Table structure for table variable -CREATE TABLE prefix_variable ( name varchar(48) NOT NULL default , value longtext NOT NULL, PRIMARY KEY (name) ) TYPE=MyISAM; --- Table structure for table vocabulary -CREATE TABLE prefix_vocabulary ( vid int(10) unsigned NOT NULL auto_increment, name varchar(255) NOT NULL default , description longtext, help varchar(255) NOT NULL default , relations tinyint(3) unsigned NOT NULL default 0, hierarchy tinyint(3) unsigned NOT NULL default 0, multiple tinyint(3) unsigned NOT NULL default 0, required tinyint(3) unsigned NOT NULL default 0,
49
Drupal Handbook
3 Aug 2007
module varchar(255) NOT NULL default , weight tinyint(4) NOT NULL default 0, PRIMARY KEY (vid) ) TYPE=MyISAM; --- Table structure for table vocabulary_node_types -CREATE TABLE prefix_vocabulary_node_types ( vid int(10) unsigned NOT NULL DEFAULT 0, type varchar(16) NOT NULL DEFAULT , PRIMARY KEY (vid, type) ) TYPE=MyISAM; --- Table structure for table watchdog -CREATE TABLE prefix_watchdog ( wid int(5) NOT NULL auto_increment, uid int(10) NOT NULL default 0, type varchar(16) NOT NULL default , message longtext NOT NULL, severity tinyint(3) unsigned NOT NULL default 0, link varchar(255) NOT NULL default , location varchar(128) NOT NULL default , hostname varchar(128) NOT NULL default , timestamp int(11) NOT NULL default 0, PRIMARY KEY (wid) ) TYPE=MyISAM; --- Insert some default values -INSERT INTO prefix_system VALUES (modules/block.module,block,module,,1,0,0); INSERT INTO prefix_system VALUES (modules/comment.module,comment,module,,1,0,0); INSERT INTO prefix_system VALUES (modules/filter.module,filter,module,,1,0,0); INSERT INTO prefix_system VALUES (modules/help.module,help,module,,1,0,0); INSERT INTO prefix_system VALUES (modules/node.module,node,module,,1,0,0); INSERT INTO prefix_system VALUES (modules/page.module,page,module,,1,0,0); INSERT INTO prefix_system VALUES (modules/story.module,story,module,,1,0,0); INSERT INTO prefix_system VALUES (modules/system.module,system,module,,1,0,0); INSERT INTO prefix_system VALUES
50
3 Aug 2007
Drupal Handbook
(modules/taxonomy.module,taxonomy,module,,1,0,0); INSERT INTO prefix_system VALUES (modules/user.module,user,module,,1,0,0); INSERT INTO prefix_system VALUES (modules/watchdog.module,watchdog,module,,1,0,0); INSERT INTO prefix_system VALUES
(themes/bluemarine/xtemplate.xtmpl,bluemarine,theme,themes/engines/xtemplate/xtemplate.engine,1,0,0);
INSERT INTO prefix_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; 9. Modify the file C:\Inetpub\wwwroot\[YOURDIRNAME]\sites\default\settings.php by giving user name, password and database name. 10. Now browse this virtual http://localhost/"aliasname" folder with its alias name in IE example
11. If following error is displayed; Client does not support authentication protocol requested by server; consider upgrading MySQL client Then use these commands; SET PASSWORD FOR some_user@some_host = OLD_PASSWORD(newpwd); Flush privileges; 12. Repeat step 10, I hope its working . Have a look at one of the pretty clean theme implementation in drupal - ENJOY . . .
Understand the different common locations. The /sites/all and the /sites/default directories are exclusive, and are intended for the above items. The critical principle is to keep all your site customizations within the /sites directory so that it is easy to upgrade when a new minor version of the Drupal core code is released (e.g. to update from 5.1 to 5.2).
52
3 Aug 2007
Drupal Handbook
Contributed and custom modules should be placed in /drupal/sites/all/modules. Additional and custom themes should be placed in /drupal/sites/all/themes. The /files directory is usually best placed in the /sites/example.com directory, which you will have to create. Then set the File system path at administer > site configuration > file system. This is ideal if a second site will likely need a separate /files directory; just create a second site-specific /files directory at /sites/example2.com/files. The same applies for the /tmp directory. Upon initial installation the /files directory is set to /sites/default/files (you will need to create the actual directory). It can be fine to leave it there (or even to use /sites/files) if you are 100% you will never want to use multi-site features. However, this location shares the /files directory in a multi-site setup , which may or may not be desired. See "Setup of /sites directory for multi-site." Backup is simplified by use of the /sites directory for all customizations. You can then easily backup all non-core material by backing up the /sites directory and the database. For multi-site setup, see Multi-site installation and set-up, the sub-topic Setup of /sites directory for multi-site, and the installation instructions (INSTALL.txt). As stated above, there are two common locations in Drupal 5.x and above: /sites/default (for settings.php) and/sites/all (for common /modules and /themes). This allows a new site to be set up using the multi-site features by simply copying the /sites/default directory to /sites/example2.com Version 4.6 and 4.7: To simplify backups and updates, the best practice (for a single-site install) is to place contributed modules in /sites/default/modules/, contributed or custom themes in /sites/default/themes/, and files in /sites/default/files (or even /sites/files). The /sites/all/ feature was added in Drupal 5.x. It will also work, but be more difficult to update your site, if contributed modules are placed in /drupal/modules, additional themes were placed in /drupal/themes, and files are stored in /drupal/files. If you expect to use multi-sites, then you should make use of /sites/example.com as explained in the "Setup of /sites directory for multi-site." Using /drupal/modules and /drupal/themes will also still work in 5.x, but the best practice above allows easier backup and expansion to multi-site.
Special cases
Various special situations (e.g., installing Drupal behind a firewall, installing Drupal in a subdirectory of the webservers document root) are discussed in this section. Information specific to particular operating systems or database platforms may be found elsewhere.
Compilation failed: this version of PCRE is not compiled with PCRE_UTF8 support
This error occurrs on release 4.6.1 onwards. Note: This issue is fixed by default on all VPS3 and new VPS2 servers, resolve-able on VPS1 and old VPS2 (with some updating).
53
Drupal Handbook
3 Aug 2007
This fix works for Verio VPS2 Servers which are installed with PCRE 6.4 by default (at this time). I see no reason why it should not work for all unix servers (perhaps with directory changes etc). The fix is to uninstall pcre and install the correct version as follows: login as root Type: # pkg_info which will show you the installed packages. type: # pkg_delete pcre-6.4 (assuming you see pcre-6.4 as 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
the
installed
Order deny,allow Deny from all </FilesMatch> Now add this line (RewriteCond %{REQUEST_URI} "!cgi-bin/") to the following:
54
3 Aug 2007
Drupal Handbook
# Rewrite current-style URLs of the form index.php?q=x. RewriteCond RewriteCond RewriteCond RewriteRule %{REQUEST_URI} "!cgi-bin/" %{REQUEST_FILENAME} !-f %{REQUEST_FILENAME} !-d ^(.*)$ index.php?q=$1 [L,QSA]
55
Drupal Handbook
3 Aug 2007
below: RewriteCond RewriteCond RewriteCond RewriteRule %{REQUEST_URI} !^/yourDirectoryName %{REQUEST_FILENAME} !-f %{REQUEST_FILENAME} !-d ^(.*)$ index.php?q=$1 [L,QSA]
It essentially means Apply this rule if the REQUEST_URI doesnt start with /yourDirectoryName and the REQUEST_FILENAME isnt a real file or a real folder. Which is exactly what you want. There is an implied "AND" between the lines of that rule. The ! says "not like this". Special thanks to Mike Smullin for help on this fix.
56
3 Aug 2007
Drupal Handbook
For PHP5: #!/bin/sh CGIFILE="$HOME/[your website directory]/cgi-bin/php.cgi" INIFILE="$HOME/[your website directory]/cgi-bin/php.ini" rsync -a /dh/cgi-system/php5.cgi "$CGIFILE" # REMOVE THE FOLLOWING LINE TO CREATE THE UPDATE-ONLY SCRIPT: cp /etc/php5/cgi/php.ini "$INIFILE" perl -p -i -e s/.*post_max_size.*/post_max_size = 100M/; s/.*upload_max_filesize.*/upload_max_filesize = 100M/; "$INIFILE" A more general script with options (for references purposes only, do not do this): #!/bin/sh test $# = 0 && exit 1 while test "$1";do case $1 in -php5) PHP=php5 ;; -sm) shift; SM=$1 ;; -rg) shift; RG=$1 ;; -pms) shift; PMS=$1 ;; -umfs) shift; UMFS=$1 ;; -mqg) shift; MQG=$1 ;; -met) shift; MET=$1 ;; -mit) shift; MIT=$1 ;; -ml) shift; ML=$1 ;; *) D=$1 ;; esac shift done test "$D" || exit 1 test -d "$HOME/$D" || exit 1 CGI="$HOME/$D/cgi-bin" mkdir -m0755 -p $CGI || exit 2 PHP=${PHP:-php} SM=${SM:-On} RG=${RG:-Off} PMS=${PMS:-8M} UMFS=${UMFS:-7M} MQG=${MQG:-Off} MET=${MET:-30} MIT=${MET:-60} ML=${ML:-8M} CGIFILE="$CGI/$PHP.cgi" INIFILE="$CGI/php.ini"
57
Drupal Handbook
3 Aug 2007
echo "CGI=$CGI MQG=${MQG} UMFS=${UMFS} PMS=${PMS} RG=${RG} SM=${SM} MET=${MET} MIT=${MIT} ML=${ML}" >&2 rsync -au /dh/cgi-system/$PHP.cgi "$CGIFILE" [ -s /etc/$PHP/cgi/php.ini ] && \ sed -e "s/^safe_mode[ ]*=.*/safe_mode = $SM/" \ -e "s/register_globals[ ]*=.*/register_globals = $RG/" \ -e "s/magic_quotes_gpc[ ]*=.*/magic_quotes_gpc = $MQG/" \ -e "s/.*post_max_size.*/post_max_size = $PMS/" \ -e "s/.*upload_max_filesize.*/upload_max_filesize = $UMFS/" \ -e "s/.*max_execution_time.*/max_execution_time = $MET/" \ -e "s/.*max_input_time.*/max_input_time = $MIT/" \ -e "s/.*memory_limit.*/memory_limit= $ML/" \ # REMOVE THE FOLLOWING LINE TO CREATE THE UPDATE-ONLY SCRIPT: /etc/$PHP/cgi/php.ini > "$INIFILE" chmod 0755 "$CGIFILE" chmod 0644 "$INIFILE" [ -s $CGI/.htaccess ] || echo "Options -Indexes" > $CGI/.htaccess touch $HOME/$D/.htaccess if grep -q ^Options $HOME/$D/.htaccess; then grep -q +ExecCGI $HOME/$D/.htaccess || \ sed -i s/^Options\(.*\)/Options\1 +ExecCGI/ $HOME/$D/.htaccess else echo "Options +ExecCGI" >> $HOME/$D/.htaccess fi grep -q ^AddHandler[ ]\+php-cgi[ ]\+.php $HOME/$D/.htaccess || echo "AddHandler php-cgi .php" >> $HOME/$D/.htaccess if grep -q ^Action[ ]\+php-cgi $HOME/$D/.htaccess; then sed -i "s@^Action[ ]\+php-cgi.*@Action php-cgi /cgi-bin/$PHP.cgi@" \ $HOME/$D/.htaccess else echo "Action php-cgi /cgi-bin/$PHP.cgi" >> $HOME/$D/.htaccess fi 3/ Prepare script for execution Execute the following commands into the shell. This will give you permission to execute the php-copy.sh that we just created. chmod +x php-copy.sh This calls our new shell script to copy the php.cgi and php.ini files into our cgi-bin directory. ./php-copy.sh If you get the error message: "bad interpreter: No such file or directory", there is probably an unseen problem with the formatting of the file.
58
3 Aug 2007
Drupal Handbook
Run the following command to convert it to proper Unix format before calling the script again: dos2unix php-copy.sh 4/ Test your new PHP setup Open one of your existing PHP pages in your browser to ensure that your newly-installed local copy of PHP is functioning properly. If there is a problem, go back over the prior steps and use your debugging skills and your mastery of PHP, shell scripts and Linux to get your newly-copied PHP interpreter working! Once everything works properly, go on to the next step. 5/ Create a shell script to make a fresh copy of php (for future use) cp php-copy.sh php-update.sh Open the newly-created php-update.sh script in your favorite text editor and find this line: # REMOVE THE FOLLOWING LINE TO CREATE THE UPDATE-ONLY SCRIPT: Delete that line as well as the line following it. Then save php-update.sh If you got a "bad interpreter: No such file or directory" error message when you executed ./php-copy.sh previously, remember to convert the new file to unix format by running the following command: dos2unix php-update.sh 6/ Set up a cron task to keep php up to date Type: crontab -e And then enter the following in the text editor that shows up (replacing myusername with your specific username): @weekly /home/myusername/php-update.sh This will update the php binary and config file once a week. 7/ Configure your website to use new the php.ini that we just set up Create the file ~/[your website directory]/.htaccess which contains the lines: Options +ExecCGI AddHandler php-cgi .php Action php-cgi /cgi-bin/php.cgi This is telling Apache (the webserver) to use the php.cgi and php.ini that php-update.sh copied into ~/[your website directory]/cgi-bin.
59
Drupal Handbook
3 Aug 2007
60
3 Aug 2007
Drupal Handbook
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.)
61
Drupal Handbook
3 Aug 2007
If you do not have the option to create new database users, use a pre-existing one. Load the Drupal database scheme From the database users overview page click DB WebAdmin The icon is a blue stack with a monkey wrench. Note that this opens phpmyadmin in a pop-up that may be blocked by your browser. First make sure the relevant database is selected. If necessary, click Databases in the phpmyadmin start screen and then the database name. Go to the SQL screen via a small button labelled SQL in the left pane of the phpmyadmin screen. If youve created a new user for the Drupal database, you need to grant priviliges to the user: execute the SQL query: GRANT ALL PRIVILEGES ON databasename.* TO username@localhost IDENTIFIED BY password; where databasename is the name of your database username@localhost is the username of your MySQL account password is the password required for that username This may not complete successfully; in that case youll have to assume / hope the user was created with the necessary privileges. To create the database layout, select the tab database/database.mysql with the database scheme. import files. Upload the file
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 dont have a single code base, only changing the group (chgrp) is enough chgrp drupal -R /var/www/apps/drupal chown drupal -R /var/www/apps/drupal 3) For the virtual hosts, change the group of the sites directory Also all directories under sites should be chmod to 2775: 2 puts all new subfiles created automatically into the group of the folder they are placed in (drupal in our case) + 7 for owner (root or drupal or ftpusername) + 7 for group (drupal) + 5 for guests If you have any more directories under sites, chmod them too chgrp drupal -R /var/www/vhosts/{domain}.{tld}/httpdocs/sites chmod 2775 /var/www/vhosts/{domain}.{tld}/httpdocs/sites chmod 2775 /var/www/vhosts/{domain}.{tld}/httpdocs/sites/default 4) Add the users to the group Plesk has a psaserv group dont worry if you dont have it... The drupal group needs the psaadm and psaftp only if you run plesk vi /etc/group psaserv:x:2523:apache,psaftp,psaadm,drupal
drupal:x:10002:drupal,apache,psaftp,psaadm,{user_of_ftp_account_of_virtual_host}
restart service apache 5) correct the tmp dir by creating a sub directory and putting the drupal group and user on it... mkdir /tmp/drupal chmod 2775 /tmp/drupal chgrp drupal /tmp/drupal ==> in admin change to /tmp/drupal 6) alter the code of file.inc so directories are made using 2775 rather then 775 find: @chmod($directory, 0775); replace: @chmod($directory, 02775); Actually my version of PHP has a bug and doesnt put the 2!!! I have to remember to chmod myself then... 7) change your virtual host settings of httpd.conf In plesk this is done in: /var/www/vhosts/{domain}.{tld}/conf/vhost.conf Other systems might have another place for the conf which is the configuration for your httpd server.. With this code I have made sure that only the drupal directories benefit from group based safe
63
Drupal Handbook
3 Aug 2007
mode (safe_mode_gid)... all other directories still use the default safe mode Remove the second DirectoryMatch in case you want all files and folders to benefit from group based safe mode... As I have a central code base in /var/www/apps/drupal, I need to add this dir to the open basedir... and again only for the drupal directories off course... # # allow all documents below this dir access to drupal core # <DirectoryMatch "^/var/www/vhosts/{domain}.{tld}/httpdocs"> <IfModule sapi_apache2.c> php_admin_flag safe_mode on php_admin_flag safe_mode_gid on php_admin_value open_basedir "/var/www/apps/drupal:/var/www/vhosts/{domain}.{tld}/httpdocs:/tmp" </IfModule> <IfModule mod_php5.c> php_admin_flag safe_mode on php_admin_flag safe_mode_gid on php_admin_value open_basedir "/var/www/apps/drupal:/var/www/vhosts/{domain}.{tld}/httpdocs:/tmp" </IfModule> </DirectoryMatch> # # now limit for all directories below root that are not includes or modules # users want other apps installed too... so no access to drupal # <DirectoryMatch "^(/var/www/vhosts/{domain}.{tld}/httpdocs/)(?!includes/|modules/).*/"> <IfModule sapi_apache2.c> php_admin_flag safe_mode on php_admin_flag safe_mode_gid off php_admin_value open_basedir "/var/www/vhosts/{domain}.{tld}/httpdocs:/tmp" </IfModule> <IfModule mod_php5.c> php_admin_flag safe_mode on php_admin_flag safe_mode_gid off php_admin_value open_basedir "/var/www/vhosts/{domain}.{tld}/httpdocs:/tmp" </IfModule> </DirectoryMatch>
64
3 Aug 2007
Drupal Handbook
65
Drupal Handbook
3 Aug 2007
<P>Body Para 3.</P> <P>Body Para, ad nauseam</P> ; set @curr_date_time = unix_timestamp(); # get current date and time as number of seconds from 01/01/1970. START TRANSACTION; /* Increment node_nid field in sequences. */ update sequences set id = id + 1 where name = node_nid; /* Get new node_nid value from sequences for later */ select @node_value := max(id) from sequences where name = node_nid; /* Increment node_revisions_vid field in sequences. */ update sequences set id = id + 1 where name = node_revisions_vid; /* Get node_revisions_vid value from sequences for later */ select @revisions_value := max(id) from sequences where name = node_revisions_vid; COMMIT; START TRANSACTION; Insert into node (nid, type, title, uid, status, created, changed, comment, promote, moderate, sticky, vid) VALUES (@node_value, story, @title_value, @uid_value, 1, @entry_date_time, @curr_date_time, 2, 1, 0, 0, @revisions_value); Insert into node_comment_statistics (nid, last_comment_timestamp, last_comment_name, last_comment_uid, comment_count) VALUES (@node_value, @curr_date_time, NULL, @uid_value, 0); Insert into node_revisions (nid, vid, uid, title, body, teaser, timestamp, format, log) VALUES (@node_value, @revisions_value, @uid_value, @title_value, @body_value, @teaser_value, @curr_date_time, @format, ""); Insert into history (uid, nid, timestamp) VALUES (@uid_value, @node_value, @curr_date_time); Insert into node_counter (nid, totalcount, daycount, timestamp) VALUES (@node_value, 1, 1, @curr_date_time); COMMIT; set @url_src = concat( "node/", @node_value ) ; Insert into url_alias (src,dst) VALUES (@url_src, @url_dest);
66
3 Aug 2007
Drupal Handbook
# ======== End Set Per Node Vars ========== # ======== Set multiple Terms per Node ========== /* set term_value and insert as many times as you need */ set @term_value = 50; Insert into term_node (nid,tid) VALUES (@node_value, @term_value); set @term_value = 48; Insert into term_node (nid,tid) VALUES (@node_value, @term_value); # ======== End Set multiple Terms per Node ========== # EOF #
DrupalCon site
design contest entry over at the DrupalCon site and become immortal in the Drupal community.
67
Drupal Handbook
3 Aug 2007
); CREATE TABLE cache ( cid varchar(255) NOT NULL default , data longblob, expire int(11) NOT NULL default 0, created int(11) NOT NULL default 0, headers text, PRIMARY KEY (cid), INDEX expire (expire) ); CREATE TABLE watchdog ( wid int(5) NOT NULL auto_increment, uid int(10) NOT NULL default 0, type varchar(16) NOT NULL default , message longtext NOT NULL, severity tinyint(3) unsigned NOT NULL default 0, link varchar(255) NOT NULL default , location varchar(128) NOT NULL default , referer varchar(128) NOT NULL default , hostname varchar(128) NOT NULL default , timestamp int(11) NOT NULL default 0, PRIMARY KEY (wid) ); 3. Make a dump for MySQL 4.0.X mysqldump -u root -p -h localhost --compatible=mysql40 mydatabase > mydatabase.sql 4. Upload this dump to your MySQL 4.0.X server. 5. Refresh your browser a couple of times. Enjoy!
Environment
this is the environment used to setup my drupal hosting linux RHEL 4 plesk 8.0.1 php 4.3.9 mysql 4.1.12 apache 2.0.52
68
3 Aug 2007
Drupal Handbook
drupal 4.7.x
Requirements
keep safe mode on at all times without the need for chmod 777 keep base dir restriction on at all times integrate into plesk so that backup, databases, quotas, etc keeps working drupal must run as managed application updates done once for all vhosts :: use single code base approved modules and themes available for vhosts to select from pre-activate drupal modules that enhance basic content management: SEO, security, ... eaccelerator must speed up php processing efficiently :: use single code base Each individual vhost should be able to use its own themes and modules should be accessible trough different URLs :: drupal multisite option should also be able to use other applications then drupal within the same site should experience drupal no different as if we would install drupal for each vhost seperatly Enhance security if needed on the drupal package Single code base should be included in the normal backup mechanism available in plesk
Next pages
As the book seems to order the sub pages by date, I list here the order of further reading: 1. Solution overview: http://drupal.org/node/90144 2. Prepare environment: http://drupal.org/node/90207
69
Drupal Handbook
3 Aug 2007
Navigation
As the book seems to order the sub pages by date, I list here the order of further reading: Previous: Solution Overview: http://drupal.org/node/90144 Next: Single code base: Comming soon...
70
3 Aug 2007
Drupal Handbook
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 vhosts location. In order to work around these issues, a relaxed form of the file permission checking is also provided by Safe Mode. Using the php.ini directive safe_mode_gid, it is possible to relax the user ID check to a group ID check. That is, if the script has the same group ID as the file on which a file operation was requested, the operation will succeed. If the script owners and the web server are members of the same group, and all hosted files are owned by this group, the file operations will succeed regardless of user ID. Thus, we will create a group "drupal" that will cover all drupal related files accross vhosts and enable the safe_mode_gid. By doing so we will still have a more secure system then when we would disable the safe mode. Information taken from here: http://www.acunetix.com/websitesecurity/php-security-5.htm
Open Basedir
Open Basedir limits the files that can be opened by PHP to the specified directory-tree, including the file itself. This directive is NOT affected by whether Safe Mode is turned On or Off. When a script tries to open a file with, for example, fopen() or gzopen(), the location of the file is checked. When the file is outside the specified directory-tree, PHP will refuse to open it. All symbolic links are resolved, so its not possible to avoid this restriction with a symlink.
71
Drupal Handbook
3 Aug 2007
In Plesk (and most other virtual hosts system) each vhost gets its own open_basedir restriction that restruicts the opening of files to the httpdocs directory and the /tmp directory. As we want a single code base located in a central place, that location will not be accepted trough this restriction. Thus, we will alter the open basedir restriction so that it includes the single code base location. But as we want other applications to be installed within the same vhost, we will add the location only for directories using drupal.
Plesk integration
The plesk control panel works great as long as you keep the directory structure and security as it is provided by plesk. Therefore we need to merge the single code base and each vhost within the provided structure. The single code base will be installed as a normal vhost but limiting web access to the domain. As such a backup of the single code base can be sheduled and FTP can be enable to upload new modules and themes. Each vhost will have his own local "sites" directory and will create its database trough the plesk interface.
Managed application
As the single code base resides as a single vhost, we can upgrade the code, add modules and themes into one location. To make upgrading easier we need to make sure that each vhost that uses drupal, references one single point independend of the drupal version. We will make subdirectories per drupal version in the single code base location and have one single reference that we can switch when going to a new version. Thus their will be a symbolic link called "drupal" pointing towards a drupal version "drupal-4.7.3" and each vhost that uses drupal will have symbolic links pointing towards the "drupal" symbolic link. When we change version, we only need to change the "drupal" symbolic link once and all vhosts will be adjusted accordingly.
eAccelerator
The eAccelerator speeds up the execution of the php script by precompiling them and putting them into memory. The dissadvantage is that you need to have the memory and the more you have the more php files can be kept for fast execution. Therefore we need to limit the number of php files on the server. By using the single code base, every vhosts uses the same files and thus memory usage can be limited and all php scripts run faster.
72
3 Aug 2007
Drupal Handbook
Navigation
As the book seems to order the sub pages by date, I list here the order of further reading: Previous: Requirements: http://drupal.org/node/80472 Next: Prepare environment: http://drupal.org/node/90207
73
Drupal Handbook
3 Aug 2007
5) Edit %your_drupal_files%/sites/default/settings.php and change the base URL to $base_url = http://localhost/drupal; You should still be able to leave the $db_url connection setting alone. 6) Edit %your_xampp_location%\apache\conf\extra\httpd-xampp.conf and add the following lines according to where your copy of drupal lives on your computer: Alias /drupal "%your_drupal_files%/" <directory "%your_drupal_files%"> AllowOverride AuthConfig FileInfo Order allow,deny Allow from all </directory> Youll need that "FileInfo" directive if you are getting 500 errors in your Apache error log like "RewriteEngine not allowed here". You could also add these lines in standard httpd.conf if you are not using XAMPP but just plain Apache. 7) (Skip this step if you are using regular Apache and not XAMPP) Edit %your_xampp_location%\apache\conf\httpd.conf and uncomment out the line LoadModule rewrite_module modules/mod_rewrite.so You need this so Drupal can have "clean links". 8) Edit %your_drupal_files%/.htaccess and change the RewriteBase to /drupal. 9) Restart the Apache service (with the XAMPP control panel if you are using XAMPP) You now should be able to navigate to your sandbox development copy of the site via http://localhost/drupal
74
3 Aug 2007
Drupal Handbook
3.
4. 5. 6.
beta.example.com. 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. Config apaches 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. 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; Its also helpful to override the site name so that the heading on the site glaringly reminds you that youre on the BETA site: $conf = array(site_name => BETA this sites name);
75
Drupal Handbook
3 Aug 2007
Download the newest version of Drupal. Upload this to your hosting space using an FTP Program or CPanels built in File Manager. Using the File Manager, extract the contents of the file: click on the files 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. 2. 3. 4. 5. Open cPanel Go to MySQL Databases Choose a databasename* for the new database and press "Add Database" Choose a username* and password for the new database user and press "Add User" Grant permissions to the user; select the username and database name, check ALL and press Grant permissions
*Note: cPanel usually adds the cPanel username as a prefix to the newly created names. Install Drupal Drupal 5.x now comes with an automated installer. You no longer have to manually load the database tables -- Drupal does it for you. Go to http://www.example.com/install.php Here you will be asked for the database name, database user, and password. If you need to use this database for more than one installation of Drupal (such as with hosting packages with a limited number of MySQL databases), you may want to click on the Advanced options and select a prefix for the tables you will be creating (such as "site_" or "main_"), This will then install Drupal for you, creating and filling all needed tables in your database. Once it is complete, you can go onto your site and set up the first user. Setting up your first user account The first user in your site (often referred to as user/1) is the "super user" on your site. It is automatically granted all admin and view permissions for your site. As such, it is important to immediately register on the site, which creates the first user.
76
3 Aug 2007
Drupal Handbook
After submitting your user name and e-mail, youll be given the option of changing the password for the account from the one the Drupal created for you. Cron tasks Many Drupal modules (such as the search functionality) have periodic tasks that must be triggered by a cron job. To activate these tasks, call the cron page by visiting http://www.example.com/cron.php -- this will pass control to the modules and the modules will decide if and what they must do. To call cron.php periodically you need to setup a cron job. cPanel offers a way to set cronjobs via Server Cron jobs. Carefully read the instructions on the screen; they may differ from the following example. To run cron.php every day set the Minute and Hour fields to 0 and the rest of the fields to *. The command to run is: GET http://www.example.com/cron.php > /dev/null Additional modules Drupal comes with a limited number of modules. To expand the functionality of your Drupal site, youll 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.
77
Drupal Handbook
3 Aug 2007
Note that other files present may be overwritten. Make backups before installing Drupal and remove files that may interfere with installation (e.g. index.php or .htaccess). If the pre-existing .htaccess file is necessary for other parts of your site, merge it with the one provided with Drupal. Upload the Drupal files and folders The first step is to download the drupal distritbution archive "drupal-x.x.x.tar.gz" onto your local computer, and then unpack it using a program such as 7zip, WinZip, WinRAR or tar. The second step is to upload the drupal files to your server. There are three options for uploading the files, two that use cPanels 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 servers document root. Because you need some files from the drupal archive in a later stage, its a good idea to decompress it locally anyway. Create a database This step may not be necessary; some hosting firms provide only one pre-made database. Before you proceed you should know: "username" - the username for connecting to the database "password" - the password for that username "databasename" - the name of the database 1. 2. 3. 4. 5. Open cPanel Go to Server MySQL Databases Choose a databasename* for the new database and press "Add Database" Choose a username* and password for the new database user and press "Add User" Grant permissions to the user; select the username and database name, check ALL and press Grant permissions
78
3 Aug 2007
Drupal Handbook
*Note: cPanel usually adds the cPanel username as a prefix to the newly created names. Create database layout 1. 2. 3. 4. 5. Open phpmyadmin (Server PhpMyadmin) Select the newly created database Depending on the phpmyadmin version select the tab SQL or import Choose the file database/database.mysql and press Go Alternatively copy-paste the contents of database/database.mysql in the query textfield and press Go
Connecting Drupal The default configuration file can be found in sites/default/settings.php. Before you can run Drupal you have to set the database URL and the base URL to the website. $db_url = mysql://username:password@localhost/databasename; Set the $base_url to match your websites URL: $base_url = http://www.example.com; See INSTALL.txt for more information. Modify settings.php locally, then upload the modified file. Alternatively use cPanels text-editor to change the file on the server. Make sure to delete all trailing whitespace from settings.php when using the latter option or you will encounter the infamous headers already sent warnings. Create the first account Point your webbrowser to your site (http://www.example.com/) and follow the instructions on the welcome screen. Cron tasks Many Drupal modules (such as the search functionality) have periodic tasks that must be triggered by a cron job. To activate these tasks, call the cron page by visiting http://www.example.com/cron.php -- this will pass control to the modules and the modules will decide if and what they must do. To call cron.php periodically you need to setup a cron job. cPanel offers a way to set cronjobs via Server Cron jobs. Carefully read the instructions on the screen; they may differ from the following example. To run cron.php every day set the Minute and Hour fields to 0 and the rest of the fields to *. The command to run is: GET http://www.example.com/cron.php > /dev/null
79
Drupal Handbook
3 Aug 2007
80
3 Aug 2007
Drupal Handbook
7. Check the Structure and Data boxes 8. (this ensures that both the structure of the database and the tables, and the content you have on site - is with you!) Check drop table (so that if the new site is installed already, you can install database on top of that. "drop table" simply ensures that if the table exists - it will be replaced by the one you backed up.)
Check complete inserts ( to make sure it does not miss anything when rebuilding the site )
Check Send box (this makes the data go to a file instead of the screen)
You can modify the File Name if you wish. (dont 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. Importing: (with phpMyAdmin) 1. Find NEW database with phpMyAdmin 2. 3. Click the tab SQL (just like when you are adding a module) 4. 5. Go to the Or Location of the text file: (just like you would for adding a module) 6. 7. Browse to local hard drive and find file. 8. 9. Click GO
81
Drupal Handbook
3 Aug 2007
10. 11. Its going to take a few minutes for everything to come over. Final process: 1. Check new site and I do mean check everything, until youre bored 2. 3. Since I usually do this stuff at night. I check everything that night and then I check once more in the morning. !Checking data is a lot faster than repairing or re-entering data :-) 4. 5. Turn Clean URLs back on Problems you might encounter with phpMyAdmin 1. phpMyAdmin has some limitations on the size of file that can be transferred. My Host has it set to 10Mb, others might be lower or higher limits. If file is bigger than limits you have to make some choices. 2. You can save the file as compressed (but you might time out on the upload) 3. You can Empty (NOT DROP) a few of tables. Below are some the tables you might want to think about cleaning up before you make data dump. (Not in any order.) a. Aggregator Items (the data from news feeds) b. Accesslog c. Cache d. Watchdog e. Search_Index with FTP (still working on this section) NOTES: 1. If you run cron make sure to change this also in /scripts/cron-lynx.sh - so it points to cron at new site.
82
3 Aug 2007
Drupal Handbook
Staggered import of large and very large MySQL Dumps (like phpMyAdmin 2.x Dumps) even through the web-servers with hard runtime limit and those in safe mode. The script executes only a small part of the huge dump and restarts itself. The next session starts where the last was stopped.
Setting up BigDump
Download BigDump from http://www.ozerov.de/bigdump.php. Once downloaded you need to open the file bigdump.php in any simple text editor (or php editor) to modify the variables required for your server and database. Commencing at line 78 with "// Database configuration" you need to setup the usual variables to connect to your database (same as are required for Drupal). There is one extra piece of information which the script needs to work well and that is the name of the sql file to be used to setup the database. Tip: Make sure you upload the file containing the SQL export of your database and bigdump.php to the same directory (root is best) on your webserver. <?php // Database configuration $db_server = "localhost"; $db_name = "your_DB_name"; $db_username = "your_DB_user_name"; $db_password = "your_DB_password"; // Other Settings // Specify the dump filename to suppress the file selection dialog $filename = "the_file_you_wish_to_execute"; // Lines to be executed per one import session $linespersession = 3000; // You can specify a sleep time in milliseconds after each session // Works only if JavaScript is activated. Use to reduce server overrun $delaypersession = 0; ?> Save the file once you have set the above (best in the same folder as your sql file backup).
83
Drupal Handbook
3 Aug 2007
Running BigDump
Once the files are uploaded you simply need to connect to the bigdump.php script by using the URL http://www.your_domain.com/bigdump.php If successfully connected bigdump will greet you with a screen like the below. BigDump: Staggered MySQL Dump Importer ver. 0.21b <a>Start Import</a> from "the_file_you_wish_to_execute.sql" "your_DB_name" at "localhost" 2003-2005 Alexey Ozerov - BigDump Home into
If it all looks good (ie: all the relavent names are correct) then click "Start Import" and the database will be setup by running in short automated stages to prevent server timeouts. At the completion BigDump will notify you that it is finished. Thats it! You have now copied, moved, migrated, synchronized or duplicated your mySQL database. Well Done! Thanks go to markus_petrux for the original tip about BigDump
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 Bs 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
86
3 Aug 2007
Drupal Handbook
You might need to modify the .htaccess file as well. Update Cron If you set up Cron on your old installation, make sure you update it to point to your new installation. Delete Old Directory Test that everything is working in your new installation. If so, it is now safe to delete the files in your old Drupal directory.
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......
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.
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.
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.
Installing XAMPP in Debian Download XAMPP Latest version from the following link
http://sourceforge.net/project/showfiles.php?group_id=61776&package_id=6... At the time of writing this article XAMPP version is 1.5.3a #wget http://kent.dl.sourceforge.net/sourceforge/xampp/xampp-linux-1.5.3a.tar.... Now you should be having xampp-linux-1.5.3a.tar.gz file in your downloaded location Go to a Linux shell and login as root: $su Extract the downloaded archive file to /opt #tar xvfz xampp-linux-1.5.3a.tar.gz -C /opt XAMPP is now installed below the /opt/lampp directory.
91
Drupal Handbook
3 Aug 2007
OK, that was easy but how can you check that everything really works? Just type in the following URL at your favourite web browser: http://localhost XAMPP Security Configuration As mentioned before, XAMPP is not meant for production use but only for developers in a development environment. The way XAMPP is configured is to be open as possible and allowing the developer anything he/she wants. For development environments this is great but in a production environment it could be fatal. Here a list of missing security in XAMPP: The MySQL administrator (root) has no password. The MySQL daemon is accessible via network. ProFTPD uses the password "lampp" for user "nobody". PhpMyAdmin is accessible via network. Examples are accessible via network. MySQL and Apache running under the same user (nobody). To fix most of the security weaknesses simply call the following command: #/opt/lampp/lampp security It starts a small security check and makes your XAMPP installation more secure. Start And Stop Server Services start Starts XAMPP. stop Stops XAMPP. restart Stops and starts XAMPP. startapache
92
3 Aug 2007
Drupal Handbook
Starts only the Apache. startssl Starts the Apache SSL support. This command activates the SSL support permanently, e.g. if you restarts XAMPP in the future SSL will stay activated. startmysql Starts only the MySQL database. startftp Starts the ProFTPD server. Via FTP you can upload files for your web server (user "nobody", password "lampp"). This command activates the ProFTPD permanently, e.g. if you restarts XAMPP in the future FTP will stay activated. stopapache Stops the Apache. stopssl Stops the Apache SSL support. This command deactivates the SSL support permanently, e.g. if you restarts XAMPP in the future SSL will stay deactivated. stopmysql Stops the MySQL database. stopftp Stops the ProFTPD server. This command deactivates the ProFTPD permanently, e.g. if you restarts XAMPP in the future FTP will stay deactivated. security Starts a small security check programm. For example: To start Apache with SSL support simply type in the following command (as root): #/opt/lampp/lampp startssl You can also access your Apache server via SSL under https://localhost. Important Configuration Files And Directories opt/lampp/bin/ - The XAMPP commands home. /opt/lampp/bin/mysql calls for example the MySQL monitor.
93
Drupal Handbook
3 Aug 2007
/opt/lampp/htdocs/ - The Apache DocumentRoot directory. /opt/lampp/etc/httpd.conf - The Apache configuration file. /opt/lampp/etc/my.cnf - The MySQL configuration file. /opt/lampp/etc/php.ini - The PHP configuration file. /opt/lampp/etc/proftpd.conf - The ProFTPD configuration file. (since 0.9.5) /opt/lampp/phpmyadmin/config.inc.php - The phpMyAdmin configuration file. If you want to confiure apache2 you have to use /opt/lampp/etc/httpd.conf(If you want to change Apache DocumentRoot directory you can chage in this file).If you want to configure namebased and ip based virtual hosts check here If you want to configure proftpd check here If you want to configure mysql check here Stopping XAMPP To stop XAMPP simply call this command: #/opt/lampp/lampp stop You should now see: Stopping LAMPP 1.5.3a... LAMPP: Stopping Apache... LAMPP: Stopping MySQL... LAMPP: Stopping ProFTPD... LAMPP stopped. And XAMPP for Linux is stopped. Uninstall XAMPP From your Machine To uninstall XAMPP just type in this command #rm -rf /opt/lampp
Windows-specific guidelines
Several packages exist which install Apache, PHP, and MySQL in one easy download. These include the following:
94
3 Aug 2007
Drupal Handbook
ApacheFriends XAMPP Miniserver Foxserv PHPHome If you want to install them separately, see the guidelines below.
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).
96
3 Aug 2007
Drupal Handbook
Best of all, however, apache2triad requires no additional configuration in order to set up and install Drupal, making it an ideal choice for novice web site creators wishing to learn to set up and use a Drupal site with only very modest skills and almost no previous experience. Tools needed to complete this tutorial: A web browser. An archive program capable of extracting .tar and .gz files, such as 7-Zip. An FTP client like coreFTP (optional).
Installing Apache2Triad
1) Download the version of Apache2Triad that best suits your needs. 2) Double-click the icon from the file you downloaded. This opens a small configuration window to begin the Apache2Triad installation. Leave the default settings as they are and click the button labeled "next". 3) The next dialog window allows you to set the destination folder, which for most people will be "C:\apache2triad", but it works equally well installed wherever you like (provided there is room available, see space requirements above). It is recommended that Apache2Triad be installed at the "root level" of the drive chosen, for example, "C:\apache2triad" as opposed to "C:\Program Files\apache2triad\", as this will save you typing later on. 4) The next dialog asks you to set a password of no less than eight characters. It will be important to know this password as you will need it later on. Select an eight character password (ideally one easily remembered), write it down, then click the button labeled "next", then the button labeled "I Agree" on the following dialog to complete the license agreement and begin the installation. 5) After the files have been installed to the directory of your choice, a dialog will open that alerts you that post configuration is needed. Click the button labeled "OK" to continue. Several
97
Drupal Handbook
3 Aug 2007
windows will open and close as the installer automatically configures most options for you, eventually stopping at a CMD window asking you to type your password from step 4. Do so now and press the "enter" key; post-configuration will complete itself, and at last open a window requesting that you reboot, which is necessary to start apache, php and mysql as Windows services. Note that depending on how Windows is configured for your computer, you may notice that there is now a "user" account named apache2triad; ignore this and log on with your regular account.
Installing Drupal
1) Obtain a copy of Drupal 4.6x, 4.7.x or 5.0 (cvs) from drupal.org as well as any contributed modules or themes you wish to use. 2) Use your archive program to extract any files from step 1; note that because the files are stored in both .gz and .tar formats, it may be necessary to extract them twice. You may wish to create a directory named DrupalX, where X is the version of Drupal, and unarchive your files to this location in order to stay organized; by copying the files you wish to use instead of using the originals, it is safe to move the archived versions to the recycle bin if you like. 3) Browse to the location you installed Apache2Triad and open its 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 (well 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 youll 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. Dont 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 files 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 youve 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.
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).
101
Drupal Handbook
3 Aug 2007
102
3 Aug 2007
Drupal Handbook
1. Download the Apache Windows MSI Installer from Apache.org 2. Download the PHP Windows Zip Package from PHP.net. The first step to getting Drupal running on your Windows machine is to set up the Apache web server by running the Apache MSI installer. The following steps will walk you through the installation: 1. 2. 3. 4. 5. 6. Select Next Select "I accept the terms in the license agreement" Select Next 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. Select the Typical Setup 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. Select Finish If a Firewall is enabled, make sure that port 80 is unblocked and open. 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!"
7. 8. 9.
Configuring Apache: 1. Using a text editor such as Notepad, open the httpd.conf file. This file is found in the /conf sub-directory under the directory that was set up during installation. Alternatively, a shortcut may be found in the start menu under the Apache HTTP Server folder. 2. Note: Windows based systems uses backslashes \ and Unix based systems use slashes / for paths. In the Apache configuration files, slashes / should be used in path names. 3. Change the DocumentRoot to point to the location of the root document folder. In the default httpd.conf file, this is found on line 149 and if the defaults were used during the installation, it would point to "C:/Program Files/Apache Software Foundation/Apache2.2/htdocs". Note: Wrapping the path name in quotes will escape out any spaces that are used. 4. Change the Directory path to match the one used in the previous step. This is found on line 177 of the default httpd.conf file. 5. Add to index.php to the DirectoryIndex. This is found on line 212 of the default httpd.conf file. 6. Append the following lines to the end of the httpd.conf file: LoadModule php5_module "c:/php/php5apache2_2.dll" AddType application/x-httpd-php .php PHPIniDir "C:/php" 7. Save and Close
103
Drupal Handbook
3 Aug 2007
Installing PHP: 1. Unzip the PHP files to C:\php 2. Copy c:\php\php-ini-recommended.ini and rename itc:\php\php.ini 3. Uncomment the Windows include_path on line 506 Note: In the PHP.ini file, semicolons are used to denote that something is commented out. To uncomment a line, simply remove the semicolon. 4. Update the doc_rootto match the one that was set up in the httpd.conf file on line 513. Note: The PHP INI files uses the Windows style backslash \ for path names. 5. Update the extension_diron line 520 to "C:\php\ext" 6. Uncomment php_gd2.dll extension on line 637. 7. Uncomment mysql.dll extension on line 651. 8. Update the sessions.save_pathto the Windows temporary files directory (i.e. C:\Temp). 9. The PHP directory needs to be added to the Path Environment Variables 1. Open the Control Panel 2. Open System > Advanced > Environment Variables 3. Append ;C:\php to the end of the Path System Variables list and Click OK. 10. Restart Apache 11. To test PHP on Apache, go to the root directory (i.e. C:\Program Files\Apache Software Foundation\Apache2.2#92;htdocs) and create a new php file in it. In this file, use PHPs phpinfo() function to see the servers configuration information. For example: <html> <body> <?php phpinfo() ?> </body> </html> Open this file in a browser (i.e. http:\\localhost\filename.htm). Alternative Options: Bundled Packages Apache2Triad Apache Friends - XAMPP
104
3 Aug 2007
Drupal Handbook
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 GUIs Go ahead and create your database tables via phpPgSQL or via the command line as described here.
Running multiple sites on a local PC (localhost) from a single codebase, using Windows
Heres how to get mutltiple sites working on localhost using Windows XP. This should work with Drupal 4.6.x and assumes that you have PHP, Apache, MySQL, phpMyAdmin and Drupal all installed and working. There are four stages to go through, but its not difficult: 1. Set up your databases, one for each website 2. Set up each website in Drupal 3. Edit the virtual host settings in Apache 4. Update the Windows hosts file
106
3 Aug 2007
Drupal Handbook
In the following example we will add a local site"http://testsite1" in addition to the default site. Well assume Drupal is installed in c:/www (and that your web root is set to c:/www in the apache confic file). Databases ========= Firstly we will set up a new database for testsite1 1. Open your phpMyAdmin page 2. Type a name for your database in the create database textbox (testsite1 is as good as anything) then click the create button. You should get a message to say your database is created. 3. Next we need to add the necessary tables. Click the sql tab, then use the browse option to navigate to the includes folder of your Drupal installation, e.g. c:/www/drupal-4.6.3/includes. Select the file database.mysql.inc then go. 4. phpMyAdmin will run the script and install the necessary tables. Drupal ====== 1. Make a copy of the folder /sites/default and call it /sites/testsite1. i.e. you should now have two folders in your sites folder, default and testsite1. 2. Open file sites/testsite1/settings.php using notepad. Edit the $db_url line to match the database defined in the previous steps: $db_url = "mysql://username:password@localhost/database"; where username, password, localhost and database are the username, password, host and database name for your set up. 3. Set $base_url to match the address to your Drupal site: $base_url = "http://testsite1"; 4. Save the file. Apache ====== 1. Open the apache config file http.conf (its in the apache/conf folder in Apache 1. I think it has moved somewhere else in Apache2) 2. Scroll to the end of the file, where you will find the virtual hosting setup. Assuming your websites are all located in the folder c:/www then add the following lines (edit the paths as necessary)
107
Drupal Handbook
3 Aug 2007
NameVirtualHost 127.0.0.1:80 <VirtualHost 127.0.0.1:80> DocumentRoot "C:/www/" ServerName localhost </VirtualHost> <VirtualHost testsite1> DocumentRoot "C:/www/Drupal-4.6.3" ServerName testsite1 </VirtualHost> There are lots of other things you can add into your VHost settings - see the Apache documentation. Windows ======= We now need to tell Windows that the domain testsite1 is hosted locally, i.e. not to look on the Internet for it. Open the hosts file with notepad. It can usually be found in c:/windows/system32/drivers/etc Edit the end of the file to read: 127.0.0.1 localhost 127.0.0.1 testsite1 Save the file. Apache, again ========= OK, thats (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
109
Drupal Handbook
3 Aug 2007
in postgresql.conf, which may not be a good solution for security concerned people, or enable unix domain sockets: $db_url = "pgsql://admin:password@unix(/tmp)/drupal" /tmp works on a slackware 9.0 Linux 2.4.21, no commas needed.
110
3 Aug 2007
Drupal Handbook
psql expects -U instead of -u. Use -f to load the file. 1) Create a new database user (I used "drupal"). As the postgres user: postgres$ createuser --pwprompt Enter name of user to add: drupal Enter password for new user: Enter it again: Shall the new user be allowed to create databases? (y/n) n Shall the new user be allowed to create more new users? (y/n) n 2) Create the new drupal database owned by the user created in 1) above As the postgres user: postgres$ createdb -O drupal drupal 3) Add the plpgsql language to the database As the postgres user: postgres$ createlang plpgsql drupal 4) Finally, read in the supplied database.pgsql file. As root postgres user: postgres$ psql -U drupal -d drupal -f database/database.pgsql 5) Set $db_url as mentioned in above documentation.
111
Drupal Handbook
3 Aug 2007
such as tar.gz. On Windows, use a program like WinZip to extract it. On the Mac, you can use Stuffit Expander. To extract the file using the Unix command line: tar -zxvf modulename-drupalversionnumber.tar.gz You should see a list of files extracted into a folder. 3. Upload the folder. FTP your files to the desired modules folder in your Drupal installation. Since the /modules/ folder is typically reserved for Drupal core modules, as of version 5.x you should create a sites/all/modules/ directory and put uploaded modules there. This will also make it easier to update your Drupal site later on. For version 4.7 and below, put contributed modules into /sites/example.com/modules/ (multi-site setup) or /sites/default/modules/ (single site setup) 4. Read the directions. If the module has an installation file (usually INSTALL.txt and/or README.txt), read it for specific instructions. There are modules that require special treatment, and even modules that depend on other downloaded files to function properly. Sometimes the readme filename has no .txt extension. When you try to double-click on it, your computer doesnt know what program to use. In that case, open Notepad (or your favorite text editor) first, and then open the file using Notepads 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 youre upgrading an existing module youll 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 doesnt have one, look for modulename.mysql and/or modulename.pgsql. If you see those, the module isnt 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 doesnt 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 hasnt 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 havent 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
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 youd rather have all you terms underlined (only with a broken line), then choose "replace with acronym link" in the Term Indicator box. When you are finished with all of your choices, click on save configuration Glossary Administration: Finally, Choose which type of user(s) that you want to be able to administer the glossary, such as all "authenticated users" or only members in a "specific user role", or just the "administrator(s)". To make this choice, go to "Administer>Access Control>Permissions. Scroll down to "glossary module" and enable your chosen user role(s). Your Glossary Module should be working now. Go back to "Administer>Categories>Vocabularies" to enter your glossary/vocabulary terms. I would suggest that you keep your terms down to one brief paragraph. This paragraph will display all through the website whenever a users mouse pointer "hovers" over the indicated word; it will only display for about 6 seconds. Keep your paragraph down to about 6 seconds of comfortable reading. (Yes, a user can go back to the indicated word and get the definition to pop up again, but why should they have to? You can put more detailed definitions or explanations on other page(s), which can be connected to any glossary/vocabulary term(s).)
115
Drupal Handbook
3 Aug 2007
116
3 Aug 2007
Drupal Handbook
http://drupal.org/project/locale - provides multiple translations of strings generated by drupal - now part of the core code of drupal, critical if you want the site in something other than english http://drupal.org/project/i18n - provides a mechnanism to define multiple a single piece of content in multiple languages. - requires locale module - only use this if you want your site in English AND french http://drupal.org/node/12875 - translation module which allows for people to switch between node content in other languages - must require locale and i18n module - designed to make it easier to produce sites in both english AND french Module Comparisons - http://drupal.org/project/scheduler vs http://drupal.org/project/event (applied to nodes) - http://drupal.org/node/19813 vs taxonomy
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 hasnt 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 havent 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
Here are some useful links: Search results 4.6 Multi-Site from single code base Multi-Site .htaccess configuration multi-site, single installation, shared db, single sign on. is this possible? Automatic Multi-site registration Using Multi-Site Multihosting Off Single Codebase Multisite and symlinks doesnt work Sharing tables between installations
119
Drupal Handbook
3 Aug 2007
[/var/www]# mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html Clean-up: [/var/www]# rm drupal-x.x.tar.gz [/var/www]# rm drupal-5.1 Create the files directory per Drupal instructions and change permissions (will change permission again after install): [/var/www]# cd html [/var/www/html]# mkdir files [/var/www/html]# chmod 777 files Make directories that will hold custom and contributes modules and themes: [/var/www/html]# cd sites/all [/var/www/html/sites/all]# mkdir modules [/var/www/html/sites/all]# mkdir themes [/var/www/html/sites/all]# cd modules [/var/www/html/sites/all/modules]# mkdir custom [/var/www/html/sites/all/modules]# mkdir contrib [/var/www/html/sites/all/modules]# cd ../ [/var/www/html/sites/all]# cd themes [/var/www/html/sites/all/themes]# mkdir custom [/var/www/html/sites/all/themes]# mkdir contrib Create directory "www.mydomain.tld": [/var/www/html/sites/all/themes]# cd ../ [/var/www/html/sites/all]# cd ../ [/var/www/html/sites]# mkdir www.mydomain.com Change permission of "settings.php" per Drupal instructions and copy "settings.php" in default to www.mydomain.tld: [/var/www/html/sites]# cd default [/var/www/html/sites/default]# chmod 777 settings.php [/var/www/html/sites/default]# cd ../ [/var/www/html/sites]# cp -rp sites/default sites/www.mydomain.tld Create database and user with permissions: [/var/www/html/sites]# mysql mysql> CREATE DATABASE wwwmydomaintld_drupal; mysql> GRANT ALL PRIVILEGES ON wwwmydomaintld_drupal.* TO wwwmydomaintld_myusername@localhost IDENTIFIED BY mypassword;
120
3 Aug 2007
Drupal Handbook
mysql> \q Go back to PuTTY to chmod on settings.php in www.mydomain.tld: [/var/www/html/sites]# cd www.mydomain.tld [/var/www/html/sites/www.mydomain.tld]# chmod 755 settings.php [/var/www/html/sites/www.mydomain.tld]# logout What next?: Make changes to "settings.php" in www.mydomain.tld? Ive read that its not necessary to make changes to setting.php. Make changes to "httpd.conf" in /usr/local/apache/conf? Ive been using WHM to create accounts, putting Drupal in public_html and having no problems. But when it comes to parting from the WHM abstraction and getting multisite set-up correctly this is the end of the proverbial road for me. Could use help...: 1. Help making improvements to steps articulated above 2. Help with next steps so that I/we can get on to grander things, like creating modules, custom themes, profiles, (and maybe - just maybe - spend some time working on business strategy :-)
Drupal as a library
Short introduction on how to share drupal with all users on a shared server (without having troubles with file-permissions). Note: it is still possible to use the Multisite option of drupal.
121
Drupal Handbook
3 Aug 2007
example servers file-structure: /path/to/phplibraries/drupal (chmod 644) /home/ user1/ (example.com) lib (symbolic link => /path/to/phplibraries/) public_html/ main/ files/ includes (symbolic link => /home/user1/lib/drupal/includes) misc (symbolic link => /home/user1/lib/drupal/misc) modules (symbolic link => /home/user1/lib/drupal/modules) profiles (symbolic link => /home/user1/lib/drupal/profiles) sites/ all (symbolic link => /home/user1/lib/drupal/sites/all) default (symbolic link => /home/user1/lib/drupal/sites/default) example.com/ settings.php themes (symbolic link => /home/user1/lib/drupal/themes) .htaccess (copy from drupal/.htaccess) cron.php (copy from drupal/cron.php) index.php (copy from drupal/index.php) install.php (copy from drupal/install.php) robots.txt (copy from drupal/robots.txt) update.php (copy from drupal/update.php) xmlrpc.php (copy from drupal/xmlrpc.php) .htaccess (1) user2/ (example2.com) (same as user1) user3/ (example3.com) (same as user1) etc... .htaccess (1) this isnt 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
This will create a symlink, allowing your subdomain to work properly. 9. Go to your subdomain. Drupal will install the tables necessary to run the new site. 10. Youre all set to use the new site. If you run into any problems, or have questions, use the contact form attached to my user account here to contact me.
123
Drupal Handbook
3 Aug 2007
124
3 Aug 2007
Drupal Handbook
have trouble editing these files, but thats the point. Its easier to change permissions temporarily on a file you want to hack than it is to fix a break-in. chown -R siteX:siteX . chmod -R 444 *.php *.gif *.jpg *.css *.tar *.module
SQL Setup
There are two ways to do this: on the command line and via a control panel. Some control panels (Ensim, for example) require that you create new databases through their interface (so they can limit a site to a set number of databases). If you can create new databases through the command line, do it like in the install file mysqladmin -u user -p create Name mysql -u user -p GRANT ALL PRIVILEGES ON Name.* password; flush privileges;
TO
user@localhost
IDENTIFIED
BY
I substituted Name for drupal in the instructions -- really, name your database something other than drupal. Helps to prevent hacking if the attacker isnt intimately familiar with the site configuration. Even if you call it mysite_drupal, thats something. I also have no idea why the installation instructions suggest permissions for nobody, so I changed that to the database user. If you dont 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 doesnt, 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 doesnt mean you have to fill it that way. You can now return to the command line and setup the database structure. mysql -u user -p Name < database/database.mysql chmod 000 database/database.* Technically, youre done after the first line, but I like to lock up all setup files once Im 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
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 doesnt 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.
127
Drupal Handbook
3 Aug 2007
1. Prepare database and database user 1.1. create a database and user
In this example, I will use: DB name: drupal_db DB username: druser Password: twosites Access right: SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES
128
3 Aug 2007
Drupal Handbook
sequences => shared_, profile_fields => shared_, profile_values => shared_, users_roles => shared_, ); the second line that goes: default => site_1_, this means tables that are not shared with other sites will have a prefix site_1_. So for example, table name node will be site_1_node. Now, when you finish editing this file, open and edit drupal/sites/www.example.com.site_2/settings.php. This time, you enter the exact same information for the database connection. So the line around 93 should look like: $db_url = mysql://druser:twosites@localhost/drupal_db; Then, you add an array of prefixes, which will look like: $db_prefix = array( default => site_2_, users => shared_, sessions => shared_, role => shared_, authmap => shared_, sequences => shared_, profile_fields => shared_, profile_values => shared_, users_roles => shared_, ); notice a prefix in the second line is now site_2_. At the installation, all tables will have this prefix except for the ones that are specifically given a prefix shared_.
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.
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.
131
Drupal Handbook
3 Aug 2007
->
If your installation isnt 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 PHPs session.cookie_domain correctly. In the case above, set it to ".example.com". You can do this through Drupals .htaccess file.
132
3 Aug 2007
Drupal Handbook
database.mysql For this example, we will assume the following: www.example.com: the MAIN site, where the codebase has already been uploaded, and settings.php has been properly configured. sub1.example.com; www.example.com/sub2; www.subexample.com : the other sites we will create. 1. Create the following folders in your sites directory: sites/sub1.example.com/ sites/www.example.com.sub2/ sites/www.sub3example.com/ Copy the settings.php file from sites/default into each of the above folders. 2. There are different database files (inside the database folder). Select the one that is appropriate for your database version. Copy it to each of the folders you made in step 1. This is OPTIONAL, but it will help you keep things straight. 3. Decide on SEPARATE PREFIXES for each site. Below is what we will use for the example: site database prefix sub1.example.com sub1_ www.example.com,sub2 sub2_ www.sub3example.com sub3_ 4. Configure your settings.php for each site. This code MUST BE CHANGED FOR EACH SITE: $db_url = mysql://username:password@localhost/databasename; Note; if you are using the same database as the MAIN site, the $db_url is the same.
133
Drupal Handbook
3 Aug 2007
OPTIONAL: # $base_url = http://www.example.com; // NO trailing slash! # # # # # $conf = array( site_name => My Drupal site, theme_default => pushbutton, anonymous => Visitor );
For sub1.example.com, the settings would be: $db_prefix = sub1_; $base_url = http://sub1.example.com; $conf = array( site_name => My SUB1 Drupal Site, theme_default => pushbutton, anonymous => Visitor ); For www.example.com/sub2, the settings would be: $db_prefix = sub2_; $base_url = http://www.example.com/sub2; $conf = array( site_name => My SUB2 Drupal Site, theme_default => fancy, anonymous => Anonymous ); For www.sub3example.com, the settings would be: $db_prefix = sub3_; $base_url = http://www.sub3example.com; $conf = array( site_name => My SUB3 Drupal Site, theme_default => marvin, anonymous => Guests ); 6. Upload the modified settings.php files in their respective folders. 7. Open the database file you copied into each sites folder. Find the following (dont 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!
/drupal/sites/default /files (used when there is no /sites/example.com directory) settings.php /files /module /themes /tmp settings.php /files /module /themes /tmp settings.php
/drupal/sites/example1.com
/drupal/sites/example2.com
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. Its possible to do this with an existing web site, but moving file uploads around can cause a lot of confusion if there are already URLs pointing to the old locations. Domain specific modules and themes should also be placed in /sites/example.com/modules and /sites/example.com/themes respectively. Contributed modules and additional themes which are for use by all domains in a multi-site installation should be placed in /sites/all/modules and /sites/all/themes. Note that there shouldnt 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 doesnt exist for a domain. In addition to multiple sites, such as www.example1.com and www.example2.com, sub domains are also easily set up. Adding sub3.example2.com and sub3.example2.com/site4, the directory structure for these four sites would be: /drupal/sites/all/modules /drupal/sites/all/themes /drupal/sites/default/files /drupal/sites/default/settings.php /drupal/sites/example1.com/files /drupal/sites/example1.com/modules /drupal/sites/example1.com/settings.php /drupal/sites/example1.com/themes /drupal/sites/example1.com/tmp /drupal/sites/example2.com/files /drupal/sites/example2.com/modules /drupal/sites/example2.com/themes /drupal/sites/example2.com/tmp /drupal/sites/example2.com/settings.php /drupal/sites/sub3.example2.com/files /drupal/sites/sub3.example2.com/modules /drupal/sites/sub3.example2.com/settings.php /drupal/sites/sub3.example2.com/themes /drupal/sites/sub3.example2.com/tmp /drupal/sites/sub3.example2.com.site4/files /drupal/sites/sub3.example2.com.site4/modules /drupal/sites/sub3.example2.com.site4/settings.php /drupal/sites/sub3.example2.com.site4/themes /drupal/sites/sub3.example2.com.site4/tmp
136
3 Aug 2007
Drupal Handbook
Once youve done this, the file structure of your site will be cleanly organized: The main Drupal directory will contain only the standard core files. All of your custom themes, add-ons, settings, and so on will be in /sites/example.com, /sites/all, or /sites/default. /sites/default/settings.php and /files will be used if there is no /sites/example.com directory. /sites/all/modules and /themes will be available to all sites. Backing up the /sites directory and your Drupal database will give you everything you need to restore the site in the event of a crash, or to move to a new server. Adding a domain is easy: just copy the /sites/default directory to /sites/example5.com Symbolic links can be used for several purposes: Even if using default settings, a good option is to use links from /sites/example.com directory to point to the /sites/default directory. That way, if the settings and /files are ever changed from the default and actually placed in /sites/example.com, their location does not move and no links are broken. Links could also be used to point the /sites/default directory to your primary site. A /files directory could easily be shared across two domains without being shared across the remaining domains. A non-domain-name path for /files can be setup. If it is possible that the domain name might change (say, from a development name), then you can set up a link from /drupal/sites/moniker to /drupal/sites/example.com, where moniker is a short version of the site name that will remain constant even if /example.com changes. Although the /sites/default directory could contain a /modules and /themes directory, these elements should usually be placed in /sites/all or /sites/example.com. Similarly, although contributed modules could be placed in /drupal/modules as was the practice in version 4.7, this is not recommended. Multi-site directory setup for sub-domains, including non-standard ports, is described in the installation instructions (INSTALL.txt). See multidomain for a contributed module that allows spanning one site across multiple domains, so that specific content types appear on specific domains or sub-domains. Version 4.6 and 4.7: Best practice for multi-site set-up under version 4.6 and 4.7 is similar to 5.x. The primary difference is that there is no /sites/all directory. Instead, /modules and /themes that are available for all domains are kept in /drupal/modules and /drupal/themes.
137
Drupal Handbook
3 Aug 2007
There are several themes which you can download from the Drupal web site which should get you started. Installing a new theme is very straightforward: 1. Download a new theme package. Note that themes for different Drupal versions are not compatible, version 4.4 themes do not work with Drupal 4.5 and reverse. 2. Read any README or INSTALL files in the package to find out if there are any special steps needed for this theme. 3. Check to see if you have the required theme engine to be able to display your theme. Theme engine files go in a folder in themes/engines in your Drupal directory. 4. Upload the contents of the theme package to a new directory in the themes directory in your Drupal site. For example; in 4.7 you place your theme in themes/box_grey. in 5.0 you place your themes in /sites/all/themes/box_grey 5. Click administer themes and enable the new theme (Drupal will auto-detect its presence). 6. Edit your user preferences and select the new theme. If you want it to be the default theme for all users, check the default box in the themes administration page. Note: You can see a variety of themes on themes.drupal.org. Some of these themes shown there are available for download from Drupal.org and others are merely samples.
138
3 Aug 2007
Drupal Handbook
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. Youll always be able to come back and experiment with them later. The one possible exception to this is the "file system settings" which you may wish to set now. For more information on the "File system settings," click its link below. This link can also help you resolve issues with errors that often appear at the top of the "settings" page after Drupal is freshly installed. You can configure your sites basic settings at administer >> settings.
139
Drupal Handbook
3 Aug 2007
General settings
The General settings area is where you configure some basic information for your site. Name: this is where you set the name displayed for your site. E-mail address: A valid e-mail address for this website, used by the auto-mailer during registration, new password requests, notifications, etc. You can set this to a real email address that people can reply to or to something generic no-reply@example.com that is outbound only. The email server that your site uses is set in the php.ini file and not by Drupal. Slogan: The slogan of this website. Some themes display a slogan when available. It will also by displayed in the title bar of your sites visitor web browser. Mission: Your sites mission statement or focus. Your mission statement is enabled in your theme settings and requires that the theme support its 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".
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 users see when they visit http://www.example.com (we are assuming Drupal is installed in the sites root directory). Solution: Determine the id number of the node you wish to have Drupal redirect users to. One way to determine the nodes id number is to visit the node and look at the number after the last slash in your browsers address bar. This is your nodes id number. Now set the "Default front page" to "node/id#". So, assuming your nodes 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 categorys 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 browsers status bar (usually located at the bottom of your browsers window). The number after the last slash in the URL is the categorys id number. Now set the "Default front page" to "taxonomy/term/id#". If your categorys id number is "5" for example, youd write "taxonomy/term/5".
Clean URLs
By default, Drupal passes path arguments to itself via its internally generated URLs. This results in URLs that look like the following: "http://www.example.com/?q=node/83." This can make URLs hard to read and it also stops many search engines, like Google, from indexing the pages with these URLs. You can tell Drupal to use "clean URLs", eliminating the "?q=" in internal URLs. Note that this works only for Apache servers which have the LoadModule rewrite_module configured and mod_rewrite enabled in httpd.conf configuration file.
141
Drupal Handbook
3 Aug 2007
There are two ways to enable URL rewrites in Apache. If there is complete control of the Apache webserver clean URLs should be enabled in the httpd.conf as this has better performance and security. Warning. Enabling "Clean URLs" if your server is not properly configured can make it difficult to navigate back to administration pages to undo your mistake. If you find yourself in this situation, you can return to the administrative settings page by typing in the URL in the non-clean form: http://www.example.com/?q=admin/settings. Enabling clean URLs involves three steps: 1. Enable mod_rewrite for Apache. Please talk to your web host or consult the Apache documentation for mod_rewrite to get more information on how to do this. At a minimum, this will involve making sure that mod_rewrite is enabled for your installation of Apache. It will have to be either compiled-in or made available as a loadable module. Generally speaking, you can tell Apache to load the module by including LoadModule rewrite_module modules/mod_rewrite.so AddModule mod_rewrite.c in your Apache configuration file. Be sure to uncomment AddModule mod_rewrite.c. Note that this may not be the case for all distributions of *nix operating systems. Consult your distributions documentation that came packaged with your Apache software. We also recommend disabling multiviews in Apache as they conflict with clean URLs. 2. Edit your Apache configuration files for your site: the configuration information may be found in httpd.conf, a virtual-host-specific file, or in an .htaccess file in your Drupal installation directory. You can find this file usually in /etc/httpd/conf/httpd.conf. You may use find /etc -name httpd to find the file if it is located else where in your Unix system. The main configuration option which may need to be changed for your site is the RewriteBase. For example, if your Apache DocumentRoot is /var/www/ (i.e., /var/www/index.html is what is displayed when you point your browser at http://www.example.com/) and your Drupal installation is installed in the subdirectory /var/www/mysite/, then the RewriteBase should be set to /mysite. In some configurations setting RewriteBase / will allow mod rewrite to work. If you dont use the .htaccess that comes with Drupal youll 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 Apaches .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 Drupals Clean URLs are enabled. Unless you know what youre doing, you should consider disabling MultiViews if you plan to use the clean URLs feature of Drupal. Be aware that theres a good chance that MultiViews is already disabled, however; its not enabled in a default Apache installation. Consult the Apache documentation for further information about MultiViews.
143
Drupal Handbook
3 Aug 2007
bobdonohue reported that this .htaccess file worked on dotster. This code was taken from the boost.module and modified just a little bit. There is no guarantee this will work for you though. Instructions: Create a text file, copy and paste the code below and save it as .htaccess Upload the file and put it in the public_html directory of your site. Modify "RewriteBase subdirectory "example." /" in line 68 to "RewriteBase /example" if your site is in
# # 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 $
146
3 Aug 2007
Drupal Handbook
Options -MultiViews
order deny,allow deny from all </Files> # Set some options Options -Indexes Options +FollowSymLinks # Customized server error messages: ErrorDocument 404 /index.php # Set the default handler to index.php: DirectoryIndex index.php # Overload PHP variables: <IfModule sapi_apache2.c>
147
Drupal Handbook
3 Aug 2007
# If you are using Apache 2, you have to use <IfModule sapi_apache2.c> # instead of <IfModule mod_php4.c>. php_value register_globals 0 php_value track_vars 1 php_value short_open_tag 1 php_value magic_quotes_gpc 0 php_value magic_quotes_runtime 0 php_value magic_quotes_sybase 0 php_value arg_separator.output "&" php_value session.cache_expire 200000 php_value session.gc_maxlifetime 200000 php_value session.cookie_lifetime 2000000 php_value session.auto_start 0 php_value session.save_handler user php_value session.cache_limiter none php_value allow_call_time_pass_reference On </IfModule> # Various rewrite rules <IfModule mod_rewrite.c> RewriteEngine on Options All # Modify the RewriteBase if you are using Drupal in a subdirectory and the # rewrite rules are not working properly: RewriteBase /drupal # Rewrite old-style URLS of the form node.php?id=x: RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{QUERY_STRING} ^id=([^&]+)$ RewriteRule node.php index.php?q=node/view/%1 [L] # Rewrite old-style URLs of the form module.php?mod=x: RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{QUERY_STRING} ^mod=([^&]+)$ RewriteRule module.php index.php?q=%1 [L] # Rewrite URLs of the form index.php?q=x: RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.*)$ index.php?q=$1 [L,QSA] </IfModule> # $Id: .htaccess,v 1.58 2004/10/09 20:41:49 dries Exp $ This is because the debian package installs the drupal "sites-enabled" virtual host, result being that drupal is accessed from http://yourhost.com/drupal, hence the need to uncomment RewriteBase. Change it to the base that corresponds to your system.
148
3 Aug 2007
Drupal Handbook
ref: http://www.debian-administration.org/articles/136 http://drupal.org/node/14322 -Sean K. OBrien CTO Colley Graphics, LLC http://www.colleygraphics.com
Apache 2 on Ubuntu
Two methods here:
Editing apache2.conf
First thing to do is make sure you have apache up and running: /etc/init.d/apache2 start Then you have to enabled the rewrite module(mod_rewrite). You no longer have to do the: LoadModule rewrite_module modules/mod_rewrite.so AddModule mod_rewrite.c Its now as easy as: a2enmod rewrite To disable this module its just: a2dismod rewrite with Apache version 2, the httpd.conf has been depreciated and the new file is located at: /etc/apache2/apache2.conf in this file you need to add your directory and the allow override to give access to your drupal site. so look for a section in your apache2.conf that has Directory tags and just add another section: <Directory /var/www/drupal_website_install> AllowOverride all </Directory> *keep in mind that my website is in a subdirectory (drupal_website_install) and so you may need to edit the above to reflect this. By this I mean if i go into my webbrowser I need to go to http://localhost/drupal_website_install/ After you edit you apache2.conf as listed above you need to restart the server by: /etc/init.d/apache2 restart
149
Drupal Handbook
3 Aug 2007
If you are having problems with getting your rewrite to work you can always use logging. To do that add this to the end of you apache2.conf: RewriteLog "/var/log/apache2/rewrite.log" RewriteLogLevel 3 Level 0 is no logging Level 9 is log everything You can pick the level to determine the amount of output you need. ***Security Warning: Make sure to take the log code out, disable it, or put the log file in a directory that cant be read by normal users (as shown above) otherwise it can result in a security breach.*** hopefulley this helps some people and saves them the time that I spent trying to get it working.
Editing apache2/sites-available
My configuration: drupal 5.x apache 2.2 mysql 5.0 debian/ubuntu server install drupal path: /www/drupal/sites/site1...site2 I have root access to my server. First, from the linux command line, I enabled the rewrite module for apache like this: a2enmod rewrite Next I restarted Apache: sudo /etc/init.d/apache2 restart Then I reloaded Apache config files: sudo /etc/init.d/apache2 reload Finally, I changed the file located at: /etc/apache2/sites-available/default (in the sites-available directory, you should see as many files as you have websites enabled. One is named default and the others should reflect the names of your additional sites if you are running virtual hosts. If you have only a single site, it will most likely be named default. You can open these files in an editor such as nano and make changes.)
150
3 Aug 2007
Drupal Handbook
change this directive in the file(s) found in sites-available: AllowOverride None to AllowOverride All Save this file and then restart apache as we did above. Now browse to your site with your browser, login, click administer, find "Clean URLs" and browse to that page, run the test for "Clean URLs" buried in the paragraph explaining "clean Urls". If your setup is like mine, you should now have Clean URLs in drupal.
151
Drupal Handbook
3 Aug 2007
1. Create the following file and save it as "/url_rewrite.php". <?php /* Add in this array the list of (old path => new path) pairs */ $redirection = array( ^(.*)$ => index.php?q=$1 ); if (!file_exists($_SERVER["REQUEST_URI"])) /* Get the URI and trim leading slashes */ $uri = ltrim($_SERVER["REQUEST_URI"], "/"); { foreach ($redirection as $key => $value) { if (eregi($key, $uri)) { /* Convert the replacement string syntax - $1 -> \1 */ /* and perform the substitution */ $uri = str_replace("index.php","",substr($uri,0)); $new_uri = str_replace("?","&",$uri); $new_uri = "/index.php?q=".$new_uri; $new_uri = str_replace("%26","&",$new_uri); break; } } } if (isset($new_uri)) { header("Status: 307"); header("Location: $new_uri"); exit; } ?> <!-- Your 404 error page --> <HTML> <HEAD> <TITLE>Not Found</TITLE> </HEAD> <BODY> The object <tt><?php echo $uri; ?></tt> is not available. </BODY> </HTML> 2. In the Abyss web console, enter the Custom Error Pages, add a 404 Status Code entry with the Associated URL value "/url_rewrite.php". Click OK and restart the Abyss webserver. 3. Test for functionality by querying your website directly with URIs such as: http://www.example.com/admin/settings http://www.example.com/node/add
152
3 Aug 2007
Drupal Handbook
If the redirection works properly, proceed to the next steps. If the redirection would not work, check if the steps above have been strictly followed. Modify only those things that you have absolute knowledge of. 4. Log on to your website and log on to your "/admin/settings" page. Under General Settings section, enable Clean URLs. If the Clean URLs option is grayed out, add the line "$conf[clean_url] = 1;" in your settings.php, then repeat this step. Dont 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.
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 Lightys 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 Drupals clean URL check (when saving Settings) succeeds (Drupal makes an HTTP request for a path of the form /system/test/yLgnwqqUu5cWnvPi4Hrz.png). Its a special case that must be handled separately (read on for the reason). The two following lines let Drupal handle any URL that doesnt contain a dot. This is significant because we can assume, fairly confidently, that addresses like /node/add are Drupal URLs, but addresses such as /themes/bluemarine/style.css are physical files. So the above configuration will work for all cases where this assumption holds true; if there are exceptions to the rule, they can be manually added to the rewrite configuration. See also the related discussion at http://drupal.org/node/20766 I just successfully set up lighttpd 1.4.8 with php4 via fastcgi using those rules above. As per lighttpd documentation I also set up /etc/php4/cgi/php.ini to have that cgi fix. Then I added those rewrite rules for corresponding virtual_host. Ubuntu breezys php4-cgi package bougymans lighttpd package (see http://www.lighttpd.net/download/ for details)
154
3 Aug 2007
Drupal Handbook
and leave like this in the same line. LoadModule rewrite_module modules/mod_rewrite.so y AddModule mod_rewrite.c and Re-start the server. Easyphp have the mod_rewrite within. If there is any problem tell me. Oskar Calvo.
155
Drupal Handbook
3 Aug 2007
There are some directories that we should not rewrite. And there are certain extensions that we should not rewrite. Using this information, we can update the rewrite rule to send everything to index.php that does not fall into this category. The first rule excludes the directories "files", "misc", and "uploads". The second rule excludes the extensions you see. Add more if you have other extensions in your directory that should not get passed to index.php. RewriteCond %{REQUEST_FILENAME} !^/$ RewriteCond %{REQUEST_FILENAME} !^/(files|misc|uploads)(/.*)? RewriteCond %{REQUEST_FILENAME} !\.(php|ico|png|jpg|gif|css|js|html?)(\W.*)? RewriteRule ^(.*)$ /index.php?q=$1 [L,QSA]
Next, add the following line to the end of your settings.php file for your site: $conf[clean_url] = 1;
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 dont apply any more rewriting rules. Use this flag to prevent the currently rewritten URL from being rewritten further by following rules. qsappend|QSA (query string append) This flag forces the rewriting engine to append a query string part in the substitution string to the existing one instead of replacing it. Use this when you want to add more data to the query string via a rewrite rule. REQUEST_FILENAME The full local filesystem path to the file or script matching the request. -d (is directory) Treats the TestString as a pathname and tests if it exists and is a directory. -f (is regular file) Treats the TestString as a pathname and tests if it exists and is a regular file. Note: Getting Apache running on MS Windows is not that bad (I had been delaying it for years). In reality its a matter of a few hours to get going. http://www.sitebuddy.com aims to save you time in that endeavor.
157
Drupal Handbook
3 Aug 2007
case settings: $settings[bulkdescr] = ?> ... <?php // LOCAL ADDON t([locale]) => t(The locale used for this node.), ?> These will be loading the data <?php function node_get_placeholders($node) { ?> ... <?php // LOCAL ADDON $result = db_query("SELECT locale FROM nid=%d", $node->nid); $nodelocale = db_fetch_object($result); $placeholders[t([locale])] = pathauto_cleanstring($nodelocale->locale); ?> Hope this helps someone !
{localizernode}
WHERE
Setting up clean URLs above web document root on virtual private servers
To set up clean URLs above web document root on virtual private servers, you need to change a setting in httpd.conf. (default setting) Options FollowSymLinks AllowOverride None Change it to Options FollowSymLinks AllowOverride All None of the other changes discussed in this section of the handbook were necessary (and in fact had to be undone). The hosting provide said this does not provide any security issues (no guarantees).
158
3 Aug 2007
Drupal Handbook
159
Drupal Handbook
3 Aug 2007
$_SERVER["REQUEST_URI"] = $parts["path"]; if ($parts["query"]) { $_SERVER["REQUEST_URI"] .= ?. $parts["query"]; $_SERVER["QUERY_STRING"] = $parts["query"]; $_SERVER["ARGV"] = array($parts["query"]); parse_str($parts[query], $arr); $_GET = array_merge($_GET, $arr); $_REQUEST = array_merge($_REQUEST, $arr); } } ?> at this point, you should be able to request clean url pages and receive a proper page in response. for example, request the page /node/1 and hopefully you will see your first node shown. you should not use the q= syntax; use the clean url syntax. if you get an IIS error, you have a problem. please fix redo the above and then retest. browse to index.php?q=admin/system, enable clean URLS, and press Submit. you may get a php error if your php error reporting in your php.ini file is set to high. Try this setting in your php.ini file error_reporting = E_ALL & ~E_NOTICE Note: This method seems to work for IIS5 but not IIS6. Check this thread for some approaches using ISAPI_Rewrite.
Alternate method
Alternatively, you can use ISAPI Rewrite by Helicon software to add mod_rewrite-like functionality to IIS: www.isapirewrite.com
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 isnt acceptable, there is a contributed module called Custom Error that avoids this problem.
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 dont 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 Drupals 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.
161
Drupal Handbook
3 Aug 2007
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.
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 dont 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 its best to plan ahead when you set your drupal site up and think carefully about whether youll need to restrict file downloads. If thats 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 issues, you can create the file manually.
164
3 Aug 2007
Drupal Handbook
Many Drupal sites will need a more unique look than these pre-built themes can offer. Therefore, many developers will want to write their own themes. Theme development requires a working knowledge of HTML/CSS and possibly some rudimentary PHP depending on the complexity of your theme. Customize the Navigation. The menus that are displayed on the top and bottom of the page are configured in administer > themes. Select the configure tab and scroll down to Menu Settings. The primary and secondary links can be defined here, using straight HTML. If the primary links are left blank your navigation will be created based on your installed modules. Each theme has an individual configuration page (listed at the top of the global settings page) as well. Unfortunately, in Drupal 4.6 and previous using PHPTemplate your navigation must be defined in that themes individual theme area. In 4.7 PHPTemplate engine is incorporated into the Drupal core and the Primary and Secondary links are now part of the menu system. Mention of this can be found here. Customize Text Strings You can also change the text strings throughout drupal using the locale feature, which was designed for running drupal in different languages, you can personalize almost all of the text in drupal. In fact, you can replace a string like "create blog entry" with html markup such as references to graphics.
165
Drupal Handbook
3 Aug 2007
You can also create more customized login blocks. You can create name and email filter rules in admin >> access control >> account rules. Set up username and e-mail address access rules for new accounts. If a username or email address for a new account matches any deny rule, but not an allow rule, then the new account will not be allowed to be created.
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 dont want to have it running every minute if you dont 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 doesnt even make sense to me so lets just have a look at the examples to figure it out. You can also use the command */ to have jobs run every interval. Here the examples to help you get the hang of it. Run cron.php task every 30 minutes: */30 * * * * lynx -source http://www.yourwebsite.com/cron.php Run cron.php task once a week at 1:00 am every saturday (you can see that saturday is represented by 0): 00 1 * * 0 lynx -source http://www.yourwebsite.com/cron.php Run cron.php task on the first day of every month at 12:00 am (midnight) : 00 0 01 * * lynx -source http://www.yourwebsite.com/cron.php I hope this is helpful for beginners who have installed Drupal and are wondering how to setup Cron.
167
Drupal Handbook
3 Aug 2007
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 modules 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 modules 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 modules 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.modules 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 menus 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 its 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. 1. First of all you might want to enable friendly URLs 2. Then, make sure that you get rid of the session ID in the URL by changing the .htaccess if you are using version 4.5.x. On 4.6, session IDs in URLs are disabled by default. 3. Optionally, use URL aliasing for some or all nodes. You can use the pathauto module to automatically create aliases for new nodes.
170
3 Aug 2007
Drupal Handbook
This file tells indexing robots that they should avoid pages that contain content for users only, for example the search page, or the Add a comment forms for nodes. Many robots obey the "Crawl-delay:" parameter. Since Drupal sites seem to be popular with search engines and lots of people have more aggresive bots than visitors at their site, it might be wise to slow down the robots by adding a robots.txt line like this: User-Agent: * Crawl-Delay: 10 Here 10 is the delay in seconds between page requests. Both "Slurp" (The robot that is indexing for yahoo and altaVista) and the Microsoft robots for the MSN sites obey this parameter. Googlebot does not use the "crawl-delay" parameter yet but will likely do so in an upcoming version. Change the file as you wish and save it. Now upload it to your webserver and make sure it is in the root of the (virtual) webserver. If you have installed Drupal in a subdirectory (for example /drupal), then change the URLs 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.
171
Drupal Handbook
3 Aug 2007
Disallow: /tracker Disallow: /comment/reply Disallow: /node/add Disallow: /user Disallow: /files Disallow: /search Disallow: /book/print Disallow: /admin Disallow: /cron.php Disallow: /xmlrpc.php Disallow: /database/ Disallow: /images/ Disallow: /includes/ Disallow: /modules/ Disallow: /scripts/ Disallow: /themes/ Disallow: /email_disclaimer Disallow: /privacy_policy Disallow: */add/ # AltaVista User-agent: scooter Crawl-Delay: 10 Disallow: /aggregator Disallow: /tracker Disallow: /comment/reply Disallow: /node/add Disallow: /user Disallow: /files Disallow: /search Disallow: /book/print Disallow: /admin Disallow: /cron.php Disallow: /xmlrpc.php Disallow: /database/ Disallow: /images/ Disallow: /includes/ Disallow: /modules/ Disallow: /scripts/ Disallow: /themes/ Disallow: /email_disclaimer Disallow: /privacy_policy Disallow: */add/ # Googlebot User-agent: googlebot Crawl-Delay: 10 Disallow: /aggregator Disallow: /tracker
172
3 Aug 2007
Drupal Handbook
Disallow: /comment/reply Disallow: /node/add Disallow: /user Disallow: /files Disallow: /search Disallow: /book/print Disallow: /admin Disallow: /cron.php Disallow: /xmlrpc.php Disallow: /database/ Disallow: /images/ Disallow: /includes/ Disallow: /modules/ Disallow: /scripts/ Disallow: /themes/ Disallow: /email_disclaimer Disallow: /privacy_policy Disallow: */add/ # Looksmart User-agent: wisenutbot Crawl-Delay: 10 Disallow: /aggregator Disallow: /tracker Disallow: /comment/reply Disallow: /node/add Disallow: /user Disallow: /files Disallow: /search Disallow: /book/print Disallow: /admin Disallow: /cron.php Disallow: /xmlrpc.php Disallow: /database/ Disallow: /images/ Disallow: /includes/ Disallow: /modules/ Disallow: /scripts/ Disallow: /themes/ Disallow: /email_disclaimer Disallow: /privacy_policy Disallow: */add/ User-agent: zyborg Crawl-Delay: 10 Disallow: /aggregator Disallow: /tracker Disallow: /comment/reply Disallow: /node/add
173
Drupal Handbook
3 Aug 2007
Disallow: /user Disallow: /files Disallow: /search Disallow: /book/print Disallow: /admin Disallow: /cron.php Disallow: /xmlrpc.php Disallow: /database/ Disallow: /images/ Disallow: /includes/ Disallow: /modules/ Disallow: /scripts/ Disallow: /themes/ Disallow: /email_disclaimer Disallow: /privacy_policy Disallow: */add/ # MSN User-agent: msnbot Crawl-Delay: 10 Disallow: /aggregator Disallow: /tracker Disallow: /comment/reply Disallow: /node/add Disallow: /user Disallow: /files Disallow: /search Disallow: /book/print Disallow: /admin Disallow: /cron.php Disallow: /xmlrpc.php Disallow: /database/ Disallow: /images/ Disallow: /includes/ Disallow: /modules/ Disallow: /scripts/ Disallow: /themes/ Disallow: /email_disclaimer Disallow: /privacy_policy Disallow: */add/ # Yahoo Vertical Crawler User-agent: yahoo-verticalcrawler Crawl-Delay: 10 Disallow: /aggregator Disallow: /tracker Disallow: /comment/reply Disallow: /node/add Disallow: /user
174
3 Aug 2007
Drupal Handbook
Disallow: /files Disallow: /search Disallow: /book/print Disallow: /admin Disallow: /cron.php Disallow: /xmlrpc.php Disallow: /database/ Disallow: /images/ Disallow: /includes/ Disallow: /modules/ Disallow: /scripts/ Disallow: /themes/ Disallow: /email_disclaimer Disallow: /privacy_policy Disallow: */add/ # Exclude every other bot (hopefully) User-agent: * Disallow: / ... this way, it blocks every bot, except the ones i listed. a much more logical approach, methinks. also, a little off-topic, but dont forget to Disable PHPs session use_trans_sid for cleaner search engine listings.
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
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> Theres 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> Youll want to leave option "strip disallowed tags". It may be useful to create extra Filters, for finer control on users and HTML they can input. For instance, if someone will be writing and editing articles, could allow them a wide range of tags. (If you have, say, a user group "writers n editors", might create Filtered HTML for Editors.) But for folk who register and can just add comments, post to forum, could have tighter list. This, perhaps, could obviate need for BBcode, albeit a few fckeditor style buttons would be more user-friendly than listing of code tags. Note that the input formats are stored as you save text etc. So if you change filter you want to be used as default for your site, wont affect saved pages.
Set default content options - Stop automatic promotion to the front page
Configure the default content workflow suitable for your site. Out of the box, Drupal modules are set to promote to the front page. While this is desirable in many instances, it is not something you always want. The administration menu has changed in 4.7, so the config screen for this has moved. In 4.6 and older: Go to the Administer > Content Select the Configure tab and then the Content Types sub tab. In 4.7: Go to Admin > Settings > Content-types In 5.x Go to Administer > Content Management > Content-types Click on the configure for the node type in question and change the default workflow options to something suitable for your site. If you add or enable modules such as CCK that create additional node types, you will need to revisit these settings. Remember that.
177
Drupal Handbook
3 Aug 2007
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 blocks 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 blocks 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 sites 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 blocks weight to position the block vertically within its column. A blocks 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
aggregator Specifies that the block appears on just the aggregator. Specifies that all URLs that start with blog/ will show the block. Note: if you want the block(s) to also appear on the main blog page, you need to add blog (that is, without the trailing slash) as well.
blog/*
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 dont 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
180
3 Aug 2007
Drupal Handbook
Hence <^node> will match http://www.example.com/node, http://www.example.com/node/foo, and http://www.example.com/node/123, if your server is www.example.com. If you omit this and type <node> for example, your regular expression will match http://www.example.com/node, but also http://www.example.com/nodessert, http://www.example.com/blog/how_to_delete_a_node, etc. OK so far? As you have perceived, parentheses group sub-expressions (sort of in the same way that parentheses group sub-expressions in arithmetic, or even in written communication, as in this example!). The pipe operator (|) is used to separate alternatives. Read it as or. So, <^(foo)|(bar)> can be read as match foo or bar at the start of the line. The expression (?!...) is called a negative look-ahead operator. It says to match only if the subexpression following the ?! does not match from the point where the ?! is evaluated (matched) So <^foo(?!(t))> matches http://www.example.com/fool and http://www.example.com/fooze but not http://www.example.com/foot, or http://www.example.com/football. One more thing - letters and numbers match themselves, but obviously certain other special characters have special meaning (e.g., weve already seen that ^,?, !, | and parentheses are treated specially). These are called metacharacters. To match a metacharacter you need to escape it, by preceding it with a \ (backslash). So, to match the pattern foo?! youd have to type <foo\?\!>. Now, we can put all of the pieces together. Just as in arithmetic, or in writing compound sentences, you can create long expressions by combining short ones. Regular expressions can be combined by simply catenating them:<foo> matches foo, and <bar> matches bar; catenate them to get <foobar> matching foobar. You can also combine by alternation: <(foo)|(bar)> matches foo or bar. You can specify that a subexpressions matches zero or more times by following it with an asterisk: <(foo)*t> matches t, foot, foofoot, foofoofoot, and so on. (Ive 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 doesnt match the subexpression following ?!, namely, node/635, or event. Ive escaped the slash - I dont know if this is necessary (but it doesnt hurt - any regular character when escaped just matches itself)
181
Drupal Handbook
3 Aug 2007
If youre beginning to love this stuff, theres hundreds of more pages of fun examples in various books and on other websites (for example at http://www.php.net). Just search for regular expression or PCRE (perl compatible regular expressions) Hope this helps, Djun
Custom blocks
A custom block contains content supplied by you (as opposed to being generated by a module). Custom content may be either static (i.e., HTML) or dynamic (PHP generated content). Virtually all of the functionality of Drupal is accessible from within a PHP content block. The flexibility of blocks provides an extremely powerful way to customize your Drupal website. You can create a custom block via the block management screen (click on administer blocks). Select the new tab and complete the form. Each custom block has a title, a description, and a body. The content within the body can be as long as you wish. Note: In Drupal 4.6, the title of the block is used as its identifier in the database table. Therefore you can only have one custom block without a title (this issue has been fixed in newer Drupal versions). One workaround for this is to enter a title such as this: <!--title of custom block-->. This satisfies Drupals need for a block title but the comment markers (<!-- ... -->) prevent it from being displayed.
182
3 Aug 2007
Drupal Handbook
Add for example: memory_limit = 12M to your php.ini file (recommended, if you have access) ini_set(memory_limit, 12M); to your sites/default/settings.php file php_value memory_limit 12M to your .htaccess file in the Drupal root You will need to experiment with the value that is right for you.
183
Drupal Handbook
3 Aug 2007
If you want to share users across multiple sites, youll need to use a $db_prefix along these lines: <?php $db_prefix = array( default => authmap => profile_fields => profile_values => role => sequences => sessions => users => users_roles => users_uid_seq => ); ?>
thissite_, shared_, shared_, shared_, shared_, shared_, shared_, shared_, shared_, shared_, // for pgsql
See the sharing tables and sharing tables across databases sections.
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... );
185
Drupal Handbook
3 Aug 2007
ADD
CONSTRAINT
test.contact_category_key
The prefix must be removed from the index and constraint name--that is they must be changed to: CREATE INDEX search_total_word_idx ON prefix.search_total(word) ALTER TABLE prefix.boxes DROP CONSTRAINT boxes_title_key ALTER TABLE test.contact ADD CONSTRAINT contact_category_key (category)
UNIQUE
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. Youll see a list of failed queries and it will be easier for you to change them. Another remark: you cant use prefix.sh to prefix the tables, it will produce incorrect CREATE [UNIQUE] INDEX queries. This, also, can be easily fixed, by changing: s/^CREATE INDEX \(.*\) ON /CREATE INDEX $PREFIX\\1 ON $PREFIX/; s/^CREATE UNIQUE INDEX \(.*\) ON /CREATE UNIQUE INDEX $PREFIX\\1 ON $PREFIX/; to: s/^CREATE INDEX \(.*\) ON /CREATE INDEX \\1 ON $PREFIX/; s/^CREATE UNIQUE INDEX \(.*\) ON /CREATE UNIQUE INDEX \\1 ON $PREFIX/; An alternate approach Heres what you need to do if you want to solve it this way: 1. Add the following at the top of your database.pgsql file: CREATE SCHEMA schemaname; SET search_path TO schemaname; 2. Edit drupal/includes/database.pgsql.inc, replacing the function db_connect() with: <?php function db_connect($url) { $url = parse_url($url); $db_and_schema = explode(".",substr($url[path], 1)); $conn_string = user=. $url[user] . dbname=. $db_and_schema[0] . password=. $url[pass] . host= . strtr($url[host],+,/); $conn_string .= isset($url[port]) ? port= . $url[port] : ; $connection = pg_connect($conn_string) or die(pg_last_error()); if(!empty($db_and_schema[1])) pg_query(SET search_path TO
186
3 Aug 2007
Drupal Handbook
.$db_and_schema[1]); return $connection; } ?> 3. Finally, use a db_url akin to such in your settings.php file(s): $db_url = pgsql://user:password@+tmp/dbname.schemaname; Not thoroughly tested, but works for me (on 4.6.3). This also fixes the inability to specify a Unix socket as the host - the +tmp gets replaced with /tmp for pg_connect().
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
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, Ill 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 doesnt hurt to have some basic knowledge of php, HTML, and CSS, but it is not required. Here are some good resources for you: W3 Schools - for virtually everything Internet-related. The Official PHP Site - the full php implementation. PHP Builder - some tutorials and code ready-to-use. Now, to be honest, I have used HTML in this book, and tweaked the CSS on my site a little bit. But I have not used one line of php code. Another common myth is that your learning curve for Drupal is going to be steep and it will take you months, or even years, to get a web site up and running. Hogwash! I had my first, largely static, web site with 36 pages up in less than a week after I installed my first copy of Drupal. Then, because my hosting provider pulled the plug, I got my groups 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
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.
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. Dont 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. [Nancys note: also stay away from access control (security) modules until later. They can really destroy your site if you dont know what youre doing.] Customize one of the default themes before creating your own, the Theme Developers 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. Its 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!
191
Drupal Handbook
3 Aug 2007
Its 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 youve done that. Now youre ready to move on to more wonderful things, but do it one step at a time. Dont 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, youre welcome to submit feature requests or explain why something is not done in the most logical manner. But dont demand it, or threaten to abandon Drupal if you dont get it your way. And certainly dont 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 - theres no need to re-invent the wheel! This package has already integrated the following things: Apache 2.2 HTTP Server MySQL 5.0 Database PHP 5.2 and Perl 5.8 Scripting Languages GUI WAMP-stack Controller Dynamic DNS Client Tomcat Servlet/JSP Container mod_aspdotnet ASP.NET Host Interface OpenSSL Cryptography Toolkit mod_security Web Application Firewall phpMyAdmin MySQL Administration Joomla Drupal WordPress MediaWiki phpBB Dont 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 dont 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. Whats 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, dont you?] But at least Im 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. Heres 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. Id give you a link to something on the Drupal site, but I never found anything like this. 1. Go to Administer>>User management>>Roles and create an "administrator" role. 2. Go to Administer>>User management>>Users and create a user entry for yourself. This allows you to test the site by changing your role to meet your needs. 3. Go to Administer>>User management>>Access control and allow the "administrator" role to do everything. 4. While youre there, go ahead and set what the "authenticated users" (logged in) and "anonymous user" (not logged in) can do, such as using your contact form. This is not engraved in stone; you can change it any time you want. 5. Go to the Administer>>Site configuration>>Site information page and, near the bottom, set the "Default front page" to "node." As long as youre on this page, set basic defaults for the other fields. I dont know about everyone, but I dont like, when I visit a site, being called "Anonymous" so I change the designation to "Visitor." 6. If there are any modules (core or contributed) that you use on all sites, go ahead and enable them now ((Administer>>Site building>>Modules). For example, you will probably use "Page" on all sites, and maybe "Story." I am finding more and more uses for "Book." 7. I do recommend turning on (enabling) the "Path" core module so you can use "normal" names for your pages. If you want to use the contact form to email anyone from the site, be sure to enable the "Contact" module.
193
Drupal Handbook
3 Aug 2007
8. The same goes for themes. There are a few things I recommend that you do in all your databases, so this is a good time to do it: Turn on "CLEAN URLS" to make your site more user friendly. Go to Administer>>Site configuration>>Clean URLs. At the bottom of the verbiage there is a link to run the "Clean URLs Test." If it passes, then the "Enable" radio button will un-dim. Click on that. (If the URLs stop working for some reason here are instructions to unset clean URLs.) In order for me to create any kind of content, I go to Administer>>Site configuration>>Input formats and set "Full HTML" as the default until I get the site ready to go live. Then I still allow administrators (like my other ID) to use that format. Do this now and you will avoid a very common problem with building your site. I dont 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 youre 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, lets 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.
194
3 Aug 2007
Drupal Handbook
Open phpMyAdmin (using "other" in Web-Developer Controller) start bulk loop 1 On the left, select the Drupal51 database. This is the one that was created by the package installation. Click on "Operations" Scroll down to "Copy Database to:" Enter the new database name. Verify that the radio buttons are clicked for: Structure and data CREATE DATABASE before copying Switch to copied database Click on the Go button just below this area. When the copy is complete, click on "SQL". In the "Run SQL query/queries on database" box, enter: GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES ON databasename.* TO admin@localhost IDENTIFIED BY superpw; FLUSH PRIVILEGES; admin is what I call my administrative role (this is the "super-user" name); superpw is the password for this user (I tend to use the same one for all my databases to make it easy). Hint: I created and saved this in c:/www/drupal/grant.txt so I could copy and paste. Change databasename to the new databases name. end bulk loop 1 Close phpMyAdmin. Go to the www/Drupal/sites directory. start bulk loop 2 Copy one of the site folders (e.g. default) and name it for your new site. Open the directory, then open the settings.php file in Notepad. Change the $base_db and $base_url lines. The $base_db line should have the name of the database you just created. The $base_url will be how you want to access the site. Close the file. If you are going to have site-specific modules or themes, go ahead and create directories in this site to hold them (named "modules" and "themes"). end bulk loop 2 Navigate to the /www/Apache22/conf folder. Locate and open the "httpd.conf" file (Hint: I always make a copy of things Im about to change, just in case I mess up.)
195
Drupal Handbook
3 Aug 2007
I did notice that my version of Apache sets index.html ahead of index.php, so dont have an index.html in your directory.
Find the line that says "# Virtual hosts." Remove the "#" from the next line. This allows you to make all your other changes in a separate, and less dangerous file. Save it. Navigate to the /www/Apache22/conf/extra folder. Open the httpd-vhosts.conf file. At the bottom of the existing list, comment out ("#") the examples. start bulk loop 3 At the bottom of the existing list, enter: <VirtualHost *:80> DocumentRoot /www/drupal/ ServerName databasename </VirtualHost> Change databasename to the new databases name. end bulk loop 3 Close the file. Navigate to the /windows/system32/drivers/etc folder. Open the Hosts file with Notepad. Hint: these two steps can be done by using "other" in Web-Developer Controller. start bulk loop 4 Add a line that says: 127.0.0.1 databasename Change databasename to the new databases name. end bulk loop 4 Close the file. Go back to Web-Developer Controller. Click on Apache2 (top left). Click the Stop Service button. Wait for it to change to "stopped." Click the Start Service button Wait for it to say "running." Go for it. You can now start the browser and enter http://databasename.
196
3 Aug 2007
Drupal Handbook
For more details on directories for multiple sites, see Setup of /sites directory for multi-site.
D. Error Pages
Occasionally, a user may do something that confuses Drupal, such as typing a wrong page name or trying to access content they shouldnt. 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 sites 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.
Access Denied
Heres the HTML for my 403 page: <p>Were 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> Dont worry that you havent 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.
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 youre 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. Thats it! Now you need to enable it.
Modules
Modules
You enable a module at Administer>>Site building>>Modules. The non-core modules are listed farther down. With 5.x, they now show you some of the inter-module dependencies. I turn them on and "Save configuration" in order of the dependencies. For example, "Views UI" requires "Views", so I turn on "Views" first, save the configuration, then turn on "Views UI." and save again. Ah, now the real work begins. Go to Administer>>User management>>Access control to select who can use the features of the new module. If the module introduced new content types, go to Administer>>Content management>>Content types and configure them. Dont forget this may also affect your "Input formats" (Administer>>Site configuration>>Input formats) and "Categories" (or taxonomy, Administer>>Content management>>Categories); youll have to check those too. Okay, now you can start using the new module.
199
Drupal Handbook
3 Aug 2007
This Site
My documentation site is a relatively "vanilla" implementation of Drupal. Core Modules Enabled Blog Book Comment Contact Help Menu Path
pieces of code. description.
Contributed Modules in Use Codefilter - Provides tags for automatically escaping and formatting large Meta Tags (Nodewords) - Allows users to add meta tags, eg keywords or Site Documentation - Documents and cleans up your configuration.
To get some idea of what modules are available, check these links: module handbook and contributed modules handbook.
Themes
Themes
You enable a theme at Administer>>Site building>>Themes If it has never been enabled on this site, you will have to check the "enable" box and then click the "Save configuration" button at the bottom. To set up how the theme works, click on the "Configure" link (not the tab at the top). Fill in the fields. Save the configuration. Dont leave the page yet.
200
3 Aug 2007
Drupal Handbook
If you want to change it, heres how: 1. First, find out what size it is because youll want your own logo to be about the same. (If you are comfortable with HTML and CSS you can also edit the themes code to accommodate your logo rather than resizing the image. How to edit theme code is not covered in this beginners guide.) 2. Theme Name Width Height Bluemarine Chameleon Garland Minelli Pushbutton Fancy 48 49 64 64 144 80 55 57 73 73 63 80
3. Under "Logo image settings" either type in the path to your logo, or upload it from your PC. 4. Note: Neither one of those options turns off the "Use default logo" radio button. You must select the correct radio button yourself. 5. The "Shortcut icon" (a.k.a. the favorite icon, or "favicon.ico") is the same way. If you want to change this, you must specifically say, "Hey, Drupal, Im changing this." Now you click the "Save configuration" button. If you did this in "Global settings" it affects all themes (assuming they behave properly); if you did it for a single theme, then only that theme is changed. For a list of all available themes, check Themes. HINT: Going to make a few (or a lot) of changes to a standard theme? Think about copying it over to your /sites/sitename/themes/ folder and renaming it. Then you can do anything you want and still be able to undo it easily by recopying. If the changes ae a bit bigger, think about contributing it back to the community (with your name, of course).
G. Creating Content
"Wow, Ive done all this and I still dont have any content on my site!" Well, lets 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 youre in a hurry, but read about both "pages" and "stories" before you decide which to use to create your front (home) page.
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, youve seen the Drupal site and noticed that there are "pieces" all over the place. Look at the front page; youll 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 didnt 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; its easy. As you go create your content, be thinking about the menu as well.
203
Drupal Handbook
3 Aug 2007
Whats 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. Heres what happens: 1. A node contains an entire article. 2. Drupals teaser function, node_teaser, strips the first x number of characters from the article and makes it available as content. The exact length is determined by the value set in Drupals Administer Content management >> Post settings. 3. So, you list a bunch of articles on a page. You want the articles to display only a snippet of text from the full article, so that you can fit a bunch of articles on a page without requiring the user to page down through tons of text. If the user likes the teaser content of the article, they will click on the articles title and see the full content of the article on its own
204
3 Aug 2007
Drupal Handbook
page. In a sense, teasers function like summaries of an article, except that the software decides where to cut off the text. If you want to determine where a teaser article ends, you can insert the comment tag to instruct Drupal exactly where to fashion the break between full text and teaser text. NOTE: There is a bug in the core Node module. Check the issue status. It is a simple change (can be done manually) and must be applied in order for some modules to render teasers correctly. By the way, you might want to add your own experience to that bug report in order to increase its attention by the developers.
205
Drupal Handbook
3 Aug 2007
H. Custom Blocks
Im not going to say a lot about custom blocks. But I will show you some really simple ones to give you a flavor. Theres a lot I still dont know about custom blocks, and that fills many posts on the Drupal web site. One good starting point is: Blocks.
Address
A business or support group should always let people know how to contact them. One easy thing is to include your mailing address on your pages. This is about the easiest kind of block to start with. 1. Go to Administer>>Site building>>Blocks. I should already be sitting on your default theme, but if not, select the right one. 2. Click on the "Add block" tab. 3. Fill in the "Description" and "Body." Heres a sample body: 4. My company name<br>123 Main St.<br>Mytown, State Zip<br>USA<br>(123) 456-7890 5. Save the block. 6. For some strange reason, you now need to "Configure" the block to add the blocks name and placement. 7. Add the name. 8. Determine whether users can turn to block on or off. Then which roles can see it; leave this with no selections to allow everyone to see it. Then choose which pages it will be shown on; I show the address on all pages. 9. Save the block. 10. Now youre back on the block list. Locate the block you just created. Select its location; I like the address in the left sidebar. You can use the "Weight" parameter to set its position with in the selected area; again, I like the address at the bottom, so I use a heavier weight. 11. Click on the "Save blocks" button. That wasnt so bad was it?
Last Updated
It is fairly common practice, especially on a group site to let the visitors know when the site was last updated. This example requires you, the webmaster or administrator (sometimes called the "super user") to maintain the block. There are ways to automate it, but I leave that until we are all farther along in our Drupal education. I followed pretty much the same process for the address block, giving this one a slightly heavier weight to sink it to the bottom. <address>Feb. 12, 2007 - NEW</address><br> <small>Best viewed in a full window with Internet Explorer 5.5 or
206
3 Aug 2007
Drupal Handbook
higher. Tested with IE6, Netscape 8, and Firefox 2.</small> The main difference is that I wanted it only on the home (front) page. So under "Page specific visibility settings," I clicked on the "Show only on the listed pages" radio button, and entered <front> in the pages box. Okay, now youre an "expert" on blocks.
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 its 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 dont 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 lets say you want this particular content listed in the menu as a child of some other page. No problem! Lets say you have a subjects introductory page already listed in the menu, for example "Family History." The page youre creating is "1860-1899." When you build the menu entry, youll 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. [Dont 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. Dont worry if you dont 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 pages address (or name) on the web." It is the "name" by which a browser identifies a page to display. Weve 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." Thats all fine and well for Drupal, because it understands that. But your visitor really doesnt 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 youd want it), then youll see a section on the edit page that says "URL path settings." So lets 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. Thats absolutely true. But then its 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 its 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 browsers address field, youll 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. Theres 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 browsers 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.
211
Drupal Handbook
3 Aug 2007
Heres 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, its 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 youve 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. Dont panic if everything looks strange, or even blank. In the URL bar, append "update.php" and press Enter. If it says you dont have the access rights, dont worry. Using Notepad or similar text editor, open "update.php". Near the top, you will see: // Enforce access checking? $access_check = TRUE; Change it to FALSE and save it. Try "update.php" again. If you have any errors listed, search the Drupal site for fixes. Theres a good chance that someone else has had the problem. If it appears to be a new error, post a request for help. Take your site out of maintenance mode and plan to start over when its fixed. Change $access_check back to TRUE. If you had a custom theme, you probably need to re-enable it for the site to look right. Now check out all your module settings. Theyll probably be okay. Look through your content, especially the front page. Make sure your menus are correct. Check out any content that uses custom code, especially if you are changing Drupal versions. Does everything check out? Good, youve done all the real work. Now the easy(er) part. Okay, now its time to do the damage. For me, the rest of this takes less than 15 minutes, so the outage to your users is minimal. If your current site was installed with Fantastico, delete the current installation. If not, then you have to manually remove all the folders. Now tell Fantastico to install the current version. Leave the directory field blank to put it in your "root" directory (probably "public_html"). The userid and password you supply will be your "super user" (user/1). When it is done, I always tell it to email me the installation summary.
8. 9. 10. 11.
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 thats 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." Theres 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 dont know why they leave it out, other than they dont use it. You may need it later.
4. name of your database - or your Drupal database if you have several databases.
Select
the
213
Drupal Handbook
3 Aug 2007
5.
6. 7. 8.
The next screen will show you all the tables inside your Drupal database. Ignore those, and click the "Export" tab on the top set of tabs.
214
3 Aug 2007
Drupal Handbook
9.
Look at the left box at the top of the Export section. All the tables in the database you selected are in that box.
If you have other programs that use the database, then choose only those tables that correspond to your Drupal installation. If you only have Drupal installed, in the left column, click "Select All." 10. Ensure that the SQL button is selected too. 11. 12. In the Structure section tick the following boxes: Structure, "Add DROP TABLE," "Add AUTO_INCREMENT," and "Enclose table and field names with backquotes." 13.
215
Drupal Handbook
3 Aug 2007
14. In the DATA section leave the boxes inside this section unticked, but make sure to keep the check box next to the "DATA" heading checked. 15. 16. Tick the "Save as file" option, and leave the template name alone. 17. 18. For now, select "None" for compression. 19. 20. Now click "Go" and you should be prompted for a file to download. Save the file to your computer. Depending on the database size, this may take a few moments. 21. You have now backed up your database! (Not so bad, was it?) Once that download is complete, you may check the "zipped" option, click "Go", and download the next file. If you want, you can download a backup in each of the compression formats. Your choice.
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 ("Thats 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 hosts 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 dont have shell access. But I did, for some reason, check the "Advanced" mode on cPanel again. I noticed that there was now a helpful hint there (of course in a small font). It said to use GET http://nanwich.info/cron.php (obviously, use your own URL). I did and the error messages went away and Cron is working great! For Cron jobs another possibility is http://drupal.org/project/poormanscron For every page view, this module checks to see if the last Cron run was more than 1 hour ago (this period is configurable). If so, the Cron hooks are executed, and Drupal is happy. These Cron hooks fire after all HTML is returned to the browser, so the user who kicks off the Cron jobs should not notice any delay.
N. Categories (Taxonomy)
You will see a lot of posts on the Drupal site about creating and using a Taxonomy (or "vocabulary" and "terms"). Most of those posts will be over your head - many are still way over my head. While it is true that the more content you have the more obvious the need for a taxonomy becomes, there is certainly no reason why a smaller website that has things to classify cant 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, Ill 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 didnt 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, Entres, Desserts, etc. So lets set up those things as a "vocabulary" with which we can organize the recipes. 1. Go to Administer>>Content management>>Categories and click on the "Add vocabulary" tab. 2. Enter the name, for example "Recipes." Then a "Description" like "Our community cookbook." 3. Select the type of content this applies to. The Recipe module introduces a "recipe" type. 4. I selected a "single" hierarchy. Later on, if the number of contributions gets large, I can always add sub-categories (like "Beef," "Poultry," and "Pork") and change to multiple level hierarchy. 5. I then selected "Required" to force the users to choose a category for any recipe they enter. Thats it for the "vocabulary," so click on the "Submit" button. Youll go back to the Categories list. You should see your new vocabulary listed. Towards the right, youll see a link to "add terms." Click on it. 1. 2. 3. 4. 5. Since this is a single level hierarchy, the "Parent" should say "<root>." In "Term name" enter your first term, such as "Appetizers." Enter a "Description" such as "Things for before the meal." Dont worry about the rest yet, just click the "Submit" button. 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 theyll see a list of categories that they can browse. That wasnt 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 cant 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 dont want anonymous users to see "Create content." - "Create content" is actually a child menu item of "Content" which is usually disabled. Go to your menus administration screen and enable the "Content" parent above "Create Content." Then you will see a "Reset" link appear. Click on that. Once again, "Content" will be disabled, but "Create content" will not be shown to anyone who does not have the access permissions to do so (especially anonymous users). Also read the handbook section Troubleshooting FAQ
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 youre 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>
220
3 Aug 2007
Drupal Handbook
Heres part of my home page. As you can see, I have links for all my maintenance tasks (cPanel, FTP, etc.) included, so I dont 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. In order for you to login, I offer two techniques: Enter http://www.myexample.com/user (or, if you dont use Clean URLs, http://www.myexample.com/?q=user). Yes, it is the word "user" -- not your user ID. Go to your Site information settings and stick a "login" link in the footer. <a href="/user">login</a> I do this on several sites.
221
Drupal Handbook
3 Aug 2007
S. More Reading
Now that youre 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 developers 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. Im 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! Thats 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? Lets try to relate this to an example youre probably familiar with. Lets 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, lets 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. Its a bit of a stretch for several reasons, but you can then think of Windows itself as your browser, since it is responsible for the final rendering of the content to you. Does that help a little? The Structured Query Language (SQL) is a standard specification for how database engines locate data that you want. An example might be SELECT country FROM user_profile WHERE username = "Nancy"; this would get the value from the column "country" in the "user_profile" table using column "username" as the key.
225
Drupal Handbook
3 Aug 2007
Moving Drupal
As of version 5, moving the Drupal base folder shouldnt 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.
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.
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 its 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.
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.
229
Drupal Handbook
3 Aug 2007
230
3 Aug 2007
Drupal Handbook
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.
Module blocks
Module blocks are available when modules are enabled. These blocks can be administered in block administration.
232
3 Aug 2007
Drupal Handbook
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.
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.
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
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 theres 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 theyll see an outline tab, and by clicking it theyll come to an interface that lets them move the post into a book. You can: create new book pages: create content >> book page. administer individual books (choose a book from list): administer >> content >> books. set workflow and other global book settings at administer >> settings >> content types >> book page. enable the book navigation block: administer >> block. control who can create, edit, and maintain book pages at administer >> access control.
237
Drupal Handbook
3 Aug 2007
This means that you cant 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.
After you have submitted this book page, you are ready to begin filling up your book with questions that are frequently asked. Creating new pages for your FAQ. The process for creating new pages in your FAQ is very similar to above. When choosing the Parent option, select the FAQ book page that you already created to add it to the book. Adding existing non-book pages to your FAQ. Whenever you come across a post which you want to include in your FAQ, 1. Click on the outline tab at the top of the page. 2. Place the relevant post wherever is most appropriate in your book by selecting a Parent. Notes: Books are quite flexible. They can have sections like Flying to Estonia, Eating in Estonia and so on. As you get more experienced with the book module, you can reorganize posts in your book so that it stays organized. Any comments attached to those relevant posts which you designate as book pages will also be transported into your book. This is a great feature, since much wisdom is shared via comments. Remember that all future comments and edits will automatically be reflected in your book. You may wish to edit the title of posts when adding them to your FAQ. Clear titles improve navigability enormously.
238
3 Aug 2007
Drupal Handbook
Book pages may come from any content type (blog, story, page, etc.). If you are creating a post solely for inclusion in your book, then use the create content book page link. If you dont see the edit link or outline tab , then you probably have insufficient permissions.
239
Drupal Handbook
3 Aug 2007
To further organize your site, you can have groups of categories intersect. For example, intersecting your musical genres you might have a set of categories indicating times: seventeenth century, eighteenth century (perhaps with subcategories like "early eighteenth century" and "late eighteenth century"). So, using our "genre" vocabulary we might call an item by the term "sonata," and using our "times" vocabulary we might call it by the term "early eighteenth century." If we add a vocabulary for "composers," we might categorize the item three ways--as an "early-eighteenth-century" "sonata" by "Bach"--and locate it by any of these three terms. Working with vocabularies On the categories page (administer >> content management >> categories) you can create, view and manage your categories. Youll see a list of the vocabularies youve created, and you can edit each one. You can add new vocabularies, using the add vocabulary tab at the top of the page. Or you can edit an existing vocabulary by clicking the edit vocabulary link next to its name (in the "Operations" column). You choose a name for your vocabulary. You can give each one a description, which modules may use in different ways. (For example, when users hover over a link that displays this vocabulary, they may see your description.) You can tie your vocabulary to particular "content types"--"story," "book page," or whatever. Then when users create content of a particular type, theyll see a list of your vocabulary terms that go with it. Users can then categorize their post by choosing from the list. (You can also give your vocabulary a help text to help your users choose.) You can make choices about the hierarchies for your vocabularies. If you want all the terms to be on only one level, choose "disabled." To allow your terms to have one (but only one) level of terms below them, choose "single." And if you want to allow still further levels, choose "multiple." You can allow "related terms." If you allow "free tagging," when your users create content they can make up their own terms as they go along, instead of having to choose from a list. By choosing "multiple select," you can allow your users to put a post into more than one category at once by tagging it with more than one vocabulary term. Also, if you like, you can require that when your users create content of a certain "content type" they assign at least one of this vocabularys terms. You can decide the order in which your vocabulary will appear in lists by assigning to it a "weight." Finally, if you like you can delete the vocabulary altogether, thereby also deleting all its terms. Working with terms To view or manage the terms of each vocabulary, click on its list terms link. On the list terms page you can edit each term by clicking the edit link. Now, on the edit term page you have several kinds of choices.
240
3 Aug 2007
Drupal Handbook
If youve allowed this vocabulary to have a hierarchy, you can put the term in its place in the hierarchy by choosing the terms "parent." You can select from this vocabulary one or more terms with which youd 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. Theres no such thing as a "nameless term.") You can list synonyms for your term. (In taxonomy lingo, youre creating for your vocabulary a "thesaurus.") You can decide the order in which your term will appear in lists by assigning it a "weight." Or, finally, if you like you can delete a term altogether. To add new terms to your vocabulary, click its add terms link. (The list terms page also has an add terms link that does the same thing.) When you add new terms you have the same options as when you edit them. Using categories in menus The menus on your site can call for items that match specific taxonomy terms--that is, terms youve named your categories. Heres 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 terms number, go to the categories page, choose list terms for the category to which your term belongs, and now hover over your terms name in the list. Youll 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, youd 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.
242
3 Aug 2007
Drupal Handbook
Action_feed-you to receive and classify incoming e-mails from many organizations taxonomy_assoc The taxonomy_assoc module lets you display a node - along with the usual node listing for that term - when you view a taxonomy term. The node can be used instead of (or as well as) the description that taxonomy_context outputs. Unlike raw descriptions, however, nodes can be commented on, can have filters applied to them, and can be used in a number of other ways. taxonomy_block This is a simple module to create blocks based on taxonomy. It displays listings of recently posted nodes based on taxonomy definitions. You can create as many blocks as you like. taxonomy_browser Think of this as a build your own category view page. Users select the terms they want to see, and are redirected to the right URL (e.g. taxonomy/term/3,4,5), which displays the matching content. taxonomy_context The taxonomy_context module enables you to display several useful types of information drawn from taxonomy terms. By default in Drupal, when you bring up a taxonomy term you get a list of "node" (stories, static pages, books, etc.) associated with that term--but nothing to describe the term itself. But for organizational websites one often wants to display information like a title and description of the current section. So this module includes several methods for displaying information about taxonomy terms: * breadcrumbs * the current term * listings of sub-terms of the current term taxonomy_defaults This module provides the ability to set default taxonomy terms per node type. taxonomy_dhtml A page listing recent nodes on your site, organized by taxonomy term. Also provides a block for each vocabulary, listing terms and their node counts. Finally, a box is exported to the syndication.module main page. taxonomy_hide This module enables to setup list of vacabularies which terms will not be listed in reference term list during node view. It enables also grouping terms by vocabulary as well. taxonomy_html This module adds an HTML representations of sites 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 terms 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.
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 its likely to be going to get too big, and is probably badly designed. Example (sort from an online arts shop) - Traditional Arts Single Select Europe -Lapp -Sami -Celtic Australia -Aboriginal This represented the way the shop classified their items. But as such it prevents some clients saying "show me European Art". Multiple Select is an option but much better to have two Vocabs - one for Region and one for Culture, make them both multi and a collector could say "What have you got which is Lapp, or Celtic or Chinese?" 3) Too Many Terms "Perfect" taxonomies are always too complex and you need to fight to make them more manageable. (Esp if you have just cut up a few Parent Child vocabs into several smaller ones each...) The advantage of VIEWS is that the multiple taxonomy terms start to build context, and that can be captured by views. There are not many sites that ever need to show more than 3-4 filters to users, even if there are 5-6 more hidden ones . Plus building them into structure adds even more granularity. Eg a site for ALL the small towns of America, where people are interested in their little towns stuff, using Book for basic structure:Top level - States - 50 items Off each State - Counties Off each County - settlements Click the named settlement and a get a VIEWS screen with filters for News, Culture, Announcements.
245
Drupal Handbook
3 Aug 2007
(Hidden filters in the Views filter by State/County/Settlement) Highly non scary - any users can use that to get what they need. 4) Clients are not experts on taxonomy, not even their own Taxonomy is a communications issue and if there is a budget for the site its always worth running it past an outsider - but note that they will need to get to understand the purpose of the site and also to an extent the jargon of the subject. This normally requires a least one decent face to face meeting to force the client to decide what is important, and what can be cut out. (Trust me, these decisions will have to be made, and if they are not, then people are probably not thinking carefully enough.) 5) Taxonomy creates Legacy issues - SO GET IT RIGHT Once you have a load of tagged data, its hard to make changes to taxonomy structures (apart from adding terms) without rendering existing nodes much harder to find. Trust me, NO ONE will go back and edit existing data, not in real life, unless there is massive funding for that purpose. 6) Taxonomy is trial and error. It should be the first thing you do on a site, but by adding test data youll find flaws, and refine and eventually go live with something that works. In between times you solved the CSS and templating... I once spent 3 days testing different ways to classify cars for one site - the makes/models complexity of past 20 years is a nightmare, and which there are several ways ot do it, all of which work, some are more userfriendly than others! Hope this helps. Ian Dickson - community specialist with a sideline in taxonomy because its the buidling block for EFFECTIVE social software... .
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.
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 terms descendents subterms are displayed.
253
Drupal Handbook
3 Aug 2007
Taxonomy ticker Provides a block displaying titles of nodes in a scrolling news ticker.
254
3 Aug 2007
Drupal Handbook
Taxonomy_theme Inserting Taxonomy Images into nodes Seperating free tagging from categories Taxonomy multi-edit Edit the taxonomy designations of multiple nodes at once, without having to select each node individually. Simplifies changing a large number of nodes from one taxonomy classification. In admin/categories, a tab is added to "assign categories." Every node with at least one taxonomy designation is displayed in a table, with the first column being and the remaining columns being the available categories.
255
Drupal Handbook
3 Aug 2007
Taxonomy_image Attach an image to each node in specified taxonomies based on terms. Child terms can have parent images if no images are designed for child terms. In admin/settings/taxonomy_image, admins can set the basic settings for the module. In admin/categories an additional tab is added to allow users to upload one image per taxonomy term. After inserting appropriate function calls to display_taxonomy_image() in the theme, images will be displayed with nodes.
256
3 Aug 2007
Drupal Handbook
Taxonomy_theme In one taxonomy, each term can be mapped to a theme that will display when the node is display on its own. In an admin/settings submenu, the module can be enabled or disabled. One taxonomy can be selected. Each term can be mapped to a theme. If it is not mapped, it gets the site default theme.
257
Drupal Handbook
3 Aug 2007
Views The views module is a query building module that can display a listing or table of results. Views can include filters to limit results by a variety of criteria. This module does not specifically organize nodes, but allows retrieval of pre-categorized nodes. In admin/views, users can create a view entering appropriate values into a form. The form has the following subsections: display, block, table, URL, arguments, filters, and sorting. If a URL is specified, a menu item can be added for later retrieval. The view can be stored for later use, or use by other modules. Views can be displayed directly as well.
258
3 Aug 2007
Drupal Handbook
Taxonomy_default This module automatically tags posts for which the taxonomy is not activated (in the categories admin section). For posts where the taxonomy is active, the tags are simply preselected. In admin/settings/taxonomy_defaults, a section is created for each content type. Each content type can set preselected tags in any vocabulary. For enabled vocabularies, the word "active" is not italicized. For non-enabled vocabularies, the word active is italicized. When entering a node, in-active vocabularies are not shown, but the term(s) are automatically added to nodes. For active vocabularies, the terms are pre-selected. In either case, the terms are visible when the node is rendered.
259
Drupal Handbook
3 Aug 2007
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 Slashdots sections. For more complex implementations, you might create a hierarchical list of categories. Sites can also use folksonomies. By checking the "Free tagging" option when creating a vocabularly, users can create and enter their own tags for their content. You can add a vocabulary at administer >> categories >> add vocabulary. administer categories at administer >> categories.
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 brothers wedding, you might select a Photo Type of Portrait, a Location of Paris (if thats where he was married, naturally!) and type in wedding and brother as keywords. If youre used to other CMS or blogging systems, these different vocabulary types might be familiar as categories or sections or keywords. Its 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 sites organization, the results are worth it.
262
3 Aug 2007
Drupal Handbook
System requirements: You need an installation of Drupal 4.7 with admin permissions. Basic terminology: Taxonomy: The name of Drupals core (included) module for classification. Category: The label used in the Administer area for configuring taxonomy. Also, the name of a contributed (add-on) module for classification. Vocabulary: A group of taxonomy terms. Term: A label (of a taxonomy vocabulary) that can be applied to an item. Labels, Tags: other words that are sometimes loosely applied to mean the same thing as "Term." Scenario: Starting a news web site You have been asked to create a web site for a news company. They want to organize web content according to the topic of the story. The topics are Politics, Technology, Business, and Lifestyle. Stories may be about just one topic, or they may be about more than one. For instance, a story may be about both technology and business. Step 1: Plan your content structure. How will you organize content in the web site? In our scenario, our client wants to categorize stories as Politics, Technology, Business, and Lifestyle. Step 2: Create a vocabulary. After logging in to Drupal, go to (administer > categories) and click the "add vocabulary" tab. In the add vocabulary screen, type "Topic" as the Vocabulary name. Next, you need to tell Drupal that the vocabulary "Topic" will be used by the Story content type. To do this, check the story checkbox under Type. This step is called binding a vocabulary to a content type. Next, click the checkbox called Multiple select. This allows selecting more than one taxonomy term for each story. At this point, you will see many other options. Ignore them for now and play around with them later. Step 3: Add terms under your vocabulary. We now need to tell Drupal what labels are available under the Topic vocabulary. To the right of the categories screen, click add terms. In the screen that follows, type a Term name (e.g.: Politics) and click submit. Repeat this for each of the terms under Topic. You can now review your vocabulary. To the right of your Topic, click list terms. You will see something like this:
263
Drupal Handbook
3 Aug 2007
Topic --Business --Lifestyle --Politics --Technology This gives you an idea of the content structure so far. Step 4: Now try it out by creating a story. In the administer menu, click create content > story. Now you see the newly created Topic tags near the top of the form. Type a Title, choose Technology as the Topic, and write some text in the Body field. Click Submit. You have just uploaded content (a story) and tagged it as Technology. Upload three other stories and multi-tag them according to the plan below. (To multi-tag, just Ctrl-Click one item after another.) 1 story - Business, Technology 1 story - Lifestyle, Technology, Politics 1 story - Business, Politics Now youre seeing a bit of the power of Drupal. Step 5: Exploit Drupals linking system. Now youll get more glimpses of Drupals 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; itll 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 Drupals power by exploiting term numbers. Thats the end of this scenario of our tutorial.
264
3 Aug 2007
Drupal Handbook
Meanwhile, you can play around with the taxonomy module further. Try out the other options and test the results by creating different stories. When you are ready, go to Scenario 2 (coming soon), which will teach you to harness more power from vocabularies. References to other beginning-level taxonomy pages (in order): Understanding categories for new users Advanced taxonomies: using hierarchies More about Taxonomy
265
Drupal Handbook
3 Aug 2007
taxonomy/term/1+2/0/feed Building individual Taxonomy URLs 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.
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).
268
3 Aug 2007
Drupal Handbook
How is it done? Theres a technical and a storytelling explanation. Lets begin with the technical explanation: The taxonomy module allows you to define vocabularies which are simply a collection of terms (similar to Gmail "labels" or Flickr "tags"). You can define 2 kinds of relationships between terms: * Hierarchical: indicates a parent-child (vertical) relationship like cat and dog are children of mammals) *Assocation: indicates a "similar to" (horizontal) relationship like mammals is similar to animals. Using these relationships, the taxonomy module allows multiple lists of categories for classification (or controlled vocabularies) and offers the possibility of creating thesauri (terms with horizontal relationships) and taxonomies (terms with hierarchical relationships). To delete a term choose edit term. To delete a vocabulary, and all its terms, choose edit vocabulary. {comment: The emphasized sentence actually sounds out of place here. Please suggest how it can be reorganized.} {factor next para into the main text}A controlled vocabulary is a set of terms to use for describing content (known as descriptors in indexing lingo). Drupal allows you to describe each piece of content (blog, story, etc.) using one or many of these terms. For simple implementations, you might create a set of categories without subcategories, similar to Slashdots 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 websites "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): Abels music website grows and it now contains stories, blogs and forum discussions. Beth and Ching are both contributors to Abels site. As they post content, they are also asked to tag their contributions. {to be continued} Its Case 3 that I am most interested in.
269
Drupal Handbook
3 Aug 2007
Im 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 its 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 dont". 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 whats hot, whats not, whos 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 OLaguna
270
3 Aug 2007
Drupal Handbook
You will need to create a new Block of type=php. You will then want to paste in the code below, and customize the Physicians subject and the $tax array. $tax the list of tids that you are inetrested in. The third element, named operator, can be and or or. So in your case, assuming the term ID for movies is 3 and the term ID admin/taxonomy/edit/term/3 for Anime is 6 admin/taxonomy/edit/term/6, you want: <?php // paste this code into a custom block of type=php // customize the $tax array and the $subject as needed $tax = array(3, 6); $operator = "or"; $result = taxonomy_select_nodes($tax, $operator); while ($obj = db_fetch_object($result)) { $node = node_load(array(nid => $obj->nid)); $items[] = l($node->title, "node/". $node->nid); } return theme(item_list, $items); ?> A Block that returns the first 5 terms for a taxonomy <?php $taxo_id = 3; $sql = "SELECT node.title, node.nid FROM node INNER JOIN term_node ON node.nid = term_node.nid WHERE term_node.tid = $taxo_id LIMIT 5"; $output .= "<ul>"; $result = db_query($sql); while ($anode = db_fetch_object($result)) { $output .= "<li>".l($anode->title, "node/$anode->nid")."</li>"; } $output .= "</ul>"; return $output; ?>
271
Drupal Handbook
3 Aug 2007
$result = taxonomy_select_nodes(array2object($tax), 0); while ($node = db_fetch_object($result)) { $output[] = l($node->title, "node/". $node->nid); } return (theme_item_list($output)); }
272
3 Aug 2007
Drupal Handbook
Threaded Displays the posts grouped according to conversations and subconversations. Flat Displays the posts in chronological order, with no threading whatsoever. Expanded Displays the title and text for each post. Collapsed Displays only the title for each post. When a user chooses save settings, the comments are then redisplayed using the users 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).
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.
275
Drupal Handbook
3 Aug 2007
For each category, you can specify whom youd like to have receive your users 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 youd like to show on your site-wide contact page. And you can limit how many times a user can contact you in an hour. You can view user profiles. let each user enable a personal contact form in my account. administer contact at administer >>contact.
276
3 Aug 2007
Drupal Handbook
run your cron job manually at your sites cron page. view the XML-RPC page. administer Drupal administer >> settings >> drupal.
Old page
The "Drupal" module features a capability whereby other drupal sites may call home to report their existence. In turn, this enables a pod of Drupal sites to find, cooperate and advertise each other. Currently, the main application of this feature is the Drupal sites page. By default, fresh Drupal installations can use drupal.org as their directory server and report their existence. This reporting occurs via scheduled XML-RPC pings. Drupal administrators should simply enable this feature to get listed on the Drupal sites page. Just set your sites 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 sites 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, dont 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.
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.
278
3 Aug 2007
Drupal Handbook
279
Drupal Handbook
3 Aug 2007
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 modules import feature allows you to add strings from such files into your sites database. The export functionality enables you to share your translations with others, generating Portable Object files from your site strings. You can administer localization at administer >> localization. manage strings for the localization: administer >> localization >> manage strings. add a locale language: administer >> localization >> add language. download translation files from the Drupal translations page.
281
Drupal Handbook
3 Aug 2007
There should be no need to leave this values that way once youve imported a big .po file. If youre confident the new settings wont hurt your webservers performance or security just leave them that way. Otherwise return them to the previous settings (even when its highly iikely that youll need to readjust them whenever you perform an upgrade or reinstall)
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 sites interface and you are done!! To avoid this painful process, there is an option of Importing a translation scheme (so we can actually import entire Marathi translation of Drupal interface in a single click). However, unfortunately, there is no standard Marathi Translation of Drupal interface available yet! So we have to wait for someone to write it or follow this string by string translation process! If you need a Marathi Transliteration Typing interface for your site (so that your users can type in Marathi using normal English keyboards), you may try a module called as UniSaraswati (http://drupal.org/project/unisaraswati) specifically written for this purpose If you need generic help about computing in Marathi, you may get it on Marathi Wikipedia http://mr.wikipedia.org You may find the examples of marathi sites created using Drupal at: www.sadha-sopa.com (Drupal 4.7) www.marathigazal.com (Drupal 5.1) www.miloonsaryajani.com (Drupal 5.1) Prasad Shirgaonkar
283
Drupal Handbook
3 Aug 2007
5. Assuming English, create a custom language by adding en-US in the Language code text field. 6. Give your language a name, such as custom-English (be sure not to use spaces in your language name), and add the language. 7. This will return you to the main localization page. Set your new language as enabled and as the default. 8. Save the configuration. 9. Then disable the original English language set (that is, unless you would like users to be given the option to choose between the two in their account area). Now, any time you visit a page with Drupal hard-coded content, it will be added into your language set database. Once you have visited a page that you wish to change the content: 1. Go to the manage strings page (admin/locale/string/search) of the localization section. 2. Enter in the string you wish to search for. 3. Edit the result and enter your replacement text.
HOWTO: Use a customized language set to change Drupal text and terminology
Depending on your particular application, you may find that the default text or terminology used in the Drupal core or a contributed module doesnt suit your style or need. Customizing this text with the locale module is fairly simple and is portable if you create an additional site up upgrade your version of Drupal or a contributed module. As simple examples, you might wish to change the "Search" button to say "Find", or you might wish that comments were shown as being "Posted by" rather than "Submitted by" a particular user. As a more advanced possibility, you might wish that the things described by Drupal as "forums" were instead called "bulletin boards", and that you could change this in every context where the word "forum" is used. The locale module is a well-developed system for handling this situation. While described as a system for making translations, it will also efficiently substitute your prefered terminology for the default Drupal terminology. You should first read the instructions for Creating a customized language set to replace Drupal terminology. After following the steps outlined there to create your custom language, this page is intended to provide additional step-by-step and detailed instructions for those new to Drupal. Again, before proceeding, follow the instructions in the first section at http://drupal.org/node/24593 to enable the locale module, create a customized language, and make it the default language. If you are not user #1, a user with appropriate access will need to go to the access control page at administer >> access control and enable "administer locales" for your user role.
284
3 Aug 2007
Drupal Handbook
Next, rather than searching for individual strings through the interface at administer >> localization, youll probably find it easier to use a template file and then import the "translated" strings. So, download the translation templates from the appropriate version of Drupal. Some contributed modules will also include a translation template in a "po" directory. In the downloaded directory of templates, you will see numerous template files ending in ".pot". The file "general.pot" contains strings that are reused in several modules. Open this in a text editor and look it over. Following through on the simple examples above, we can find these strings in the file in the following form: #: includes/locale.inc:327;346 modules/search.module:142;996 modules/system.module:1198 modules/user.module:1958 msgid "Search" msgstr "" Edit the file so as to specify a replacement text, such as: #: includes/locale.inc:327;346 modules/search.module:142;996 modules/system.module:1198 modules/user.module:1958 msgid "Search" msgstr "Find" Similarly, we can change the text shown by each comment by making a change to this entry: #: themes/engines/phptemplate/phptemplate.engine:250;273 msgid "Submitted by %a on %b." msgstr "Posted by %a on %b." Note that the text following the "#:" is for information only and does not affect the outcome of this process. From here, save your edited file somewhere handy (you might keep it together with your local copy of your customized theme). Now go back to administer->localization and choose "import" from the top tabs. Browse and choose your edited translation file, and then import it into your customized language. Voila, you should see that the name of the Search box it changed to "Find", etc. For a more sweeping change, you could open the "forum-module.pot file", and provide an alternate term every place the word "forum" is used. For example, you could edit the following entry as shown: #: modules/forum.module:51;110;216 msgid "forum topic" msgstr "bulletin board subject" Additional help and techniques for using the locale module and generating substitute text can be found in the Translators guide.
285
Drupal Handbook
3 Aug 2007
Search is a t-ified string, which means it can be replaced by using the locale module.
286
3 Aug 2007
Drupal Handbook
The expected behavior is that when a link that points to this named anchor is clicked, the users browswer should jump to a to the anchor tag on the html page, making it appear at the top of the users browser window. This desired behavior can be accomplished by adding the following function to your themes template.php file: function phptemplate_menu_item_link($item, $link_item) { // Convert anchors in path to proper fragment $path = explode(#, $link_item[path], 2); $fragment = !empty($path[1]) ? $path[1] : NULL; $path = $path[0]; return l( $item[title], $path, !empty($item[description]) ? array(title => $item[description]) : array(), !empty($item[query]) ? $item[query] : NULL, $fragment, FALSE, FALSE ); }
287
Drupal Handbook
3 Aug 2007
search for content at search. administer all nodes at administer >> content management >> content. administer workflow and other default settings for individual node types at administer >> content management >> content types. configure the number of nodes to display on the main page and the length of trimmed posts at administer >> content management >>post settings. set access permissions for various node types at administer >> user management >> access control.
288
3 Aug 2007
Drupal Handbook
A page doesnt post author information, timestamps or comments by default. A story does post author information, timestamps or comments by default. It is still possible to configure a story and a page to be exactly the same. Drupal core now also allows administrators to edit the names of page and story to anything you want and create your own different types of content that suit the needs of a specific site.
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 Drupals source code. You can set the path for a post with the path module. add a URL alias: administer >> url aliases >> add alias. administer the list of URL aliases: administer >> url aliases. read how to configure clean URLs for your webserver. enable Clean URLS to remove the =? at administer >> settings in the General settings area. automate URL alias creation by installing and using the pathauto module.
290
3 Aug 2007
Drupal Handbook
return preg_replace(!^node/(\d+)$!, display/\1, $path); } } ?> This function will shorten every node/$node_id type of URL to display/$node_id. Individual URL aliases defined on the browser interface of Drupal take precedence, so if you have a contact page alias for example, then the display/3 alias will not be effective when outgoing links are created. Incoming URLs however always work with the mass URL aliased variant. Only two modes are supposed to be supported by your custom function. You cannot only use this feature to shorten the URLs, or to translate them to you own language, but also to add completely new subURLs to an already existing modules 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 Drupals inner workings and regular expressions though to make such advanced aliases.
291
Drupal Handbook
3 Aug 2007
*/ function ping_ping($name = , $url = ) { $result = xmlrpc(http://rpc.pingomatic.com, weblogUpdates.ping, $name, $url); if ($result === FALSE) { watchdog(directory ping, t(Failed to notify pingomatic.com (site).), WATCHDOG_WARNING); } else { watchdog("directory ping", t(successfully notified pingomatic.com (site).), WATCHDOG_NOTICE); } unset($result); $result = xmlrpc(http://rpc.technorati.com/rpc/ping, weblogUpdates.ping, $name, $url); if ($result === FALSE) { watchdog(directory ping, t(Failed to notify technorati.com (site).), WATCHDOG_WARNING); } else { watchdog("directory ping",t(successfully notified technorati.com (site).), WATCHDOG_NOTICE); } unset($result); $result = xmlrpc(http://ping.blo.gs, weblogUpdates.ping, $name, $url); if ($result === FALSE) { watchdog(directory ping, t(Failed to notify blo.gs (site).), WATCHDOG_WARNING); } else { watchdog("directory ping", t(successfully notified blo.gs (site).), WATCHDOG_NOTICE); } unset($result); } - David Herron - http://7gen.com/
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 havent already) and view the results. On the access control page (administer >> access control) you can decide which users have permission to vote, to see the voting results, and to create polls of their own. You can see some sample polls on Drupal.org. You can view the polls page. administer >> settings >> content types >> poll.
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 users 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 users 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 users 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 sites 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. (Youll find the permissions for profiles under "user module.") In any case, the profiles are always accessible to your site administrators. Contributed modules can also deploy the fields in user profiles to do much more with them. Such modules, for example, can help community-based sites identify and organize users through their profile fields. You can view user profiles. administer profile settings: administer >> settings >> profiles.
294
3 Aug 2007
Drupal Handbook
Drupal 4.7 allows you to enable avatars at administer settings users (admin/settings/user).
295
Drupal Handbook
3 Aug 2007
1. Create a new profile field. 2. Go to the profile settings page (administer > settings > profiles ?q=admin/settings/profile) 3. Select the list selection type of form field. 4. Category (required): It can be a category you already have or a new one. (Suggested: Personal Information) Title (required): Anything is OK. (Suggested: Country) Form name (required): Anything is ok, as long as it is unique. (Suggested: profile_country) Explanation (optional): Usually, country is self explanatory, but you may want to write a note here to your users about this field. Selection options: Copy the list from the attached file here. This file is from Wikipedia (http://en.wikipedia.org/wiki/List_of_countries May 2006) Weight: Select whatever you like (this is the weight in the category selected above). Visibility: Select one of the Public Field options. Page title (required): You must put something here. (Suggested: People who live in) Check boxes: Check the user must enter a value to make this field required. Check visible in user registration form to make it part of user registration. 5. Click on Save field.
296
3 Aug 2007
Drupal Handbook
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 sites 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 theres 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 its 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.
298
3 Aug 2007
Drupal Handbook
Node count displays the number of times a node has been accessed in the nodes link section next to # comments. Configuring the statistics module Enable access log allows you to turn the access log on and off. This log is used to store data about every page accessed, such as the remote hosts IP address, where they came from (referrer), what node theyve viewed, and their user name. Enabling the log adds one database call per page displayed by Drupal. Discard access logs older than allows you to configure how long an access log entry is saved, after which time it is deleted from the database table. To use this you need to run cron.php Enable node view counter allows you to turn on and off the node-counting functionality of this module. If it is turned on, an extra database query is added for each node displayed, which increments a counter. Display node view counters allows you to globally disable the displaying of node view counters. You can administer statistics administer >> setttings >> statistics. access statistics logs administer >> logs. view recent hits administer >> logs >> recent hits.
299
Drupal Handbook
3 Aug 2007
Some of Drupals 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 sites content. All of these services rely on cron. Cron (which stands for chronograph) is not a part of Drupal. Its 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 youd 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 whats 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 Drupals 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 modules caching mechanism stores dynamically generated web pages in a cache--a stockpile--and reuses them. The pages on your site, rather than being never-changing sets of text and images, are all (or nearly all) likely to use elements pulled together "on the fly" from various parts of your database. Such pages are said to be "dynamically generated." By caching such pages, the system module keeps them ready to use again, instead of having to create them again each time someone wants to view them. This way, displaying a page takes only one database query instead of several. Queries take time and system power, so caching lightens the load on your system and lets it respond more quickly. Only pages requested by anonymous users are cached. To reduce server load and save bandwidth, the system module stores and sends cached pages compressed. You can run your cron job manually at your sites cron page. read about configuring cron jobs. administer cache settings in administer >> settings in the Cache settings area.
300
3 Aug 2007
Drupal Handbook
301
Drupal Handbook
3 Aug 2007
Cron doesnt guarantee your commands will run at the specified interval. But Drupal will try its best to come as close as possible. The more you visit cron.php, the more accurate cron will be. Some guidelines of a more technical nature: Take a look at the example scripts in the scripts directory. Make sure to adjust them to fit your needs. For example, the cron-lynx.sh file contains the line: /usr/bin/lynx -source http://example.com/cron.php > /dev/null 2>&1 Enter: whereis lynx from your shell to make sure lynx is located at /usr/bin/lynx (if not, adjust the path as needed). Also change http://example.com/cron.php to the location of your Drupal installation (for instance, http://www.example.com/drupal/cron.php). A good crontab line to run this cron script once every hour would be: 00 * * * * /home/www/drupal/scripts/cron-lynx.sh Note that it is essential to access cron.php using a browser on the web sites 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 doesnt give you permission to use a browser such as wget or lynx, there is also a script in Drupals /scripts/ directory called cron-curl.php which uses curl instead. Its also possible to write a simple PHP script which simulates a browser accessing your websites cron.php (using curl, fopen, or similar), and write a cron configuration which calls that instead.
302
3 Aug 2007
Drupal Handbook
45 2 * * * /home/user/script.pl The first number is the minute of the hour for the command to run on. The second number is the hour of the day for the command to run on. The third number is the day of the month for the command to run on. The fourth number is the month of the year for the command to run on. The fifth number is the day of the week for the command to run on. Here are some examples to help you learn the syntax for the numbers: 32 * * * * : will be run every hour on the 32nd minute. 12,42 * * * * : will be run twice an hour on the 12th and 42nd minutes. */15 */2 * * *: will be run at 0:00, 0:15, 0:30, 0:45, 2:00, 2:15, 2:30, ... 43 18 * * 7: will be run at 6:43pm every Sunday. You can also edit crontab on a local file. Upload it to a directory and run: crontab YourFileName Itll replace your crontab with whats on the text file, without having to edit it online. This is useful if youre using a telnet client which doesnt support ANSI control codes (such as the Windows one) and cant understand what the heck is going on on the editors. In my own experience, I found that only by entering one cron command per line worked (one line each for :10, :20, :30, etc.). I could not get crontab to take the "*/15" argument, so I worked around it. Also, if you have ANY character after the last command (space, CR, whatever) the file will not take. I like this file-load approach because I have a basic command file to edit or call up again if needed. Afterwards, running crontab -l will confirm that the job did take. I hope this helps people making new installations. --
303
Drupal Handbook
3 Aug 2007
e.g., 55 23,5,11,17 * * * /home/accountname/public_html/drupal/scripts/cron-lynx.sh (a cron run every 11:55pm, 5:55am, 11:55am, 5:55pm) 6. import this script into crontab by typing crontab cron.txt 7. type crontab -l to see your new jobs for site. Voila, much easier than I thought!
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
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, youd like the task to run under a user with fewer privileges security reasons). Click Next. 9. On the final page, select the checkbox Open advanced properties for this task when I click Finish and click Finish. Configuring the task 1. Go to the tasks 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 websites cron.php page in double quotations (for example, C:\PROGRA~1\MOZILL~1\firefox.exe http://www.example.com/cron.php 3. To set a frequency more often than Daily (for example, hourly), click the Schedule tab, then click Advanced. Here you can set options such as Repeat task, every 1 hour for 23 hours. Click Ok when finished. 4. Change the start time on the task to one minute from the current time. This will allow you to test the task and make sure that it is working. 5. When all settings have been configured to your liking, click Apply and OK (note: you may be prompted for your password) Command-line version Another way to perform the above commands is by using the schtasks (or at in Windows 2000) command from the command line. To duplicate the example above, which runs Firefox hourly to execute http://www.example.com/cron.php, open a command prompt (Start > Programs > Accessories > Command Prompt) and enter: schtasks /create /tn "Drupal Cron Job" /tr "C:\PROGRA~1\MOZILL~1\firefox.exe http://www.example.com/cron.php" hourly Enter your password if prompted. /sc
306
3 Aug 2007
Drupal Handbook
might choose to disable some complicated logic (reducing CPU utilization). The congestion control throttle can be automatically enabled when the number of anonymous users currently visiting the site exceeds the specified threshold. The congestion control throttle can be automatically enabled when the number of authenticated users currently visiting the site exceeds the specified threshold. You can enable throttle for modules at administer >> module. enable throttle for blocks at administer >> block. administer throttle at administer >> settings >> throttle.
307
Drupal Handbook
3 Aug 2007
308
3 Aug 2007
Drupal Handbook
You can view your user page. administer users at administer >> user. create new users at administer >> user >> add user. configure user registration, user email, and user picture settings at administer >> settings >> user. allow users to select themes from their user account by enabling themes in administer >> themes. read user profile help at administer >> help >> profile. configure access permissions at administer >> access control.
block module
administer blocks use PHP for block visibility
filter module
administer filters
menu module
administer menu
node module
access content Allows the user to view content. This should be enabled for all users, unless you want a private site. administer content types Allows the user to edit and add content types at /admin/content/types. administer nodes Allows the user to create, edit, and delete nodes of all types. This overrides all the create/edit own/edit options for specific content types below. This also exposes the Publishing options section when editing nodes, allowing users to promote content to the front page, publish and unpublish, make sticky, and create new revisions. create [TYPE] content Allows the user to create content of this type. This permission exists for page and story and each additional content type defined on the site. Overridden by the administer nodes permission.
309
Drupal Handbook
3 Aug 2007
edit own [TYPE] content Allows the user to edit content of this type that they have created. This permission exists for page and story and each additional content type defined on the site. Overridden by the administer nodes permission. edit [TYPE] content Allows the user to edit all content of this type. This permission exists for page and story and each additional content type defined on the site. Overridden by the administer nodes permission. revert revisions view revisions
path module
administer url aliases allows users the ability to administer the url aliases (modify, add, remove) create url aliases allows users to create url aliases
user module
access user profiles Can see user profiles; users without this set dont 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]. Then add 2 email address rules: Deny %@% (which should block everyone) and Allow %@allowed.com(which will allow people with anyone@allowed.com Thats pretty much all there is to it. Have fun with Drupal! ).
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.
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 wont have to re-authenticate. To keep track of the individual sessions, Drupal relies on PHPs session support. A visitor accessing your website is assigned an unique ID, the so-called session ID, which is stored in a cookie. For securitys sake, the cookie does not contain personal information but acts as a key to retrieve the information stored on your servers 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 dont 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 doesnt 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 doesnt exist in database. Retrieve user info and add user. if (! $result->uid) { $ldap_server = directory.appl.yourcompany.com; $ds=ldap_connect($ldap_server); if ($ds) { $r=ldap_bind($ds); $sr=ldap_search($ds, "o=yourcompany.com", "(uid=$user_tid)"); $info = ldap_get_entries($ds, $sr); $user_mail = $info[0][mail][0]; $user_name = $info[0][cn][0]; $user_number = trim($info[0][personalnumber][0]); # Use replace instead of insert to avoid errors in the event the uid has been added ahead of time, such as in the case of the administrators... db_query("REPLACE INTO {users} (uid,tid,name,mail,status,created) VALUES (%d,%s,%s,%s,1,%d)", $user_number,$user_tid,$user_name,$user_mail,time()); ldap_close($ds); } else { drupal_set_message(t(Unable to contact Ldap server %name., array(%name => check_plain($ldap_server)))); return; } } else {
314
3 Aug 2007
Drupal Handbook
# User exists in database. Set user info from there. $user_name = $result->name; $user_number = $result->uid; } # Log in, updating logs and redirecting to where the user requested, or home. Good stuff stolen from persistent login module. drupal_set_message(t(Authenticated via Ldap. Welcome %name., array(%name => check_plain($user_name)))); $l = array(ldap_auth_login => 1,name => $user_name,uid => $user_number); drupal_load(module, user); $user = user_load(array(uid => $l[uid])); user_login_submit(ldap_auth_login,$l); drupal_goto(substr(drupal_get_destination(), 12)); } ?>
NTLM Authentication
NTLM is a proprietary (and not so good) protocol for deploying Single Sign On in predominantly Windows oriented networks (our company network also). NTLM sits on top of HTTP, so users who are logged on to the Windows Active Directory network can transparently log-on to web services using their Microsoft Windows credentials (and thereby having Single Sign On). Getting IIS servers working with NTLM is easy (it should be), but traditionaly Apache servers have had problems in doing this. This document explains how to get NTLM authentication working in Drupal in Linux + Apache boxes. There are various methods for getting NTLM authentication working in Apache. mod_ntlm - This is an Apache module which will add NTLM support to Apache. However, this module is not very actively maintained, and getting it compiled and running in various Apache versions ( and various distributions ) is a herculean task. To top it, the compilation throws out a lot of warnings, and one tends to feel uncomfortable with it. mod_ntlm_winbind - for boxes that have Winbind ( 1, 2 ) configured, this module can be configured to provide NTLM authentication for Apache. However, this module is still under development and is not well tested. However, for the help of people working in such unfriendly conditions, there is an excellent perl module that provides good support for NTLM authentication. Follow the steps given below for getting NTLM authentication working. 1. Install/Configure mod_perl under Apache - (and get it working of-course) 2. Download the following files for doing NTLM authentication (the following files worked for us)
315
Drupal Handbook
3 Aug 2007
For Fedora Core systems download the module from http://search.cpan.org/~speeves/Apache2-AuthenNTLM-0.02/AuthenNTLM.pm For Debian Linux systems, download the module from http://search.cpan.org/~speeves/Apache-AuthenNTLM-2.10 Install the module tar xvfz Apache*AuthenNTLM*.tgz cd Apache*AuthenNTLM* perl Makefile.PL make make test make install Edit the Apache configuration and enable KeepAlive KeepAlive On Restart your Apache server. Configure apache to do the authentication. For eg in .htaccess add. # Enable the Authentication module PerlAuthenHandler Apache2::AuthenNTLM # Do NTLM and basic authentication AuthType ntlm,basic # The name that should be displayed in the Auth box, if NTLM fails AuthName OurCompany # Ask for a valid user. require valid-user # domain pdc bdc # Domain : Your windows domain # pdc : Primary Domain Controller # bdc : Backup Domain controller. # # Note : Multiple domains can be specified. PerlAddVar ntdomain "OURDOMAIN domainpdc domainsdc" # What should be the default domain PerlSetVar defaultdomain OURDOMAIN # The user names are in the form "OURDOMAIN\user_name". Let us split it. PerlSetVar splitdomainprefix 1 # Set the debug variables PerlSetVar ntlmdebug 0 PerlSetVar ntlmauthoritative off More documentation is available in the accompanying README file in the tarball or the following link Once this is done, the domain user is populated as REMOTE_USER in the http server variables, which can be picked up by any application for doing authentication.
316
3 Aug 2007
Drupal Handbook
Now we need to enable Drupal to pick up this user id and automatically create a user. Once we have NTLM authentication working, the user id is available as REMOTE_USER. The WebServer Auth module can use this variable to automatically log the user in. Download, install, enable and configure the Webserver auth module and you should have a Drupal setup which can seamlessly integrate into Windows AD based networks.
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.
318
3 Aug 2007
Drupal Handbook
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 sites 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 youre ready to log in.
Logging in
Before you can add or edit content, you usually need to log in. If you havent 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 youre 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 everythings 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.
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.
A step-by-step example
We will assume that you have selected create content and chosen "story" as a content type. You should be looking at a form with the title "Submit story". From here, it is just a matter of filling in the form and posting it. Administrative options At the top of the form you may see some administrative options. For example, there is a box with the heading User comments. Drupal supports discussion/comments on postings--but such comments are not always appropriate. If your article is one that could be usefully commented on, keep the default settings: "Read/write". Otherwise, choose "Disabled". Title The title is straightforward enough. Try to be descriptive and catchy.
321
Drupal Handbook
3 Aug 2007
Topic: (may not be visible if you do not have categories defined) Next comes the "Topic" menu. This is the section your article will go in--or in the technical language of Drupal, its ("taxonomy categories"). This list presents all the sections available on the website, with their structure. So, choose the appropriate section or sections for your story and continue down the form to supply the body of your text. Body The "body" field is where you put the main content of the page. If youve 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 youre a novice, dont worry--its not as difficult as it sounds. Heres a quick primer: If you want something to be bold, just enclose it in <b> or <strong> tags, like this: <b>This text is bold</b> <strong>This text is bold</strong> Note that there is always an opening tag (no forward slash) and a closing tag (a forward slash before the tag name, indicating that you are "turning it off"). To make something italic, put it in <i> or <em> tags: <i>This is in italics</i> <em>This is emphasized</em> There is considerable debate about the semantic nature of the <b></code <code><i> tags versus the <strong> and <em> tags. To put things nicely in paragraphs, enclose them in <p> tags: <p>This is a paragraph.</p> To make a bulleted list, first open a list with a <ul> tag (that stands for "unordered list"), then put each list item in <li> (yes, for "list item") tags. Dont forget at the end to close off your list with a closing </ul> tag. Heres how it looks: <ul> <li>This is the first bulleted item</li> <li>This is the second bulleted item</li> </ul> and
322
3 Aug 2007
Drupal Handbook
The result is displayed below: This is the first bulleted item This is the second bulleted item To add a link to you need to use the <a> (anchor) tag. <a href="http://www.example.com">Example.com</a> To add links to other pages within your Drupal site you do not need to add the full URL, you can simply refer to the node like so: <a href="/?q=node/1222">My node</a> Note the "/" at the beginning. Also the above example is using non-clean URLs. If your site has clean URLs enabled you can remove the ?q= so that you just have <a href="/node/1222">My node</a>. That wasnt too painful, was it? Decide where you want the "teaser" (the part of the main text used in links to the article) to end. If you do nothing, Drupal will choose a breaking point for you -- but its 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 youre set! You can preview the page youve prepared by hitting "Preview" (recommended, and sometimes required) or you can bravely or recklessly just go ahead and publish it by hitting "Submit".
323
Drupal Handbook
3 Aug 2007
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 youre 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 youre 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.
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 youre 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 youre 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, its 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 whats 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 Flickrs "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 sites maintainer to make sure it accepts blog posts. The key question to ask is: "Is the BlogAPI enabled?" If the answer is yes, youre ready to roll. If not, you could request that it be enabled to allow you quick updates.
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.
327
Drupal Handbook
3 Aug 2007
In Drupal, you must enable the blogger.api module. You dont necessarily require blog module. Im only using story nodes, so I didnt enable blog module. After enabling blogger.api, go to settings >> blogger.api and: check off the content type you wish to edit via the API. In my case, its story. change the XML-RPC engine to MetaWeblog.
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
330
3 Aug 2007
Drupal Handbook
Sports
football
is david beckham the greatest footballer ever in england??
331
Drupal Handbook
3 Aug 2007
332
3 Aug 2007
Drupal Handbook
If you are using a database other than MySQL, that vendors documentation should have backup information. For a list of even more methods, consult the Handbook pages in the Upgrade Guide as well.
333
Drupal Handbook
3 Aug 2007
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.
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.
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 tared 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=sitebackupdatestamp=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 " .. sqldumping 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 tared 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 # # Database connection information dbname="drupal" # (e.g.: dbname=drupaldb) dbhost="localhost" dbuser="" # (e.g.: dbuser=drupaluser) dbpw="" # (e.g.: dbuser password)
338
3 Aug 2007
Drupal Handbook
# Website Files webrootdir="/var/www/drupal" # (e.g.: webrootdir=/home/user/public_html) # # Variables # # Default TAR Output File Base Name tarnamebase=sitebackupdatestamp=date +%m-%d-%Y # Execution directory (script start point) startdir=pwd logfile=$startdir"/fullsite.log" # file path and name of log file to use # Temporary Directory tempdir=$datestamp # # Input Parameter Check # if test "$1" = "" then tarname=$tarnamebase$datestamp.tgz else tarname=$1 fi # # 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
340
3 Aug 2007
Drupal Handbook
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
echo " Directory: $webrootdir does not exist" echo "" exit fi # # Create temporary working directory and expand tar file # echo " .. Setup" mkdir $tempdir cd $tempdir tar xzf $startdir/$tarfile echo " done" # # Remove old website files # echo " .. removing old files from $webrootdir" rm -r $webrootdir/* echo " done" # # unTAR website files # echo " .. unTARing website files into $webrootdir" cd $webrootdir tar xf $startdir/$tempdir/filecontent.tar echo " done" # # Load database information # cd $startdir/$tempdir echo " .. loading database:" echo " user: $dbuser; database: $dbname; host: $dbhost" echo "use $dbname; source dbcontent.sql;" | mysql --user=$dbuser --host=$dbhost echo " done" # # Cleanup # echo " .. Clean-up" cd $startdir rm -r $tempdir echo " done" # # Exit banner # echo " .. Full site restore complete" echo ""
--password
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 # Execution directory (script start point) startdir=pwd # return of pwd() populates statdir var logfile=$startdir+"fullsite.log" # file path and name of log file to use
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 # # 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" >> $logfile echo " Exiting ..." >> $logfile exit fi # Check that the webroot directory exists if [ ! -d "$webrootdir" ] then echo " Invalid internal parameter: webrootdir" >> $logfile echo " Directory: $webrootdir does not exist" >> $logfile echo " Exiting ..." >> $logfile exit fi # # 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
347
Drupal Handbook
3 Aug 2007
#Go ahead and give users access to manipulate their vhost to their #hearts content. AllowOverride All #Since mod_php doesnt like yo respect su_exec, and safe_mode is just # too paranoid to be usable restrict php to the proper vhost, but a level #above the document root so users have some private file space for #.htpasswd, drupal files, backups, etc php_admin_value open_basedir /var/www/example.com #move phps temp files into the open_basedir php_admin_value upload_tmp_dir /var/www/example.com/tmp #session.save path isnt really necessary for drupal since it #stores sessions in the database, but for general php enabled #vhosts it keeps session data tied to each vhost. php_admin_value session.save_path /var/www/example.com/tmp //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
348
3 Aug 2007
Drupal Handbook
My site is called yoursite.com its hosted on a shared server I have shell access to my hosted files. Without shell I wouldnt really want to attempt all this. I am allowed to have two mysql databases on my account all site files are at /home/user/public_html (theres also an alias, /home/user/www, which points to public_html) in the above, user stands for my username, which Im not telling you I keep my production drupal database in mysql; that db is named mydb_prod Apache is set up so that http://www.yoursite.com and http://yoursite.com will point to /home/user/public_html 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: 1. 2. 3. 4. 5. 6. Make a new (empty) database, and name it mydb_test Copy your prod db into mydb_test Copy all of your prod files (from public_html) into your test directory Make three settings changes to connect the test site to the test db Make changes to your test site. (optional) replicate test sites files and db back into the prod site to make your changes live
So how to actually do all this? Dont worry, its 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! Step 0 - work with your host provider 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 didnt, but even if this costs you a couple of extra bucks, its 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 havent put anything here yet) /home/username could in your case be /var/www/username, or something else entirely. The point is to have a test directory which is not part of your normal html directory, and which acts as a separate site in all ways. Youll also need a second mySQL database to house your test sites data. Step 1 - Create an Empty Database I use the commands mysql -uuser -ppassword -e "create database mydb_test;" mysql -uuser -ppassword -e "grant all privileges on mydb_test.* to user@localhost identified by password;" to create my database and set the permissions. The I broke a single mysql command into the last two lines because drupal.org wasnt 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. Step 2 - Replicate the database 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. Youll 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 youve 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 well 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 sites
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); its not needed anymore now that we have loaded it into mySQL. Step 3 - Copy the web files 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 dont want it to pollute my fresh new exact replica of my prod site. Step 4 - Edit Settings nano ~/test/sites/default/settings.php This starts the nano editor (or use whatever you like) and loads drupals 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 thats 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. Step 5 - Make your changes This is where you make you changes. Change settings, add/remove modules, muck with the code - its up to you. Remember you are working in a copy of your site - one that users dont know about - so you dont 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 dont 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
Step 6 - Promoting changes to production 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, Im essentially doing everything mentioned above, but this time copying the test site into the production location. So Ill 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 youll 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)
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 its 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 dont 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). Read the upgrade portion of the INSTALL.txt file Log in with UID 1. Run sitename/update.php. On the update.php page, check the schema date of the database, I generally leave it where it defaults to. Upgrade. Check for errors. Resolve all errors BEFORE proceeding. Log in check it out. Get your modules and read the install and readme files to see if there are any special upgrade instructions. Upgrade and activate modules one at a time. Test, etc. Put your own favicon.ico back. Congratulations. You can restore this to your live site. - or Follow the steps on your live site now that you are confident it will work. Start working on your theme updates and other and stuff.
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.
355
Drupal Handbook
3 Aug 2007
356
3 Aug 2007
Drupal 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 theyre still an issue, try out patches to see if they work and comment on whether or not theyd be useful. Youll 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 wouldnt 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 Bryghts "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 users profile data on every comment, just below users image. Data like location, country and a nice country flag. Well, the only way I could imagine to do this was either loading users 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 users 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); } 2. On template.php file, create this function:
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 users profile. 3. On comment.tpl.php file, display users info whenever you want it: 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 thats it! I love to do stuff without touching a line of Drupals or modules code. PS: I have been looking for some kind of solution for this on the forum, but havent found anything so I did it myself. PS2: Should this be on PHP snippets section?
June 2005: Custom Content Types, WYSIWIG Editors, Organize Your Content & Quick Support
CUSTOM CONTENT TYPES Need more flexibility in creating content? Are the simple page and story content types not enough for your sites 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. ORGANIZE YOUR CONTENT 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.
September 2005: Newest modules, Change any string, Remote authentication, and tracking project issues
Get the newest modules -- fast!
This tip comes from kbahey: To view a list of newly released modules, use the URL: http://drupal.org/taxonomy/term/14. This will show you the newest modules at the top of the list!
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 its nopermissionuser@my.drupal.site.
360
3 Aug 2007
Drupal Handbook
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: Administrators This group will have full control over the site. They will be able to change site layout. They will have control over user access controls. Family members This group will contribute content. They will need to be able to update and upload content. Many of the users are not technical. Friends This group will view all of the content but will not contribute content. Anonymous users This group will be able to view some of the content but not all. They will not need to be able to update the content or provide comments. 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 dont 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. Evaluating CMSes and Modules
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 wont go through all of the modules here but basically this step was just a bunch of reading. Testing Drupal and modules 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 cant say I have everything i want but you cant 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: Subject This would be the subject of the content. It could be one of the children, a house, my truck, or a project. Every node should have at least one subject and the ability to have multiple subjects. Subject Date This will default to the submit date but it can be changed since many times content is added that is older media. Type This is the node type (image, video, story, blog, ....
364
3 Aug 2007
Drupal Handbook
Submitter This is who submitted the content. Category This is some more descriptive category (funny, news, woodworking, taekwondo, ...). Basically I expect this to grow as our hobbies change and develop but every node should have at least one category and the ability to have multiples. Submit Date When the content was submitted. 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.
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. 2. Analyze your sites performance bottlenecks: CPU, memory, bandwidth, input/output. Once you have identified what is causing your system performance problems you can make configuration changes or resource upgrades. Use top and ps for analysing processes that are using up too much RAM or CPU. Netstat, mrtg/awstats, whos online block will help for identifying network problems. top ps -aux netstat -anp | sort -u 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. MySQL performance tuning Bandwidth: Images or media are likely to be the greatest source of bandwidth consumption which with limit Apaches performance. In order to ensure images are delivered quickly the theme should explictly call the images directly to reduce the PHP overhead of looking for image files. Details will be provided in the future. Drupal resource consumption: Measuring modules memory usage, measure DB query times, and duplicate queries for modules or pages with devel.module. 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 Drupals 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.
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> We also need to put a new line: RewriteCond %{REQUEST_FILENAME} !\.(gif|jpe?g|s?html|css|js|cgi)$ Just before the line: RewriteRule ^(.*)$ index.php?q=$1 [L,QSA] 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 Drupals 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 Drupals 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
Heres my scaling tree. As you progress up the tree, you will find that time, money, maintenance, headaches will all increase. 1. Use a PHP cache: 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. 2. Use mod_gzip (or ob_compress or whatever it is in php, I prefer mod_gzip, or mod_deflate in Apache2) The benefits of this are amazing, considering the minimal effort it takes to implement. If doesnt 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. Im 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 7. Profile / tune Drupals code (shudder).
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.
370
3 Aug 2007
Drupal Handbook
query_cache_type = 1 tmp_table_size = 16M For a system with 256mb of ram: [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 Ive 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 doesnt really explain why). Also, Ive found that the way Ive 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 youd like to read up on more about mysql tuning I suggest taking a look at these resources: Tuning MySQL for Drupal Tuning a MySQL server in 5 minutes 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 A comment in php.ini explains:
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." This functionality is further described here. very interesting presentation from a PHP developer Additional resources: PHP Project Page
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. There are a number of PHP caches (aka accelerators) available, including: PHP Accelerator After Burner Zend Accelerator
373
Drupal Handbook
3 Aug 2007
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 shouldnt 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 dont need to restart web server ; if you are editing your php. You arent 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 projects 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): 11:00:00 %idle 11:10:00 94.44 11:20:00 95.64 11:30:00 95.18 11:40:00 95.58 11:50:00 95.88 12:00:00 96.11 12:10:00 99.38 12:20:00 99.01 12:30:00 99.31 12:40:00 AM AM AM AM AM AM PM PM PM PM PM CPU all all all all all all all all all all %user 3.71 3.86 4.49 4.05 3.76 3.38 0.52 0.79 0.57 0.59 %nice 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 %system 1.85 0.50 0.33 0.36 0.36 0.52 0.10 0.20 0.12 0.12
375
Drupal Handbook
3 Aug 2007
PM
all
0.44
0.00
0.11
Troubleshooting: An easy way to tell if MMCache is working properly after following the installation
told them to be written with the mmcache.cache_dir directive. If no files are appearing, something is wrong.
instructions is to see if temporary files are being created in /tmp/mmcache, or wherever you
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 its 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 servers 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 youre finished troubleshooting.) Additional resources: Turck MMCache Home Page
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 cant 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 havent resolved yet. I didnt 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
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: 1. Back up your existing site and database. 2. Download and unzip the new Drupal files to your server. 3. Run the update.php script, which will update your database. 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).
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), youre ready to prepare to upgrade by following the instructions given in the links below.
379
Drupal Handbook
3 Aug 2007
Click the "Export" tab Click "select all" Make sure to check the "structure" and "data" checkboxes Check "Save as File" desktop Click the "Go" button and save the .sql file to your desktop. Lets put it in the same backup folder where you backed up your Drupal files.
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: ./drupalsqldump.sh sites/default/settings.php > backup/backup.sql If you are running a version of Drupal 4.5 or older, run the following: ./drupalsqldump.sh includes/conf.php > backup/backup.sql
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.
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 In FTP world this is usually seen as public_html/test_site" or "www/test_site". IV. Check if your test site works. Navigate to http://www.example.com/test_site and you should see a working copy of your live 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.
382
3 Aug 2007
Drupal Handbook
mysqladmin -u dba_user -p create test_site_database (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: GRANT ALL PRIVILEGES ON IDENTIFIED BY password; test_site_database.* TO nobody@localhost
where test_site_database is the name of your database nobody@localhost is the username of your webserver MySQL account password is the password required to log in as the MySQL user. d) To activate the new permissions you must enter the command: flush privileges; and then enter \q to exit MySQL. III. Change settings.php (or includes/conf.php) in your test_site directory a) Open and edit the file located under sites/default/settings.php (or includes/conf.php) with an editor. Follow the directions in the file and modify these three settings: $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
a) Change to the test_site directory. 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. wget http://civicspacelabs.org/home/files/drupalsql chmod +x drupalsql.sh -O drupalsql.sh
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: ./drupalsql.sh test_site/sites/default/settings.php < /path/to/backup.sql If you are running a version of Drupal 4.5 and older, run the following: ./drupalsql.sh test_site/includes/conf.php < /path/to/backup.sql V. Check if your test site works Navigate to http://www.example.com/test_site and you should see a working copy of your live site.
384
3 Aug 2007
Drupal Handbook
Make sure your files directory is writable. IV. Upload contributed modules Again with your FTP client, upload the new version of all your contributed modules. Make sure you have the version of the module which matches your new Drupal version. V. Copy over necessary files from the backup copy directory Using your FTP client, copy the following files from your backup directory to the Drupal directory on your server: .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> Its 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.
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. II. Copy over necessary files from the backup directory Copy over the following files from the backup directory to your Drupal site directory: .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 Its 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. I. Did you login as USER 1? Previously, you were asked to login as USER 1, the root user, the first user created on your Drupal site. If you were not able to do so, you will need to edit the update.php script in a text
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 ITs ORIGINAL STATE if you have made this change. Otherwise, anyone would be able to run the update.php file on your site. II. Run update.php In your web browser navigate to the directory where Drupal is installed: http://www.example.com/update.php or http://www.example.com/test_site/update.php test site)
(if
you
are
upgrading
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 dont 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 dont hesitate to Ask for Help in the Forums.
388
3 Aug 2007
Drupal Handbook
II. Prevent file not found errors After you upgrade your site you should check your site for bad links, to prevent the file not found errors. The http error number for these pages is 404. You can use a simple tool to check the links on your site. You will see errors in you Drupal Administrator logs as well as your web server error logs. Perform the following commands through the administrator menu on your site: Enable contributed image module administer >> modules Set permissions so images can be written for userid running link check. administer >> access control Enable the menu module administer >> modules Disable the logout menu administer >> menus 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. wget -r --delete-after --cookies=off --header=Cookie: PHPSESSID=xxx http://yoursite.com -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. III. Invite users to test Your users are your best source of feedback. They will tell you quickly which parts of your site are not working like they expect them to. Send an email informing users that your test site is available for them and instruct them how to give feedback. You may wish to install the feedback module to assist with user feedback.
389
Drupal Handbook
3 Aug 2007
Make a backup of your test site files Copy the test site files to your root directory on your server Change some configuration settings Choose either the GUI or command line method below.
390
3 Aug 2007
Drupal Handbook
I. Backup Your Test Site Files Using an FTP client such as SmartFTP, download all your existing test site files to your hard drive. The especially important files to keep track of are settings.php, and .htaccess. II. Change settings.php in your test site Drupal files Open and edit the file located under sites/default/settings.php (or includes/conf.php) with a plain text editor such as jEdit. Follow the directions in the file and modify this setting: $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/ In FTP world this is usually seen as "public_html/" or "www/". IV. Check if your test site works Navigate to http://www.example.com/ and you should see your newly upgraded Drupal site.
391
Drupal Handbook
3 Aug 2007
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) ); Note from comments: For upgrading from 4.4 to 4.5 you need to run extra SQL stuff. If your phpwebdmin broken, you can use this small php script to do the update. <?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); ?>
393
Drupal Handbook
3 Aug 2007
394
3 Aug 2007
Drupal Handbook
user.module watchdog.module ================= 2. Go to ADMINISTER --> THEMES and make BLUEMARINE the default theme. 3. Go to the root of the Drupal directory and open the file called CHANGELOG.txt. Make a note of the version number and date (important!) in the first line at the top of the file. 4. Go to your includes directory and make a copy of the conf.php file on your local computer. 5. Delete all the Drupal files and directories from your server using an FTP program or a control panel filemanager provided by your web host. IMPORTANT: before doing this, make sure you have a backup of your Drupal MYSQL database and the Drupal 4.5 files & folders on your server. You will need your old "/files/" folder and its contents to copy to the new site later, and backing up the other files will allow you to recover your complete site in case anything should go wrong during the upgrade. 6. Download Drupal 4.6.0 and upload all the files to your server. 7. Go to the sites/default directory and edit the settings.php file (you can use your old conf.php file as reference). 8. Once settings.php file has been edited, go to your site and login as the administrator. 9. Go to http://www.yoursite.com/update.php. 10. You should be presented with the instruction screen for upgrading. Click on the link to start the upgrade script; you will be asked from which version you are upgrading from. This is very important: revert back to the note you made earlier from the 4.5 CHANGELOG.txt file. 11. Click the "Update" button. You should see a successful green "OK" after each update operation and finally a link to go to your main and administration pages. If you get red error messages, it means some or all of your update has failed. 12. On a sucessful update, go to the root Drupal directory and make a note of the version number & date from the very top of the CHANGELOG.txtfile (important). 13. Go to the sites/default directory and make a copy of the settings.php file to your local computer. 14. Delete all the Drupal files from your install. 15. Download Drupal 4.6.2 and upload the files to your server and restore the information in settings.php. 16. Go to your site and login as the administrator. 17. Go to http://www.yoursite.com/update.php (click on your browsers Refresh button a few times to make sure its not loading from cache and the previous update.php file). 18. Click on the link to run the update script. Select the correct version number and date from the CHANGELOG.txt file you made a few steps back. 19. Click the "Update" button. You should see a successful green "OK" after each update operation and finally a link to go to your main and administration pages. If you get red error messages, it means some or all of your update has failed. 20. Repeat this process again to upgrade from Drupal 4.6.2 to version 4.6.3. 21. Once you have reached a live version of 4.6.3, you can now start downloading the 4.6 versions of the add-on contributed modules & Themes you used with your 4.5 site. All appear to work okay apart from event.module that needs extra special attention. When youre
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.
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, youll have to reconfigure these after the upgrade. 1. Go to ADMINISTER --> BLOCKS 2. Click on the CONFIGURE link for each BLOCK you applied special PATH conditions to on your Drupal 4.5 site and modify accordingly
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: 1. Go to ADMINISTER --> ACCESS CONTROL 2. Double check that the permissions are correct and click on SAVE CONFIGURATION.
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. 1. Go to ADMINISTER --> CATEGORIES 2. Click on EDIT VOCABULARY TERM for the FORUM category 3. Scroll down and ensure that FORUM TOPIC node types are associated with your Vocabulary Term. 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 whats wrong.
Images
Upgrading a site with the image.module installed also appears very problematic. I didnt have the image.module in the site I upgraded so I cant 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 doesnt seem to upgrade properly. I ended up spending so long trying to work out whats 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
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 its 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.
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.
400
3 Aug 2007
Drupal Handbook
during the Drupal update process. This of course requires that the modules 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 modules update afterwards is a rather cumbersome task.
401
Drupal Handbook
3 Aug 2007
402
3 Aug 2007
Drupal Handbook
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 dont 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.
404
3 Aug 2007
Drupal Handbook
4.
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 wont help much when searching for the problem elsewhere. 6.
7.
406
3 Aug 2007
Drupal Handbook
and see if that gives any clue. A useful data dump when debugging, even within node pages themselves is sometimes. print("Node is : ".print_r($node,1)"); 8.
407
Drupal Handbook
3 Aug 2007
1. Remove (unused) modules--the quickest/easiest solution. 2. Increase PHPs memory limit, either by adding: memory_limit = 12M to your php.ini file (recommended, if you have access) ini_set(memory_limit, 12M); in your sites/default/settings.php file php_value memory_limit 12M in your .htaccess file in the Drupal root 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: Fatal error: Allowed memory size of 8388608 bytes exhausted (tried to allocate 418591 bytes) in /path/to/drupal/includes/database.mysql.inc on line 29 That indicates that Drupal needed more memory than PHP was allowed to give it. 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.
408
3 Aug 2007
Drupal Handbook
409
Drupal Handbook
3 Aug 2007
Note: this doesnt 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 cant 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 isnt the owner and isnt 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 isnt really required for PHP files as they dont 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
Webmasters.com
Webmasters.com
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.
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. (Im 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.
412
3 Aug 2007
Drupal Handbook
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 whats 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 dont 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. Basic summary of file permissions for a Drupal installation: 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 doesnt have read permissions for it. Recheck the permissions on subdirectories etc. Ideally your settings.php file wont be world readable as it contains your database connection string (with password). But sometimes you cant avoid it if making it world readable is the only way your webserver can read it. Along similar lines, ideally for security reasons you wont 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 dont 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 wouldnt 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
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.
"Method POST is not allowed for the URL /index.htm" error (Error 405)
Your Drupal directory contains both an index.html and index.php file. Remove the index.html file or configure your web server to look for index.php first before index.html. The same goes for basically any html file in your Drupal directory. If you have for example "node.html" in your root, you get the error message for every form that is submitted to node/*.
417
Drupal Handbook
3 Aug 2007
418
3 Aug 2007
Drupal Handbook
RewriteRule .* - [F] You dont 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 URLs. 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 didnt 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.
419
Drupal Handbook
3 Aug 2007
Remember to use [ and ] to close the arguments above. read more on: http://www.i-marco.nl/weblog/archive/2005/08/29/saving_some_valuable_ban... Or another way is to block domains also in the .htaccess file: SetEnvIfNoCase Referer ".*.baddomain.com" BadReferrer SetEnvIfNoCase Referer ".*anotherbaddomain.com" BadReferrer order deny,allow deny from env=BadReferrer read more on: http://www.hojohnlee.com/hacks/2006/01/12/blocking-spam-domain-referrals...
420
3 Aug 2007
Drupal Handbook
421
Drupal Handbook
3 Aug 2007
The solution (long form): The error itself can tell us a lot. Lets divide it into 3 parts: The error: user error: Duplicate entry 24 for key 1 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: query: INSERT INTO node (status, moderate, promote, body, format, uid, created, type, teaser, changed, nid) sticky, title,
INSERT INTO [tablename] tells us which table produced the error. What follows is a list of column names. The values: VALUES(1, 0, 1, 0, test, this is a test, 1, 1, 1149692821, story, this is a test, 1149692832, 24) in .../includes/database.mysql.inc on line 66. 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. Lets 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
Check out http://cvs.drupal.org/viewcvs/drupal/contributions/tricks/smtp/ for an example. Originally written by Kjartan on January 9, 2002, with modifications. Customize smtp.inc from the repository above to ensure that the proper settings for your SMTP server are being used.
423
Drupal Handbook
3 Aug 2007
mail gateway. For example: yourmailgateway.yourdomain.com. If your gateway requires SMTP authentication to relay mail, then you will need to modify the following lines to appropriately reflect the authentication credentials. (If you manage your own mail gateway or it resides within local subnets behind your firewall, then you should be able to leave authentication set to FALSE and allow relaying based upon IP address/network ID. This will probably only affect you if you use a hosting company for email management. $this->auth = FALSE; (change to TRUE) $this->user = ; (put username here(you may need to preceed with domain; e.g. domain\username)) $this->pass = ; (put password here) 4. Download smtp.inc from http://cvs.drupal.org/viewcvs/drupal/contributions/tricks/smtp/ and place it in your /includes directory. No modification to this file is needed. 5. Add the following line to the sites/default/settings.php file before the closing ?> tag: $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.
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 There are several workarounds 1. Replace in my.ini the current sql-mode line with sql-mode="MYSQL40" 2. Start MySQL with the option --sql-mode="MYSQL40" 3. Execute the query SET GLOBAL sql_mode=MYSQL40 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.
425
Drupal Handbook
3 Aug 2007
Fatal error: Allowed memory size of X bytes exhausted (tried to allocate Y bytes)...
That indicates that Drupal needed more memory than PHP was allowed to give it. Increase PHPs memory limit, either by adding: memory_limit = 12M to your php.ini file (recommended, if you have access) ini_set(memory_limit, 12M); in your sites/default/settings.php file php_value memory_limit 12M in your .htaccess file in the Drupal root The popular distribution from CivicSpace requires 24MB of memory so you may have to experiment with what memory value works for your needs.
426
3 Aug 2007
Drupal Handbook
formupdater.module. An online version of this is available here: 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) youll get this error. Go in and physically remove/move the module/theme files you dont 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. PS - NEVER have a module the same name as a theme!
427
Drupal Handbook
3 Aug 2007
Execute the following query on your drupal database: UPDATE users SET pass = MD5(newpwd) WHERE uid=1; Of course, change newpwd to the password you want.
The Fix
... is to tell the forum module to forget its old invalid vocabulary id and make a new one. Short answer is this code needs to run: <?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: Create new node (dont save) Set content to php code. Disable wysiwyg if needed Paste the above in the body Preview the php code will execute, although you wont see anything yet. discard the node, dont 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.
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. For example in a custommade sideblock you can say:
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 thats 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 ?>
How do I get rid of the "Welcome to your new Drupal website" on the front page?
If you are seeing this message it is because your front page is set to node and you have no content promoted to the front page. 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 dont 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 its 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 .
How to login once you have turned your site off-line for maintenance
432
3 Aug 2007
Drupal Handbook
Once you have turned your site off-line using 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.
admin
settings
site
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 browsers 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. To return the site to online mode visit the following page: Drupal 4: administer settings (admin/settings) Drupal 5: Administer Site configuration Site maintenance (admin/settings/site-maintenance). On the page, set Site status to Online. If you are truly desperate you can try the following database queries to restore access: UPDATE variable SET value = s:1:"0"; WHERE name= site_offline; DELETE FROM cache WHERE cid = variables;
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 youve installed Drupal and enabled the BlogAPI module or the Drupal login module on such a provider, youll 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 drupals main directory. While this is bad and will make upgrading a bit of a hassle, it can get you up and running. Youll 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: 560: $xmlrpc = $base_url ./. xmlrpc.php;
434
3 Aug 2007
Drupal Handbook
Another solution is to switch to a PHPTemplate based theme. PHPTemplate is another theme engine, which will become the default in Drupal 4.7 anyway. You will need to download and install PHPTemplate before you can use themes that depend on it. 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.
Cookies
Make sure cookies are enabled in your browser.
Cache Problems
It seems that sometimes the cache doesnt 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.
My layout collapses - content appears below left column (IE) or overflows over the right (FF)
This commonly happens in themes that use CSS for flexible column layouts. 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 its been given
Whats a poor robot to do? If you tell a robot to push 1130 pixels into a bag that only holds 1000 - somethings 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 isnt 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 youve pasted in a fixed-with table. Just remove the width attribute. Another approach is it apply #content{overflow:auto;} on your css. This results in a scrollbar in the middle of your page when the content forces it, and is not always very nice-looking, but its better than the alternatives. #content{overflow:hidden;} also works, is safer on your design, and looks better (maybe) but may hurt accessibility slightly. You can try #content{min-width:450px;} and similar fixes, but youll 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: document type does not allow element "div" here; (inside a P) - may have side effects, but is probably non-fatal. Its because of the way some themes, or the line-break converter place extra (block-level) markup inside paragraphs - which is not technically right. Can ignore. end tag for element "..." which is not open. Possibly related to the above. Fix it if possible
437
Drupal Handbook
3 Aug 2007
there is no attribute ... or required attribute ... not specified. OK to ignore. or end tag for "..." omitted, but OMITTAG NO was specified Likely to be a sign of layout problems. If the end of a DIV or a TABLE (or other block-type tags) is missing this will probably be very bad and needs fixing. Traditionally seen in badly cropped teasers that try to display the top half of a table. an attribute value specification must be an attribute value literal unless SHORTTAG YES is specified. Fix it if possible, but probably safe to ignore. cannot generate system identifier for general entity ... or reference to entity "..." for which no system identifier could be generated. OK to ignore. For more CSS troubleshooting, try the instructions for using the CSS inspector to find the active styles and go from there.
438
3 Aug 2007
Drupal Handbook
http://www.example.com/?q=admin/settings might yield error messages like this: warning: mkdir(files): Permission denied in /data/www/public/includes/file.inc on line 77. warning: mkdir(files/tmp): No such file or directory in /usr/data/www/public/includes/file.inc on line 77. 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
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(); ?> It will probably mess up your sites formatting.
440
3 Aug 2007
Drupal Handbook
441
Drupal Handbook
3 Aug 2007
442
3 Aug 2007
Drupal Handbook
A: Most likely, you need to assign a taxonomy vocabulary to the content type. Youve just created a taxonomy and filled it with a perfect array of terms. But theres no category menu on the post submission page! What gives? Youve forgotten a critical step: Assigning your taxonomy to a content type. 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 Drupals character encoding? (UTF-8 and Unicode)
Several people have asked how to specify the character encoding that Drupal uses. The short answer is: you cant, but you dont 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 Drupals 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