Lurch web app user interface

Class

LurchDocument

A Lurch document will have several parts, including at least the following.

  • The document content as the user sees it in the editor (HTML)
  • Any per-document settings stored in the document as metadata (JSON)
  • Information about dependencies on which the document depents (the form of which has not yet been decided)

When stored in a filesystem, the document must contain all three of these parts, but when displayed in the editor, it should show only the first of them, keeping the rest somewhere outside of the user's view. And yet those other parts will be editable by the user, through a UI not yet developed. And so when the document is saved, the latest versions of all three parts of the document must be saved, not just the part visible in the editor.

This class provides a clean API for moving documents between any filesystem and the editor. It is an ephemeral/disposable class, in the sense that you will often create an instance just for use in one command, and then let it be garbage collected. Examples:

// Clear out the editor, as in response to File > New:
new LurchDocument( editor ).newDocument()
// Get the document from the editor, in a form ready to save
// (that is, including all of its parts, not just what's visible in the UI):
const doc = new LurchDocument( editor ).getDocument()
// Load into the editor a document retrieved from a filesystem, which will
// have all 3 parts described above, only one of which should be shown:
new LurchDocument( editor ).setDocument( doc )

Constructor

new LurchDocument(editor)

Construct a new instance for reading and/or writing data and metadata to and/or from the given editor. Also, if the editor does not already have a LurchDocument instance stored in its lurchDocument property, place this new instance there.

Parameters

  • editor tinymce.editor

    the editor with which this object will interface

Source

Classes

LurchDocument

Members

bodySettings

This array lists those settings that should be marked as classes on the body element of the editor's document. This exposes them to CSS rules in the editor, so that they can be used to style the document content.

In general, a setting with key "example one" and value "foo bar" will be marked on the body element with a class of "example-one-foo-bar".

See

Source

settingsMetadata

This metadata object can be used to create a Settings instance for any given document, which can then present a UI to the user for editing the document's settings (using its userEdit() function). We use it for this purpose in the menu item we create in the install() function, among other places. Instances of this class also use it to return the appropriate defaults for settings the user may query about a document.

This metadata can be used to edit document-level settings, which are distinct from the application-level settings defined in the Settings Installer module.

Source

Methods

deleteMetadata(category, key)

Pieces of metadata are indexed by a category-key pair, facilitating "namespaces" within the metadata. See setMetadata() for more information on why. This function deletes the unique metadata item stored under the given category-key pair if there is one, and does nothing otherwise.

Also, some pieces of metadata, when deleted, require placing attributes or classes in the editor's DOM, and this function will take that action as well, if needed.

Parameters

  • category string

    the category for the piece of metadata to delete

  • key string

    the key for the piece of metadata to delete

See

Source

getDocument(openLink) → {string}

Return the document being edited by the editor that was given at construction time. This includes its visible content as well as its metdata, which includes document settings and dependencies. It may also include a link at the top of the document, which allows the reader to open the document in the live app from which it was saved. That link can be customized using the parameter.

Parameters

  • openLink string | function

    the HTML content to use at the top of the document, to provide a link for opening the document in the live Lurch app. If not provided, a sensible default is used, which is a DIV containing just one link, whose URL is supplied by a small script that runs at page load time and reads the document URL. You can remove this link entirely by setting this value to the empty string. If this is a function instead of a string, it will be called on the document content without the open link, and should return an open link to be used as a prefix.

See

Returns

  • string

    the document in string form, ready to be stored in a filesystem

Source

getMetadata(category, key) → {string|number|bool|Object|HTMLDivElement|undefined}

Pieces of metadata are indexed by a category-key pair, facilitating "namespaces" within the metadata. See setMetadata() for more information on why. This function looks up the value that corresponds to the given category and key.

If the value is stored in JSON form, then the corresponding object will be returned (as produced by JSON.parse()). If the value is stored in HTML form, then an HTMLDivElement instance will be returned, the contents of which are the value of the metadata item. The element returned is a copy of the one stored internally, so the caller cannot alter the internal value by modifying the returned element.

Parameters

  • category string

    the category for the piece of metadata to look up

  • key string

    the key for the piece of metadata to look up

See

