Skip to content

Themes

Jump to bottom
Eunbin Jeong edited this page May 8, 2019 · 3 revisions

Serum Themes

A Serum theme is a set of predefined templates and assets which are used while Serum is building a project.

How Themes Work

A Serum theme is a Mix project which has the following contents:

  • Modules that implement Serum.Theme behaviour,
  • And theme files such as templates, includes, and other assets. These files are usually stored in the priv/ directory.

The Serum.Theme behaviour

Your theme package must have at least one module that implements the Serum.Theme behaviour, as Serum will call callbacks of this behaviour to ensure that your modules provide appropriate theme resources when needed.

  • name() :: binary()

    Returns the name of the theme.

  • description() :: binary()

    Returns a short descriptive text about the theme.

  • author() :: binary()

    Returns information about the theme author, such as name, contacts, etc.

  • legal() :: binary()

    Returns the legal information regarding the theme, such as copyright notice, license, etc.

  • version() :: binary()

    Returns the theme version. Must follow the semantic versioning scheme.

  • serum() :: binary()

    Returns the required version of Serum. Refer to this document for the string format.

  • get_includes() :: [binary()]

    Returns a list of paths to include files. All paths in the list must end with ".html.eex". Anything that does not end with ".html.eex" will be ignored.

    Example Return Value:

    [
  "/path/to/theme/priv/includes/nav.html.eex",
  "/path/to/theme/priv/includes/sidebar.html.eex",
  "/path/to/theme/priv/includes/footer.html.eex"
]

  • get_templates() :: [binary()]

    Returns a list of paths to template files. Each path in the list must end with one of these: "/base.html.eex", "/list.html.eex", "/page.html.eex", and "/post.html.eex". Anything else will be ignored.

    Example Return Value:

    [
  "/path/to/theme/priv/templates/base.html.eex",
  "/path/to/theme/priv/templates/list.html.eex",
  "/path/to/theme/priv/templates/post.html.eex"
]

  • get_assets() :: binary() | false

    Returns a path to the assets directory. All files in the directory pointed by the returned value will be copied to the destination assets directory using File.cp_r/2.

    This callback may return false to indicate that no asset will be copied.

Using Serum Themes

To use a Serum theme, you first need to add the theme package to your dependencies list.

# mix.exs
defp deps do
  [
    {:serum, "~> 1.0"},
    # ...

    # If the theme is available on Hex.pm:
    {:serum_theme_sample, "~> 1.0"}

    # If the theme is available on somewhere else:
    {:serum_theme_sample, git: "https://github.com/..."}
  ]
end

Fetch and build the theme package using mix.

$ mix do deps.get, deps.compile

To configure your Serum project to use a theme, you need to put a :theme key in your serum.exs.

# serum.exs:
%{
  theme: Serum.Themes.Sample,
  # ...
}

Read the documentation provided by the theme author, to see the list of files the theme consists of. Files provided by the theme are always overridden by corresponding files in your project directory. So it is safe to remove files from your project if the theme has ones.

Finally, try building your project to see if the theme is applied correctly.

$ mix serum.server
# Or,
$ MIX_ENV=prod mix serum.build
Clone this wiki locally