remixml v7.0.5

Remixml is a sophisticated XML/XHTML macro language/templating compiler engine in Javascript.

The Remixml templating engine has the following features:

• It don't need no stinkin' artificial magic delimiters.
• Rich powerful language with dynamic inheritance, autoescaping, functions, whitespace-collapsing, asynchronous control and more.
• Fast & lean: Small 7 KB gzipped runtime which includes the compiler which can precompile templates in node and in the browser.
• Compiles to minified Javascript.
• User defined HTML tags in Remixml support named parameters and recursion.
• Extensible with custom filters and tags programmed in Javascript.
• Easy multi-level caching for even more speed.
• Available everywhere in node and all modern web browsers.
• It contains a fully featured fast validating XHTML parser.
• It shields the Remixml programmer from fatal browser errors by trapping and logging all errors from within (even from direct javascript embedded in Remixml), but forgivingly continues parsing to deliver content regardless.
• Comes with numerous loadable library modules to tailor functionality to the specific environment leaving the core small.
• Turing complete.
• Preserves all whitespace by default.

The language and primitives used, blend in completely with standard XML/XHTML syntax and therefore integrate smoothly with existing XML/XHTML syntax colouring editors.

Compiling and processing XML, XHTML and Remixml automatically performs sanity checks and shows clear and precise warnings about missing opening or closing tags.

The package includes a comprehensive regression-testsuite to assure code quality.

Requirements

It runs inside any webbrowser or NodeJS environment supporting at least ECMAScript ES2018.

Minified and gzip-compressed, it is less than 7 KB of code.

It has zero dependencies on other modules.

It supports (but does not require) output to the incremental-dom.

Basic usage

In essence Remixml is a macro language that has XHTML/XML-like syntax and uses special entities to fill in templates. The entities that are recognised by Remixml are always of the form: &scope.varname; I.e. they distinguish themselves from regular HTML entities by always having at least one dot in the entity name.

The following sample Javascript code will illustrate the point:

Remixml.parse2txt(`
  <h1>Title of &_.sitename; for &_.description;</h1>
  <p at="&anything.whatever;">
   Some global variables &var.some; or &var.globalvars; or
   &var.arrays.1; or &var.arrays.2; or &var.objects.foo; or
   &anything.really;
  </p>
 `,
 {_: {
    sitename: "foo.bar",
    description: "faster than lightning templates"
  },
  var: {
    some: "other",
    globalvars: 7,
    arrays: ["abc", 14, "def"],
    objects: {"foo":"bar", "indeed":"yes"}
  },
  anything: {
    really: "other",
    whatever: 7
  }
 });

Native Remixml examples

Simple assigment:

<set var="_.variablename">the new value</set>

Simple calculations:

<set var="_.variablename" expr="_.variablename + 1" />

Conditionals:

<if expr="_.variablename > 1">
 yes
</if>
<elif expr="_.variablename == 'foobar'">
 second condition valid
</elif>
<else>
 otherwise
</else>

Counted loop:

<for from="1" to="42">
 This is line &_._recno;<br />
</for>

Iterating through an object or array:

<set var="_.foo" split=",">aa,b,cc,d,eee,f</set>
<for in="_.foo">
 This is record &_._recno; value: &_._value;<br />
</for>

Defining your own HTML to make it more readable, maintainable and DRY:

<comment> First define some macros </comment>

<set tag="literallink">
 <a href="&_.href;">&_.href;</a>
</set>

<set tag="decorate">
 You can click towards <literallink href="&_.link;"/>. <br/>
</set>

<comment> Now use them </comment>

<decorate link="https://some.where/foo/bar" />
<decorate link="https://some.where/bar/foo" />

Even recursive functions are possible:

<set tag="faculty">
 <if expr="_.val <= 1"> 1 </if>
 <else>
  <set var="_.oneless" expr="_.val - 1" />
  <insert expr=""> _.val * <faculty val="&_.oneless;" /> </insert>
 </else>
</set>

<set tag="facultyverbose">
 <h1>Faculty calculation of &_.valinput;</h1>
 <p>
  &_.valinput;! = <faculty val="&_.valinput;" />
 </p>
</set>

<comment> Now call our custom HTML tag </comment>

<facultyverbose valinput="7" />

Reference documentation

