Components inside content: a marker an author writes into stored HTML — a post's body — drawn as the runtime component it names. WordPress calls these shortcodes; Joomla, content plugins.

[[component chelekom-alert title="Heads up"]]Text, <b>with</b> HTML[[/component]]
[[component chelekom-badge size="small" /]]

A template draws such content with rich_content/1, imported into every runtime template — see MishkaCmsCore.Runtime.LiveViewHelpers.rich_content/1:

<.rich_content
  id={"#{@id}-body"}
  html={@body}
  site={site_name()}
  current_user={@current_user}
/>

The marker

• [[component NAME ATTRS]]INNER[[/component]] — INNER is HTML, and becomes the component's inner_block slot when the component declares one.
• [[component NAME ATTRS /]] — no inner content.
• NAME is letters, digits, - and _. It names a component of the site being drawn, or a global one when the site has none of that name.
• Each of ATTRS is key="value", key='value', key=value or a bare key, which is true. A quote may arrive as an entity — ", ", ', ', ' — and a value is entity-decoded. A value cannot hold both kinds of quote: the sanitizer content is stored through decodes every quote entity back into the quote itself.
• Whitespace is spaces, tabs, line breaks and the non-breaking space, written or as an entity.

A marker is found only in text: never inside a tag, and never inside <pre> or <code>, so a page can show the syntax. A marker that does not parse, an opening marker nothing closes and a closing marker nothing opened are left in the text as they are.

Inside a component

INNER may hold markers of its own, drawn inside the component — a timeline holding its sections, a card holding its title:

[[component chelekom-timeline]]
  [[component chelekom-timeline-section title="Started" /]]
  [[component chelekom-timeline-section title="Shipped" /]]
[[/component]]

and, for a component that declares named slots, a slot marker for each entry it takes:

[[component chelekom-video]][[slot source src="/intro.mp4" type="video/mp4" /]][[/component]]
[[slot item title="Question"]]The answer, as <b>HTML</b>[[/slot]]

A slot marker is read with the same rules as a component's, belongs to the component it sits directly inside, and is passed as that slot when the component declares it — its attributes cast against the slot's own. A slot marker anywhere else is text. Markers are drawn eight levels deep; the content of a deeper one is drawn as it is written.

What a component hands its content — render_slot(@inner_block, value), or a slot entry's render_slot(entry, value) — reaches each marker inside that content, at any depth, as runtime:render:before_content_component's slot_arg meta. A marker outside the component never sees it, and a component inside that hands nothing (render_slot(@inner_block)) passes on the one it was given.

A paragraph holding one marker and nothing else — whitespace and non-breaking spaces aside — is drawn as the component alone, without the <p> an editor wraps a line in: a block inside a <p> is HTML a browser takes apart. A marker sharing its paragraph with other text keeps it.

What is drawn

Only a component the request's site may render: active, and the site's own or a global one — the rule MishkaCmsCore.Runtime.LiveViewHelpers.component/1 holds every template to. The name is first checked, as a string, against the active components SiteState knows the site and the global scope have: a name an author typed that names none of them makes no module name, no atom and no remembered failure. A name that resolves to nothing, an inactive component, another site's, one that draws content itself (it could draw the content that holds it, forever), one missing an attribute it requires, and one whose list or map value cannot be read (see Lists and maps) are drawn as nothing. The same render in a preview (MishkaCmsCore.Runtime.StaticHelpers) draws a notice saying why in their place. On a page, one that passes every check and then raises while it draws is drawn as a small box, and the content around it draws — see MishkaCmsCore.Runtime.ComponentBoundary.

A component is handed what <.component> in a template would hand it: the attributes the marker writes, and for one it leaves out the default the component declares, or nothing at all when it declares none, as Phoenix leaves it. A clause matching %{navigate: _} is taken only when the marker writes navigate, and a template reads an attribute with no default as assigns[:label], never @label.

Only the attributes the component declares are read from the marker, each cast to its declared type: string and any as written, boolean from true/false or a bare key, integer and float from a number, list and map from JSON (see Lists and maps), and anything that declares values only as one of them — which is the only way an atom is taken. id, site, component_name, current_user, rest and any phx- name are never an author's. A stateful component, and one declaring id, gets the id "<id>-<n>", n counting the content's markers from 0 — "<id>-<n>-<m>" for the mth inside it — so it stays the same component across renders.

A component declaring a global attribute (attr :rest, :global, include: ~w(disabled circle)) takes, through it, the HTML attributes that attribute names and a few every element has: each name in its include list, aria-*, data-*, and accesskey, autocapitalize, autocorrect, autofocus, dir, draggable, enterkeyhint, hidden, inert, inputmode, lang, role, spellcheck, tabindex, title and translate. A bare key or "true" is true, "false" leaves it out, and anything else is the text written. Never an event handler (on…), style, a phx- or data-phx- name, data-method, data-to, data-csrf, method, csrf_token or a name the component declares, and a link or source (href, src, action, formaction, poster, cite, ping) only when it is a path or an http, https, mailto or tel address:

