Enhance documentation of modifyBlocks

[philippfrank]

@neilj, Squire is by far the most elegant, clean and flexible RTE I have worked with. The documentation though needs some examples and guides, especially on extending Squire. I'll be happy to open a PR for that, since I did some really heavy integration work and can provide several howtos:

One thing I am trying to figure out is how to remove entire block formats, in other words realizing "make headline" and "unmake headline". I managed to wrap the selection into a bock tag. Could you provide an example of removing a tag from a fragment:

// Triggered on click on the "Headline"-Button
function toggleHeading(editor, tagName = "h1") {
  if (editor.hasFormat(tagName)) {
    editor.modifyBlocks(frag => removeTag(editor, frag, tagName));
  } else {
    editor.modifyBlocks(frag => wrapInTag(editor, frag, tagName));
  }
}

function wrapInTag(editor, frag, tagName) {
  const output = editor._doc.createDocumentFragment();
  let block = Squire.getNextBlock(frag);

  while (block) {
    output.appendChild(editor.createElement(tagName, [Squire.empty(block)]));
    block = Squire.getNextBlock(block);
  }

  return output;
}

function removeTag(editor, frag, tag) {
  // How to remove the tag from frag?

  return frag;
}

[neilj]

More/better documentation would be great! Also happy to replace the demo if you want to do a better one with your integration.

Regarding your question, I would do this:

Squire.prototype.changeBlockType = function ( tag, attrs ) {
    if ( !tag ) {
        var config = this._config;
        tag = config.blockTag;
        attrs = config.blockAttributes;
    }
    return this.modifyBlocks( function ( frag ) {
        var walker = Squire.getBlockWalker( frag, this._root );
        var output = this.getDocument().createDocumentFragment();
        var node;
        while ( node = walker.nextNode() ) {
            output.appendChild( this.createElement( tag, attrs, [
                Squire.empty( node )
            ]));
        }
        return output;
    });
};

Then to "make heading", call something like editor.changeBlockType( 'h1' ) and to revert to the default block type (normal paragraph style) just call editor.changeBlockType().

[philippfrank]

That works perfectly, thanks! I'll gebt back to you regarding the docs and demo.

[jcupps]

@neilj Your example of using modifyBlocks is really helpful. Is there any reason the changeBlockType function shouldn't be added to core, especially since toggling headers (and other block-level elements like <p> and <blockquote>) is such a common feature for RTEs?

[tv42]

For anyone stumbling here in some 6 years later, this seems to do the trick for making headings with Squire v2.0.2:

  function toggleBlockType(tag: string) {
    editor.modifyBlocks(function (frag): Node {
      if (frag.children.length != 1) {
        return frag;
      }
      const orig = frag.firstElementChild;
      if (orig === null) {
        return frag;
      }

      const tagName = orig.tagName == tag ? "DIV" : tag;
      const elem = frag.ownerDocument.createElement(tagName);
      while (orig.firstChild !== null) {
        elem.append(orig.firstChild);
      }
      return elem;
    });
  }

For Svelte, you do something like

    <button class="button" on:click={() => toggleBlockType("H1")}>H1</button>