# `MishkaCmsCore.Runtime.ContentBlocks`
[🔗](https://github.com/mishka-group/mishka_cms_core/blob/v0.0.1/lib/mishka_cms_core/runtime/content_blocks.ex#L5)

Ready-made blocks the content editor offers beside its single components — whole
`MishkaCmsCore.Runtime.ContentComponents` markers, components inside components and slots filled
in, so an author places one and only changes the words.

THEY COME FROM THE COMPONENTS' OWN EXAMPLES — a component's `examples`, finished uses of it as a
page would hold them, which a kit ships with its components and a component an author adds in the
CMS may carry too. Each example of each component the palette lists is read with the page builder's
template parser (`MishkaCmsCore.Runtime.PageBuilder.Tree`) and written as a marker: a component
as a component marker, a slot as a slot marker, HTML as the HTML it is. An example that needs
more than a marker holds — an expression, a loop, a component the palette does not list, a slot
its component does not declare — is not offered. Only the attributes a component declares and a
marker can carry are kept; the rest of an example's attributes are left to their defaults.

A component that declares how it arrives when dropped — the `furnishing` the page builder places
(`MishkaCmsCore.Builder.Furnishing`) — is offered that way too, first among its blocks: the plain
one, an author's starting point, named after the component itself.

Nothing here names a kit or a component: a site offers exactly the blocks its components bring.

## Events

  * `runtime:content:editor_blocks` — before the blocks are offered, with
    `%{site_id: site_id, blocks: blocks}` and `%{current_user: user}` as meta. Each block is
    `%{id, title, component, category, tree}`, `tree` a `t:MishkaCmsCore.Runtime.ContentComponents.tree/0`
    and `title` `nil` for the plain one, which is named after its component.
    A plugin answers the map with other `blocks` to add its own or take some away; the editor
    offers only those whose components the palette lists.

# `block`

```elixir
@type block() :: %{
  id: String.t(),
  title: String.t() | nil,
  component: String.t(),
  category: String.t(),
  tree: MishkaCmsCore.Runtime.ContentComponents.tree(),
  marker: String.t()
}
```

A block the editor offers, its marker written; `title` is `nil` for the plain one.

# `available`

```elixir
@spec available(
  [MishkaCmsCore.Runtime.ContentComponents.entry()],
  String.t() | nil,
  map() | nil
) :: [
  block()
]
```

The blocks the editor offers on `site_id` to `actor`, given the palette's `entries`: every example
of every entry that a marker can hold, as a plugin answering `runtime:content:editor_blocks`
leaves them, with its marker.

# `examples`

```elixir
@spec examples(MishkaCmsCore.Runtime.ContentComponents.entry(), %{
  required(String.t()) => MishkaCmsCore.Runtime.ContentComponents.entry()
}) :: [map()]
```

The blocks one palette entry's examples make, `listed` the palette by name: each example a marker
can hold, in the order the component lists them.

# `plain`

```elixir
@spec plain(MishkaCmsCore.Runtime.ContentComponents.entry(), %{
  required(String.t()) => MishkaCmsCore.Runtime.ContentComponents.entry()
}) :: [map()]
```

The plain block of one palette entry, `listed` the palette by name: the component as its
`furnishing` says it arrives, when it says so and a marker can hold it.

---

*Consult [api-reference.md](api-reference.md) for complete listing*