Operator - js-lib-com/wood GitHub Wiki
WOOD uses just six operators to link components in structures of arbitrary complexity. These operators are declared on component layout file; even if we talk about components relation, strictly speaking it is about layout files relation.
Operators are declared using well known HTML attributes syntax; there is no programing language mixed in.
| Name | Syntax | Description |
|---|---|---|
| Child Reference | wood:compo="component/path" | Child component path for an aggregation |
| Editable Declaration | wood:editable="editable-name" | Declare an editable element in a template |
| Template Reference | wood:template="template/path" | Template binding from content component |
| Editable Content | wood:content="editable-name" | Provide content for template editable element |
| Template Fragment | wood:template="template/path#editable-name" | Reference for single editable template |
| Layout Parameters | wood:param="name:value;*" | Parameters for related components |
In an aggregation relation, child reference operator is used by parent component to declare the child component path. It uses wood:compo="component/path" syntax; this operator has a single argument, the child component path.
Child reference operator is used into parent component, that is, the component that includes the child component. Declared component path should point to an existing component, otherwise build process will fail.
<!-- parent component -->
<body xmlns:wood="js-lib.com/wood">
...
<!-- child reference element -->
<div wood:compo="compo/dialog"></div>
...
</body>A component can aggregate more that one single child component that, on its turn can aggregate its own components, creating a tree of not restricted complexity.
This operator is the base for OOP inheritance via templates. A template is a component that has at least one editable element, declared by wood:editable="editable-name" operator. Editable declaration has a single argument: the editable element name; editable name should be unique on template scope.
<!-- template component -->
<body xmlns:wood="js-lib.com/wood">
...
<!-- editable element -->
<section wood:editable="section"></section>
...
</body>There is no formal limitation on templates inheritance hierarchy. A template can inherit from another template creating an arbitrary long templates chain; but multiple inheritance is not supported.
In order for content components to provide implementation for template editables, it needs to know the template path. For that uses wood:template="template/path" operator that has a single argument, namely the template path. Template path should point to an existing template otherwise build process will fail.
<!-- content component -->
<embed wood:template="template/page" xmlns:wood="js-lib.com/wood">
...
</embed>Template reference is always declared on content component root element. This is in contrast with inline template that is always declared on a descendant element.
Multiple inheritance is not supported: a content component can have a reference to a single template.
This operator is a variant for template reference that declares an aggregation with inheritance. See Inline Template for more details.
Syntax is identical with template reference, wood:template="template/path". Build tool knows it is an inline template because is declared on a descendant element but not on the root.
<!-- parent component -->
<body xmlns:wood="js-lib.com/wood">
...
<!-- inline template -->
<section wood:template="template/page">
<!-- inline content -->
</section>
...
</body>Inline content declared into parent component is injected into template and resulting layout replace source inline template in place.
Editable content operator is used by content components to define content for template editables. It has syntax wood:content="editable-name", where editable name should match a template editable element name.
This operator is always used in conjunction with template reference operator, that should be declared on root element. For templates with single editable there is an operator that combines template reference and editable content - see template fragment.
<!-- content component -->
<embed wood:template="template/page" xmlns:wood="js-lib.com/wood">
<!-- content element -->
<section wood:content="section">
...
</section>
</embed>Content component should provided content elements for all template editables. It is legal to have editables not provided but in this case content component becomes a template on it turn.
For templates with a single editable element is possible to merge template reference and editable content operators.
Resulting operator has syntax wood:template="template/path#editable-name", inspired by URL fragment syntax - hence the operator name. Please note the hash (#) character that separates template path and editable name.
<!-- content component -->
<section wood:template="template/page#section" xmlns:wood="js-lib.com/wood">
...
</section>This syntax can replace both template reference and inline template. For details see Template Fragment.
In both aggregation and inheritance relations is possible for parent to define layout parameters using wood:param="name:value;*" operator. This operator accepts as argument a list of parameters separated by semicolon (;). A parameter is a name, value tuplu separated by colon (:). Semicolon at the list end is optional.
Here is an example for an aggregation. On templates inheritance is similar.
<!-- parent component -->
<body xmlns:wood="js-lib.com/wood">
...
<!-- child component reference with parameter -->
<div wood:compo="compo/dialog" wood:param="title:Dialog Title"></section>
...
</body>On compo/dialog child component, parameter reference @param/title is text replaced with value provided by parent component - Dialog Title. Parameter name should also match, in our example title.
<!-- child component -->
<div>
<!-- parameter reference -->
<h3>@param/title</h3>
...
</div>Parameter reference is allowed anywhere XML syntax allows a string.
Last updated 9/6/2022.