Ratatouille v0.5.1 Ratatouille.View View Source

In Ratatouille, a view is simply a tree of elements. Each element in the tree holds an attributes map and a list of zero or more child nodes. Visually, it looks like something this:

%Element{
  tag: :view,
  attributes: %{},
  children: [
    %Element{
      tag: :row,
      attributes: %{},
      children: [
        %Element{tag: :column, attributes: %{size: 4}, children: []},
        %Element{tag: :column, attributes: %{size: 4}, children: []},
        %Element{tag: :column, attributes: %{size: 4}, children: []}
      ]
    }
  ]
}

View DSL

Because it's a bit tedious to define views like that, Ratatouille provides a DSL to define them without all the boilerplate.

Now we can turn the above into this:

view do
  row do
    column(size: 4)
    column(size: 4)
    column(size: 4)
  end
end

While the syntax is more compact, the end result is exactly the same. This expression produces the exact same %Element{} struct as defined above.

To use the DSL like this, we need to import all the functions:

import Ratatouille.View

Alternatively, import just the ones you need:

import Ratatouille.View, only: [view: 0, row: 0, column: 1]

Forms

All of the possible forms are enumerated below.

Element with tag foo:

foo()

Element with tag foo and attributes:

foo(size: 42)

Element with tag foo and children as list:

foo([
  bar()
])

Element with tag foo and children as block:

foo do
  bar()
end

Element with tag foo, attributes, and children as list:

foo(
  [size: 42],
  [bar()]
)

Element with tag foo, attributes, and children as block:

foo size: 42 do
  bar()
end

Empty Elements

Similar to so-called "empty" HTML elements such as <br />, Ratatouille also has elements for which passing content doesn't make sense. For example, the leaf node text stores its content in its attributes and cannot have any child elements of its own.

In such cases, the block and list forms are unsupported.

Validation

While some errors---such as passing children to empty elements---are prevented by the DSL, it's still possible (for now, at least) to build semantically-invalid element trees using the DSL. This means that the elements are being used in a way that doesn't make sense to the renderer.

In order to prevent cryptic rendering errors, the renderer first validates the element tree it's given and rejects the whole thing if the structure is unsupported. It currently checks the following things:

The top-level element passed to the renderer must have the :view tag.
A parent element may only have child elements that have one of the supported child tags for the parent element.
An element must define all of its required attributes and may not define any unknown attributes.

The last two rules are based on the element's specification in Ratatouille.Renderer.Element.

Link to this section Summary

Functions

bar()

Defines an element with the :bar tag.

bar(attributes_or_children)

Defines an element with the :bar tag and either

bar(attributes, children)

Defines an element with the :bar tag and the given attributes and child elements.

canvas()

Defines an element with the :canvas tag.

canvas(attributes_or_children)

Defines an element with the :canvas tag and either

canvas(attributes, children)

Defines an element with the :canvas tag and the given attributes and child elements.

canvas_cell()

Defines an element with the :canvas_cell tag.

canvas_cell(attributes)

Defines an element with the :canvas_cell tag and the given attributes.

chart()

Defines an element with the :chart tag.

chart(attributes)

Defines an element with the :chart tag and the given attributes.

column()

Defines an element with the :column tag.

column(attributes_or_children)

Defines an element with the :column tag and either

column(attributes, children)

Defines an element with the :column tag and the given attributes and child elements.

element(tag, attributes_or_children)

element(tag, attributes, children)

label()

Defines an element with the :label tag.

label(attributes_or_children)

Defines an element with the :label tag and either

label(attributes, children)

Defines an element with the :label tag and the given attributes and child elements.

overlay()

Defines an element with the :overlay tag.

overlay(attributes_or_children)

Defines an element with the :overlay tag and either

overlay(attributes, children)

Defines an element with the :overlay tag and the given attributes and child elements.

panel()

Defines an element with the :panel tag.

panel(attributes_or_children)

Defines an element with the :panel tag and either

panel(attributes, children)

