Theme Development

Want to learn how to make your own themes for Opal? Well, you're in the right place, then.

Theme Directory Location

Opal Themes are stored in the public/themes directory. Opal automatically looks in the public/themes directory for any of these theme directories. Let's pretend we're working with a theme named example_theme. Here's the structure of our theme's directory:

public/
  themes/
    example_theme/
       images/
       javascripts/
         application.js
       layouts/
         application.html.erb
       stylesheets/
         application.css
       theme.yml
       screenshot.png
       screenshor_thumbnail.png

Theme Files & Subdirectories

Here's a brief explanation of what you'll find inside an Opal theme directory:
  • screenshot.png & screenshot.png - This a screenshot(and a thumbnail 100x100px) of your theme, which will be shown from Opal's interface.
  • theme.yml - A file that contains information about your theme(name, author, description, etc.).
  • stylesheets/ - contains css files that your theme will use.
  • javascripts/ - contains javascript files that your theme will use.
  • layouts/ - contains the template files for the application.
  • images/ - contains icons, backgrounds, and any other graphics or images your theme will use.

Theme Configuration File: theme.yml

Opal will automatically load all theme directories inside of public/themes. First, it will try to load the YAML file, theme.yml. This file contains all the the Theme's metadata(name, author, website, version, etc.). Here's an example of what a theme.yml file should look like:

# Example Theme for Opal 
theme:
    name: Example Theme
    description: An example theme for Opal.
    version: 0.0.1
    author: John Doe
    author_website: http://www.mywebsite.com
    theme_website: http://www.mywebsite.com/mythemewebpage

Theme CSS with application.css

Opal will also automatically load the css file: stylesheets/application.css and the javascript file: javascripts/application.js. The file, application.css, defines the look and feel of your your theme(colors, backgrounds, etc.).

Theme Javascript with application.js

Opal will also automatically load the javascript file, application.js, provides any custom javascript your theme will use. You can also modify application.js to change the jquery transition effects for Opal's toggle_box and replace_box functions.

Customizing Opal Core Views & Layouts

You can override any Opal core view or layout file from within your theme. To do this, create an identically named file inside your theme directory, under app/views. So, For example, if I wanted my theme to have a different homepage than Opal's default one, I'd create this file inside of my theme directory: app/views/browse/index.html.erb. That's it! Opal automatically knows to look in your theme directory for any views before using its default core views.

Similarly, you can also override Opal's default layout template(which all of the views are rendered inside). You can do this by creating app/views/layouts/application.html.erb inside your theme directory. Opal will look for this file and load it automatically. Otherwise, Opal's default layout template file is used.

Other Stuff

  • You can also add your own custom favicon to your theme, just place the favicon.ico file into the images directory of your theme, eg: public/themes/example_theme/images/favicon.ico.

That's it!

Once you've created and customized your Opal theme, try it out! To install a theme in Opal, just upload the theme directory into public/themes, and it will automatically show up in the Admin Section of Opal, on the Themes page of the Configure Page.

Packaging Your Theme for Opal's Theme Installer

As of Opal 0.4.1, you can now install themes from Opal's User Interface. Any theme installed with Opal's Theme Installer must be packaged inside a zip archive. So, if your theme is packaged into example_theme.zip, When a user installs your theme, all files inside example_theme.zip will get extracted into public/themes/example_theme. Here's an example of what a finished theme package should look like:

-example_theme.zip
   images/
   javascripts/
      application.js
   stylesheets/
      application.css
   theme.yml
   screenshot.png
   screenshor_thumbnail.png

Submit Your Theme

If you've created a theme, you can host it at Customize, along with many other Opal plugins and themes. All you have to do is create an account and submit your theme for approval. Easy Peasy!