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.

Renderables

Component #

Reusable, repeatable and nestable building blocks of the design system. Each component meets a specific UI need. Thet 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 avaialble 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 deisgn 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, folloiwng 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 dependecies mangament.

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 attchced 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 overriden 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 rendrered
system_javascript object The javascript specific to the payload, not rendered yet
javascript object The default javascript, not rendrered yet
body string (markup) The main HTML output