Creating Themes - nicolaschan/bell GitHub Wiki

Even if you have very little experience programming, you can contribute to Bell by adding your own custom themes! This is a great way to add functionality that everyone will see, as well as practice the process of submitting your code.

We are very grateful to all that try to contribute and are happy to answer your questions.

Themes are modular and each one has its own separate file in src/themes. There are helper functions that have already been written to make it as easy as possible to make a simple theme, but you also have the option to do more advanced things. You can look at the other themes as examples.

How to create a simple theme

Let's take a look at the Default theme.

const BasicLightAndDarkTheme = require('./templates/BasicLightAndDarkTheme')
const BasicTiming = require('./timings/BasicTiming')

module.exports = BasicLightAndDarkTheme(
  'Default',
  BasicTiming,
  ['red', 'orange', 'yellow', 'lime'],
  {
    weekend: 'cyan',
    holiday: 'magenta'
  })

The Default theme uses some helper functions, imported at the top. BasicTiming takes care of changing the colors so we don't have to worry about programming when the colors should change. BasicLightAndDarkTheme combines the timing with the colors we will add and creates both a Light and Dark version of our theme.

If you want your theme to be the same as the Default theme except with different colors, simply copy the Default theme and replace the color names.

You will also need to change the name (currently it says 'Default') and create a new file in the src/themes folder for your theme. After you're done, you can submit a pull request (step 3 of the Github flow). We (and some automated bots) will help check for any mistakes. If all is well, we can accept your code into the repository!

How themes work

At its simplest, a theme is just a function:

theme :: BellTimer -> ThemeCSS

The function takes one argument, the current instance of BellTimer, and depending on the state of BellTimer returns an object with CSS to apply to various elements on the page.

A theme can adjust CSS for four parts of the Bell interface:

  1. Background: simply the background color
  2. Text: the text that displays the time
  3. Subtext: the text below the time that says the schedule name (as well as the text in the top corners)
  4. Contrast: the background color for the popup

We use helper functions to simplify common use cases. For example, often we simply want to specify the color of an element, but the CSS is different for text color or background color, so we have ColorSchemeTransformations.fromObjectStrings to do that transformation for us. Other helper functions abstract away timing concerns or creating light and dark versions of a theme.