best practices

Note: This document describes a file organization and aggregation strategy that has not yet been implemented in Drupal 8. See this core issue for that on-going work: http://drupal.org/node/1921610

File Structure

Rulesets should be grouped into logical files that enforce the separation of concerns within the CSS, that can be aggregated efficiently and that can be easily overridden by themers.

Drupal 8 follows a SMACSS-style categorization of its CSS rules:

1. Base — CSS reset/normalize plus HTML element styling.
2. Layout — macro arrangement of a web page, including any grid systems.
3. Component — discrete, reusable UI elements.
4. State — styles that deal with client-side changes to components.
5. Skin — purely visual styling (“look-and-feel”) for a component.

For more information about Drupal 8’s use of SMACSS, see the “Separate Concerns” section of the CSS Architecture page.

These categories help us keep CSS styles with different purposes from getting intertwined with one another. However, they don’t directly dictate file structure. Drupal 8 recommends the following guidelines for structuring CSS across files:

Note: This document aims to apply emerging best-practices for CSS to Drupal 8. As we implement these ideas in Drupal 8, this document may need to be updated.

Goals

The goals of good CSS should not be so different from those of good software engineering. Well-architected CSS, like PHP or JavaScript, should be:

1. Predictable

CSS throughout Drupal core and contributed modules should be consistent and understandable. Changes should do what you would expect without side-effects.

2. Reusable

CSS rules should be abstract and decoupled enough that you can build new components quickly from existing parts without having to recode patterns and problems you’ve already solved. – Philip Walton, CSS Architecture

3. Maintainable

As new components and features are needed, it should be easy to add, modify and extend CSS without breaking (or refactoring) existing styles.

4. Scalable

CSS should be easy to manage for a single developer or for large, distributed teams (like Drupal’s).

The Component

To minimize friction when contributing to CSS, the front-end developers of the Drupal community have reached consensus about our coding standards for:

• Formatting CSS code.
• CSS architecture, including goals, pitfalls and best practices.
• Grouping rulesets into files.

Despite our natural range of working styles and coding preferences, we value collaboration and ease of development, so we have attempted to explain our standards clearly in this document.

"Part of being a good steward to a successful project is realizing that writing code for yourself is a Bad Idea™. If thousands of people are using your code, then write your code for maximum clarity." - Idan Gazit

Acknowledgements

This guide is based upon the works, Principles of writing consistent, idiomatic CSS by Nicolas Gallagher and Scalable and Modular Architecture for CSS (SMACSS) by Jonathan Snook with a hat tip to Nicole Sullivan’s ground-breaking Object Oriented CSS.

What You Should Know

This book page is not for developers new to application testing; therefore, it does not describe unit testing concepts and techniques. The following list describes the level of experience or knowledge required to understand this book:

• Familiarity with unit tests, programming on PHP 5.x with the corresponding development tools for that platform, and the process of writing tests in general.
• A general understanding of the structure and concept of xUnit testing frameworks; the object model; dependency management (composition, inheritance patterns) including database mocking.

Agile testing combines engineering with testing activities into one activity and can be expressed by following Test Driven Development where a developer would write tests first. In particular, this book page focuses on unit testing where units represent objects or single architectural layers in contrast to functional testing (customer tests) where a unit represents the complete application (many architectural layers). Functional testing is also vitally important to Drupal but the focus of a separate book page.

Why to Isolate - Focus on Unit Tests

This page gives a short list of things to be aware of when developing Drupal modules.

Use tools to evaluate your module’s pages for accessibility

Use the Web Accessibility Evaluation Tool (WAVE) toolbar or another automated tool to check any pages or blocks that your module creates for accessibility issues.

Here is a list of more accessibility validation tools. These tools will not detect all accessibility problems, but are a great start.

Use the Form API appropriately

If you use the Drupal Form API, it will do a lot of work towards making your forms accessible. Make sure when using hook_form_alter and other techniques to modify forms that you are not reducing the accessibility of forms.

Use #title and #description

Every FAPI element should have the #title property set. This makes a label for the input field so that screenreader users know what the input field is for. The #title property should indicate the label associated to the form element. It should not be used for formatting other text (to create a heading, for example).

If the form element needs additional description beyond the title, set the #description property as well.

For example,

<?php
$form['pass'] = array(
'#type' => 'password',

When a site is made live, it faces a variety of new performance, user interaction, security, maintenance, and quality assurance concerns. Every site is different, but this checklist will get you started with common site launch tasks. It will also get you thinking about the kind of tasks that may be needed for your specific site's needs.

Performance

• Go to Site Configuration -> Performance and within the Cache area enable Cache pages for anonymous users and Cache blocks by clicking in the checkbox if necessary. You should see checks appear.
• Within Bandwidth Optimization enable Compress cached pages, Aggregate and compress CSS files, and Aggregate JavaScript files.
• Turn off unnecessary modules, such as Devel.

User Interaction

• Protect your forms against spam and attacks.
• What kind of forms are anonymous and authenticated users able to access on your site?
• Have you enabled CAPTCHA, reCAPTCHA, or an anti-spam service such as Mollom?