Module: object-to-microdata

This module contains the functions to convert ONE objects in their Javascript representation to a UTF-8 microdata string, the format ONE objects are stored in and - very important! - from which the SHA-256 representing the ONE object is calculated.

ABOUT ONE MICRODATA

"Recipes" are a collection of rules used to construct microdata strings. ONE microdata must be much more finical about syntax than HTML: After all, a crypto-hash of the microdata string is used to identify the object, and identical data must produce an identical crypto-hash!

Therefore, in order to ensure that microdata created as representation for data is created exact down to the last character we use recipes to transform data into microdata.

To remove any ambiguity there is no unnecessary whitespace: ONE microdata HTML is on one line, with one space exactly to separate components within one tag (name, attributes) and no spaces or newlines between tags unless they belong to the encapsulated data (strings).

The same rules used to create the microdata string are used to parse them, the module object-recipes.js has the recipes.

To get an identical crypto-hash we must also impose an exact order on the items in the microdata string. We do this by using an array instead of a hash to store the rules for the individual items for each ONE object type. The ordering of the array is used during creation and also during parsing of ONE Microdata.

A ONE microdata object contains any of these items: a) simple values (strings - everything that is not a string must be "stringified") b) simple links: hashes pointing to unspecified files (BLOBs/CLOBs) identified by their crypto-hash c) ONE object links: hashes pointing to files containing another ONE microdata object d) ("imploded form") instead of a link to a ONE object it can contain that object directly. e) same as d) but it is a direct include, not an imploded reference object

The rules to create ONE objects are kept as simple as possible. Data checks are mostly left out of the specification apart from basic "type" tests. The converter will write whatever it gets, as long as there is a rule for it, and it will write it n times or just once depending on if it gets an array or an individual value. Similarly, the parser will read what is there. If an Email ONE object is missing the From address or if it contains two subject fields instead of one is something a higher level module should be concerned about.

Any data not found in a rule is ignored (we iterate over the rule-set and then grab the required data from the object).

Any rule for which there is no data is ignored, unless it is an ID rule - ID fields are mandatory.

RULE MEANINGS: See object-recipes.js, in particular the definition of the JSDoc type RecipeRule.

Source:

Methods

(static) escapeForHtml(value) → {string}

Parameters:
Name Type Description
value string

The raw string of a ONE object property value potentially containing characters that would break the HTML parsing of the microdata

If we save random user/3rd party supplied strings within an HTML document we must escape characters that would cause problems with HTML parsing. The reverse is done in the module doing the opposite conversion from microdata to (Javascript) object.

The strings go between HTML tags, for attributes inside HTML tags we would also have to change single and double quote characters because both could be used to enclose the attribute string. Something to keep in mind should ONE microdata ever use attributes.

See https://stackoverflow.com/a/7279035/544779

Source:
Returns:

Returns the string with "<", ">" and "&" characters replaced by their respective HTML entities

Type: string

(inner) convertArrayValueType(newVal, itemProp, valueType) → {string}

Parameters:
Name Type Description
newVal unknown
itemProp string
valueType ArrayValue

Converts the given array into microdata. Array is ordered by the app. E.g. the following array ['string1', 'string2'] will be transformed into this:

<ol itemprop="some-item-prop">
    <li> string1 </li>
    <li> string2 </li>
</ol>
Source:
Returns:

Type: string

(inner) convertBagType(newVal, itemProp, valueType) → {string}

Parameters:
Name Type Description
newVal unknown
itemProp string
valueType BagValue

Converts the given bag into microdata. Array is ordered by ONE. E.g. the following array ['string1', 'string2'] will be transformed into this:

<ul itemprop="some-item-prop">
    <li> string1 </li>
    <li> string2 </li>
</ul>
Source:
Returns:

Type: string

(inner) convertMapType(newVal, itemProp, valueType) → {string}

Parameters:
Name Type Description
newVal unknown
itemProp string
valueType MapValue

Converts the given map into microdata. E.g. the following map new Map([['key1','string1'],['key2','string2']]) will be transformed into this:

<dl itemprop="some-item-prop">
    <dt> key1 </dt>
    <dd> string1 </dd>
    <dt> key2 </dt>
    <dd> string2 </dd>
</dl>
Source:
Returns:

Type: string

(inner) convertSetType(newVal, itemProp, valueType) → {string}