Full entity syntax

& scope . variablename : encoding % formatting ;

• scope References the primary level in the context object.
• variablename References second and deeper levels in the context object (can contain multiple dots to designate deeper levels, is used to access both objects and arrays). Variables from the parent scope can always be referenced: e.g. &_.foo; is a variable named foo in the current scope, whereas &_._.foo; refers to a variable named foo in the parent scope. By prepending _. to the path every time, you go one level deeper.
• encoding (optional) Specifies the encoding to be used when substituting the variable. The standard encodings available are (you can add custom encodings using add_filter()):
  • html Default: encodes using HTML entities. This is AKA auto-escaping, which prevents XSS (Cross-Site-Scripting).
  • uric URI component: encodes URI arguments in an URL.
  • json Encodes as a JSON string.
  • none No encoding, as is, can be abbreviated as ":;".
  • recurse or r Like none but immediately searches for new entities to substitute inside the replaced content.
• formatting (optional) Note: in order to use this, the remixml-fmt module must have been loaded. printf()-like formatting specification . Supported formats: %c, %d, %e, %f, %g, %s, %x. If the formatting string equals a three-letter currency (all capitals), the value will be formatted like a currency (including currency symbol) in the current locale. There is a special format %t: any string following it will be parsed as a strftime()-like formatting specification . Most formats are supported. Unsupported formats will stay in the string unchanged.

Note: all entity references evaluate safely. If the entity contains undefined parts, the resulting substitution string will always be empty.

Note: the entity reference must not contain spaces (the spaces shown above are there to clarify the format, they should not be used in a real entity reference). The scope and variablename parts can be described using the following regular expression: [_$a-zA-Z0-9]+.

Language tags

All tags strip fully enclosed whitespace patches between tags on the first level if a single - parameter is given.

<div ->
 <p>
  This will strip all fully enclose whitespace
  (between the div and p tags).
 </p>
</div>

• <set var="" variable="" expr="" regexp="" split="" join="" mkmapping="" selector="" json="" clone="" tag="" args="" scope="">...</set> Attributes:
  • var or variable Assign to the named variable.
  • expr Use the javascript expression specified in this attribute. Or, alternately, if the attribute is empty, javascript from the content of this tag is used. Evaluates the javascript and stores the result.
  • regexp A regular expression to match the content to.
  • split Split the content on this value; if used together with regexp, it will split the content using a regular expression.
  • join Join an array using the specified separator.
  • mkmapping Assign this comma-separated list of names to the columns of the array.
  • selector Extract the selected content into an array of Nodes.
  • clone Clone the first level an array of object into the target while copying.
  • json Parse the content as JSON.
  • tag Declare a custom tag. &_._contents; can be used to reference the contents of the tag. All argument values are accessible as variables from the local scope (_). E.g. an attribute foo="bar" can be referenced as &_.foo; inside the tag definition.
  • args Specifies which arguments this tag expects. All other arguments are accessible through &_._restargs;. Using something like <img ::="&_._restargs;" /> allows you to pass on all the remaining arguments. The special argument :: accepts an object and spreads out the elements as individual attributes. Note that all locally defined variables in the current _. scope not mentioned in the args argument will be included in &_._restargs;.
  • scope Create a toplevel alias for the local scope in this tag definition.
• <unset var="" variable="" tag=""></unset> Attributes:
  • var or variable Delete the named variable.
  • tag Delete the named tag from the current scope, restores the definition of this tag from the parent scope (if any).
• <if expr="">...</if> Attributes:
  • expr If the Javascript expression evaluates to true, include the content of the if tag.
• <then>...</then> If the last truth value was true, include the content of the then tag. Not needed for a typical if/else construction; usually used after a for tag to specify code that needs to be included if the for tag actually completed at least one iteration.
• <elif expr="">...</elif> Attributes:
  • expr If the last truth value was false and the Javascript expression evaluates to true, include the content of the elif tag.
• <else>...</else> If the last truth value was false, include the content of the else tag. Can also be used after a for to specify code that needs to be included if the for tag did not iterate at all.

