Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

remixml

Package Overview
Dependencies
Maintainers
1
Versions
346
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

remixml

XML/HTML-like macro language/template engine

  • 1.6.1
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
456
increased by256.25%
Maintainers
1
Weekly downloads
 
Created
Source

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.

Keywords

FAQs

Package last updated on 26 Mar 2019

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc