drupalib A place for library drupallers to hang out

Pro Drupal Development, by John VanDyk and Matt Westgate (Apress, 2007) is the first book aimed specifically at Drupal developers. Until now, developers have had to refer to Drupal's vast and rich online documentation, which encompasses the "Developing for Drupal" section of the drupal.org Handbook, the documentation at api.drupal.org (which would be much improved if users could post comments, php.net-style), and the invaluable code examples and explanations of how Drupal works under the hood that make grazing the various support forums for hours worthwhile. The Drupal documentation team is doing a commendable job of keeping the technial and general end-user documentation in shape but that is an endless and thankless task. Supplementing the information available within the drupal.org domain are clusters of useful developer-oriented documentation and articles, typified by the resources on the Lullabot website (who Matt Westgate works for). Pro Drupal Development brings a high level of cohesion and clarity to the often frustrating variety of existing Drupal technical documentation and will prove to be an indispensable reference and how-to for anyone who wants to extend Drupal.

Drupal module development and theming are based on overriding core functions, not modifying Drupal code. Pro Drupal Development makes that sometimes forgotten principle clear:

Drupal is designed to be customized, but customization is done by overriding the core or by adding modules, not by modifying the code in the core. [page 1]

and

[...] you don’t need to (nor should you) edit the HTML within module files to change the look and feel of your site. By doing that, you’ve just created your own proprietary content management system, and have thus lost one the biggest advantages of using a community supported open source software system to begin with. Override, don’t change! [page 107]

These two quotations encapsulate the zen of Drupal, and Pro Drupal Development contains chapters on everything developers need to know to live by this philosophy. Two chapters deal specifically with writing modules and one with creating themes, and the rest either provide detailed coverage of topics directly related to module development, such as the Drupal menu system and the ubiquitous node and user objects, or provide information that is more generally applicable to Drupal development, such as writing secure code in the Drupal environment and performance tuning. The text is presented in a refreshing balance of prose, code examples, screensnaps, flowcharts, block diagrams, and tables, and the back-of-the-book index, which is over 35 pages long, is both detailed and user friendly. Pro Drupal Development only covers Drupal version 5.x, although much of its content is applicable to the other currently-supported version, 4.7.6. The Apress website provides a table of contents for the book (as well as code examples and a sample chapter, "Theming System").

Overall, this book brings together in a very nice 428-page package the most essential developer-oriented documentation that is also available, in one form or another, on the drupal websites or elsewhere. Having the hard copy and the PDF version of the book (available for an exta $10 from Apress) will save Drupal hackers countless hours of time. Chapters that stand out include those on the Form API, jQuery (the JavaScript library bundled with Drupal), localization, and theming. The chapter on writing secure code is also worth mentioning, since even though this topic is covered in some detail at the drupal.org site, seeing yet another explanation of the security mechanisms Drupal provides, such as its "t()" function, that supplement safe PHP programming practices is very useful.

Since the book is so good in general, a few deficiencies stand out:

• First, even though the book provides a detailed appendix containing the definitions of all of Drupal's core database tables, the appendix lacks descriptions of the purpose of each field. Often, a field's purpose is apparent ("id" generally means an auto-incremented key) but many are not. Looking in the book's index usually turns up an entry for esoteric or non-obvious fields like block.delta, but a brief indication of what the function of the fields do, in the context of their table, would be useful.
• Second, one resource I was hoping Pro Drupal Development would provide is a comprehensive list of all the variables available to modules and PHP code used in node bodies. The authors indicate that developers must use the standard PHP "global" keyword to access variables defined elsewhere in the Drupal environment, and explain the use of "variable_get()" to access Drupal system varibles, but a comprehensive list of what variables are available would be very useful. $node and $user objects and their respective properties are described, as is use of the devel module (which lets you inspect system variables), and as is a comprehensive list of variables available to themes. However, a list of all variables and objects available in the Drupal environment, similar to what you get when you call phpinfo() but just for Drupal-specific variables, would save a lot of developers' time.
• Third, there is no explicit mention of PHP snippets, which are raw PHP code used outside of modules to create dynamic content. Entering raw PHP code into node bodies and blocks is a very convenient way to solve problems without the overhead of developing a whole module (not something you want all users to be able to do, but many site admins take advantage of this technique frequently). The authors mention the PHP input format and provide an example of a "standalone PHP" script which includes the full Drupal bootstrap, and snippets are mentioned incidentally in the chapters on blocks and theming, but the book does not provide any substantive discussion of this type of coding to extend Drupal. The "Customization and theming" part of drupal.org Handbook contains links to information on PHP, SQL, and JavaScript snippets, so perhaps VanDyk and Westgate consider these techniques to be outside the scope of their book, which focusses on module development.
• Finally, the chapter on "Development Best Practices" provides detailed information on using CVS in the Drupal environment but doesn't describe how to add and commit code to the cvs.drupal.org repository. Instead, the authors describe how to apply for a CVS account and point to the project maintenance quickstart guide on the Drupal site. That approach is probably sensible given that the exact procedures for committing code change occasionally, but the presence of so many other cvs commnands highlights the absence of "add" and "commit", especially given their focus on module development.

Apart from these gaps, a chapter on the must-have content-management modules cck, views, and contemplate would be useful since these three groups of modules add vastly to what is an already awesomely sophisticated content management system. Many helper modules are sprouting up around cck and views in particular, and a chapter on this topic may inspire developers to help extend Drupal in those dimensions, and to explain the internals of these complex but essential modules.

In general, Pro Drupal Development is well organized, clearly written, carefully edited, and a very valuable resource for Drupal hackers. I would characterize it as a nicely packaged, value-added "best of" collection from the vast and loosely coupled online documentation that you need to explore and make sense of on your own if you are developing Drupal modules. Calling it a collection suggests that VanDyk and Westgate are simply compiling other people's content, which is not the case -- when using their book I don't get the nagging sense that I've paid for a hard copy of a website. Their book is actually much more useful than the documentation available on the web because it trims out the information you don't need and presents the information you do need effectively. You should consider buying it if you are starting to develop Drupal modules or already have developed a few, even if it lacks a few things that would make it a complete API docs/cookbook/howto. Buy it from http://www.drupalbook.com/ and the Drupal Association gets $5.