• <for from="" to="" step="" in="" orderby="" scope="" mkmapping="">...</for> Upon iteration the following special variables are defined:

  • &_._recno; Starts at 1 and counts up per iteration.
  • &_._index; Contains the current loopindex for counted loops, or the index for iterations through arrays, or the key of the current element for iterations through objects.

  • &_._value; Contains the current value for iterations through arrays or objects.

    Attributes:

  • from Start counting from here (defaults to 0).

  • to Count up till and including to.
  • step Stepsize (defaults to 1).
  • in Iterate through the named variable (the variable needs to contain either an array or an object).
  • orderby A comma-separated list of Javascript variable expressions to sort an iteration through an object by. When the function desc() is applied to the expression, the order of that expression will be reversed. Use the _ scope to designate elements from the current element. There is shortcut reference _index which refers to the index of the current element.
  • scope Create a toplevel alias for the local scope in the current for loop.
  • mkmapping Assign this comma-separated list of names to the columns of an array in each record. If mkmapping="" and the object in _._value already has members, then these members are simply copied into the _ scope; i.e. _._value.foo becomes accessible as _.foo as well.

• <delimiter>...</delimiter> Should be used inside a for loop. It will suppress its content upon the first iteration.

• <insert var="" variable="" quote="" format="" offset="" limit="" join="" variables="" scope="" expr=""></insert> More explicit way to access variable content instead of through entities. Attributes:
  • var or variable Variable name to be inserted. Typically convenient to index objects using a different variable content as the index.
  • quote Quote method (see entities), defaults to none (contrary to the entities, which default to html).
  • format Format method (see entities).
  • offset Substring index starting at this offset.
  • limit Substring limit the total number of characters.
  • join If it is an array, join it to a string using the provided separator.
  • variables Insert a variable group:
    • dump Insert a JSON encoded dump of all accessible variables.
  • scope Limit the scope of the dumped variables to the mentioned scope only.
  • expr Use the javascript expression specified in this attribute. Or, alternately, if the attribute is empty, javascript from the content of this tag is used. Evaluates the javascript and inserts the result.
• <replace from="" regexp="" flags="" to="" expr="">...</replace> Attributes:
  • from Search in the content of this tag for this text.
  • regexp Search for this regular expression.
  • flags Regular expression flags.
  • to Replace found occurrences with this text. $ characters here have special meaning.
  • expr Replace found occurrences with this javascript expression.
• <washtags keep="" strip="">...</washtags> Attributes:
  • keep A comma separated list of all tags that need to be preserved.
  • strip A comma separated list of all tags that need to be stripped.
• <trim>...</trim> Truncates whitespace at both ends, and reduce other whitespace runs of more than one character to a single space.
• <maketag name="">...</maketag> Attributes:
  • name Construct a new tag inline using this name. Subtags:
  • <attrib name="">...</attrib> Attributes:
    • name Add attributes to the tag with these names and values. The attrib subtags need to be at the beginning of the maketag.
• <eval recurse="">...</eval> Reevaluate the content (e.g. useful to execute a tag created with maketag). Attributes:
  • recurse Specify the maximum recursion depth; defaults to 0. Specifying no value sets the maximum depth to unlimited. Evaluation stops automatically as soon as no changes are detected anymore.
• <script>...</script> Copy the contents of this tag verbatim without further parsing (and leave the script tag itself). To force parsing inside script tags use <maketag name="script">...</maketag> instead.
• <style>...</style> Treated exactly like <script> tags.
• <noparse>...</noparse> Copy the contents of this tag verbatim without further parsing (but strip the noparse tag itself). The content needs to be well-formed XHTML (no dangling tags).
• <?noparse ...?> Copy the contents of this tag verbatim without further parsing (but strip the noparse tag itself).
• <nooutput>...</nooutput> Suppress output inside this tag. The content needs to be well-formed XHTML (no dangling tags).
• <comment>...</comment> Strip and skip this tag with content. The content needs to be well-formed XHTML (no dangling tags).
• <?comment ...?> Strip and skip this tag with content.
• <cache var="" variable="" key="" shared="" ttl="">...</cache> Caches the content. Attributes:
  • var or variable Comma-separated list of variable names that the cached content should depend on.
  • key Use the stringvalue of this parameter as a direct key for the cached content to depend on. It's usually better to use var instead.
  • shared Normally all instances of <cache> reference distinct caches that use an integer number to indicate different cache contexts. By defining this you can explicitly define the cache context to store and retrieve from.
  • ttl Time to live for new cache entries in ms; if unspecified or zero it defaults to maxttl.
