HTMLON

HTMLON (pronounced HT-em-elon, like the, er, fruit) is a JavaScript-powered rich text editor in the vein of (but much simpler and smaller than) Tiny MCE. It doesn't really need to exist; yet it does, so here we are.

HTMLON is the editor used to write the project and blog pages on this website.

HTMLON, like many rich text editor scripts, is based on execCommand, which is now obsolete. Support for it may be removed from browsers at any time.

Examples 🔗

Example 1: A simple rich text editor with some start HTML and support for bold, italic, unordered lists, links and headings.

let instance = new HTMLON({
    container: '#editor',
    field: 'field',
    buttons: ['bold', 'italic', 'uList', 'link', 'heading'],
    html: '<p>This is some starting HTML.</p>'
});

Example 2: An editor with a custom button which inserts a picture of a dog at the current cursor when clicked. Also, editing of the HTML code is allowed.

let instance = new HTMLON({
    container: '#editor',
    field: 'field',
    buttons: ['bold', 'italic', 'uList', 'link', 'heading', 'dog'],
    allow_html_edit: 1,
    extra_buttons: {
        dog: {
            text: 'Dog',
            hint: 'Insert a dog pic',
            callback: () => {
                let doc = this.get_cntnt_doc();
                doc.execCommand('insertHTML', 0, '<img src=dog.png>');
            }
        }
    }
});

You can see a working demo over here.

API 🔗

Constructor 🔗

HTMLON is initiated by instantiating the HTMLON() constructor. It accepts a single object of params, including:

container (str; obj) - a selector or object reference pointing to an element into which the HTMLON editor will be inserted.
field (str; obj) - the name of a hidden field that will be used to store the generated HTML, or an object reference to an existing field element to use.
buttons (arr) - an array of IDs relating to buttons that should be provided in the editor e.g. bold, underline. See Buttons.
editable (bool) - whether or not the document should be editable (true; default) or merely stylable (false), without the ability to edit the content.
class (str) - an optional, space-separated list of classes to apply to the wrapper element housing HTMLON.
styleWithCSS (bool) - whether to use inline CSS styling instead of stylistic tags such as b, u tags etc default: false).
css (str; arr) - a string or array of CSS rules to be injected into the document to override default styling.
css_path (str) - a URI to an optional CSS file to load into the document to override default styling.
allow_html_edit (bool) - whether to allow the user to edit the derived HTML (default: false).
html (str) - some HTML to inject into the editor onload, rather than beginning empty.
extra_buttons (obj) - an object of custom buttons to use alongside default buttons. See Buttons.
allow_custom_col (bool) - when using colour picker buttons, whether to allow the user to enter a HEX code for a custom colour. See Buttons.
ext_links_in_new_tab (bool) - whether external links, entered via the Link button, should open in a new tab rather than the current one (default: false).
warn_on_html_mode (bool) - when allowing HTML editing (see the allow_html_edit param), whether to warn the user the first time they click the HTML button that doing so can be dangerous (default: false).

Static methods 🔗

The following methods are used to programmatically configure HTMLON.

HTMLON.add_button(name, cfg) - register a new button with HTMLON identified by the ID name (string) and configured by the object cfg. See Buttons.
HTMLON.add_palette(name, cols) - register a new palette (for use with colour picker buttons) with HTMLON identified by the name name (string) and consisting of the colours (as HEX codes) cols (array).
HTMLON.add_font(name, title) - register a new font with HTMLON identified by the name name (string) and the human-readable label title (string).

Instance methods 🔗

The following methods concern the editor's current HTML.

::commit_html() - programmatically derive HTML from the current editor contents and commit it. This saves it to the field (see field constructor param) and returns it as the method's return value.
::set_html(html) - programmatically set the contents of the editor by passing HTML as html (string).
::get_html() - return the current derived HTML from the editor.

The following methods allow you to access the inner objects and elements relating to the canvas.

::get_cntnt_doc() - get the inner contentDocument (or document, in some browsers) of the editor's iframe.
::get_body() - get a reference to the body element within the editor's iframe.
::get_head() - as with ::get_body(), but for the head element.
::get_cntnt_win() - get a reference to the inner contentWindow of the editor's iframe.
::get_el() - get a reference to the wrapper element encasing the editor.

Buttons 🔗

HTMLON supports default and also custom buttons. They are made available to a HTMLON instance by passing them in the buttons property (array) of the constructor params. See Examples.

Default buttons 🔗

The default buttons available are as follows:

"bold" - toggle bold on the selected text.
"underline" - toggle underline on the selected text.
"italic" - toggle italic on the selected text.
"sub" - toggle subscript on the selected text.
"super" - toggle superscript on the selected text.
"info" - create an boxout, useful for info, warnings etc.
"uList" - create an unordered list or apply to selected text.
"oList" - create an ordered (numbered) list or apply to selected text.
"indent" - indent the selected list item to become a sub-list item.
"unindent" - unindent the selected list item to revert to being an item of the parent list.
"heading" - create a heading element or convert the selected text to one. In the popup that appears, enter "2" (for H2) or "3" (H3), optionally followed by a comma then an ID, to give the heading element an id attribute.
"quote" - create a blockquote item or convert the selected text to be one.
"nav" - create a nav element or convert the selected text to be within one.
"link" - convert the selected text to a hyperlink. The popup will ask the HREF of the link.
"highlight" - set a highlight colour on the selected text. The popup will ask the user to choose a colour from the loaded palettes.
"col" - set a text colour on the selected text. The popup will ask the user to choose a colour from the loaded palettes.
"font" - set a font for the selected text. The popup will ask the user to choose a font from the loaded fonts.
"codeB" - create a code block or convert the selected text to one.
"iCode" - convert the selected to an inline code element.

Custom buttons 🔗

You can create custom buttons for use with HTMLON. Doing so involves two steps:

Configure the button in the extra_buttons constructor param (array).
Declare the button in the buttons constructor param (array).

See Example 2 to see a custom button in action.

A custom button takes the form of an object with the following params:

text (str) - the label to appear on the button.
hint (str) - an optional hint to appear when the user hovers over the button.
callback (func) - a function to be called when the button is clicked. Normally this function will make a call to execCommand() in the context of the inner iframe's contentDocument via the ::get_cntnt_doc() method.

Notes 🔗

As noted above, HTMLON is, like many rich text editor scripts, based on execCommand. This is now obsolete, and could be removed from browsers at any time.

Also note that HTMLON is far from perfect; the rich text editor API is, famously, shit; it's inconsistent and varies in behaviour wildly in different browsers and in different situations. HTMLON was intended as a project to tame it. It does a reasonable job, but it definitely has quirks.

Download Download from Github

Did I help you? Feel free to be amazing and buy me a coffee on Ko-fi!