View Source Serum.Theme behaviour (serum_md v1.6.0)

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_md, "~> 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

Summary

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.

Functions

Returns a specification to start this module under a supervisor.

Types

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

Callbacks

@callback author() :: binary()

Returns information about the theme author.

@callback description() :: binary()

Returns a short descriptive text about the theme.

@callback 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.

@callback 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"
]
@callback 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"
]
@callback legal() :: binary()

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

@callback name() :: binary()

Returns the theme name.

@callback 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.

@callback version() :: binary()

Returns the theme version.

The returned value must follow the semantic versioning scheme.

Functions

Returns a specification to start this module under a supervisor.

See Supervisor.