README

The Atomium theme is a Drupal 7 base theme.

The goal of this base theme is to rewrite most of the core theme functions of Drupal and use proper render arrays and templates instead. This will allow users to customize most of the elements in a custom sub-theme using preprocess functions or by providing a custom template.

Installation & requirements

Since the branch 7-x-3.x, Atomium requires the module Registry on steroids and its submodule to be installed and enabled.

As it is technically not possible for a theme to depends on a module, please make sure that these modules are enabled.

Download the theme manually or using Drush.

Requirements

PHP: greater or equal to version 5.6.
Drupal 7: latest stable version,
Drupal contrib module: Registry on steroids

Go to top

Activation

To enable the theme, go to admin/appearance and select an Atomium based theme.

Atomium comes with "Atomium Bartik" sub-theme provided as an example, also, it can be used as a starter-kit. It is a fork of the Bartik core theme but based on Atomium.

The sub-theme provide examples of preprocess functions and templates, allowing custom theme to be crafted quickly.

Go to top

Configuration

Atomium is not intended to be a full featured theme as most of themes on drupal.org, full of configurable settings and with a friendly user interface. The sole purpose of this theme is to provide clean markup that can be easily extend.

However, Atomium provides the following setting:

Allow CSS double underscore.

The theme debug mode setting has been moved to Registry on steroids module.

As of Drupal 7.51, a new allow_css_double_underscores variable has been added to allow for double underscores in CSS identifiers. In order to allow CSS identifiers to contain double underscores (.example__selector) for Drupal's BEM-style naming standards, this variable can be set to TRUE.

Go to top

Contributing

Atomium is licenced under the EUPL Licence. All contributions to Atomium and its sub-themes are made on Github, the main Atomium repository.

To ensure its code quality, Atomium depends on:

In order to use it and pass the automated tests, run:

Using Docker Compose

A very easy and handy way to speed up the development environment is by using Docker and Docker Compose.

Docker provides the necessary services and tools such as a web server and a database server to get the site running, independent of host machine configuration.

Requirements:

Configuration

By default, Docker Compose reads two files, a docker-compose.yml and an optional docker-compose.override.yml file. By convention, the docker-compose.yml contains the common configuration and it is provided by default. The override file, as its name implies, can contain configuration overrides for existing services or entirely new services. If a service is defined in both files, Docker Compose merges the configurations. By using .env file to define variables, such as PHP version, which allows a quick debug on docker-compose by running the below command without spinup the container and also avoid hard-coding values.

docker-compose config

Find more information on Docker Compose extension mechanism on the official Docker Compose documentation.

Usage

To start, run:

docker-compose up

It is advised to not daemonise docker-compose so it can be turned off (CTRL+C) quickly when it is not anymore needed. However, there is an option to run docker on background by using the flag -d:

docker-compose up -d

Then:

docker-compose exec web composer install
docker-compose exec web ./vendor/bin/taskman drupal:site-install

Using default configuration, the development site files should be available in the build directory and the development site should be available at: http://127.0.0.1:8080/build.

Running the tests

To run the grumphp checks:

docker-compose exec web ./vendor/bin/grumphp run

To run the phpunit tests:

docker-compose exec web ./vendor/bin/phpunit

Without docker

composer install

This will:

Build a target test site in ./build
Run $ ./vendor/bin/taskman drupal:site-setup which will setup site and tests configuration files, such as phpunit.xml

After that:

Copy taskman.yml.dist into taskman.yml and customize it according to your local environment
Install the site by running $ ./vendor/bin/taskman drupal:site-install

For a list of available commands run:

./vendor/bin/taskman

Generate changelog

Place your token in taskman.yml file:

github:
  token: YOUR_TOKEN

and then:

./vendor/bin/taskman github:changelog

For more information about how to customise the building process check PHP Taskman project page.

Go to top

Extending

Atomium provides a way of extending just by creating some files without modifying the core Atomium files. Each theme definition, core or custom, is treated as a component. Theme definitions can be found in the templates directory of each sub-theme.

To create a new theme definition:

Create a directory in templates and name it as desired. A good practice is to give it the name of the definition.
Create a file [NAME-OF-THE-THEME-DEFINITION].component.inc,
Create the function [NAME-OF-THE-THEME]_atomium_theme_[NAME-OF-THE-THEME-DEFINITION](),
Create a file [NAME-OF-THE-THEME_DEFINITION].css and/or [NAME-OF-THE-THEME_DEFINITION].js to get these files automatically loaded.

Atomium provides a custom page available on the path: atomium-overview. This particular page is only available to users with _administer themes_ permission.

This page acts as a showcase page of components. To add a component in there, a custom component needs to define two hooks:

hook_atomium_definition_hook()

This hook allows to define only one component.
hook_atomium_definition_form_hook()

This hook allows to define one or multiple components in a Drupal form.

For a better understanding and examples, see the atomium.api.php file.

Do not forget to clear the cache every time a new theme definition or process/preprocess is added or removed.

Go to top

Developer's note

During the development of this project, a lot of time has been put into analyzing how Drupal's core functions were implemented and how to improve them for better customization.

A good example of this is the breadcrumb generation.

Let's analyse how it is currently done in Drupal and how it is implemented on this project.

$variables['breadcrumb'] = theme('breadcrumb', array('breadcrumb' => drupal_get_breadcrumb()));

By default, Drupal uses the function drupal_get_breadcrumb() in its template_process_page() hook.

The function drupal_get_breadcrumb() returns raw HTML. Thus, it is impossible to alter the breadcrumbs links properly.

In order to get a render array, it requires a deeper analyse and rewrite functions accordingly.

drupal_get_breadcrumb() calls menu_get_active_breadcrumb(). This is actually the function that returns the HTML.

There is no way to alter the result of that function as it returns an array of raw HTML links.

Unfortunately, in order to change this behaviour, two extra functions were implemented in Atomium, also the way the breadcrumb is generated changed, by overriding the default one as shown below:

  $variables['breadcrumb'] = array(
    '#theme' => array('breadcrumb'),
    '#breadcrumb' => atomium_drupal_get_breadcrumb(),
  );

atomium_drupal_get_breadcrumb() is an Atomium internal function written only for the breadcrumb handling. Instead of calling menu_get_active_breadcrumb(), it calls atomium_menu_get_active_breadcrumb() which is also a custom Atomium function that, instead of returning an array of raw HTML links, returns an array of render arrays.

This is why, in page.tpl.php, instead of writing:

<?php print $breadcrumb; ?>

should be:

<?php print render($breadcrumb); ?>

The rendering process is at the very end of the Drupal's chain of preprocess, process and render functions.

Go to top

In the press

A word about Atomium

Go to top

ec-europa / atomium

Maintainers

Details

README

Table of contents:

Installation & requirements

Requirements

Activation

Configuration

Contributing

Using Docker Compose

Requirements:

Configuration

Usage

Running the tests

Without docker

Generate changelog

Extending

Developer's note

In the press