ec-europa / atomium
A clean and atomic base theme.
Installs: 6
Dependents: 0
Suggesters: 0
Security: 0
Stars: 9
Watchers: 29
Forks: 5
Open Issues: 39
Type:drupal-theme
Requires (Dev)
- composer/installers: ^1.6
- drupal-composer/preserve-paths: ^0.1.5
- drupal/admin_menu: 3.0.0-rc6
- drupal/composer_autoloader: ^1
- drupal/devel: ^1.7
- drupal/drupal: ^7.67
- drupal/drupal-extension: ~3.4
- drupal/realistic_dummy_content: ^2
- drupal/registryonsteroids: ^1.9
- drupal/xautoload: ^5.7
- drupol/drupal-conventions: ^1.4.15
- drupol/htmltag: ^2.2
- drush/drush: ^8.2.3
- mikey179/vfsstream: ^1.6
- phptaskman/changelog: ^0.2.1
- phptaskman/drupal: ^0.1.15
- phpunit/phpunit: ^5.7
- webflo/drupal-finder: ^1.1
- webmozart/path-util: ^2.3
- dev-7.x-3.x
- dev-nept-2797
- dev-7.x-2.x
- dev-issue-448-bug_item_list_children-7.x-2.x
- dev-issue-455-update_phptaskman
- dev-issue-455-update_taskman
- dev-issue-452-improve-hook-suggestion
- dev-issue-446-bug_fix_item_list-7.x-2.x
- dev-397-pager-component-more-flexibility
- dev-381-get-rid-of-html-tag
- dev-436-update-status-messages
- dev-390-atomium-overview-one-page-per-component-pol-7.x-3.x
- dev-390-atomium-overview-one-page-per-component-7.x-2.x
- dev-390-atomium-overview-one-page-per-component-7.x-3.x
- dev-343-fix-breadcrumb-anchor-7.x-2.x
- dev-275-update-readme-file-7.x-2.x
- dev-155-atomium_theme_registry_alter-optimize
- dev-130-optimize-attributes-classes
- dev-NEPT-1627_visual_regression_with_backstop
- dev-7.x-1.x
- dev-master
This package is auto-updated.
Last update: 2024-11-06 00:07:29 UTC
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.
Table of contents:
- Installation
- Requirements
- Activation
- Configuration
- Contributing
- Extending
- Developers note
- In the press
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
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.
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.
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 asphpunit.xml
After that:
- Copy
taskman.yml.dist
intotaskman.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.
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.
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.