@wider/utils_markup

A class object to macro expand values in a source string supporting nested definitions, formulae, and conversion of values according to nature of use - such as in plain text or in an xml/html attribute

Do not confuse this with markdown in @wider/utils_proto.

Overview

Provides a markup akin to what you get on an operating system command line except that you can add your own extra markups on the fly. Can be used on a simple string from your source code or the content from complete files of any size. Marking up is optimised for speed.

If your resultant string happens to be in JSON format, you have the option of obtaining the parsed object with markups that include your own objects as well.

If you provide an object instead of a string, the string properties inside the deep scan of the object will be marked up. If any of these strings are solely a markup and the markup value is an object, object is inserted instead of the string - see [Marking up Objects](tutorial-Marking up with Objects.html).

The data used to provide the replacement values for your markups may come from any or all of four sources. They are simple keyName / value pairs in an object.

• the optional values you provide each time when you execute the .markups() method
• the optional values you define when you create an instance of the class
• the operating system's environment variables (only available when run on a nodeJS server)
• intrinsic variables provided in this utility - see [intrinsic variables](tutorial-Marking up with Objects.html).

If the same key name is used in more than one of the above, the first one encountered in the order given will dominate.

Markup references can be nested in the resultant values of other markup results - however if you create circular references then the last reference that would create the circle is not expanded.

Performance is impacted by the number of markup references needing to be converted as encountered in your source string. The number of markup definitions you put forward for potential use has negligible impact. So where it is more convenient to you, consider grouping your definitions in one place and ignore the overhead of those that are not used.

Qualifiers and Genre

When a value is referenced you may add genre and qualifiers that alter the treatment of the matched value. If there is no qualifier then the value is used as it is provided, where feasible automatic type conversion applies.

Genres, if specified, determine whether or not a keyName is actually marked up according to the Genre of the server/tool that is running this utility. Common genre values are server and browser. For a full list see @wider/utils_where-am-i.

Qualifiers, if specified, alter the content that is delivered. For example the value encoded will encode a string so the markup can appear in an html or xml attribute. For further details see [About Qualifiers](https://y-d-r.co.uk/packages/@wider/utils_markup/tutorial-About qualifiers.html)

Documentation

Full Documentation

Install

npm install "@wider/utils_markup"

Use at Server

To prepare a markup processor on a nodeJS server..

const Markups = require("@wider/utils_markup");

const commonMarkups = { /* some key value pairs */};
const thisMarkerUpper = new Markups(commonMarkups);

const tester = "some string with eg %TEMP% markups";

/*optional*/ const myExtras = { /* for this first call to the instance */}
const markedUpTester = thisMarkerUpper.markups(tester, myExtras);

/*optional*/ const myExtras2 = { /* for this second call to the instance */}
const markedUpTester = thisMarkerUpper.markups(tester, myExtras2);

Please review the [example](tutorial-Illustration of test.js.html) for a fully worked demonstration with input and generated result;

Use at client

You can use the third party npm package browserify to encapsulate this for operation at the client browser.

This package is part of the YDR core bundle and can be found in the client script file @wider/utils_bundle/ydrCore$.js. The class object is found in global variable $ydr.Markups

For security reasons, this package does not macro expand server environment variables at the client - but you can ship the relevant safe details to the client yourself if you so wish.

Caution

When using these markups in the source string of an object that is subject to a schema, you will need to ensure that you structure keyNames and their values so that they do not result in schema errors.

Example Uses

• Convert server customised html pages to static cacheable content marked up at client. For example a data entry form can be static with the initial values of the fields set via markups at the client - so the form is cached and can be rendered at the client quickly and the server only has to send a JSON object to the client with customised values.
• Provide standard boiler plate in the <head></head> section of an HTML document so the same content does not have to be replicated in each .html file.
• Prepare fully expanded commands for your server's command processor.
• Tailoring a JSON settings file.

You might be interested in

package:@wider/utils_requireJSON allows a JSON object to have parts that are selected according to run time environment (development / production) as well as these markups during the load of a JSON object from its string definition.