what_is_substance.md

What is Substance?

Substance is a library for creating web-based WYSIWIG editors. With all the features you would expect from a WYSIWIG editor.

As opposed to other existing editors, such as TinyMCE, Aloha, etc. Substance is not just a widget you include into your web-application. It is a library. Widgets are just not enough. They lead to a bad UX. They are like alien isles within the web-app. And those are very limited regarding customization.

The unique point of Substance: Customizability. You can customize everything. And we try to make this as simple as possible for you.

It begins with the data. For instance, a scientific article is more complex than a blog post Still there is some similarity. Both of them have paragraphs, for instance. In Substance you define a schema, containing a set of Node descriptions.

var Figure = BlockNode.extend();

Figure.static.name = "figure";

Figure.static.defineSchema({
  "title": "text",
  "img": "src",
  "caption": "text"
});

The next thing: Data conversion. Probably you are already using a certain data format, XML files or HTML. With Substance you can create your own converter very easily:

  type: 'figure',
  tagName: 'figure',

  import: function(el, node, converter) {
    var title = el.find('.title');
    var img = el.find('img');
    var figcaption = el.find('figcaption');

    node.title = converter.annotatedText(title, [node.id, 'title']);
    node.img = img.attr('src');
    node.caption = converter.annotatedText(figcaption, [node.id, 'caption']);
  },

  export: function(node, el, converter) {
    // title
    el.append($$('h1').addClass('title').append(
      converter.annotatedText([node.id, 'title']))
    );
    // image
    el.append($$('img').attr('src', node.src);
    // caption
    el.append($$('figcaption').append(
      converter.annotatedText([node.id, 'caption']))
    );
    return el;
  }

You can customize many more things: how things get rendered, toolbars, adding tools, defining keybindings, macros... Everything.

Find out more about Substance on substance.io