Defines an element with the :panel tag and the given attributes and child elements.

row()

Defines an element with the :row tag.

row(attributes_or_children)

Defines an element with the :row tag and either

row(attributes, children)

Defines an element with the :row tag and the given attributes and child elements.

sparkline()

Defines an element with the :sparkline tag.

sparkline(attributes)

Defines an element with the :sparkline tag and the given attributes.

table()

Defines an element with the :table tag.

table(attributes_or_children)

Defines an element with the :table tag and either

table(attributes, children)

Defines an element with the :table tag and the given attributes and child elements.

table_cell()

Defines an element with the :table_cell tag.

table_cell(attributes)

Defines an element with the :table_cell tag and the given attributes.

table_row()

Defines an element with the :table_row tag.

table_row(attributes_or_children)

Defines an element with the :table_row tag and either

table_row(attributes, children)

Defines an element with the :table_row tag and the given attributes and child elements.

text()

Defines an element with the :text tag.

text(attributes)

Defines an element with the :text tag and the given attributes.

tree()

Defines an element with the :tree tag.

tree(attributes_or_children)

Defines an element with the :tree tag and either

tree(attributes, children)

Defines an element with the :tree tag and the given attributes and child elements.

tree_node()

Defines an element with the :tree_node tag.

tree_node(attributes_or_children)

Defines an element with the :tree_node tag and either

tree_node(attributes, children)

Defines an element with the :tree_node tag and the given attributes and child elements.

view()

Defines an element with the :view tag.

view(attributes_or_children)

Defines an element with the :view tag and either

view(attributes, children)

Defines an element with the :view tag and the given attributes and child elements.

viewport()

Defines an element with the :viewport tag.

viewport(attributes_or_children)

Defines an element with the :viewport tag and either

viewport(attributes, children)

Defines an element with the :viewport tag and the given attributes and child elements.

Link to this section Functions

bar()

(macro)

Defines an element with the :bar tag.

Allowed Child Elements

label

Examples

Empty element:

bar()

With a block:

bar do
  # ...child elements...
end

bar(attributes_or_children)

(macro)

Defines an element with the :bar tag and either:

given attributes and an optional block
a list of child elements

Attributes

None

Allowed Child Elements

label

Examples

Passing attributes:

bar(key: value)

Passing attributes and a block:

bar(key: value) do
  # ...child elements...
end

Passing list of children:

bar([elem1, elem2])

bar(attributes, children)

(macro)

Defines an element with the :bar tag and the given attributes and child elements.

Attributes

None

Allowed Child Elements

label

Examples

bar([key: value], [elem1, elem2])

canvas()

(macro)

Defines an element with the :canvas tag.

Allowed Child Elements

canvas_cell

Examples

Empty element:

canvas()

With a block:

canvas do
  # ...child elements...
end

canvas(attributes_or_children)

(macro)

Defines an element with the :canvas tag and either:

given attributes and an optional block
a list of child elements

Attributes

height (required) - Integer representing the canvas height
width (required) - Integer representing the canvas width

Allowed Child Elements

canvas_cell

Examples

Passing attributes:

canvas(key: value)

Passing attributes and a block:

canvas(key: value) do
  # ...child elements...
end

Passing list of children:

canvas([elem1, elem2])

canvas(attributes, children)

(macro)

Defines an element with the :canvas tag and the given attributes and child elements.

Attributes

height (required) - Integer representing the canvas height
width (required) - Integer representing the canvas width

Allowed Child Elements

canvas_cell

Examples

canvas([key: value], [elem1, elem2])

canvas_cell()

(macro)

Defines an element with the :canvas_cell tag.

Examples

Empty element:

canvas_cell()

canvas_cell(attributes)

(macro)

Defines an element with the :canvas_cell tag and the given attributes.

Attributes

x (required) - Integer representing the cell's column (zero-indexed)
y (required) - Integer representing the cell's row (zero-indexed)
color (optional) - Constant representing color to use for foreground
char (optional) - Single character to render within this cell
background (optional) - Constant representing color to use for background
attributes (optional) - Constant representing style attributes to apply

