Building Drupal with Naming Conventions

Creating Drupal sites is easy and requires no fancy skills. Drupal installation is simply one-click; setting up modules is simply one-click; creating new content types is also simple mouse clicks. Unfortunately, the power of control over Drupal is usually abused because of Drupal’s initial impression of simplicity. When building a hobby site, Drupal entities, such as blocks, content types, views, and URLs, are created randomly without deliberate consideration. Meanwhile, Drupal gurus would probably go in another approach by carefully planning names ahead.

Naming conventions

Naming conventions are overhead for most casual hobby use of Drupal. When a hobbyist wants to install Drupal for the first time, the guy won’t gain anything from naming conventions. When the hobbyist becomes a Drupal professional and sets up his tenth Drupal installation for a client, the guy may want some naming conventions for blocks, fields, content types, and views he created so he can easily maintain the other nine Drupal websites.

The Drupal community has defined coding standards for naming functions and variables. This standard is roughly based upon PEAR Coding Standard. Unfortunately PHP does not support either dot-separated packages or namespaces. Neither does Drupal support namespaces for its variable names and machine names for fields, content types, views, and other Drupal entities.

Human-readable Names and Machine-readable Names

Drupal demands two different types of names: a human-readable name and a machine-readable name.

Human-readable name and machine-readable name

The human-readable name is a text field containing any character. Drupal stores it as plain text into the database and treats it as plain text to display. Drupal recommends the human-readable name to contain only alphanumerics and spaces. However, this is not a strict restriction. The human-readable name can be used for applying naming conventions.

The machine-readable name is a text field containing only lowercase letters, numbers, and underscores. Drupal usually uses the machine-readable name directly as PHP variable names, database table names, and database field names. The machine-readable name must then follow the strict character restrictions. Machine-readable names only allow the use of lowercase letters, numbers and underscores. Underscore becomes the only option to define namespaces in machine names.

For example, for a user-created Blog type:

> * Name: user.Blog
> * Type: user_blog
> * Description: A user Blog content type.

End users may be unable to understand the meaning of Create a user.Blog. Using underscore-separated machine names and leaving the human-readable names as usual is probably a better idea.

The user created blog type can be rewritten as:

> * Name: Blog
> * Type: user_blog
> * Description: A user Blog content type.

While developers can recognize the user.Blog content type from user_blog, users reads Create a Blog in their menus.

A longer name example may write:

> * Name: Journal
> * Type: webinit_acad_journal

Journal Issue:
> * Name: Journal issue
> * Type: webinit_acad_journal_issue

Journal Article:
> * Name: Journal Article
> * Type: webinit_acad_journal_article

Building Conventions

Naming conventions to Drupal developers are kinda the same thing as coding standards to programmers. Building conventions among Drupal developers is reaching consensus among a team of developers. The technical leader is responsible for building up conventions in his team.

Consumer Consensus Although consumers may not see any machine-readable names explicitly on web pages, human-readable names are visible to consumers in many menu items. Developers must realize that human-readable names are consumed by end users. Display names are not only meaningful to developers, but also meaningful to end-users. In addition, end-users are also concerned about entity descriptions.

Developer Consensus Developers may reach an agreement about naming conventions.

The above example about academic journals and articles is defined by use case. All journal-related items belong to the journal subsystem of the acad scope because journals and articles are designed within the journal subsystem. Along with the content types, developers can create journal related blocks and views following the namespace webinit_acad_journal_. For example,

A Journal View:
> * Name: Journal view
> * Machine: webinit_acad_journal_view_journal

A Journal Issue View:
> * Name: Journal issue view
> * Machine: webinit_acad_journal_view_issue

The functionality domain is more useful for functions like node reference views and other assisting-purpose views. For example, in webinit_acad_journal_issue content type, it has a node reference field of journals from a view dedicated to listing journals. The view follows the pattern,
> * Name: Node reference view of journals
> * Machine: noderef_journal

However, this view can also be put into the namespace specified above,
> * Name: Node reference view of journals
> * Machine: webinit_acad_journal_noderef_journal

By packaging content types and views into the same namespace, users are able to focus on the problem scope and the set of features in Drupal provided by developers. Developers can easily find out bugs within the scope during maintenance.

Next article will discuss Reusable Fields.