Serum.Theme behaviour (serum v1.5.1) View Source

A behaviour that all Serum theme module must implement.

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

More specifically, a Serum theme is a Mix project which has the following contents:

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

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

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

Link to this section Summary

Functions

Returns a specification to start this module under a supervisor.

Callbacks

Returns information about the theme author.

Returns a short descriptive text about the theme.

Returns a path to the assets directory.

Returns a list of paths to include files.

Returns a list of paths to template files.

Returns the legal information about the theme, such as license.

Returns the theme name.

Returns the required version of Serum.

Returns the theme version.

Link to this section Types

Specs

t() :: %Serum.Theme{
  author: binary(),
  description: binary(),
  legal: binary(),
  module: module() | nil,
  name: binary(),
  version: Version.t()
}

Link to this section Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this section Callbacks

Specs

author() :: binary()

Returns information about the theme author.

Specs

description() :: binary()

Returns a short descriptive text about the theme.

Specs

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.

Specs

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"
]

Specs

get_templates() :: [binary()]

Returns a list of paths to template 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/templates/base.html.eex",
  "/path/to/theme/priv/templates/list.html.eex",
  "/path/to/theme/priv/templates/post.html.eex"
]

Specs

legal() :: binary()

Returns the legal information about the theme, such as license.

Specs

name() :: binary()

Returns the theme name.

Specs

serum() :: binary()

Returns the required version of Serum.

Read the "Requirements" section in the documentation for Version module for more information about version requirement format.

Specs

version() :: binary()

Returns the theme version.

The returned value must follow the semantic versioning scheme.