demarcate.js 2.0

A WYSIWYG Markdown Editor from Will Hart

demarcate.js is an MIT licensed, javascript library for editing web pages "in place" and genearting Markdown from the resulting HTML.

This documentation is for developers and describes how to install and utilise demarcate.js.

Note that there were some API changes in version 2.0. If you are upgrading from 1.1.4 or earlier please review the documentation carefully.

  • Installation: the files you need to include to install demarcate.js in your web page.

  • Methods: the methods demarcate.js exposes.

  • Events: the events demarcate.js exposes.

  • Styling: how to override the deault editor styles.

  • Deployment: how to rebuild the minified docs.

 

Installation

To install textr in a web page you need to include one CSS file (demarcate.min.css) and one javascript file (demarcate.min.js). demarcate.js has one optional dependency (keymaster.js can be used for shortcut keys). 

<!-- Optionally include keys.js BEFORE demarcate - https://github.com/madrobby/keymaster -->
<script src="js/keys.min.js" type="text/javascript"></script>

<!-- include demarcate like this: -->
<link rel="stylesheet" href="css/demarcate.min.css">
<script src="js/demarcate.min.js" type="text/javascript"></script>

Methods

demarcate.js setups and tears down editors using two main methods - enable() and disable(). Only one editor can be active at any once.

A third method, parse() is used to retrieve the HTML from a given element.

 

demarcate.parse

Since v2.0

Takes the given DOM element and converts the HTML to Markdown. The given element does not have to be the demarcate editor.

If no element is provided, the Markdown from the current editor will be returned.

Params
elem DOM element The top level DOM object you want to edit with demarcate.js 
// get the Markdown from the current editor
demarcate.parse();

demarcate.disable

Since v1.1.3

disables the demarcate.js editor, unbinding all event handlers and removing all demarcate.js css classes. Allows toggling of editing on and off. 

// Disables the current demarcate editor
demarcate.disable();

demarcate.enable

Since v1.1.3

take a DOM element and set it up for demarcate editing.

Params
elem DOM element The top level DOM object you want to edit with demarcate.js 
demarcate.enable($("#dom_to_edit");

demarcate.isEnabled

Since v1.1.4

Helps determine if demarcate.js is "enabled" meaning that it is set up for blocks to be clicked on and edited. Calling demarcate.enable() sets this state to true.

Return
boolean true if currently enabled for editing, false otherwise 
// for instance
if (demarcate.isEnabled()) {
    demarcate.disable();
}

demarcate.demarcate

Since v1.0
Deprecated v2.0
Removed in future release

Takes the given jQuery DOM element and converts the HTML to Markdown. The given element does not have to be the demarcate editor.

If no element is provided, the Markdown from the current editor will be returned.

Params
elem jQuery object The top level DOM object you want to edit with demarcate.js 
// DEPRECATED - use demarcate.parse() instead

// get the Markdown from the current editor
// demarcate.demarcate()

// get the Markdown for any element
// demarcate($("#any_element"));
// $("#any_element").demarcate();

demarcate.isActive

Since v1.1.4
Deprecated v2.0
Removed in future release

Helps determine if demarcate.js is currently editing a block.

Return
boolean true if currently editing a block, false otherwise 
// DEPRECATED AND REMOVED IN VERSION 2.0
// for instance
//if (demarcate.isActive()) {
//    demarcate.save();
//}

Events

demarcate.js triggers several events to allow your web page to respond to actions made by the user or editor. You can bind to these events using either native javascript, or through a library such as jQuery.

jQuery examples are provided below for simplicity, however you can also use the native addEventListener approach to bind to all these events.

Note 1: in version 2.0 event names were changed from underscore to camel case convention.

Note 2: custom event support in Internet Explorer ranges between totally broken and terrible. NO demarcate events are thrown in Internet Explorer.

 

demarcateEditorClosed

Since v1.0

Triggered when an editor is closed.

Raised When
An editor is closed
Provides
event.detail.editor DOM element The editor DOM element 
// bind to the editor closed event and push the resulting Markdown to a server
$(document).on('demarcateEditorClosed', function(e) {
    // use 'e.detail.editor' to access the DOM element, or just use the helper methods:
    var op = demarcate.parse();
    ajax_request_to_server(op);
});

demarcateEditorEnabled

Since v1.0

Triggered when an editor is enabled using demarcate.enable()

Raised When
An DOM element is enabled for demarcate.js editing 
// bind to the editor enabled event and push the resulting Markdown to a server
$(document).on('demarcateEditorEnabled', function(e) {
    // use 'e.detail.editor' to access the DOM element, or just use the helper methods:
    var op = demarcate.parse();
    ajax_request_to_server(op);
});

demarcateEditorUpdated

Since v1.0

Triggered when an editor has changes made. This triggers either after five seconds once a change has been made or after 10 changes (i.e. keypresses, mouse clicks, etc).

Raised When
The editor becomes "dirty" i.e. has changed. 
// bind to the editor updated event and push the resulting Markdown to a server
$(document).on('demarcateEditorUpdated', function(e) {
    // use 'e.detail.editor' to access the DOM element, or just use the helper methods:
    var op = demarcate.parse();
    ajax_request_to_server(op);
});

Styling

demarcate.js uses a stylesheet for editor styles. It uses two main classes for displaying the menu:

  • .demarcate-menu
  • .demarcate-menu-button

To customise the menu placement and style simply override these styles in a CSS stylesheet.

All other styles (e.g. typography and layout) are taken from the CSS stylesheets of your web page.