remixml

Remixml

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

The Remixml templating engine has the following features:

• Rich powerful language with dynamic inheritance, autoescaping, functions, whitespace-collapsing, asynchronous control and more.
• Fast & lean: Small 6 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.
• 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 6 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.
  • 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.

• <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>...</cache>
  Reserved for future use.

• <nocache>...</nocache>
  Reserved for future use.

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 & 4 is true.
• 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))
• 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.
• Remixml.set_log_callback(callback)
  If not set, it defaults to console.error(). This callback function is used to log remixml runtime errors.
• 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.