At Meta Reference - js-lib-com/wood GitHub Wiki

Component source files may contain at-meta references, for example a variable reference defined into a variables definition file. All at-meta references starts with at character (@), hence the name.

There are three families of at-meta references: variables, resource files and layout parameters references. But all have the same at-meta syntax: at-meta references have a type and a name separated by slash - @type/name.

<body>
	<!-- variable reference -->
	<h1>@string/title</h1>
	<!-- resource reference -->
	<img src="@image/logo" />
</body>

at-meta Syntax

Here is the formal at-meta reference syntax, for short at-meta syntax:

reference = AT type SEP ?(path SEP) name
path      = 1*CH           ; optional path, for ?(re)source files only
name      = 1*CH           ; reference name, unique in scope; for ?(re)sources it is the file base name
; type is defined in references description table

; terminal symbols definition
AT  = "@"                 ; at-meta reference mark
SEP = "/"                 ; reference name and optional path separator
CH  = ALPHA / DIGIT / "-" ; character is US-ASCII alphanumeric and dash

; ALPHA and DIGIT are described by RFC5234, Appendix B.1

Here are supported at-meta reference types:

Type Family Description
audio resource file The same as image but with audio content.
file resource file Generic file, for example license text file.
font resource file Font family file loaded from server and declared by @font-face style rule.
image resource file Image file stored on server and linked via URLs from source files.
layout layout file HTML layout file for generated site page.
link variable Links references to local or third part resources, mainly for href attribute.
param layout parameter Layout parameter declared by child component and with value defined by parent.
project project property Property defined by value element from project descriptor.
string variable Plain string values mainly for multi-languages support.
style style file Site CSS style file usable, for example, by dynamic style loading.
text variable Same as string but allows for HTML format.
tip variable Tool-tip value, usually for elements supporting title attribute.
video resource file The same as image but with video content.

All at-meta references start with at character (@). If at character is to be present into source file content ad litteram need to repeating it, i.e. @@.

Anyway, build tool does silently ignore not recognized at-meta like expressions (starting with at character but of unknown type or not strictly obeying at-meta syntax) so that escaping is necessary only if text matches the syntax described here.

Samples

Here are sample usage cases. Note that at-meta references are text replaced and where source file syntax requires quotes (") they should be explicitly used.

<!-- layout file -->
<section>
	<!-- string variable reference -->
	<h1>@string/title</h1>
	<!-- image reference and layout parameter reference -->
	<img src="@image/logo" title="@param/title" />
	<!-- HTML text reference -->
	<p>@text/message</p>
</section>
/* layout style file */
body {
	/* image reference */
	background-image: url("@image/page-bg");
}
// layout script file

// HTML text reference
this.section.innerHTML = "@text/message";
// audio stream reference
this.audio.src = "@audio/beep";
// link element for dynamic style loading
document.createElement("link").setAttribute("href", "@style/section");
<!-- string variables definition file -->
<string>
	<!-- variable definition -->
	<app-name>Application</app-name>
	<!-- definition can include variable reference -->
	<app-description>@string/app-name description.</app-description>
</string>

Processing

There is a source file reader with at-meta references processing; this class is a decorator for a characters stream reader. Beside standard reading it looks on the fly for at-meta references and text replace them with resolved values.

Variables

A variable reference identify a variable defined into a variables definition file. In this case at-meta reference name uniquely identify the variable into its scope.

Variable reference can be used in any component source file, including in variables definition files. Is legal for variable values to also contain references; this creates a tree of references that is traversed recursively in depth-first order.

There are a number of methods invoked in a chain that creates this recursive variables reference scanning:

  1. source reader discovers a variable reference and delegates reference handler,
  2. reference handler retrieves value from variables definition file,
  3. invokes references resolver with found value and return resolved value,
  4. references resolver discovers a variable reference and delegates reference handler, back to 2,
  5. repeat 2..4 till entire values tree is resolved.

Note that references resolver invocation, at point 3, implements recursive loop level guard.

See Variables for more details and usage.

Resource Files

Regarding resource files, at-meta reference is a sort of abstract addressing. It does not identify precisely the file; extension and variants are not included into resource reference. Also resource file can be stored private into component directory or global into project assets. Anyway, resource file references support sub-directories, for example @image/icon/logo.

Resource file references can be used in any component source file less variables definition files, that can contain references only to variables.

Processing resource file references is not recursive, as for variable references. It is performed by the same source file reader but is a simple text replace of the resource reference with resource URL, generated by build tool based on target site layout. For that, build tool first need to locate resource file.

First attempt to find resource file into component directory then on project assets directory. Resource reference contains only file base name; no variants and no extension. Build tool uses this base name to locate resource file in mentioned directories; this implies is not possible to have resource files with the same base name but with different extensions.

Layout Parameters

Component layouts can contain layout parameters defined by @param/name parameter reference syntax. For example a child section title provided by parent component.

<!-- child component -->
<section>
	<!-- parameter reference -->
	<h1>@param/title</h1>
</section>

When a component source reader discovers a parameter reference, retrieves named parameter value from layout parameters map and text replace parameter reference with its value. Layout parameters map is initialized beforehand and injected at source file reader instantiation.

Layout parameters map is initialized from wood:param="name:value;*" operator at component creation.

<!-- parent component -->
<body xmlns:wood="js-lib.com/wood">
	<!-- operator for layout parameters declaration -->
	<div wood:compo="compo/section" wood:param="title:Section Title"></div>
</body>

Parent component should define values for all parameter references, using wood:param="name:value;*" operator. Is parent component responsibility to match parameter names and number. Order is not relevant.

See Layout Parameters for details.

Layout File

When there is the need to refer a site page URL, developer can use page layout file reference - @layout/compo-path. In this case reference type is layout and reference name is the page component path.

<section>
	<!-- page layout file reference -->
	<a href="@layout/page/index">...</a>
</section>

WOOD tools resolve layout reference and replace it with URL, relative to current context. This URL depended on generated site file system.

<SECTION>
	<!-- index page URL relative to current context -->
	<A href="index.htm">...</A>
</SECTION>

Layout file reference is especially useful for site pages navigation.

<nav>
	<A href="@layout/page/index">Index</A>
	<A href="@layout/page/about">About</A>
</nav>

Style File

Style file reference is similar to layout reference. It is experimental and currently used for shadow styles.

Project Properties

It is possible to use at-meta to refer values defined by project descriptor. In sample, authors are loaded project descriptor.

<body>
	<!-- project property reference -->
	<footer>@project/authors</footer>
</body>

The name of the project property reference - authors in our example - should textually match an element from project descriptor. WOOD tools fails if reference name is not recognized by project descriptor.

Uses project descriptor default value if property name is correct but its value is not defined.

Custom project descriptor properties are allowed. These are properties not recognized by project descriptor but used only for project property references. For custom properties there is no default value.

<body>
	<!-- custom project property reference -->
	<footer>@project/display</footer>
</body>

In sample, display is not a property recognized by current project descriptor implementation; anyway, since it is defined by project descriptor it can be used by project property reference.

<project>
	<!-- custom property definition -->
	<display>Custom Project</display>
</project>

Last updated 9/8/2022.

⚠️ **GitHub.com Fallback** ⚠️