Top Menu

Jump to content
Home
    • Projects
    • Work packages
    • News
    • Getting started
    • Introduction video
      Welcome to OpenProject Community
      Get a quick overview of project management and team collaboration with OpenProject. You can restart this video from the help menu.

    • Help and support
    • User guides
    • Videos
    • Shortcuts
    • Community forum
    • Professional support

    • Additional resources
    • Data privacy and security policy
    • Digital accessibility (DE)
    • OpenProject website
    • Security alerts / Newsletter
    • OpenProject blog
    • Release notes
    • Report a bug
    • Development roadmap
    • Add and edit translations
    • API documentation
  • Sign in
      Forgot your password?
      Create a new account

      or sign in with your existing account

      Google

Side Menu

  • Overview
  • Activity
  • Roadmap
  • Work packages
  • Calendars
  • Team planners
  • Boards
  • Forums
  • Wiki
    • Table of contents
      • Expanded. Click to collapseCollapsed. Click to showDeveloper
        • Hierarchy leafAccessibility Checklist
        • Hierarchy leafCode Review Guidelines
        • Expanded. Click to collapseCollapsed. Click to showContribution
          • Hierarchy leafGit Workflow
          • Hierarchy leafTranslations
        • Expanded. Click to collapseCollapsed. Click to showDeveloping Plugins
          • Hierarchy leafDeveloping an OmniAuth Authentication Plugin
        • Hierarchy leafRelease Process
        • Hierarchy leafReport a bug
        • Hierarchy leafSecurity
        • Hierarchy leafSetting up an OpenLDAP server for testing
        • Hierarchy leafTheme Features
      • Hierarchy leafDownload
      • Expanded. Click to collapseCollapsed. Click to showFeature tour
        • Hierarchy leafRelease Notes OpenProject 30
        • Expanded. Click to collapseCollapsed. Click to showRelease Notes OpenProject 30 - Overview
          • Hierarchy leafGlossary
          • Hierarchy leafRelease Notes - Accessibility
          • Hierarchy leafRelease Notes - Accessibility changes
          • Hierarchy leafRelease Notes - Add work package queries as menu items to sidebar
          • Hierarchy leafRelease Notes - Copy projects based on Templates
          • Hierarchy leafRelease Notes - Design changes
          • Hierarchy leafRelease Notes - Fixed Bugs
          • Hierarchy leafRelease Notes - Keyboard Shortcuts
          • Hierarchy leafRelease Notes - Project settings
          • Hierarchy leafRelease Notes - Ruby&Rails Update
          • Hierarchy leafRelease Notes - Security
          • Hierarchy leafRelease Notes - Timelines
          • Hierarchy leafRelease Notes - Work packages
      • Hierarchy leafHowto create animated gifs
      • Hierarchy leafMigration Squashing
      • Hierarchy leafMod security
      • Hierarchy leafNew work package page
      • Hierarchy leafOP3 to OP4 Debian upgrade
      • Hierarchy leafOP4 Ubuntu1404 Stable with MySQL in production
      • Hierarchy leafOpenProject 40 Development Setup
      • Expanded. Click to collapseCollapsed. Click to showOpenProject Foundation
        • Hierarchy leafBoards
        • Hierarchy leafMembers
        • Hierarchy leafOPF-Meetings
        • Hierarchy leafStatutes
      • Expanded. Click to collapseCollapsed. Click to showRelease Notes
        • Hierarchy leafOpenProject released on Bitnami
      • Expanded. Click to collapseCollapsed. Click to showRelease Notes OpenProject 40 - Overview
        • Hierarchy leafRelease Notes OpenProject 40 - Accessibility improvements
        • Hierarchy leafRelease Notes OpenProject 40 - Column header functions in work package table
        • Hierarchy leafRelease Notes OpenProject 40 - Improved Design
        • Hierarchy leafRelease Notes OpenProject 40 - Integrated query title on work package page
        • Hierarchy leafRelease Notes OpenProject 40 - Integrated toolbar on work package page
        • Hierarchy leafRelease Notes OpenProject 40 - OmniAuth integration for OpenProject
        • Hierarchy leafRelease Notes OpenProject 40 - Work package details pane
      • Expanded. Click to collapseCollapsed. Click to showSecurity and privacy
        • Hierarchy leafFAQ
      • Expanded. Click to collapseCollapsed. Click to showSupport
        • Expanded. Click to collapseCollapsed. Click to showDownload and Installation
          • Hierarchy leafInstallation MacOS
          • Expanded. Click to collapseCollapsed. Click to showInstallation OpenProject 3 0
            • Hierarchy leafDebian Stable with MySQL in production
            • Hierarchy leafInstallation Ubuntu
            • Hierarchy leafInstallation Windows
            • Hierarchy leafInstallation on Centos 65 x64 with Apache and PostgreSQL 93
          • Expanded. Click to collapseCollapsed. Click to showInstallation OpenProject 40
            • Hierarchy leafOP4 Debian Stable with MySQL in production
          • Expanded. Click to collapseCollapsed. Click to showMigration paths
            • Hierarchy leafFrom Chilliproject to OpenProject
            • Hierarchy leafMigration 15 to 30
            • Hierarchy leafMigration 24 to 30
            • Hierarchy leafMigration Redmine 2x › OpenProject 30
            • Hierarchy leafOpenProject 3 Migration
          • Hierarchy leafOpenProject 40
        • Expanded. Click to collapseCollapsed. Click to showNews
          • Hierarchy leafNew OpenProject Translations Plugin
          • Hierarchy leafNew Plugin on OpenProjectorg Local Avatars
          • Hierarchy leafNew design for OpenProject
          • Hierarchy leafNews Accessibility workshop for OpenProject
          • Hierarchy leafNews Glossary for OpenProject
          • Hierarchy leafNews Heartbleed fixed
          • Hierarchy leafNews Icon Fonts
          • Hierarchy leafNews OpenProject 30 Release
          • Hierarchy leafNews Release GitHub Integration Plugin
          • Hierarchy leafNews Success Story Deutsche Telekom
          • Hierarchy leafNews Timelines
          • Hierarchy leafOpenProject 3013 released
          • Hierarchy leafOpenProject 3017 released
          • Hierarchy leafOpenProject 40 released
          • Hierarchy leafOpenProject 40 will be coming soon
          • Hierarchy leafOpenProject 405 released
          • Hierarchy leafOpenProject and pkgrio
          • Hierarchy leafOpenProject news moved to a new blog
          • Hierarchy leafOpenProjectBitnami
          • Hierarchy leafPackager version with plugins released ("Community edition")
          • Hierarchy leafRegistration OpenProject-Foundation
          • Hierarchy leafRelease OpenProject AuthPlugins
          • Hierarchy leafUpdates on OpenProject
          • Hierarchy leafWe need your feedback for the the new fullscreen view for work packages
        • Hierarchy leafOpenProject Plug-Ins
      • Hierarchy leafWiki
You are here:
  • Developer
  • Theme Features

Content

Theme Features

  • More
    • Print
    • Table of contents

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.

Loading...