Theming¶

Custom Bootstrap 5 Theme¶

With the new BS5 framework, creating a custom theme that is an extension of the default arDominionB5Plugin theme has become significantly easier. A skeleton for an empty AtoM theme plugin that extends arDominionB5Plugin without any modifications can be found in this arThemeB5Plugin repository.

$ npm install
$ npm run build

$ cd ~/atom
$ git clone --depth=1 https://github.com/artefactual-labs/arThemeB5Plugin.git plugins/arCustomThemeB5Plugin
$ rm -rf plugins/arThemeB5Plugin/.git plugins/arB5ThemePlugin/README.md

$ cd plugins/arCustomThemeB5Plugin/config/
$ mv arThemeB5PluginConfiguration.class.php arCustomThemeB5PluginConfiguration.class.php

cd ~/atom
npm install
npm run build

Custom Bootstrap 2 Theme¶

Let’s start building the plugin structure from the command line. Our theme is going to be called Corcovado (arCorcovadoPlugin). We are going to track its contents with git and publish them in a remote repository hosted by GitHub so we can enable others to contribute in the development. The repository is open source so you can use it for your own reference, see https://github.com/artefactual-labs/atom-theme-corcovado. You can also create your own repository.

Let’s begin to do some real work:

$ cd ~/atom/plugins
$ mkdir arCorcovadoPlugin
$ git init
$ echo "# Corcovado theme" > README.md
$ git add README.md
$ git commit -m "Initial commit"
$ git remote add origin git@github.com:artefactual-labs/atom-theme-corcovado.git
$ git push

We’ve created an empty directory where our plugin is going to be contained, made a git repository of it, tracked our first file and published our work to GitHub! However, our plugin does not meet the needed requirements for AtoM to recognize it and allow us to enable it. Let’s make that happen:

$ cd ~/atom/plugins/arCorcovadoPlugin
$ mkdir config
$ cd config

Create a new file arCorcovadoPluginConfiguration.class.php with the following contents:

<?php

class arCorcovadoPluginConfiguration extends sfPluginConfiguration
{
  // Summary and version. AtoM recognizes any plugin as a theme as long as
  // the $summary string contains the word "theme" in it (case-insensitive).
  public static
    $summary = 'Theme plugin, extension of arDominionPlugin.',
    $version = '0.0.1';

  public function contextLoadFactories(sfEvent $event)
  {
    // Here we are including the CSS stylesheet build in our pages.
    $context = $event->getSubject();
    $context->response->addStylesheet('/plugins/arCorcovadoPlugin/css/min.css', 'last', array('media' => 'all'));
  }

  public function initialize()
  {
    // Run the class method contextLoadFactories defined above once Symfony
    // is done loading the internal framework factories.
    $this->dispatcher->connect('context.load_factories', array($this, 'contextLoadFactories'));

    // This allows us to override the application decorators.
    $decoratorDirs = sfConfig::get('sf_decorator_dirs');
    $decoratorDirs[] = $this->rootDir.'/templates';
    sfConfig::set('sf_decorator_dirs', $decoratorDirs);

    // This allows us to override the contents of the application modules.
    $moduleDirs = sfConfig::get('sf_module_dirs');
    $moduleDirs[$this->rootDir.'/modules'] = false;
    sfConfig::set('sf_module_dirs', $moduleDirs);
  }
}

You may also have to clear the Symfony cache, depending on the configuration of your environment but it’s not necessary in our Vagrant box. Now open the theme manager in AtoM found under the Admin menu. The new arCorcovadoPlugin should appear and you can enable it now. We have not defined our stylesheets yet so you will basically see a bunch of text and links on a blank page. We are going to fix that now.

Download the reference stylesheet and compile it:

$ cd ~/atom/plugins/arCorcovadoPlugin
$ mkdir css
$ cd css
$ wget https://raw.githubusercontent.com/artefactual-labs/atom-theme-corcovado/master/css/main.less
$ lessc --compress --relative-urls main.less > min.css

Now try to visit your AtoM site again from your browser. The aspect of Corcovado is a bit unusual and buggy but you can have an idea of how much you can achieve with just a small number of CSS selectors and expressions. Additionally, you can take advantage of the extra sugar supported by the Less CSS pre-processor, e.g. variables, functions, includes, etc…

The arCorcovadoPlugin repository includes a Makefile that simplifies the compilation of the final stylesheet artifact which you could track in your git repository or build when needed. We prefer the latter but you may prefer to avoid having to install Less and its dependencies in production.

In Dominion, we use the Gulp build system in order to automatically build the final CSS file when we make changes in our stylesheets, saving us from running that extra step. It’s a tiny improvement that really counts when you spend hours building a theme. Gulp can do much more than that, like refreshing our browser or doing live reload each time we make a change, but that’s something that we haven’t tried yet.

Symfony plugins allow you to do much more. For example, you could include and use custom images, add your own templates or override the original ones provided by AtoM, inject new controllers, filters, or signal callbacks, and much more. Take a look at our arArchivesCanadaPlugin. This theme overrides the original homepage template as well as the search box and the main header template. Other plugins in the same repository may give you more ideas of what’s possible - we’ve built much more than simple application themes through plugins, e.g. our metadata templates or our initial HTTP API work are Symfony plugins too.

Back to the top