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:
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.
- 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¶
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.
- 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.
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:
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!