Parameters:
Name Type Description
newVal unknown
itemProp string
valueType SetValue

Converts the given bag into microdata. Array is ordered by ONE. E.g. the following set ['string1', 'string2'] will be transformed into this:

<ul itemprop="some-item-prop">
    <li> string1 </li>
    <li> string2 </li>
</ul>
Source:
Returns:

Type: string

(inner) convertNestedObjectType(newVal, itemProp, valueType, isNestedCallopt) → {string}

Parameters:
Name Type Attributes Default Description
newVal unknown
itemProp string
valueType ObjectValue
isNestedCall boolean <optional>
 false

Converts the given object into microdata. E.g. the following object {foo: 2} will be transformed into this:

<div itemprop="some-item-prop">
    <span itemprop="foo">2</span>
</div>
Source:
Returns:

Type: string

(inner) convertStringType(newVal, itemProp, valueType) → {string}

Parameters:
Name Type Description
newVal unknown
itemProp string
valueType StringValue

Converts the given string into microdata. E.g. the following string 'string1' will be transformed into this:

<span itemprop="some-item-prop">
    string1
</span>
Source:
Returns:

Type: string

(inner) convertIntegerType(newVal, itemProp, valueType) → {string}

Parameters:
Name Type Description
newVal unknown
itemProp string
valueType IntegerValue

Converts the given integer into microdata. E.g. the following integer 1 will be transformed into this:

<span itemprop="some-item-prop">
    1
</span>
Source:
Returns:

Type: string

(inner) convertNumberType(newVal, itemProp, valueType) → {string}

Parameters:
Name Type Description
newVal unknown
itemProp string
valueType NumberValue

Converts the given number into microdata. E.g. the following number 2 will be transformed into this:

<span itemprop="some-item-prop">
    2
</span>
Source:
Returns:

Type: string

(inner) convertBooleanType(newVal, itemProp, valueType) → {string}

Parameters:
Name Type Description
newVal unknown
itemProp string
valueType BooleanValue

Converts the given boolean into microdata. E.g. the following boolean 'true' will be transformed into this:

<span itemprop="some-item-prop">
    true
</span>
Source:
Returns:

Type: string

(inner) convertReferenceType(newVal, itemProp) → {string}

Parameters:
Name Type Description
newVal unknown
itemProp string

Converts the given reference into microdata. E.g. the following reference 'dd005c5a25fac365f2d72a113a754a561a9a587530b5a2f1d1ae0ec3874cf5c3' will be transformed into this:

<a itemprop="some-item-prop" href
="dd005c5a25fac365f2d72a113a754a561a9a587530b5a2f1d1ae0ec3874cf5c3">
dd005c5a25fac365f2d72a113a754a561a9a587530b5a2f1d1ae0ec3874cf5c3
</a>
Source:
Returns:

Type: string

(static) getHashLinkTypeFromRule(type) → {"obj"|"id"|"clob"|"blob"|void}

Parameters:
Name Type Description
type RecipeRule
Source:
Returns:

Type: "obj" | "id" | "clob" | "blob" | void

(static) convertObjToMicrodata(obj) → {string}

Parameters:
Name Type Description
obj OneObjectTypes

A Javascript object describing a ONE object

Convert the Javascript object representation of a ONE object to microdata following the rules in object-recipes.js. An exception is thrown if there is a problem during the conversion. Note Any property not found in a rule is ignored - we iterate over the rules and then check for a property on the object. Also ignored are rules marked as optional if there indeed is no data for them.

Source:
Throws:

Throws an Error if the mandatory object parameter is missing

Type: Error

Returns:

Microdata representation of the object

Type: string

(static) convertObjToIdMicrodata(obj) → {string}

Parameters:
Name Type Description
obj OneIdObjectTypes

A Javascript object describing a ONE ID object

Convert the Javascript object representation of a ONE object to ID microdata following the rules in object-recipes.js. An exception is thrown if there is a problem during the conversion. Note Any property not found in a rule is ignored - we iterate over the rules and then check for a property on the object. Also ignored are rules marked as optional if there indeed is no data for them.

Source:
Throws:

Throws an Error if the mandatory object parameter is missing

Type: Error

Returns:

ID Microdata representation of the object

Type: string

Type Definitions

HashLinkTypeStrings

Hash link type identifier strings returned by getHashLinkTypeFromRule

Type:
  • 'obj' | 'id' | 'clob' | 'blob'
Source: