SIMAI Framework ui.* components

The ui.* Smart components are ready-made interface elements from SIMAI Framework: a button, an alert, an input field and others. In Markdown you call them with a :::ui.name block with parameters in JSON. Docara checks the parameters against the component description already at build time, and in the browser the component works the same way as in other products on SIMAI Framework.

How they differ from regular Docara components:

• a regular component, for example the alert :::alert, is written as Markdown text and suits most pages;
• a Smart component takes parameters exactly as the Framework describes them and is needed when the page must have a real Framework element: a button with a loading state, an alert with a heading and supporting text and so on.

How a site allows components

A site can call only the Smart components listed in the simai-framework.lock.json file next to docara.json, in the manifests section. For each component it pins the provider, the exact version and the checksum of its description, and also the restrictions for a static site:

{
  "manifests": {
    "ui.button": {
      "provider_revision": "4b055d09926fec4c32f2ae43b2e7e0a6f64d7663",
      "sha256": "235e049d…"
    },
    "ui.alert": {
      "provider_revision": "4b055d09926fec4c32f2ae43b2e7e0a6f64d7663",
      "sha256": "056329bb…",
      "consumer_policy": {
        "blocked": [
          {"prop": "closable", "value": true, "code": "FRAMEWORK_PROP_UNSUPPORTED_IN_BOUNDED_RUNTIME"},
          {"prop": "type", "value": "success", "code": "FRAMEWORK_PROP_UNSUPPORTED_IN_BOUNDED_RUNTIME"}
        ]
      }
    }
  }
}

docara init creates the file; a Docara update does not change it. The build checks the checksums against the component descriptions that ship with Docara: if a component is not in the lock or the description does not match, the build stops. This site’s lock allows ui.button and ui.alert — the same ones a new project gets. The lock fields are described in detail in the Framework lock reference.

The ui.button button

:::ui.button
{"preset":"primary","text":"Continue","aria-label":"Continue the setup"}
:::

Result:

preset picks a ready-made style: primary, secondary, tonal_on_surface, outline, outline_on_surface, link, link_on_surface or on_surface. The other parameters:

ui.button is an action button in an interface, not a link. To make a button lead to another page, use a button link :button[...] or the cta block.

The ui.alert alert

:::ui.alert
{"type":"info","variant":"default","title":"The build checks parameters","supporting-text":"An unknown parameter or value stops the build before publishing.","closable":false,"aria-label":"The build checks parameters"}
:::

Result:

This site’s lock forbids type=success and closable=true: a static site has nothing to support them with. Such a call stops the build with FRAMEWORK_PROP_UNSUPPORTED_IN_BOUNDED_RUNTIME. Docara sets the id identifier itself.

Other components

• ui.input, ui.checkbox, ui.dropdown and ui.list-item (only the text variant inside ui.dropdown) also ship with Docara. The site’s own components use them, for example the install command builder — see the extension examples. Directly in Markdown they can be called only on a site whose lock allows them.
• ui.badge, ui.tabs and ui.dataview are not accepted yet. Use the Docara badge, tabs and table instead.

The php vendor/bin/docara atlas --json command shows which components are available to your site, and php vendor/bin/docara inspect smart ui.button --json the details of one component. How Smart components work inside and how to write your own is described in the Docara Smart components section.

Errors

An incorrect call stops the build. The most common ones:

The causes and fixes for all codes are in the page error reference.