Creating a Mode¶

We recommend creating new modes by inheriting from the generic mode. The first thing you must do is set the metadata on the wedOptions object because wed will refuse to load your mode if these are not set:

this.wedOptions.metadata = {
    name: "Foo",
    authors: ["Ty Coon"],
    description:
       "This mode does foo!",
    license: "MPL 2.0",
    copyright: "2013 Ty Coon Industries"
};

Modes may set other options on the wedOptions property. This is essentially a mean for the mode to control how wed operates when the mode is active. These are not meant to be directly settable by the user or by the application in which wed is being used. (Although it would be possible for the mode to expose options to make them settable.)

See the file lib/wed/wed-options-schema.yml to learn what options are available.

Submodes¶

A submode is a mode that applies only to a portion of a file. Suppose that you are editing a TEI or Docbook file, and it contains an image encoded as SVG or an equation recorded as MathML. It would be onerous to require that the mode that has been tailored for TEI or Docbook also be tailored for SVG or MathML. Submodes allow the editor to switch modes when it encounters regions of a document that require specialized handling.

Caveats:

A submode must know that it is a submode. It is possible to write a mode in a way that allows it to be used as a main mode and a submode but it must be aware of when it is used as a submode and adapt accordingly.
The Mode object created for a submode is created once per document, even if the mode applies to multiple subregions. If the submode may apply to multiple regions of a document and these regions are to be handled as self-contained structures, the submode must handle it itself. (This is by opposition to the hypothetical situation where the editor would create a different Mode object per region governed by the submode. In this case, the submode would not have to take special care to treat different regions in isolation. We do not create a new submode for each region because the memory requirements would be prohibitive, with benefits that are very situation-specific.)
A submode is not a substitute for schema design. There is no such thing as a “subschema”. A document is validated by one schema — and only one — which must support all structures expected in a valid document. So if you want to incorporate MathML in a TEI schema, you must create and use a schema that supports it.
Wed determines that a submode applies to a region of the document through the following mechanisms:
- A CSS selector into the data tree: the matching elements indicate where the submode can be used.
- [More methods to be added later.]

Design goals:

Provided that a mode is well-behaved, it should not have to be modified to work with submodes. (What “well-behaved” means remains to be determined. The point here is that there should be a set of rules that allow writing modes in a way that does not require ad-hoc modifications later if they are used with submodes.)

Well-behaved modes:

Take care to not operate inside elements that are managed by submodes. However, they may operate on such elements as a whole and may allow editing attributes on such elements.

This rule extends to classes or instances provided by modes. E.g. a ModeValidator must check that it is operating only on appropriate nodes.
Take care to not operate on elements that are outside the region they manage, even though they have access to the whole document.
- In particular a customized Decorator will normally want to check that the nodes it operates on are governed by the mode associated with the decorator. The typical test is:
```
if (this.editor.modeTree.getMode(el) !== this.mode) {
  // The element is not governed by this mode.
  return;
}
```
Use stylesheets that are designed to apply only to the elements they manage. This entails using CSS selectors that have enough specificity. [Wed may eventually help with this, but for how the onus is entirely on mode designers.]