remixml

<h1>Remixml</h1> [![NPM version](http://img.shields.io/npm/v/remixml.svg?style=flat)](https://npmjs.org/package/remixml) [![Downloads](https://img.shields.io/npm/dm/remixml.svg?style=flat)](https://npmjs.org/package/remixml) [![Rate on Openbase](https://badges.openbase.io/js/rating/remixml.svg)](https://openbase.io/js/remixml?utm_source=embedded&utm_medium=badge&utm_campaign=rate-badge) ![Lib Size](https://img.badgesize.io/https:/unpkg.com/remixml/remixml.min.js?compression=gzip) [![Code Quality](https://api.codeclimate.com/v1/badges/a99a88d28ad37a79dbf6/maintainability)](https://codeclimate.com/github/BuGlessRB/remixml) 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: ```js Remixml.parse2txt(` <h1>Title of &_.sitename; for &_.description;</h1> 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 } }); ``` ### Native Remixml examples Simple assigment: ```html <set var="_.variablename">the new value</set> ``` Simple calculations: ```html <set var="_.variablename" expr="_.variablename + 1" /> ``` Conditionals: ```html <if expr="_.variablename > 1"> yes </if> <elif expr="_.variablename == 'foobar'"> second condition valid </elif> <else> otherwise </else> ``` Counted loop: ```html <for from="1" to="42"> This is line &_._recno; </for> ``` Iterating through an object or array: ```html <set var="_.foo" split=",">aa,b,cc,d,eee,f</set> <for in="_.foo"> This is record &_._recno; value: &_._value; </for> ``` Defining your own HTML to make it more readable, maintainable and <a href="https://en.wikipedia.org/wiki/Don%27t_repeat_yourself">DRY</a>: ```html <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;"/>. </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: ```html <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> &_.valinput;! = <faculty val="&_.valinput;" /> </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](https://dev.w3.org/html5/html-author/charref). 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](https://www.json.org/) 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](https://en.wikipedia.org/wiki/Printf_format_string) . 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](http://www.cplusplus.com/reference/ctime/strftime/) . 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. ```html <div -> This will strip all fully enclose whitespace (between the div and p tags). </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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split). - `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](https://developer.mozilla.org/en-US/docs/Learn/CSS/Introduction_to_CSS/Selectors). - `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; if we are iterating over an array, then a mere `_` thus will have the value of the 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions). - `to` Replace found occurrences with this text. [`$` characters here have special meaning](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_string_as_a_parameter). - `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](http://remixml.org/) uses the smallest and fastest [lockandload AMD-loader](https://www.npmjs.com/package/lockandload). - For historical reference: Remixml was originally inspired by [RXML, the Roxen webserver macro language](http://docs.roxen.com/). - [remixml-dom](https://github.com/BuGlessRB/remixml-dom). - [remixml-htmldom](https://github.com/BuGlessRB/remixml-htmldom). - [remixml-idom](https://github.com/BuGlessRB/remixml-idom). - [remixml-pathencode](https://github.com/BuGlessRB/remixml-pathencode). - [remixml-jsobj](https://github.com/BuGlessRB/remixml-jsobj). - [remixml-embed](https://github.com/BuGlessRB/remixml-embed). - [remixml-fmt](https://github.com/BuGlessRB/remixml-fmt). Card-carrying member of the `zerodeps` movement.