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.

It has zero dependencies on other modules.

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.
  • path
    Path component; performs a lossy transformation of the value into a format that can be inserted into a path:
    • Cast to lowercase.
    • Replace diacritics by their ASCII equivalent.
    • Replace all strings of non-alphanumeric characters with single dashes.
    • Strip dashes from start and end.
  • 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)
  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: 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="" variable="" expr="" regexp="" split="" join="" mkmapping="" selector="" json="" tag="" args="" noparse="" 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, 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.
  • mkmapping
    Assign this comma-separated list of names to the columns of the array.
  • selector
    Extract the selected content into an array of Nodes.
  • 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.
  • noparse
    Causes &_._contents; to be returned unparsed in this tag definition.
  • scope
    Create a toplevel alias for the local scope in this tag definition.

• <unset var="" variable=""></unset>
  Attributes:

  • var or variable
    Delete the named variable.

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

• <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=""></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.

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

• <noparse>...</noparse>
  Copy the contents of this tag verbatim without further parsing (but strip the noparse tag itself).

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

• <comment>...</comment>
  Strip and skip this tag with content.

Javascript helperfunctions

These are extra helperfunctions which will be available in the 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.

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 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:

• Remixml.preparse(template, context)
  Clones and parses the template. It returns the parsed version, the original template is left in a preparsed/precompiled state to accellerate repeated parsing.
• Remixml.parse(template, context)
  In-situ parses the template and returns it. If you want to reuse the template, clone it first.
• Remixml.parse2txt(template, context)
  Destructively parses the template, returns the result as a string (convenience function for dom2txt(parse())).
• Remixml.parse_tagged(template, context)
  In-situ parses the template and returns it, but only touches regions enclosed in <remixml>...</remixml> tags.
• Remixml.parse_document(context)
  In-situ parses the whole current page document (head and body) and returns it.
• Remixml.set_tag(callback, context, name, scope?, noparse?, 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-template. E.g. when the tag is referenced as <name foo="bar"></name> then inside the callback function context._.foo will have the value bar. noparse is a boolean that defaults to false.
• Remixml.dom2txt(template)
  Destructively converts the domNode(s) to a string and returns it.
• Remixml.txt2dom(template)
  Turns the string template into a domNode structure. If passed a domNode object, it returns it unchanged.
• Remixml.path_encode(string)
  Strips and encodes string to something which can be safely inserted in an url (compare path encoding for entities).
• Remixml.trim(template)
  In-situ trims whitespace like the Remixml <trim> tag and returns the trimmed template..
• Remixml.set_log_callback(callback)
  If not set, it defaults to console.log(). This callback function is used to log remixml runtime errors.

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.

Card-carrying member of the zerodeps movement.