Drupal jargon explained!

Drupal has a reputation for having a steep learning curve, but I remain convinced that it's largely overstated. Nonetheless, it's true that right from the start the new Drupal user has to contend with documentation that uses unfamiliar, arguably non-intuitive jargon. That said, "What's a node in Drupal?" is a harder question to answer than one might think. Because the pieces of Drupal are usually inter-connected, an easier term to define, like "CCK", depends on the reader understanding what a "node" is. The Views documentation might tell you how to create a Block, but without understanding what each of those things is, it's easy to get frustrated.

So, for the sake of Drupal newbies who want to like Drupal but are struggling to get past the jargon, I've put together my own attempt at some practical definitions, and a diagram of how the pieces link together, at the bottom. My goal here is to make things clearer for the sort of Drupal site developer who will mostly be using the UI; when having choose between technical accuracy and clarity for practical, hands-on purposes, I've sided with clarity. I've organized it in such a way that, with some exceptions, each definition provides prerequisite information for understanding subsequent definitions.

Role

Simply put, a role is a grouping assigned to user accounts, that gives all the user accounts classified in that way the same set of permissions. A user can have more than one role, and permissions are cumulative-- the user has the most liberal permissions from all his roles, combined. You can define roles (point your browser to yoursite.com/admin/user/roles), and when you edit permissions (/admin/user/permissions) there are different columns of check boxes for each role.

Module

If it's not something Drupal does out-of-the-box (and, to be perfectly honest, there's not a whole lot that Drupal does out-of-the-box), it's because of a module. A module is a directory (folder) of code and related files that you generally upload to /sites/all/modules (a directory you have to create yourself in /sites/all; this is in the filesystem, not something you do in the browser). Once your modules have been uploaded, point your browser to yoursite.com/admin/build/modules, check the boxes for the modules you want to enable, save, and your site has new functionality!

A lot of modules don't work (or don't work well) if you don't configure them. If you can't figure out where your module's configuration page got stuck among the various administrative options, go to /admin/by-module, and it should be listed there. Also, unless you're logged in using the first account that was created for the site during set-up, you may have to go to /admin/user/permissions to ensure that your role has permission to administer (or even use) the functionality the module provides, by going to the permissions page.

Node