[[component my-video controls muted]][[slot source src="/intro.mp4" /]][[/component]]
[[component my-button circle disabled aria-label="Scan"]][[/component]]

A slot the component declares and the content does not fill is passed empty, and one it requires draws the component as nothing — as a required attribute does. A slot's attribute the marker leaves out is passed as its declared default, and an entry with nothing inside it draws nothing where the component renders its content.

The HTML around the markers is drawn as it is given: pass only HTML that was sanitized.

Lists and maps

An attribute declared list takes a JSON array, and one declared map a JSON object, written in single quotes around JSON's own double ones:

[[component chelekom-headless-tree nodes='[{"value":"src","label":"src","children":[{"value":"app","label":"app.ex"}]}]' /]]
[[component chelekom-headless-sparkline values='[3,5,2,8,6]' /]]
[[component chelekom-headless-segmented-control options='["Day","Week","Month"]' value="Week" /]]
[[component chelekom-headless-countdown seconds="93784" show_labels labels='{"days":"d","hours":"h"}' /]]

An any attribute that declares no values takes an array or an object the same way, and every other value as it is written: option='{"series":[]}' is a map, option="{draft" the text.

The value reaches the component as data: strings, numbers, true, false and null as Elixir's own, an array as a list, an object as a map. Nothing in it is run, and no string in it becomes a module or an atom. An object's keys are atoms when it is a record — an object inside an array, such as a tree's node read as node.label, and the object of an attribute whose declared default is a map with atom keys. Any other object keeps its keys as written: a lookup such as a countdown's labels, read by the strings its units hold. A key becomes an atom only when the VM already has that atom — as it has every key the component's code reads — and a key starting with __ is always a string.

A value is at most 32 KB as written, and 8 levels deep, each array and object a level: a tree's node is two. A ' inside the JSON is written \u0027, and &, < and >, as in any value, as entities. A list or map value that is not JSON of its kind, that is larger or deeper, or that is a bare key draws the component as nothing, and a preview says which attribute and why. An any value is then handed as it is written.

Cost

Content holding no [[component is drawn as it is, and nothing is parsed. A marker asks only what the runtime keeps in memory: SiteState for the site and its component names, then the loaded code table for the compiled module. The first render of a component nothing has built yet builds it, once, as component/1 does.

Styles

A site's stylesheet is built from the templates it reaches (MishkaCmsCore.Runtime.Compilers.CssClosure), and the components content names are in no template. Whoever stores content answers runtime:compile:content_components with the names its content uses — see MishkaCmsCore.Runtime.Compilers.TailwindCompiler.content_components/1 — and a template that draws content reaches exactly those. names/1 reads them out of content, to store beside it when it is written.

The icons content names are in no template either: a marker's icon="hero-inbox" reaches the component as an expression, and a <span class="hero-inbox"> in the HTML is never scanned. The same event answers them as icons — see MishkaCmsCore.Runtime.Compilers.TailwindCompiler.content_icons/1 — and icons/1 reads them out of content.

Nor are the classes content writes: a <div class="bg-[#282828]"> in the HTML, a marker's class, its *_class attributes, and the attributes its component takes a class string in. The same event answers them as classes — see MishkaCmsCore.Runtime.Compilers.TailwindCompiler.content_classes/1 — and site_classes/2 reads them out of content.

The editor

The admin's content editor holds content as segments/1 splits it: the HTML it edits, and each component standing alone as a block it shows drawn. The block writes its marker back as a paragraph of its own, so content saved from the editor stores what it was opened with. Its palette is palette/2.

Events

• runtime:render:before_content_component — before each embedded component is drawn, with %{component_name: name, site: site, attrs: attrs, inner: inner_html | nil} and %{site_id: site_id, index: n, marker_attrs: written, slot_arg: arg, slot_args: args} as meta. attrs is atom-keyed and already cast; marker_attrs are the attributes as the marker writes them, string-keyed and uncast. slot_arg is the value the nearest component around the marker hands its content (nil when none does), and slot_args every such value, nearest first. A plugin answers the map with other attrs or inner to change what is drawn — an attribute taken out of attrs is not handed at all, for a component's own clause to fill, as a form field's name from its field — or suppress: true to draw nothing.
• runtime:component:crashed — a marker's component raised while it was drawn, and a box was drawn in its place; see MishkaCmsCore.Runtime.ComponentBoundary.
• runtime:content:editor_palette — before the content editor's palette is shown, with %{site_id: site_id, components: entries} (embeddable/2's entries) and %{current_user: user} as meta. A plugin answers the map with other components to narrow or extend what an author may place; the editor places only what the palette lists.