View Source Surface.Catalogue.Examples (Surface v0.12.1)

A generic LiveView to create multiple stateless examples for the Surface Catalogue.

Each example must be a function component defined with the module attribute @example.

NOTE: If your examples require manipulating state (data) through handle_event callbacks, use Surface.Catalogue.LiveExample instead.

Options

Besides the buit-in options provided by the LiveView itself, examples can also pass the following options at the module level:

  • subject - Required. The target component of the Example.

  • catalogue - Optional. A module that implements the Surface.Catalogue providing additional information to the catalogue tool. Usually required if you want to share your components as a library.

Other options can be defined at the module level but also overridden at the function/example level using the @example module attribute. They are:

  • height - Required (either for the module or function). The height of the Example.

  • title - Optional. The title of the example.

  • body - Optional. Sets/overrides the attributes of the the Example's body tag. Useful to set a different background or padding.

  • direction - Optional. Defines how the example + code boxes should be displayed. Available values are "horizontal" or "vertical". Default is "horizontal" (side-by-side).

  • code_perc - Optional. When the direction is "horizontal", defines the percentage of the total width that the code box should take. Default is 50. Note: This configuration has no effect when direction is "vertical".

  • assert - Optional. When using catalogue_test/1, generates simple =~ assertions for the given text or list of texts.

When defined at the module level, i.e. passing to use Surface.Catalogue.Examples, ..., the options apply to all examples. Aside from subject and catalogue, options can be overridden at the function level using the @example module attribute.

Examples

Basic usage 

@example true
def basic_example(assigns) do
  ~F"""
  <Button>OK</Button>
  """
end

Defining a custom title + docs 

@example "Example with docs"
@doc "A simple example with documentation"
def example_01(assigns) do
  ~F"""
  <Button>OK</Button>
  """
end

Defining other options 

@example [
  title: "Example and Code split vertically",
  direction: "vertical",
  height: "110px",
  assert: ["Small", "Medium", "Large"]
]
def vertical(assigns) do
  ~F"""
  <Button size="small" color="info">Small</Button>
  <Button size="medium" color="warning">Medium</Button>
  <Button size="large" color="danger">Large</Button>
  """
end

Notice that whenever you want to pass other options using a keyword list as in the example above, in case you need to customize the title, it must to be passed as a key/value option as well.