OpenProject Themes - Creating a Theme

Note: This article was based on an older version of OpenProject and some details could be out of date.

This article describes the basics and technical details of creating a theme and making it available to the OpenProject application.

OpenProject’s new theme functionality (introduced with version 3.0) was designed with the asset pipeline in mind, provides an object-oriented way to register and configure themes on the source code level and enables its distribution through the Plugin/RubyGems ecosystem.

OpenProject uses the asset pipeline introduced in Rails 3.1 for most of its core assets. This allows for performance improvements due to compression and merging of stylesheet and JavaScript files. It also enables developers to write their files in Sass or CoffeeScript and letting these files be preprocessed by ERB. Consequently it is desirable to let custom themes profit from the asset pipeline as well.

An OpenProject theme consists of two parts:

1. Ruby code. It hooks up your theme into any OpenProject based application as well as gives you some methods to override for configuration.
2. Assets. Stylesheets, JavaScript and other asset files that make up your theme which live in a folder under app/assets.

This series of posts will focus on the former (1).

Themes can be distributed as OpenProject plugins, which themselves can be distributed as RubyGems. Themes register themselves with OpenProject by subclassing a specific OpenProject theme base class, much like engines do. In fact, OpenProject’s default theme is just a normal theme that is conveniently distributed with the core application.

Alright, let’s create a new theme from scratch. To make it easy we first create a theme directly in the core application so we don’t have to deal with RubyGems and Bundler. Once we have done that, we could create an OpenProject plugin with almost no extra work.

Suppose you want to write a goofy theme called Goofy, that changes or introduces some styling.

Create a file called goofy_theme.rb in OpenProject’s config/initializers directory with the following content:

class GoofyTheme < OpenProject::Themes::Theme
end

We place it there so it gets loaded when OpenProject boots up, but you can put it anywhere and it will be available once you require the file. It is noteworthy, that it’s just another plain old ruby object that’s not tied directly to Rails at this point.

Any class that descends from OpenProject::Themes::Theme will be available in OpenProject’s administrative area as a choosable theme. Start the OpenProject app and browse to Administration >> Settings and click on the Display tab. You can select your new goofy theme in the theme select box. Do it and press Save.

What happened? All the styles are missing. A closer look into the source of the page reveals the following:

<link href="/assets/goofy.css" media="all" rel="stylesheet" type="text/css" />

OpenProject’s Themes module tries to be smart and loads a CSS file based on the selected theme’s name but we haven’t created any content for the theme yet.

So let’s change the hover color of the default theme’s main menu links from light blue to black. Create a file called goofy.css in your app/assets/stylesheets folder and give it the following content:

/*
 *= require default
 */

#main-menu ul.menu_root li a:hover {
  background-color: black;
}

You may wonder what is going on here. First of all, as seen above goofy.css is the file that gets loaded by OpenProject when you activate the Goofy theme in the settings. It is a Sprockets manifest file so it can take any Sprockets as well as Stylesheet directives. The file can even be a goofy.scss for Sass or a goofy.css.erb if you need some Ruby preprocessing. The other thing to note is require default. This Sprockets directive includes OpenProject’s light blue default theme and adds all of its stylings to Goofy’s theme as well. After that, Goofy changes the background color of menu links to black.

Look at the page and hover over the main menu buttons to see the difference.

Of course, you don’t need to require all of the stylings of the default theme. You can pick and choose any file from the core app, such as reset.css or build everything from scratch.

For historical reasons all current OpenProject themes are an extension of the default theme, because all former themes for OpenProject (and its predecessor ChiliProject) were extensions of the core stylesheets of which a part became today’s default theme. Both parts combined were in fact foundation stylesheets (things like reset.css, libraries that are always included, i.e. jQuery UI, etc.) and specific theming styles (colors etc.). That means most themes worked by overwriting values defined by the default theme. A much better approach is to have each theme be based on a foundation like base.css, which in turn is based on a sophisticated reset.css and so on. From there, each theme goes independent ways. To be more specific, there is an application.css on which default.css is based upon which includes a lot of the mentioned foundation behaviour, but separating the foundation and pure theming parts inside default.css has not been tackled yet.

The other point worth noticing here is rather simple: goofy.css is a manifest file that OpenProject loads. Whatever is in there gets compressed, merged and finally displayed on your OpenProject instance. This is a notable improvement to the old themes functionality. Usually you want the manifest file to only contain Sprockets directives rather than styles. You can include any file that makes sense in the context of Sprockets. You can even require core stylesheet files from themes provided by plugins. For our toy example, it makes sense to create a goofy subfolder inside app/assets/stylesheets, put all stylesheet files in there and reference them from the manifest file so they will be included in the final merged version but be separate files in development. Look inside app/assets/stylesheets/default.css and the app/assets/stylesheets/default folder to get an idea how the default theme works.

When subclassing a theme it automatically adds its stylesheet manifest file (goofy.css in our case) to the asset pipeline’s precompile list so that your theme is available in production as well.

Congratulations, you now know how to create and hook up a new theme into an OpenProject instance.