The node is your core unit of storing content. If you're inputting and saving content, you're probably saving it as a node (you'll find a few small exceptions in other definitions). Nodes can come in many shapes and sizes (see content type), but what they have in common, at their essence, is that they're a place to store content in different fields.

Fields are one of the most important aspects of nodes. When you're editing a node, you don't just have a big HTML free-for-all box. By default, there's a title field, and a body field. The title field is mandatory, but you can replace the body field, or augment it, with additional fields of various kinds. More details on that in content type.

For the new Drupal user, it's tempting at first to equate a node with a webpage. In a lot of cases, that's a reasonable unfair comparison. There's even a default Drupal content type called "page", which is intended for you to post webpage-style content. On a lot of simple Drupal sites, each node serves as a webpage, and each webpage is a node. But that one-to-one correspondence can break down. There are sites where all nodes are webpages, but some webpages aren't nodes (see Views). There are sites where some nodes are never meant to be viewed as webpages by themselves, and the content in those nodes is only accessible through webpages that aren't nodes (e.g. there are reasons why you might store each line in a poem in its own node, but you might want to display it along with all the other lines in the poem.)

A node can be as little as a title, or it can have a theoretically unlimited number of fields where the user can enter an unlimited number of values.

Content type

When you go to "Create content" in a new Drupal site, there's no option for creating a "Node". That's because each node is an instantiation of a content type. Different content types can have different fields (see below)-- or sometimes not. Even if all your content types only have the default "Title" and "Body" fields, setting up different content types for "News" and "Essay" (or, using the default content types "Page" and "Story" for different kinds of content) can be useful in conjunction with other modules. "Content type" is an easy way to create lists of the same kind of content (just news items, just essays) using Views, and it's easy to generate different automatic path aliases with Pathauto based on content type (more on both of those below).

CCK/Fields

Recognizing the importance of fields besides just "Title" and "Body", the Drupal dev team incorporated fields into Drupal core as of Drupal 7. For Drupal 6, though, you'll see references to CCK (Content Construction Kit), a module you need to install in order to add custom fields. What's more, in both Drupal 6 and Drupal 7, there's a number of modules you can add to get extra options for field type (file upload, link, etc.)

When you create a new content type, you can add new fields, select the field type, and configure the field, though configuration options vary based on type. For a file upload type, you can specify what types of files a user can upload, and how large they can be; for a text field, you can define how many characters it will allow, etc.

The fields you add, and the order you put them in, define what it looks like when you create or edit a node, though other modules (such as Taxonomy, below) can add other things on the page for you to fill in. With the right module enabled (in Drupal 6, it's "Content Permissions", which comes with CCK), you can restrict certain roles from editing certain fields.

Input format

Under text area fields, there's a toggle-down for "input format". Input formats are filters that strip out HTML and scripting that users enter. Input formats don't remove any text-- all of it is still saved in the node-- but input formats prevent certain elements from being processed. It's particularly useful if you're allowing anyone to sign up and create content, as a way to block XSS (cross-site scripting, in short, when people put malicious code into what you intend to be simply a text box, and without a filter to stop it from running, bad things can happen.)

If you put HTML into a Drupal text box and things don't show up right, the first thing you should do is check the input format. Even the >img< tag isn't included in the default filtered HTML format-- fair enough, but a bit annoying if you're just running your own site. If you're using a WYSIWYG editor, in particular, be sure to configure your input format, or much of "what you see" in the editing view will emphatically not be "what you get" in the output.

Personally, since none of my sites have public logins, and the other content editors are averse to angled brackets, out of laziness I usually set the default input format (/admin/settings/filters) for authenticated users to "Full HML". For better information about the right way to do things, I have notes on a wonderful Do it with Drupal session from a few years back on "Configuring a kick-ass WYSIWYG editor".

Taxonomy

If you've been to library school, this bit of Drupal "jargon" should be self-explanatory. For others, it might be one of the more opaque terms. Taxonomies (/admin/content/taxonomy) are ways of categorizing nodes. You can set up hierarchically structured vocabularies (where "quadruped" is nested under "animal", and "cat" is nested under "quadruped"), you can set up relationships between terms (one term can be a "related term" for another), and you can provide a definition. For each vocabulary, you can choose which content types it's associated with; when a vocabulary is associated with a content type, it will appear on the node creation/editing page. You can place various restrictions on the vocabulary-- whether a user can choose one or multiple terms, whether it's a free-tagging vocabulary (where users type in terms, possibly with auto-suggest based on existing terms, but the user is free to add new terms) or whether the user can only choose terms that are already in the vocabulary.

Theme

In Drupal, the theme is the site design-- not just CSS, but also things like page layout (the .tpl.php files), and other pieces of the skeleton for your site. To write a Drupal theme from the ground up you need to know PHP and the Drupal API. Since it's not necessarily safe to assume that the site design crowd knows PHP, and since most websites are laid out in similar ways, there's a lot of "starter themes" you can download (Zen, Fusion, Tao, and others) that largely deal with the skeleton/PHP part, allowing the site designer to focus on the CSS.

One of the important things a theme does is create and place "regions" that specify where blocks (see below) can go. If you're choosing a theme that someone else has built, make sure it's got enough regions in the right places for your site. On drupal.org, almost every theme mentions at least how many columns (regions for blocks) it has. Many themes also describe what other regions are included, like headers and footers.

One (possibly biased) note about Drupal theming: in my experience, I've found it can get messy fast. A live Drupal site has a handful or two of stylesheets; modules often come with their own stylesheet, and if you have a lot of modules, the number of stylesheets can start piling up. In principle, you can override all those other stylesheets with the style.css in your theme folder, but this hasn't always worked out for me, possibly because I had some issues nailing down exactly which >div> was causing me grief-- and the number of nested >div>'s can be reminiscent of a matryoshka carved by an obsessive artist with an insane amount of time on his hands. That said, I'm hardly a CSS wizard to begin with, and the theme designers I know only complain about half as much as I do about it, so don't be too discouraged my my pessimism.

Block

Blocks are one of the more user-facing pieces of Drupal, unlike the topics we've covered so far, which deal more with storing and classifying data or configuring Drupal. In short, blocks are chunks of content that you can make appear on one or more pages. The kinds of content in a block can vary widely. When you create a menu, it's available as a block. The login box is a block. You can make views (see below) appear as blocks. You can even create "custom" blocks, where you can just enter content right into a block-- this is one of the cases where you're saving content, but not in a node.

On the block administration page (/admin/build/block) you can see all the available blocks and all the available "regions" (which appear in yellow in the place on the page where the blocks will appear.) As mentioned above, regions are defined in your theme. Depending on the theme, you may have the option of one, two, or three columns, a header and/or footer, a place to put blocks above or below your main page content, and/or any number other places. To place a block in a region (at least in Drupal 6) drag the block up the block administration page into the labeled area that corresponds to the region where you want it.

If you choose to configure a block, you can set the paths (URLs) where the block should (or shouldn't) appear, what roles the block can appear for (e.g. members-only info for authenticated uers). This functionality is a big incentive for setting up custom paths for nodes, and being mindful about the path you set for your views (see below). If you want a block to only appear on pages with news items, you have to have something in the path to differentiate news items from any other content, so setting the path for news items to include the word "news" is a good way to do that (more on paths below). You can also use wildcards here (which mean "there might be all sorts of stuff in the path at this point, anything is okay so long as the rest of the path matches").

Panels

Panels is a very handy module that gives you more control over the site layout on certain pages than themes + blocks by themselves. After you install Panels, it appears as a content type. When you create a Panel, you can choose the layout for that page (e.g. you can set up columns within the main area of the page, without using either of the sidebars if your theme provides them, or you can set up "stacked" content, which is more like rows.) Then, you can assign content to the different regions. You can put blocks there, or views, or even full (or truncated) nodes. You can also create "custom content", much like the custom block, content that only appears on that panel-- this is another example of saving content without a node.

Panels are not the way to create a list of recent content, though it's possible to do manually putting in every new node you publish. Please don't use Panels for something like that; Drupal can make your life so much easier with Views.

Views

If you want to present your site content as anything other than individual pages accessible via a menu, you need the Views module. It's so indispensable that I'm surprised its functionality didn't make it into Drupal 7 core, along with CCK; Views become much more powerful if you're using CCK fields.

Using Views you can do things like create a block or page with the titles for the five most recent News items on your site, linked to the full node, and with a link to show all News items. You can create any number of RSS feeds. If you have a content type with a field that refers to another node, you can display data from that referenced node alongside data from the referring node. (Imagine a content type, CD, with a list of music tracks, that refers to an Artist node; you can show the list of music tracks along with biographical info about the artist from the Artist node.) You can filter and sort nodes, and you can allow the site's users to do the same (sorting only available in version 6.x-3.0-alpha or later). You can display nodes in lists, tables, grouped in various ways. Other modules expand the functionality of Views, to do things like export in CSV or XML, or edit nodes inline.

As a consequence of being powerful, Views isn't terribly intuitive when you find yourself staring at the Views configuration screen for the first time. There's a number of tutorials out there to help you get started (ask Google), some better than others, and even after a few years I'm still wrapping my head around all the things you can do with Views. (I recently started a project in part to make myself sit down and figure out the awesomeness of Views' Relationships.) Still, even with a basic knowledge of Views, there's a lot of very useful things you can do. It's worth the investment of time.

Paths, Pathauto, and Tokens

I've mentioned paths above. Path is a module in Drupal core that allows you to give your nodes a nicer name than "node/31". (Note: even if you use Paths, it's just an alias-- you can change the Path for a node, but the node number remains. To find out the number for a given node, just edit it and look at the URL. The number after node/ is the node number.)

If you just have Path installed, what you get is an option when editing nodes to manually enter a path alias. It's better than nothing, but far from ideal-- let's face it, you and your content managers are going to forget to do it.

What you need here is Pathauto, where you can set up automatic aliases based on patterns you define in the Pathauto configuration (/admin/build/path/pathauto). You can set up different aliases for different content types and taxonomy vocabularies, and then leverage that when configuring blocks. If there's a node where you don't want to use the automatic node alias, there's still that option for entering a path alias on the node page, and you can uncheck the option for using the automatic node title and put in whatever you want.

Pathauto and a few other modules make use of Tokens, which are very small pieces of data-- a node title, the year a node was published, a taxonomy term, etc. This fine granularity is very helpful for allowing you to set up very precise paths; for blog posts on this site, I've set up blog/[yyyy]/[mm]/[dd]/[title-raw]

One caveat with pathauto: if you decide to change the automatic path, it does not retroactively change all the nodes that have already been aliased up to that point. You need to install Views Bulk Operations (VBO) and set up a batch path alias change. While a change in alias won't affect things like links to nodes in menus, views, or anything else that's pulling data directly from the database, if you've linked to nodes when entering content into a text area, using the pathauto alias, you'll have to go back and change those manually, or concoct a SQL query to fix it in the database.

Putting it all together

The following chart may look intimidating at first glance, but if you've read all the way up to this point, it should hopefully make sense. Click for a bigger version on Flickr.
How the pieces work

Project: 

Tags: 

Add new comment

Filtered HTML

  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.