Drupal Don’ts: Pitfalls to Avoid for Site Success

Success with Drupal development often depends as much on knowing what NOT to do as much as what to do.

If you are not “Thinking in Drupal," you are likely to develop a Drupal site using strategies that are not conducive to a:

• Drupal-friendly site that allows changes to be made to configuration without writing code;
• Site that is as accessible as it could be; and/or
• A low-maintenance coding strategy.

Let’s take a look at common Drupal development practices that do not reflect “Thinking in Drupal.”

Data Structures

The first category of “Don’ts” we want to share has to do with data structures. Content is the foundation of your site.

Don’t use the body field to create the webpage vs. regions and blocks.

In order to create a content page in Drupal, you fill out a form called a Content Type. By default, the form includes a title field and body field. If this feature is all you use, technically, you could use traditional HTML strategies and the body field to create the page you need.

For example, copying the code from an HTML page and pasting it into the body field. If that code includes structural elements and supplemental content, that practice is defeating the purpose of using Drupal and limits content reuse.

Don’t forget to use fields to structure content.

This next example overlaps a little with the example above. Assume for a moment that you are using content blocks to place various bits of content in the page sidebars on your content page. Congratulations. You’re “Thinking in Drupal.”

However, if you don’t take the next step and structure your content into more than just the title and body field, you are not setting up your site for easy content reuse. An easy way to explain this issue is with an event content page.

You can use the body field to enter the event description, date, time, location, audience, price, etc. Or, you can add fields to the content type for each bit of content. This strategy helps you create a consistent presentation of data and sets you up for the next issue.

When you split your content into bits of data, you take the next step towards “Thinking in Drupal” and are able to take advantage of the database query and display feature called Views.

Don’t forget to use Views to create dynamic lists of content.

The next step in “Thinking in Drupal” is querying the database to reuse the bits of content you have placed in fields. 

It is true that you can type a list into the body field of a page and make the list a set of links, just as you would do on hand-made HTML pages. However, that defeats the purpose of using a content management system. Enter it once, reuse it many times over. 

Views is the tool that lets you grab data from fields and display them in blocks and pages. Then, in the event the data source is updated, every instance of that data display is also updated automatically.

Don’t miss out on the power of Views.

Want to learn more about Drupal? Sign up for training!

Styling 

Your data has been stored and queried using Drupal-friendly strategies. Now’s the time to apply your look and feel to your content.

There is no getting around the fact that presentation of content is important to every site owner. Drupal ships with features that allow you to layout both content fields and supplemental blocks of data. It also includes what we call a theme that helps manage the look and feel of the site.

Although it is likely that you will use a theme that is customized to your branding, one needs to be careful not to prevent configuration settings from being overwritten. 

Don’t forget to use semantic HTML and WAI-ARIA.

With the arrival of HTML5, meaningful elements such as <article> and <header> came into play, among others. That doesn’t mean there haven’t been other meaningful elements.

The <p> element tells the reader the content is a paragraph. The <h1> through <6>, <blockquote>, <code> and <em> elements also carry meaning.

The most common non-semantic HTML element is <div>. Used to create sections on web pages, it often includes an ID that describes the sections: main, header, nav, and footer.

Unfortunately, human IDs aren’t recognized by assistive technology because, for example, “main” could also be written as “main content” or “content.” Then there are the various formats for “nav” such as “navigation”, “menu”, or “main menu.”

If you want to describe the semantic element, consider using ARIA rules. For example, <header role=”banner”> indicates that this instance of <header> is the banner on the page and not the header for some content.

How does this apply to Drupal? The theme templates and content entered by content authors. Although Drupal 8 uses HTML5, theme developers don’t always use it when customizing the look and feel of the site.

When creating templates and content, think beyond Drupal and include strategies that make your pages accessible. 

Don’t avoid using Drupal build features to manage the page layout.

When you were creating your blocks of content, be it manually or with Views, you placed them in regions defined by the theme. 

It is possible to create theme templates that manually render fields and blocks via the same strategies used by other content management frameworks. However, in doing so, you prevent the use of Drupal’s configuration interface from having any influence on that template.

Imagine you have five fields for a content type. By default, you can configure Drupal to display all five using the default templating strategies. Assume you add a field at a later time, or want to hide one of the existing fields, you can do so via the configuration interface.

However, if you deviate from the default and manually render the five fields, changes in configuration will not be realized on the page until the code is updated in the template.

This practice, unfortunately, is one that creates problems for site owners who believe they are receiving the flexibility that Drupal promises. Confusion and frustration ensue. If you are a site owner, insist on a configuration-based page/field layout strategy versus a hard-coded approach.

Read: A Quick Guide to Drupal Terminology

Customization

You can create complex sites without one line of custom code outside the appropriately coded custom theme you may need. However, when you have exhausted all configuration options, including using pre-existing features contributed by the Drupal community, you might have to write some custom code.

Adding or editing features in a Drupal site require developers to follow Drupal coding standards and practices. This means, a coder might not be able to follow the same practices used in other frameworks. Unfortunately, this is sometimes not understood.

Here are just a couple of examples of coding for Drupal.

Don’t forget to use patches to track code changes.

Given the numerous contributed modules available on Drupal.org, it’s likely your site will use one or more. There might be times when a contributed module offers, for instance, 95% of what you need, with a minor tweak of the code and it will do the job nicely.

The best practice is to create your own custom module with code that hooks into the contributed module in question. Your custom module makes the change the Drupal way and will be executed with calls to the site.

Unfortunately, not all contributed modules are coded with hook options. Although “hacking” contributed modules is not a recommended practice, sometimes it’s the best course of action for minor changes. However, this introduces a maintenance problem if not done correctly via patching. 

What is a patch? Simply put, a fix to the code. As issues are reported to the module project lead, recommended coding fixes are often shared as well for the next version of that module.

Meanwhile, your site might need that patch, so you take the new code and “fix” the module versus waiting for the next module release.

This same practice of patching can be used to keep track of minor code tweaks you need to make in the contributed module. Again, all efforts should be made to use existing code.

If not possible, create your own custom module. Then, if tweaking the functionality of a contributed module is what you choose, track the changes you made with a patch.

Lastly, store all your patches (fixes and tweaks) in a file on the server. For example, here sites/all/patches/PATCHES.txt.

Read: How to Fix Common Web Accessibility Barriers in Drupal

Don’t forget the admin interface for your custom module.

If you need a custom module to complete your site’s functionality, does the custom module need variables with values assigned? For example, you create a custom module that allows you to integrate an external service with your site. In order to access the external service, you need to pass a key to the service to gain access.

For some, the first thought might be to put that key into the code, with the assumption that the key will never change. This is a “hard coding” practice and hard coding is never recommended. 

The better approach is to separate the key from the code. Store the key in the database, separate from the code. How? Via an administrative interface.

In Drupal 8, entities are stronger than ever. A unique admin interface isn’t necessarily required. In some instances, you can create a content type to collect the data needed to store the key and other configuration options.

Be sure to provide clients with the means to manage custom features versus relying on code edits.

Conclusion

The above are just the basics when it comes to “Thinking in Drupal” and avoiding long-term issues in development and maintenance on your site.

If you are a developer, don’t assume that the coding practices that work in other frameworks are the best approach to developing in Drupal.

If you are a site owner, don’t assume your development team will choose strategies that will allow you to easily change and maintain your site without making that request specifically. Make it a point to "Think in Drupal."

Contact us today to continue the conversation about Drupal best practices that achieve distinct goals and create new possibilities.