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.

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:

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

And the following piece of DOM:

<someElement someAttribute="Fonto" />

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

{"someAttribute": "Fonto"}

Setting information

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

Given the following stencil:

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

And the following model:

{"someAttribute": "Fonto"}

Combined, it results in the following piece of DOM

<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

[
  "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:

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

And the following stencil:

[
  "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:

[
  "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

# Name Type Description
1. stencilModel Object
2. stencilMetadata Object

Methods

Name Description
complete

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


  Arguments
# Name Type Description
1. blueprint Blueprint
2. rootNode Node

The existing node, matching the root of the stencil

3. format Format

The format to use to ensure the structure can completed in a valid way

4. [selectionRange] Range | Null

The current selectionRange, used to align with

  Returns
generate

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


  Arguments
# Name Type Description
1. blueprint Blueprint
2. format Format

The format to use to ensure the structure can completed in a valid way

3. documentNode Node
  Returns
match

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


  Arguments
# Name Type Description
1. matchingDom Node

The root of where the stencil should match the dom

2. blueprint Blueprint

The blueprint in which to match

3. selectionRange Range | Null

The selectionRange which can possibly be used to match

  Returns