Oh The Huge Manatee

A blog about technology, open source, and the web... from someone who works with all three.

Drupal Quick Learning Guides: Drupal Structure

I’ve been lax about posting lately, and to make this easier on myself I think I’ll post a bunch of quick guides for basic coding procedures with Drupal. Simple things and concepts, explored in just enough detail for you to understand how it works, resource links so you can actually go and put it into practice.

The first thing you need to understand about Drupal is the structure. Drupal is a modular Content Management System, built on PHP and whatever-database-you-want-which-is-probably-mysql-lets-face-it. Drupal <=6.x actually requires MySQL or PostGres, and they're still the standard on 99% of installs you'll face. The thing is, Drupal is incredibly flexible and capable. And the trick to coding with Drupal is to code WITH Drupal, not against it. There are tons of helper functions built in that make your life easier, if only you'll work the way Drupal expects you to work. So this first post is about how Drupal expects you to work. Drupal itself is a complicated guy that lives in several php files and directories. You are expected to NEVER touch any of these files or directories yourself. Seriously. 16,000 coders can't be wrong, just leave it the fuck alone. You have access to OVERRIDE anything and everything that Drupal does though, and you can do that from a nice contained subdirectory where you can keep an eye on your code. This is the /sites subdirectory. See, one Drupal codebase can actually host many websites. Each one gets its own subdirectory under /sites. for example, I might have: /sites/swearingatcomputers.blogspot.com /sites/subdomain.swearingatcomputers.blogspot.com /sites/swearingatcomputers.blogspot.com.subdirectory The directory name tells Drupal what incoming requests should be forwarded to which site. You can see how subdomains and subdirectories are handled in the naming convention, too. Pretty easy stuff. There's also a special subdirectory for "default", and one for "all". Not to complicated to figure out: "all" is for code that applies to all your sites, and "default" is the sites subdirectory for when other names don't match. I'll tell you a pro secret: hardly any of the big shops ever actually use the multi-site capability. In practice it's a pain in the ass to remember which sites use which version of which module, and Drupal itself doesn't take up any significant space. So most of us just set up a separate Drupal codebase for each site, and use sites/default and sites/all for our code. Inside each site directory you'll find: * settings.php : This contains the database connection information, and any special settings that Drupal needs for similar low-level tasks. Set once, never modified. Doesn't exist in sites/all. * files : Any user-uploaded files. This one doesn't exist in the sites/all directory. * modules : any modules that are available to Drupal. This is where you'll keep the contributed modules which are the majority of Drupal’s capabilities.
* themes : This contains the themes - layouts - that are available to Drupal.

I mentioned that most professional Drupal shops just use a separate codebase for each site they set up. They also don’t mix and match between using sites/default and sites/all . This is because it’s very easy to end up with a copy of the same module in two places, and it’s hard to know which version Drupal is actually using. So everyone standardizes their own practice here. Personally, I keep modules and themes in sites/all . sites/default only contains settings.php and the files directory.

Inside the modules directory you’ll find all your contributed modules that you’ve downloaded. But this is also where you have to keep Features (exportable collections of settings, very useful!) and any custom code that you write for your site. This presents a namespace problem. What if you create a feature called ‘Views’, to hold all the Drupal Views you have? You don’t want to include it in the directory for the Views module… So underneath sites/all/modules , I create subdirectories custom_features and custom_modules. It’s still not good practice to have duplicate module or feature names though, so it’s wise to prefix your custom work with custom_ or the name of the project.

That’s all you need to know about the Drupal file structure. Once again, NEVER EVER HACK CORE. Don’t touch anything outside of the ‘sites’ directory, and you’ll be OK. There is always a way to override any behavior you like from inside the ‘sites’ directory, and that will make your life MUCH easier down the road, trust me.