Examples

canvas_cell(key: value)

chart()

(macro)

Defines an element with the :chart tag.

Examples

Empty element:

chart()

chart(attributes)

(macro)

Defines an element with the :chart tag and the given attributes.

Attributes

series (required) - List of float or integer values representing the series
type (required) - Type of chart to plot. Currently only :line is supported
height (optional) - Height of the chart in rows

Examples

chart(key: value)

column()

(macro)

Defines an element with the :column tag.

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

Empty element:

column()

With a block:

column do
  # ...child elements...
end

column(attributes_or_children)

(macro)

Defines an element with the :column tag and either:

given attributes and an optional block
a list of child elements

Attributes

size (required) - Number of units on the grid that the column should occupy

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

Passing attributes:

column(key: value)

Passing attributes and a block:

column(key: value) do
  # ...child elements...
end

Passing list of children:

column([elem1, elem2])

column(attributes, children)

(macro)

Defines an element with the :column tag and the given attributes and child elements.

Attributes

size (required) - Number of units on the grid that the column should occupy

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

column([key: value], [elem1, elem2])

element(tag, attributes_or_children)

element(tag, attributes, children)

label()

(macro)

Defines an element with the :label tag.

Allowed Child Elements

text

Examples

Empty element:

label()

With a block:

label do
  # ...child elements...
end

label(attributes_or_children)

(macro)

Defines an element with the :label tag and either:

given attributes and an optional block
a list of child elements

Attributes

content (optional) - Binary containing the text content to be displayed
color (optional) - Constant representing color to use for foreground
background (optional) - Constant representing color to use for background
attributes (optional) - Constant representing style attributes to apply
wrap (optional) - Boolean indicating whether or not to wrap lines to fit available space

Allowed Child Elements

text

Examples

Passing attributes:

label(key: value)

Passing attributes and a block:

label(key: value) do
  # ...child elements...
end

Passing list of children:

label([elem1, elem2])

label(attributes, children)

(macro)

Defines an element with the :label tag and the given attributes and child elements.

Attributes

content (optional) - Binary containing the text content to be displayed
color (optional) - Constant representing color to use for foreground
background (optional) - Constant representing color to use for background
attributes (optional) - Constant representing style attributes to apply
wrap (optional) - Boolean indicating whether or not to wrap lines to fit available space

Allowed Child Elements

text

Examples

label([key: value], [elem1, elem2])

overlay()

(macro)

Defines an element with the :overlay tag.

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

Empty element:

overlay()

With a block:

overlay do
  # ...child elements...
end

overlay(attributes_or_children)

(macro)

Defines an element with the :overlay tag and either:

given attributes and an optional block
a list of child elements

Attributes

padding (optional) - Integer number of units of padding

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

Passing attributes:

overlay(key: value)

Passing attributes and a block:

overlay(key: value) do
  # ...child elements...
end

Passing list of children:

overlay([elem1, elem2])

overlay(attributes, children)

(macro)

Defines an element with the :overlay tag and the given attributes and child elements.

Attributes

padding (optional) - Integer number of units of padding

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

overlay([key: value], [elem1, elem2])

panel()

(macro)

Defines an element with the :panel tag.

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

Empty element:

panel()

With a block:

panel do
  # ...child elements...
end

panel(attributes_or_children)

(macro)

Defines an element with the :panel tag and either:

given attributes and an optional block
a list of child elements

Attributes

color (optional) - Color of title
background (optional) - Background of title
attributes (optional) - Attributes for the title
padding (optional) - Integer providing inner padding to use when rendering child elements
height (optional) - Height of the table in rows or :fill to fill the parent container's box
title (optional) - Binary containing the title for the panel

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

Passing attributes:

panel(key: value)

Passing attributes and a block:

panel(key: value) do
  # ...child elements...
end

Passing list of children:

panel([elem1, elem2])

panel(attributes, children)

(macro)

Defines an element with the :panel tag and the given attributes and child elements.

Attributes

color (optional) - Color of title
background (optional) - Background of title
attributes (optional) - Attributes for the title
padding (optional) - Integer providing inner padding to use when rendering child elements
height (optional) - Height of the table in rows or :fill to fill the parent container's box
title (optional) - Binary containing the title for the panel

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

panel([key: value], [elem1, elem2])

row()

(macro)

Defines an element with the :row tag.

Allowed Child Elements

column

Examples

Empty element:

row()

With a block:

row do
  # ...child elements...
end

row(attributes_or_children)

(macro)

Defines an element with the :row tag and either:

given attributes and an optional block
a list of child elements

Attributes

None

Allowed Child Elements

column

Examples

Passing attributes:

row(key: value)

Passing attributes and a block:

row(key: value) do
  # ...child elements...
end

Passing list of children:

row([elem1, elem2])

row(attributes, children)

(macro)

Defines an element with the :row tag and the given attributes and child elements.

Attributes

None

Allowed Child Elements

column

Examples

row([key: value], [elem1, elem2])

sparkline()

(macro)

Defines an element with the :sparkline tag.

Examples

Empty element:

sparkline()

sparkline(attributes)

(macro)

Defines an element with the :sparkline tag and the given attributes.

Attributes

series (required) - List of float or integer values representing the series

Examples

sparkline(key: value)

table()

(macro)

Defines an element with the :table tag.

Allowed Child Elements

table_row

Examples

Empty element:

table()

With a block:

table do
  # ...child elements...
end

table(attributes_or_children)

(macro)

Defines an element with the :table tag and either:

given attributes and an optional block
a list of child elements

Attributes

None

Allowed Child Elements

table_row

Examples

Passing attributes:

table(key: value)

Passing attributes and a block:

table(key: value) do
  # ...child elements...
end

Passing list of children:

table([elem1, elem2])

table(attributes, children)

(macro)

Defines an element with the :table tag and the given attributes and child elements.

Attributes

None

Allowed Child Elements

table_row

Examples

table([key: value], [elem1, elem2])

table_cell()

(macro)

Defines an element with the :table_cell tag.

Examples

Empty element:

table_cell()

table_cell(attributes)

(macro)

Defines an element with the :table_cell tag and the given attributes.

Attributes

content (required) - Binary containing the text content to be displayed
color (optional) - Constant representing color to use for foreground
background (optional) - Constant representing color to use for background
attributes (optional) - Constant representing style attributes to apply

Examples

table_cell(key: value)

table_row()

(macro)

Defines an element with the :table_row tag.

Allowed Child Elements

table_cell

Examples

Empty element:

table_row()

With a block:

table_row do
  # ...child elements...
end

table_row(attributes_or_children)

(macro)

Defines an element with the :table_row tag and either:

given attributes and an optional block
a list of child elements

Attributes

color (optional) - Constant representing color to use for foreground
background (optional) - Constant representing color to use for background
attributes (optional) - Constant representing style attributes to apply

Allowed Child Elements

table_cell

Examples

Passing attributes:

table_row(key: value)

Passing attributes and a block:

table_row(key: value) do
  # ...child elements...
end

Passing list of children:

table_row([elem1, elem2])

table_row(attributes, children)

(macro)

Defines an element with the :table_row tag and the given attributes and child elements.

Attributes

color (optional) - Constant representing color to use for foreground
background (optional) - Constant representing color to use for background
attributes (optional) - Constant representing style attributes to apply

Allowed Child Elements

table_cell

Examples

table_row([key: value], [elem1, elem2])

text()

(macro)

Defines an element with the :text tag.

Examples

Empty element:

text()

text(attributes)

(macro)

Defines an element with the :text tag and the given attributes.

Attributes

content (required) - Binary containing the text content to be displayed
color (optional) - Constant representing color to use for foreground
background (optional) - Constant representing color to use for background
attributes (optional) - Constant representing style attributes to apply