• <nocache>...</nocache> Mark sections inside a <cache> section to be uncached instead.

Javascript helperfunctions

These are extra helperfunctions which are available in the context of inline Remixml Javascript scripts.

• sizeof(x) Returns the number of elements in an array or object, or the size of the string. It is implemented as a definition in the global scope.

• desc(x) This function is only available inside the orderby parameter of the for loop. It causes the argument to be sorted in reverse.

• abstract2txt(abstract, html?) A shortcut reference to Remixml.abstract2txt().

• abstract2dom(abstract, node?) A shortcut reference to Remixml.abstract2dom().

API

Specified parameters:

• template Can be text-html.
• context Argument which specifies an object which can be referenced from within Remixml code. The toplevel entries are the toplevel scopes in Remixml. Within Remixml Javascript, this object will always be referenced using a single $. The local scope will always exist as $._ and that can always be referenced using a direct _ shortcut. I.e. in Javascript $._.foo and _.foo will both refer to the same variable, in Remixml both are referred to as &_.foo;.
• flags is an optional bitmask with:
  • 1: Kill all whitespace (different than the - parameter to strip whitespace per tag).
  • 4: Asynchronous processing (compiled Remixml code returns a Promise instead of a direct abstract).

Exposed API-list (in NodeJS and the browser):

• Remixml.remixml2js(remixmlsrc, flags?) Compile Remixml into remixml-javascript source.
• Remixml.js2obj(jssrc) Compile remixml-javascript source into object code. Running the object code with a context parameter returns a DOM-abstract structure (AKA virtual DOM), or a Promise to return a DOM-abstract structure when flags has the async-processing bit set.
• Remixml.abstract2txt(abstract, html?) Converts a DOM-abstract into an XHTML/Remixml-string. By default it produces valid XHTML, if it must be HTML compliant (e.g. for parsing by the browser built-in HTML parser) set the optional argument html to 1.
• Remixml.compile(remixmlsrc, flags?) Shorthand for Remixml.js2obj(Remixml.remixml2js(remixmlsrc, flags))
• Remixml.parse2txt(template, context, flags?) template can either be direct remixml source, or a precompiled object from Remixml.compile. Returns an XHTML/Remixml-string.
• Remixml.add_filter(name, filterfunction) Adds a new filter function to be used as encoding when inserting entities.
• Remixml.set_tag(callback, context, name, scope?, args?) Creates a tag definition in the given context just like <set tag="name"></set> would have done. callback is a javascript function which will be called as callback(context) and must return the replacing DOM-abstract. E.g. when the tag is referenced as <name foo="bar"></name> then inside the callback function context._.foo will have the value bar. Please take note that the provided callback can only return a Promise when flags has the async-processing bit set.
• Remixml.set_log_callback(callback) If not set, it defaults to console.error(). This callback function is used to log remixml runtime errors.
• Remixml.set_cache_options(maxttl, maxentries?, intervaltime?, intervalentries?) Sets the various cache-option defaults; if any parameters are zero or unspecified they stay unaltered.
  • maxttl: Maximum time to live in ms for cache entries (defaults to 32768 ms).
  • maxentries: Maximum number of entries in the cache (defaults to 1024).
  • intervaltime: Interval in ms between garbage collections (defaults to 256 ms).
  • intervalentries: Every intervalentries allocations it performs a garbage collection (defaults to 32).
• Remixml.abstract2dom(abstract, node?) Converts a DOM abstract into DOM nodes. If the optional node argument is specified, it replaces the children of node with the content described in DOM abstract. Returns node if specified, or the new nodes. This API-function is only available from this module if one of the optional remixml-*dom modules has been loaded.

Reserved object variables

• $.sys.lang If set, it overrides the default locale of the browser environment (currently only used during currency formatting).

References

• The Remixml website uses the smallest and fastest lockandload AMD-loader.
• For historical reference: Remixml was originally inspired by RXML, the Roxen webserver macro language.
• remixml-dom.
• remixml-htmldom.
• remixml-idom.
• remixml-pathencode.
• remixml-jsobj.
• remixml-embed.
• remixml-fmt.

Card-carrying member of the zerodeps movement.