Lurch web app user interface

Module

Utilities

A set of generic utility functions used in this project.

Source

Members

staticconstant

copyHTMLToClipboard

This makes a call to the Clipboard API's write() function, constructing the necessary parameters and MIME types for HTML, to write the given HTML to the clipboard. It happens asynchronously, so this function returns a promise that resolves when the operation is complete, or rejects if the operation is not allowed at the time the function is called. See the documentation linked to above for more details on how the API works.

Source

staticconstant

fullUnindent

This function inspects a string and finds the largest prefix of whitespace on each line, then removes that prefix from each line, unindenting the text maximally. Blank lines are ignored. The resulting string is returned.

Source

staticconstant

htmlToImage

Convert arbitrary HTML code to an HTML image element whose contents is the rendered version of the given HTML code. This uses the html2canvas library, imported from a CDN on the fly as needed, to accomplish this. The function is asynchronous, returning a promise that resolves to the image element on success, or rejects on failure.

Source

staticconstant

isEmbedded

Determine whether the application is in an iframe inside another window. It does this by checking to see if the window containing the application is the top-level window in the browser or not.

One can also force the app to behave like an embedded version by passing actAsEmbed=true in the query string. This function respects that as well, and classifies an app with that in its query string as embedded.

Source

staticconstant

isOnScreen

TinyMCE sometimes stores elements off screen, but still part of the document, so if we search for elements by selector, we will find them, even though they are invisible and should not be taken into account as part of the user's document content. This function checks to see if a given DOM node is really a visible, relevant part of the document or not. It does so by ensuring that no ancestor of the given node has the special TinyMCE class for off-screen copies of the user's selection, mce-offscreen-selection.

Source

staticconstant

isValidURL

This function tries to run the built-in browser URL constructor on the given text. If an error is thrown, it returns false. Otherwise it returns true.

Source

Methods

static

appURL()

Return the URL for this app. It is taken directly from the browser's navigation bar, but it excludes any query string that may be present. It will be of the form protocol://domain.name/path/to/file.html.

See

Source

static

copyWithoutPrototype(object) → {Object}

From any JavaScript object, we can create another object by first constructing a new instance of the Object prototype, then copying over all of the "own" properties from the original object (by reference). This is like the original object, but without its prototype or any other inherited data or methods. This function does that.

Parameters

  • object Object

    any JavaScript object

Returns

  • Object

    a shallow copy of the original object, but without copying its prototype information

Source

static

editorForNode(node) → {tinymce.Editor}

Given a DOM Node, find the TinyMCE editor containing it.

Parameters

  • node Node

    HTML node for which to find the editor

Returns

  • tinymce.Editor

    the editor whose document contains the given node

Source

static

escapeHTML(text) → {string}

Escape a string so that it can be safely inserted into an HTML document and still represent the plain text within the given string (not interpreting the string as HTML itself). For example, the string "x < a and a > b" should appear exactly that way in the rendered HTML, meaning that the < and > will need to be escaped so that "<a and a>" does not appear to be a tag.

Parameters

  • text string

    text to escape for insertion into HTML

See

Returns

  • string

    the same text, but with the characters "&", "<", ">", "'", and '"' replaced with character references instead

Source

static

escapeLatex(text) → {string}

Escape a string so that it can be safely inserted into a LaTeX document and still represent the plain text within the given string (not interpreting any symbols in the string as LaTeX code). All backslashes, dollar signs, octothorpes, and curly brackets in the string will be replaced with escaped versions of themselves. Although this may not be a comprehensive list of escaping needs for LaTeX, it is what is implemented here.

Parameters

  • text string

    text to escape for insertion into LaTeX

See

Returns

  • string

    the same text, but with the characters "\\", "$", "#", "{", and "}" replaced with backslash-escaped versions of themselves

Source

static

loadScript(url) → {Promise}

Create a script element to load a script from the given URL, append that script element to the page's head, and notify us (via a returned Promise) when the script completes loading successfully or fails with an error.

Example use:

loadScript( 'https://some.cdn.org/script.js' ).then( () => {
    // Run code that depends on the script having loaded.
} )

Note that if this function has already been called on this URL, so that there already is a script tag with this source, then the promise resolves immediately without doing anything first.

Parameters

  • url String

    URL of the script to load

See

Returns

  • Promise

    a promise that is resolved if the script finishes loading or rejected if the script encounters an error

Source

static

loadStylesheet(url) → {Promise}

Create a link element to load a stylesheet from the given URL, append that link element to the page's head, and notify us (via a returned Promise) when the stylesheet completes loading successfully or fails with an error.

Example use:

loadStylesheet( 'https://some.cdn.org/styles.css' ).then( () => {
    // Run code that depends on the stylesheet having loaded.
} )

Note that if this function has already been called on this URL, so that there already is a link tag with this source, then the promise resolves immediately without doing anything first.

Parameters

  • url String

    URL of the stylesheet to load

See

Returns

  • Promise

    a promise that is resolved if the stylesheet finishes loading or rejected if the loading encounters an error

Source

static

makeAbsoluteURL()

Take a relative path and convert it to an absolute URL on the same server as the current page. If the path begins with a slash, it will just have the protocol and host prepended to it. If it does not begin with a slash, it will also have the full path to the current page (minus the page name) prepended as well. If the path is already absolute, it is just returned unmodified.

See

Source

static

onlyBefore(nodes, point) → {Array.<Node>}

Given an ordered set of HTML Nodes in an array, and a node in the same document, return just the subset of nodes that appear before point. Because the given set of nodes are in order, this subset will always be an initial segment of the given array. It can be empty (if none precede point) and it can be the whole array (if all preceded point).

While this could be done with a simple array filter, that could be slow on larger arrays; this uses a binary search. Furthermore, node comparisons are a tedious process that uses an enum, so this function is simpler.

Parameters

  • nodes Array.<Node>

    ordered array of Nodes to filter

  • point Node

    the node that will determine which subset of nodes gets rerturned

Returns

  • Array.<Node>

    some initial segment of nodes, including precisely those that appear before point

Source

static

removeScriptTags(html) → {string}

The following function takes as input an string containing HTML code and removes from it all script tags, so that the code can be used safely within the app itself, knowing that no malicious code will be executed.

Parameters

  • html string

    the HTML code from which to remove script tags

Returns

  • string

    the same HTML code, but with all script tags removed

Source

static

simpleHTMLTable(…rows) → {string}

This function makes it easy to construct two-column tables of HTML content, which is something that several types of Atoms will want to do. The arguments to the function are the rows of the table, and they are treated as follows.

  • Any string is treated as the content for a row of the table spanning both columns (using colspan) and in bold font.
  • An array of strings containing just one entry is treated the same as a single string.
  • An array of two strings is treated as the contents of the two cells in the row.
  • An array of three strings is treated as two rows, first a two-cell row, and then an optional error row (only if the third entry is not falsy) that places the error message in red font in the second cell.

Example use:

simpleHTMLTable(
    'Here is the information you entered:',
    [ 'Your name:', 'Frederick the Great' ],
    [ 'Your age:', '42' ],
    [ 'Your favorite color:', color,
      !isColor(color) && 'That is not a valid color.' ]
)

Parameters

  • rows any <repeatable>

    the data representing the rows of the table to construct

Returns

  • string

    the HTML code for the table

Source

static

unescapeHTML(text) → {string}

Unescape a string so that was escaped by the escapeHTML function.

Parameters

  • text string

    text to unescape

See

Returns

  • string

    the same text, but with the characters "&", "<", ">", "'", and '"' recreated from their character references

Source