remixml

Remixml

Remixml is an XML/HTML macro language/template engine.

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

Requirements

It runs inside any webbrowser environment (starting at IE11 and up).

The engine uses browser primitives to accellerate parsing; most notably it uses documentFragments and will therefore have trouble running in a plain NodeJS environment.

Basic usage

In essence Remixml is a macro language that has HTML/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 code will illustrate the point:

Remixml.parse('<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;',
 {_: {
    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
  }
 });

Reference documentation

Full entity syntax

& scope . variablename : encoding % formatting ;

• scope
  References the primary level in the variables object (the second argument to parse()).
• variablename
  References second and deeper levels in the variables object (can contain multiple dots to designate deeper levels, is used to access both objects and arrays).
• encoding (optional)
  Specifies the encoding to be used when substituting the variable. The encodings available are:
  • html
    Default, encodes using HTML entities.
  • uric
    URI component, encodes URI arguments in an URL.
  • json
    Encodes as a JSON string.
  • none
    No encoding, as is, can be abbreviated as ":;".
• formatting (optional)
  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.

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).

Language tags

• <set var="" expr="" split="" join="" tag="" scope="">...</set>
  Attributes:

  • var
    Assign to the named variable.
  • expr
    Use the javascript expression specified in this attribute. Or, alternately, if the attribute is empty, a javascript from the content of this tag is stored.
  • 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.
  • 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.
  • scope
    Create a toplevel alias for the local scope in this tag definition.

• <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 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="">...</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.
  • scope
    Create a toplevel alias for the local scope in the current for loop.

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

• <insert var="" quote="" format="" offset="" limit="" variables=""></insert>
  More explicit way to access variable content instead of through entities.
  Attributes:

  • var
    Variable name to be inserted. Typically convenient to index objects using a different variable content as the index.
  • quote
    Quote method (see entities).
  • format
    Format method (see entities).
  • offset
    Substring index starting at this offset.
  • limit
    Substring limit the total number of characters.
  • variables
    Insert a variable group:
    • dump
      Insert a JSON encoded dump of all accessible variables.

• <replace from="" regexp="" flags="" to="">...</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.

• <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>...</eval>
  Reevaluate the content (e.g. useful to execute a tag created with maketag).

• <nooutput>...</nooutput>
  Suppress output inside this tag.

• <comment>...</comment>
  Skip the content of this tag.

Examples

Simple assigment:

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

Simple calculations:

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

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>

API

Specified parameters:

• template
  Can be a domNode, documentFragment, or text-html.
• context
  Optional argument which specifies an object which can be referenced from within Remixml code. The toplevel entries are the toplevel scopes in Remixml. Within the 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.

Exposed API-list:

• template = Remixml.parse(template, context);
  Destructively parses the template. If you want to reuse the template, clone it first.
• txt = Remixml.parse2txt(template, context);
  Destructively parses the template, returns the result as a string (convenience function for dom2txt(parse())).
• template = Remixml.parse_tagged(template, context);
  Destructively parses the template, but only touches regions enclosed in `... tags.
• domtop = Remixml.parse_document(context);
  Destructively parses the whole current page document.
• txt = Remixml.dom2txt(template);
  Destructively converts the domNode(s) to a string.
• template = Remixml.trim(template);
  Trims whitespace like the Remixml <trim> tag.

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.
• For historical reference:
  Remixml was originally inspired by RXML, the Roxen webserver macro language.