BLOG

Handy Drupal links for beginners who want to understand the framework, part one

Drupal documentation is the kind of word that brings up aweful feelings, and I have often wondered why this is. Even good books like Drupal Pro Development seem to skip over much of the really important stuff, which is knowing what all your functions are that you can use, how to find the information you need to make changes, and how Drupal's "signal path" works when it accesses a page or render an element.
 
To try and help with this process, I'm going to list here some useful references. These references are intended to supplement someone who has gotten far enough that they understand the front-end experience of the administration, they know how to make a theme, they can generally understand PHP code; but they just don't understand how Drupal works "under the hood" yet.
 
This description is not meant to be extensive, but rather general so that you can get started.
 

Tutorials

The only way you are going to learn what all of the best-practices are, is by watching a lot of videos, working with other Drupal people, reading Drupal Pro Development, and by systematically going through all of the code in core and the main modules used by the framework.
 
If you want videos, the best ones I have seen so far are from:
 
Lullabot and Mustardseedmedia
 

Important Modules for Development

On any website you make, you are going to really need a few modules:
 
Administration Menu
Provides an easier method of navigation for the admin
 
Devel
Provides an important devel-block, access to the theme registry at: yoursite.com/devel/theme/registry -- new PHP functions like dpm(), generation tools and more
 
Theme Developer
Provides an overlay that can help you to understand the theming engine; what variables are available, what functions and files are called.
 
Drush
Provides a command line (SSH / Unix) for Drupal with many extremely useful commands. You can use it to update your website rapidly, clear cache when the front-end is broken, or to enable and disable modules, or values in the database.
 
There are more tools you will need, but these are the Drupal-specific ones that will help you time and again. If you need to have a staging environment as well as a dev and test, then you will also need to consider scripting your changes with something like the macro feature in devel.
 

The API

First of all, bookmark the API page:
 
http://api.drupal.org
 

Internal Functions

Once you have this page, you want to understand the functions that Drupal calls. Drupal comes with a folder called "/includes" and in this folder, there are a number of files, take these file names and type them into the api.drupal.org to learn what core functions are available in ALL your future-PHP files you will make in your modules and themes. Some of the more important ones are:
 
common.inc
Tons of useful functions here.
 
bootstrap.inc
Yet more important functions.
 
form.inc
Although forms is a special-subject and requires separate effort to theme and use beyond just this .inc file.
 
menu.inc
For menu related functions, menu's are manipulated on a different layer than they are stored in the DB.

session.inc
For working with a user's sessions
 
theme.inc
Incredibly important for theming, and involves signal-path work and a separate understanding. The way the signal path works is notoriously confusing for people new to the framework and requires a separate explanation. That said, there are important functions here.
 
After looking at these files, make sure you open the /includes folder and that you type in the API search the file you are interested in if you want to look at some other .inc files. The modules.inc file is another important file, however I feel that module development should come a little later and most of the functions here are related to loading and calling modules.
 
Please note that of these functions, many here do things which you normally do with PHP. Drupal has certain built functions that you will want to use, rather than writing normal code. Most of these are contained in the .inc files I have listed above.
 
For example: if you want to render text, you want to use the t() function. Links want to use the l() function. Security-prone variables need to be run through check_plain() and so forth. When you are considering doing something from scratch, first check the .inc files to see if Drupal already has her own way of doing it; if so, stick to the Drupal way -- you will avoid problems later.
 

Coming up

The three things I will need to cover next, to cover the very basics of what needs to be learned, involves the forms, the modules that are a part of core, and the theme engine itself.
 
Understanding the Theme signal path, which is what all those weird "preprocess", "theme_" functions and so forth are all about is an involved subject, so I will have to treat that in a part II of this ultra small crash course series.