Stencil

Type: Class

Stencils are an XSD inspired JsonML based language used for describing a fragment of an XML DOM. This means any JsonML fragment is a valid stencil.

Note: Stencils do not work properly when the node(s) being inserted will be validated using simple types. Please use XQuery in those cases.

Use createStencil to create a stencil.

Stencils can be used to define a regular grammar over the DOM, just like regular expressions can be used to query over strings.

Stencil property

Semantic

multiple

Multiple in stencil gaps can be seen as the analogue of the Kleene star (*) in regular expressions. This switches between matching multiple nodes in a childList and forcing just a single node.

required

Required can be seen as the inverse of a optionality marker (?) in regexes. This option can force a gap to match (at least) a single node.

empty

Empty can be used to force a gap to match a position. There is no true analogue in regular expressions

doesNotContainSelection

Whether the selection cannot occur in the given gap. true indicates not contained by the gap, before and after indicate the selection is also disallowed to be directly before / after the node. There is no real analogue in normal regexes.

Binding to models

Retrieving information

Regular expressions can retrieve information using (named) capture groups. Stencils can also be used to retrieve information.

Given the following stencil:

JSON

["someElement", [{ "someAttribute": { "bindTo": "someValue" }}]

And the following piece of DOM:

XML

<someElement someAttribute="Fonto" />

Using the correct operation, we can retrieve the following model from the stencil:

JSON

{"someAttribute": "Fonto"}

Setting information

Unlike regular expressions, stencils can even fill in information in the DOM.

Given the following stencil:

JSON

["someElement", [{ "someAttribute": { "bindTo": "someValue" }}]

And the following model:

JSON

{"someAttribute": "Fonto"}

Combined, it results in the following piece of DOM

XML

<someElement someAttribute="Fonto" />

This can then be inserted using an operation of your choice.

Pseudo gaps

When provided with a named gap, Fonto automatically creates a .start and .end gap. These gaps can be used as a shortcut to writing extra gaps.

Example

JSON

[
  "someElement",
  [{ "bindTo": "selection" }]
]

This stencil knows the following gaps: selection, selection.start and selection.end. Since some operations define selection.start and selection.end as special, they can find it in the stencil.

Restricted gaps

Gaps can be restricted to match only when a given XPath query matches the node or attribute. These gaps can be used for some more specific situations.

Example

Given the following XML structure:

XML

<someParent>
  <someElement>
  <someElement someAttribute="someValue">
  <someElement>
</someParent>

And the following stencil:

JSON

[
  "someParent",
  [{ "bindTo": "someValue", "multiple": true }]
]

This will result in the stencil matching all the children of the someParent element. The following stencil can be used to make the gap more specific:

JSON

[
  "someParent",
  [{
    "bindTo": "someValue",
    "multiple": true,
    "restrictTo": "self::*[@someAttribute="someValue"]"
  }]
]

This will result in the stencil matching only the child element with its someAttribute set to someValue.

Constructor arguments

  1. stencilModel

    (Required)

    Type: Object

  2. stencilMetadata

    (Required)

    Type: Object

Methods

complete

Type: Function

Make the existing structure match the stencil. Note the structure may not be valid, it can always be made valid using the synthesizer.

Arguments

Returns

generate

Type: Function

Generate a new AlignedStencil from this stencil, holding a new, valid structure

Arguments

Returns

match

Type: Function

Align the stencil to the given dom, not changing the structure

Arguments

Returns