Examples

text(key: value)

tree()

(macro)

Defines an element with the :tree tag.

Allowed Child Elements

tree_node

Examples

Empty element:

tree()

With a block:

tree do
  # ...child elements...
end

tree(attributes_or_children)

(macro)

Defines an element with the :tree tag and either:

given attributes and an optional block
a list of child elements

Attributes

None

Allowed Child Elements

tree_node

Examples

Passing attributes:

tree(key: value)

Passing attributes and a block:

tree(key: value) do
  # ...child elements...
end

Passing list of children:

tree([elem1, elem2])

tree(attributes, children)

(macro)

Defines an element with the :tree tag and the given attributes and child elements.

Attributes

None

Allowed Child Elements

tree_node

Examples

tree([key: value], [elem1, elem2])

tree_node()

(macro)

Defines an element with the :tree_node tag.

Allowed Child Elements

tree_node

Examples

Empty element:

tree_node()

With a block:

tree_node do
  # ...child elements...
end

tree_node(attributes_or_children)

(macro)

Defines an element with the :tree_node tag and either:

given attributes and an optional block
a list of child elements

Attributes

content (required) - Binary label for the node
color (optional) - Constant representing color to use for foreground
background (optional) - Constant representing color to use for background
attributes (optional) - Constant representing style attributes to apply

Allowed Child Elements

tree_node

Examples

Passing attributes:

tree_node(key: value)

Passing attributes and a block:

tree_node(key: value) do
  # ...child elements...
end

Passing list of children:

tree_node([elem1, elem2])

tree_node(attributes, children)

(macro)

Defines an element with the :tree_node tag and the given attributes and child elements.

Attributes

content (required) - Binary label for the node
color (optional) - Constant representing color to use for foreground
background (optional) - Constant representing color to use for background
attributes (optional) - Constant representing style attributes to apply

Allowed Child Elements

tree_node

Examples

tree_node([key: value], [elem1, elem2])

view()

(macro)

Defines an element with the :view tag.

Allowed Child Elements

overlay
canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

Empty element:

view()

With a block:

view do
  # ...child elements...
end

view(attributes_or_children)

(macro)

Defines an element with the :view tag and either:

given attributes and an optional block
a list of child elements

Attributes

top_bar (optional) - A :bar element to occupy the view's first row
bottom_bar (optional) - A :bar element to occupy the view's last row

Allowed Child Elements

overlay
canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

Passing attributes:

view(key: value)

Passing attributes and a block:

view(key: value) do
  # ...child elements...
end

Passing list of children:

view([elem1, elem2])

view(attributes, children)

(macro)

Defines an element with the :view tag and the given attributes and child elements.

Attributes

top_bar (optional) - A :bar element to occupy the view's first row
bottom_bar (optional) - A :bar element to occupy the view's last row

Allowed Child Elements

overlay
canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

view([key: value], [elem1, elem2])

viewport()

(macro)

Defines an element with the :viewport tag.

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

Empty element:

viewport()

With a block:

viewport do
  # ...child elements...
end

viewport(attributes_or_children)

(macro)

Defines an element with the :viewport tag and either:

given attributes and an optional block
a list of child elements

Attributes

offset_x (optional) - Integer representing the number of columns to offset the child content by. Defaults to 0.
offset_y (optional) - Integer representing the number of rows to offset the child content by. Defaults to 0.

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

Passing attributes:

viewport(key: value)

Passing attributes and a block:

viewport(key: value) do
  # ...child elements...
end

Passing list of children:

viewport([elem1, elem2])

viewport(attributes, children)

(macro)

Defines an element with the :viewport tag and the given attributes and child elements.

Attributes

offset_x (optional) - Integer representing the number of columns to offset the child content by. Defaults to 0.
offset_y (optional) - Integer representing the number of rows to offset the child content by. Defaults to 0.

Allowed Child Elements

canvas
chart
label
panel
row
sparkline
table
tree
viewport

Examples

viewport([key: value], [elem1, elem2])