unfoldingword/epitelete-html

Epitelete taken a step forward to generate and parse Html.

epitelete-html

Epitelete sub-class for HTML handling.

Installation

npm install epitelete-html

Usage

import EpiteleteHtml from 'epitelete-html';
// Instantiate Proskomma and load some content into it
const epiPerfHtml= new EpiteleteHtml({proskomma: proskommaInstance, docSetId: "doc_set_id"});
const epiPerfHtml= new EpiteleteHtml({proskomma: proskommaInstance, docSetId: "doc_set_id", options: {historySize: 10}});

Html handling

const htmlContainer = await epiPerfHtml.readHtml(bookCode); // => Object { docSetId, mainSequenceId, headers, sequencesHtml };
const { sequencesHtml } = htmlContainer; //Object containing html sequences { [sequenceId] : '<sequence html>'}
//Make changes to sequences html and merge them back to htmlContainer
...
//write back the changed htmlContainer
await epiPerfHtml.writeHtml(bookCode, sequenceId, changedHtmlContainer);
...
// undo
await epiPerfHtml.undoHtml(bookCode);
...
// redo
await epiPerfHtml.redoHtml(bookCode);

Inherited functionality

epiPerfHtml.localBookCodes()   // => Array of 3-character book codes cached in Epitelete
epiPerfHtml.bookHeaders()      // => Object containing titles and other headers for each bookCode in Proskomma
epiPerfHtml.readPerf(bookCode) // => PERF for this bookCode, fetching from Proskomma if necessary
epiPerfHtml.clearPerf()        // Deletes all local PERF data

epitelete-html's Issues

Document: customizing the resulting HTML

Per @abelpz :

The epitelete-html walks the perf object for parsing it, and there is a prop called htmlMap that let the user hook into that parsing process to add their own html tag names and attributes, basically to customize the resulting html, but they needed to be able to store some context to save things like previously parsed chapter, verse, etc.

This should be added to the docs to explain how this can be done.

A schema needs to be designed so the element IDs can be generated. This would allow developers to find text blocks more easily. Autographa is doing something similar.

Split error

See marked up snippet.

html2perf

Input

The HTML produced by the Simple Text Editor (which should have the same format as the HTML given to it by this class). That HTML is really a transliteration of the underlying PERF.

Output

Schema-valid PERF for the modified sequence

Usage

This method should eventually be used to implement writeHTML which will pass most of the work to writePerf which the class inherits.

How to do it

I'm assuming that we're going to turn the HTML fragment into DOM. There are lots of DOM parsers out there, but https://www.npmjs.com/package/node-html-parser looks interesting to me because it's popular, maintained and because it can give us a JSON representation of the HTML without actually doing any DOM.

So at that point we're converting one format of JSON into another format of JSON, which typically involves lots of mapping. In most cases the levels of HTML should follow the levels of PERF so this ought to be relatively clean.

We'll need to validate the PERF, at least in the unit tests and during development. The validator is at https://www.npmjs.com/package/proskomma-json-validator

Use superclass PERF validator

See Proskomma/epitelete#20