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..
Reserved object variables
$.sys.lang
If set, it overrides the default locale of the browser environment
(currently only used during currency formatting).
References
Card-carrying member of the zerodeps
movement.