Returns

  • string number bool Object HTMLDivElement undefined

    the value stored in the metadata, or undefined if there is no such metadata

Source

getMetadataCategories() → {Array.<string>}

Pieces of metadata are indexed by a category-key pair, facilitating "namespaces" within the metadata. See setMetadata() for more information on why. This function returns all categories that appear in the document's metadata. There is no defined order to the result, but no category is repeated. The list may be empty if this document has no metadata stored in it.

See

Returns

  • Array.<string>

    an array containing all strings that appear as categories in this document's metadata

Source

getMetadataKeys(category) → {Array.<string>}

Pieces of metadata are indexed by a category-key pair, facilitating "namespaces" within the metadata. See setMetadata() for more information on why. This function returns all keys that appear in the document's metadata under a given category. There is no defined order to the result, but no key is repeated. The list may be empty if this document has no metadata stored in it under the given category.

Parameters

  • category string

    the category whose keys should be listed

See

Returns

  • Array.<string>

    the keys corresponding to the given category

Source

newDocument()

Clear out the contents of the editor given at construction time. This includes clearing out its content as well as any metdata, including document settings and dependencies. It also clears the editor's dirty flag.

Source

setDocument(document)

Load the given document into the editor given at construction time. This will replace what's visible in the UI with the visible portion of the given document, and will also replace the invisible document settings and dependencies with those of the given document. It also clears the editor's dirty flag.

Parameters

  • document string

    the document as it was retrieved from a filesystem (or another source), ready to be loaded into this editor

See

Source

setFileID(id)

If the application loaded a file from a given filename, or a given online storage location, it may want to save a unique ID (such as the filename or a pointer to the online storage location) so that the user can later just choose "Save" and have the file instantly stored back in the same location. To facilitate this, we allow the storing of an arbitrary ID associated with the given file. This ID is cleared out whenever newDocument() is called.

Parameters

  • id any

    the ID to store

See

Source

setMetadata(category, key, valueType, value)

Store a new piece of metadata in this object, or update an old one. Pieces of metadata are indexed by a category-key pair, facilitating "namespaces" within the metadata. This is useful so that we can partition the metadata into things like document-level settings, the document's list of dependencies, data cached by algorithms in the app, and any other categories that arise.

Values can be either JSON data (which includes strings, integers, and booleans, in addition to the more complex types of JSON data) or HTML in string form (for example, if you wish to store an entire dependency).

Also, some pieces of metadata, when stored, require placing attributes or classes in the editor's DOM, and this function will take that action as well, if needed.

Parameters

  • category string

    the category for this piece of metadata

  • key string

    the key for this piece of metadata

  • valueType string

    either "json" or "html" to specify the format for the value

  • value string | Object

    a string of HTML if valueType is "html" or an object we can pass to JSON.stringify() if valueType is "json"

See

Source

updateBodyClasses()

For each setting mentioned in bodySettings, this function ensures that there is precisely one CSS class on the body of the document beginning with that setting's key, and that is the class that ends with that setting's value.

As documented in bodySettings, spaces are replaced with dashes, so that a setting with key "number of tacos" and value "not enough" would become a CSS class "number-of-tacos-not-enough".

See

Source

static

documentParts(document) → {Object}

A Lurch document has two main parts, a DIV storing the metadata followed by a DIV storing the actual document content. This function takes a string containing the HTML for a Lurch document and extracts those two components from it, returning each one as a fully constructed HTMLDivElement.

Note that a Lurch document's HTML text also begins with a brief script to create the link to open the document in the Lurch app, but that portion of the input string is ignored, because it is not part of the document, nor its metadata.

Parameters

  • document string

    the document as it was retrieved from a filesystem, ready to be loaded into this editor

See

  • isDocumentHTML()

Returns

  • Object

    an object with "metadata" and "document" fields, as documented above

Source

static

isDocumentHTML(document) → {boolean}

Is the given text a valid Lurch document? This is checked by applying the documentParts() function to it, and ensuring that it has at least a document member, even if it does not also have a metadata member.

Parameters

  • document string

    the document in HTML form

See

  • documentParts()

Returns

  • boolean

    true if the document is a valid Lurch document, false otherwise

Source