A powerful Render API to easily build complex displays

Function call

Some popular languages examples:

      <?php

declare(strict_types=1);

require 'vendor/autoload.php';

use Extism\Plugin;
use Extism\Manifest;
use Extism\PathWasmSource;
use Extism\UrlWasmSource;

$payload = \json_encode([
  '@component' => 'alert',
  "@variant" => "info",
  'heading' => 'Hello from PHP!'
]);

$url = "https://data.dilla.io/extism/bootstrap_5/bootstrap_5.wasm";
$wasm = new UrlWasmSource($url);
// Or local file
// $path = "bootstrap_5.wasm";
// $wasm = new PathWasmSource($path);

$manifest = new Manifest($wasm);
$plugin = new Plugin($manifest, true);

$output = $plugin->call("render", $payload);

$result = json_encode(json_decode($output), JSON_PRETTY_PRINT);

print $result;

Payload format

The payload is a "render tree", a collection of nested JSON objects.

There are 2 kind of JSON properties:

Reserved properties: starting with a @ character, with defined specific processing. The ones not described in this documentation will be ignored.
Free properties: not starting with a @ character. The processing will be context dependent.

Payload root has a slot value (any renderable) type.

Get JSON schema

Renderables

Component #

Reusable, repeatable and nestable building blocks of the design system. Each component meets a specific UI need. They are rendered by the template engine.

Property	Type	Description
`@component`	string	Component Required. The component ID as described in the design system. If the value is empty or not defined in the design system, the full object will be ignored and its children will not be rendered.
`@variant`	string	Variant A variant ID as described in the component definition. If the value is not defined in the components definitions, it will be ignored and the component will be processed normally.
`@attributes`	attributes	Attributes An attributes mapping with a special behaviour: always available to the component template, even if missing from payload.
`@styles`	styles	Styles property
`@theme`	theme	Theme property
`@local_variables`	local	Local variables property
`@library`	library	Library property
`@attached`	attached	Attached property
`@variables`	variables	Variables property
`@trans`	trans	Translations property
^(?!@).*$	slot prop	Slots and props They will be injected into the rendering engine as template context.

            
              {
    "@component": "card",
    "@variant": "horizontal",
    "header": "Card title",
    "content": [
        {
            "@element": "p",
            "@content": "Welcome!"
        },
        {
            "@component": "button",
            "label": "Discover",
            "url": "/foo/bar"
        },
        {
            "@component": "button",
            "@variant": "warning",
            "label": "Unsubscribe",
            "url": "/bar/foo"
        }
    ]
}

Element #

The basic building blocks, which does not use the template engine, making it light and faster to render than a component. They are low level and not part of the design system.

Property	Type	Description
`@element`	string	Element name Required. Any value will be processed, even if not existing in the target markup language. If the value is empty, the full object will be ignored and its children will not be rendered.
`@content`	slot	Content Any renderable.
`@styles`	styles	Styles property
`@theme`	theme	Theme property
`@local_variables`	local	Local variables property
`@library`	library	Library property
`@attached`	attached	Attached property
`@variables`	variables	Variables property
`@trans`	trans	Translations property
^(?!@).*$	attribute	Attributes Markup (HTML/SVG/XML...) attributes

            
              {
    "@element": "h1",
    "id": "intro",
    "class": [
        "warm",
        "quote"
    ],
    "@content": [
        "My tailor is ",
        {
            "@element": "a",
            "href": "http://example.org",
            "@content": "rich"
        }
    ]
}

Attachable element #

More strict than a regular element: any reserved property outside of @element and @content will be ignored. Used in the @attached property.

Property	Type	Description
`@element`	string	Element name Required. Any value will be processed, even if not existing in the target markup language. If the value is empty, the full object will be ignored and its children will not be rendered.
`@content`	string	Content Only strings to prevent nested attachment.
^(?!@).*$	attribute	Attributes Markup (HTML/SVG/XML...) attributes

            
              {
    "@element": "link",
    "rel": "next",
    "href": "http://example.org/123"
}

            
              {
    "@element": "meta",
    "name": "keywords",
    "content": "foo, bar"
}

Template #

A jinja-like template. Can host bubbable properties, but no scoped properties.

Property	Type	Description
`@template`	string	Inline template Required. A jinja-like template.
`@library`	library	Library property
`@attached`	attached	Attached property
`@variables`	variables	Variables property
`@trans`	trans	Translations property
^(?!@).*$	slot prop	Template context Variables which will be injected into the rendering engine as template context.

            
              {
    "@template": "<span class=\"foo\">{{ bar }}</span>",
    "bar": "Hello"
}

Empty renderable #

Can only host bubbable properties.

Property	Type	Description
`@library`	library	Library property
`@attached`	attached	Attached property
`@variables`	variables	Variables property
`@trans`	trans	Translations property

