Components

Components are your way to build re-usable element templates.

A .press file's top-level <components> element contains all component definitions. A component definition is a skeleton of elements with <slots /> reserving space for inputs the come later on.

When instantiated (i.e. used as an element), a component expands into a single element, determined by the definition's as attribute (v-stack by default).

Slots

A child-less <slot /> element within a component definition acts as reserved space for inputs to come at the time of instantiation. By default, slots are nameless, though if the component must differentiate between parts of its input then named slots can be used (by giving the slot a name attribute).

Note that you can't mix named and un-named slots.

Additionally, slots can have the attribute single="true" meaning they will only take a single element from their input sequence.

Repeats

Elements (and slots) can be grouped within a component definition via a <repeat> element. By default this will loop over all elements contained within it until any slot children are empty. Although certain slots can be selected by giving the repeat a content attribute. Similar to document.

Attribute Arguments

Beyond slots, components can accept arguments in the form of attributes given in their instantiations. The syntax of this is {{ attrs.attr-name }} where attr-name is an attribute of the component itself.

Attribute arguments can be used as text or as the value for another attribute.

Examples

Below is a simple image figure component definition.

<image-figure img="fallback.png">
  <frame border-weight="2pt" border-color="black">
    <img src="{{ attrs.img }}"/>
  </frame>
  <p>
    <slot/>
  </p>
</image-figure>

This can be used anywhere a regular element can be like so:

<image-figure img="my-image.png">
  This is a caption.
</image-figure>

Here's a simple footer you might place at the bottom of a page:

<footer as="h-stack" style="border-weight-top=2pt; border-color-top=black;
margin=4pt">
  <frame width="fill">
    <slot name="prefix"/>
    | {data.date}
  </frame>

  <frame>
    <slot name="postfix"/>
  </frame>
</footer>

Note the named slots. This would be instantiated like so:

<footer>
  <prefix>
    A report by Papermill.
  </prefix>

  <postfix>
    visit <a href="https://www.papermill.io/">papermill.io</a>
  </postfix>
</footer>