serum v1.4.1 Serum.Theme behaviour 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

Link to this type

t()

View Source
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

Returns information about the theme author.

Link to this callback

description()

View Source
description() :: binary()

Returns a short descriptive text about the theme.

Link to this callback

get_assets()

View Source
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.

Link to this callback

get_includes()

View Source
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"
]
Link to this callback

get_templates()

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

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

Returns the theme name.

Returns the required version of Serum.

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

Returns the theme version.

The returned value must follow the semantic versioning scheme.