Lurch web app user interface

Class

Shell

For information about the concept of shells in Lurch in general, see the documentation of the Shells module. Because Shells are a type of Atom, much of their API comes from the Atom class. This subclass changes a few of the base implementations and adds a few new function specific to shells.

As with atoms, one constructs an instance of this class by passing the corresponding HTML element from the editor, along with the editor itself, and the resulting object provides an extensive API (documented below and in the Atom class) for interfacing with the shell in a variety of ways useful for the Lurch app.

Constructor

new Shell()

Source

Methods

contextMenu(forThis) → {Array.<Object>}

Items to be included on the TinyMCE context menu if a shell is right-clicked. For information on the format of the returned data, see the TinyMCE v6 manual on custom context menus.

In this case, it adds one item, for editing the type of the shell. It opens a dialog that provides a drop-down list for choosing which subclass of shell this one is, so that when we use shells to implement common mathematical concepts (e.g., Theorem, Proof, Rule, etc.) the user will automatically have a way to convert among those types of document structure.

Note: If the application has no proper subclasses of Shell installed, this function will not add the item to the context menu.

Parameters

  • forThis Atom

    the atom that received the right-click action that led to the creation of the context menu

Returns

  • Array.<Object>

    data representing the contents of a TinyMCE context menu

Source

edit() → {Promise}

The default behavior for clicking a shell is that nothing should happen, so this function typically just calls the superclass method, which does nothing. However, when inserting a shell for the first time, we do want the edit() action to do something, so you can set shellInstance.inCreationPhase = true before calling this method (directly or indirectly through editThenInsert()), and in that case, it will call editShellType().

Returns

  • Promise

    the result of calling editShellType() if in the creation phase, and a promise that resolves immediately to false otherwise

Source

editShellType() → {Promise}

Show a dialog to allow the user to edit the type of the shell. The dialog will show a drop-down list of all subclasses of Shell, from which the user can choose this shell's type. If there are no registered subclasses of Shell, this function returns a promise that resolves immediately to false, and does nothing else.

Returns

  • Promise

    a promise that resolves to true if the editing dialog is shown and the user confirms their edits, or resolves to false if the editing dialog cannot be shown or the user cancels

Source

finalize(shellLC)

After converting a shell to LCs using toLCs(), its children (if any) will be created and added to it. Specifically, we expect that toLCs() will return a single environment, to which children will be added. Then this function will be called on that same environment object, allowing the shell to tweak attributes of its children to respect the meaning of the shell itself. For example, if the shell implies that any child environments should be givens, it can make them so.

This default implementation does nothing. Subclasses may override it.

Parameters

  • shellLC LogicConcept

    the Environment LC represneting this shell

See

  • toLCs()

Source

getTitle() → {string}

Every shell may provide a title to decorate the top of its DIV, on the left-hand side. This is optional. The default is the name of the class, in title case, followed by a colon. Subclasses may override this, e.g., by returning the empty string to remove the title entirely.

Returns

  • string

    the title to use at the top of the shell, when displayed in the document

Source

setSubclass(subclassName) → {Shell}

Assign this shell a specific subclass, by name. You must assign a subclass by name, using one of the names registered using registerSubclass(), and that subclass must be a subclass of Shell. This routine stores the subclass in the shell, updates any other related information (e.g., how the shell is displayed), and returns a new instance of the Atom class, specifically of the named subclass, for this shell.

Parameters

  • subclassName string

    the name of the subclass to assign

Returns

  • Shell

    an instance of the given subclass, representing this same shell

Source

setValidationResult()

Override the default implementation, which uses a child element, to instead place the validation result in an attribute of the element, where it can be found and respected by CSS.

See

Source

toEmbed() → {string}

When embedding a copy of the Lurch app in a larger page, users will want to write simple HTML describing a Lurch document, then have a script create a copy of the Lurch app and put that document into it. We allow for representing shells using <classname>...</classname> elements, where the tag name comes from the name of the Shell subclass. The content of the tag will be the simplified HTML representation of the contents of the shell.

Returns

  • string

    the representation of the atom as a lurch element

Source

toLCs() → {Array.<LogicConcept>}

The default way to convert a Shell to LCs is to represent it as a single Environment. Subclasses may override this implementation as needed. This functionality is used by the conversion function of the whole document into LCs for validation.

Note that this does not add any of its child atoms to itself as LCs. The conversion is done by the function referenced above, which takes care to give each LC a unique ID, post-process the conversion to respect various conventions, etc.

See

  • finalize()

Returns

  • Array.<LogicConcept>

    an array containing exactly one Environment instance, representing this shell, with no children

Source

toLatex(innerLaTeX) → {string}

When exporting a Lurch document (or a portion thereof) to LaTeX format, this function determines how a Shell is represented. This is a simple default that is likely to be overridden by subclasses. It just places the contents of the shell in a LaTeX block quote, unless the class (or subclass) has defined a static member latexEnvironment, in which case it wraps it in the \\begin{X} and \\end{X} for that environment (e.g., "theorem").

Parameters

  • innerLaTeX string

    the LaTeX representation of the contents of the shell, already computed recursively

Returns

  • string

    the LaTeX representation of the shell, with the given contents included in it

Source

static

accessibles(editor, target, predicatenullable, classNamenullable) → {Array.<Node>}

For the meaning of accessibility, see isAccessibleTo(). This function returns the array of all HTML nodes that are accessible to the given target in the given editor, as long as they have the given className and satisfy the given predicate. HTML nodes that appear in dependencies and in the document header are also included. All nodes are returned in the order that they appear in the document (counting the header as earliest).

The predicate can be omitted and defaults to an accessibility check relative to the given target node. The class name can be omitted and defaults to the class name used to mark nodes as being part of the Atoms module.

Parameters

  • editor tinymce.Editor

    the editor in which to search

  • target Node

    the node to use for filtering the result list

  • predicate function <nullable>
     null

    a function that takes a node and returns true if that node should be included in the results

  • className string <nullable>

    the class name of the nodes to include

Returns

  • Array.<Node>

    the ordered array of accessible nodes satisfying all of the given criteria

Source

static

createElement(editor, subclassName)

Creating shells is not the same as creating atoms:

  • the user cannot choose to use a SPAN element to represent a shell
  • the contents of a shell remain contenteditable:true
  • the shell must have some default content, which can be replaced later

Parameters

  • editor tinymce.Editor

    the editor in which to create the shell

  • subclassName string shell

    the name of the subclass of Shell to be represented by this element (defaults to 'shell')

See

Source

static

isAccessibleTo(earlier, later, editor) → {boolean}

Accessibility of HTML nodes sitting inside a hierarchy of Shells is analogous to accessibility of MathConcept or LogicConcept instances inside their own hierarchy. The shells create the hierarchy/tree and the HTML nodes within them act as leaves of the tree.

Of course, one HTML node is not accessible to another if it comes later in the document, so this function assumes that you are asking about accessibility of an earlier node to a later node. It does not check to be sure that this is true; the client must ensure that.

It returns true if the earlier node is accessible to the later node.

Parameters

  • earlier Node

    the earlier of the two DOM nodes to compare

  • later Node

    the later of the two DOM nodes to compare

  • editor tinymce.Editor

    the editor in which these nodes sit

Returns

  • boolean

    whether the earlier node is accessible to the later node

Source

static

subclassNames() → {Array.<string>}

Find the names of all subclasses that have been registered as subclasses of this class, using the registerSubclass() method of the Atom class. This is useful for populating the dialog for changing a shell's type.

Returns

  • Array.<string>

    the names of all subclasses of Shell

Source