Scoped properties

Some universal properties can alter the renderable HTML class attribute.

Local variables #

Scoped. The CSS variables to dynamically override, as defined in the design system. Added as a style attribute on the renderable root tag. Keys not defined in the design system will be ignored. Double dash prefix (--) can be ignored in the request.

            
              {
    "@local_variables": {
        "secondary": "@feeae6cc"
    }
}

Styles #

Scoped. A list of values which can be used additively to style an element from scratch or to override a the look of a component. Each value is a style option, a simple HTML classes typically scoped to a single CSS property. Mutually exclusive options are defined as "styles" in the design system.

            
              {
    "@styles": [
        "mt-1",
        "text-truncate"
    ]
}

Theme #

Scoped. A theme is also expected to alter the display of the nested content, until a new @theme is found. Careful, some design systems are applying the theme to the global display anyway.

            
              {
    "@theme": "dark"
}

Bubbable properties

Some universal properties are not altering the local rendering but are bubbling to the top of the render tree.

Attached #

Bubbable. An array of attachable @element.

            
              {
    "@attached": [
        {
            "@element": "link",
            "href": "?page=2",
            "rel": "next"
        },
        {
            "@element": "title",
            "@content": "My title"
        }
    ]
}

Asset library #

Bubbable. A library of CSS and JS assets, following the design systems library definition. Generates link and/or style element in the HTML head, and script element at the bottom of the HTML body. More powerful than using directly @attached because of advanced processing like dependencies management.

Property	Type	Description
`css`	object	Keys are URL. Values are HTML attributes which will be added to the attached element.
`js`	object	Key are URL. Values are HTML attributes which will be added to the attached element.
`dependencies`	array	A list of libraries ID which will be attached before the current library.

            
              {
    "@library": {
        "css": {
            "slider.min.css": {
                "minified": "true",
                "media": "screen"
            }
        },
        "js": {
            "slider.js": {
                "defer": "true"
            }
        }
    }
}

Variables #

Bubbable. A list of attachable elements. The CSS variables to dynamically override, as defined in the design system. Generate a <style> tag with all the collected CSS custom properties and their overridden values for the header.

Property	Type	Description
\S+	local	Scopes Every scope is an object with variables as keys. Keys not defined in the design system will be ignored. Values equal to default will be ignored.

            
              {
    "@variables": {
        ":root": {
            "primary": "red",
            "secondary": "#feeae6cc"
        },
        ".sidebar": {
            "secondary": "yellow"
        }
    }
}

Translations #

Bubbable. A mapping of translation for template's translatable text.

Property	Type	Description
.+	string	Every key is a translatable value, according to the template. Every value is the current translation.

            
              {
    "@trans": {
        "My tailor is rich": "Mon tailleur est riche",
        "Is this your handbag?": "Est-ce votre sac \u00e0 main ?"
    }
}

Value types

The properties not starting with a @ character can have any JSON value (string, number, integer, boolean, array, object) or some types specific to the Dilla Render API.

Slot value (any renderable) #

The payload root, the component slots, some templates variables, and the @content property can host any renderable value.

Possible value	Note
string	A string is the simplest renderable
array	A list of renderables is also a renderable. Each rendered item is concatenated with a whitespace as separator.
empty	Empty renderable
element	Element renderable
template	Template renderable
component	Component renderable

            
              [
    "Hello",
    {
        "@element": "strong",
        "@content": "beautiful"
    },
    "world"
]

Prop value #

Non renderable, strictly typed, values.

Possible value	Note
string	Any scalar is a legitimate prop value.
boolean	Any scalar is a legitimate prop value.
number	Any scalar is a legitimate prop value.
attributes	Pairs of attribute key and attribute value.
array	List Props can be a nestable list of value if there are no renderable inside.
object	Mapping Props can be a nestable key/value mapping if there are no renderable inside. Useful for menu structures.

Attribute value #

A single attribute value. They are rendered as key="value".

Possible value	Note
string	The plain, usually expected, type for an attribute value.
number	Needed by some templates expressions which are manipulating numerical values. Casted into a string before rendering.
array	Array of strings and numbers. Concatenated before rendering, with single space character as separator

Attributes value #

Pairs of attribute key and attribute value.

Property	Type	Description
\S+	attribute	A single attribute value.

Return value

A mapping with:

Property	Type	Description
`attached`	string (markup)	The head elements from @attached, already rendered
`stylesheet`	string (markup)	The stylesheet specific to the payload, already rendered.
`system_stylesheet`	string (markup)	The default stylesheet, already rendered
`system_javascript`	object	The javascript specific to the payload, not rendered yet
`javascript`	object	The default javascript, not rendered yet
`body`	string (markup)	The main HTML output