Parchment is Quill's document model. It is a parallel tree structure to the DOM tree, and provides functionality useful for content editors, like Quill. A Parchment tree is made up of Blots, which mirror a DOM node counterpart. Blots can provide structure, formatting, and/or content. Attributors can also provide lightweight formatting information.
Note: You should never instantiate a Blot yourself with
new. This may prevent necessary lifecycle functionality of a Blot. Use the Registry's
create() method instead.
npm install --save parchment
See Cloning Medium with Parchment for a guide on how Quill uses Parchment its document model.
Blots are the basic building blocks of a Parchment document. Several basic implementations such as Block, Inline, and Embed are provided. In general you will want to extend one of these, instead of building from scratch. After implementation, blots need to be registered before usage.
At the very minimum a Blot must be named with a static
blotName and associated with either a
className. If a Blot is defined with both a tag and class, the class takes precedence, but the tag may be used as a fallback. Blots must also have a scope, which determine if it is inline or block.
Implementation for a Blot representing a link, which is a parent, inline scoped, and formattable.
;LinkBlot.blotName = 'link';LinkBlot.tagName = 'A';Parchment.registerLinkBlot;
Quill also provides many great example implementions in its source code.
Basic implementation of a block scoped formattable parent Blot. Formatting a block blot by default will replace the appropriate subsection of the blot.
Basic implementation of an inline scoped formattable parent Blot. Formatting an inline blot by default either wraps itself with another blot or passes the call to the approprate child.
Basic implementation of a non-text leaf blot, that is formattable. Its corresponding DOM node will often be a Void Element, but can be a Normal Element. In these cases Parchment will not manipulate or generally be aware of the element's children, and it will be important to correctly implement the blot's
position() functions to correctly work with cursors/selections.
The root parent blot of a Parchment document. It is not formattable.
Attributors are the alternative, more lightweight, way to represent formats. Their DOM counterpart is an Attribute. Like a DOM attribute's relationship to a node, Attributors are meant to belong to Blots. Calling
formats() on an Inline or Block blot will return both the format of the corresponding DOM node represents (if any) and the formats the DOM node's attributes represent (if any).
Attributors have the following interface:
Note custom attributors are instances, rather than class definitions like Blots. Similar to Blots, instead of creating from scratch, you will probably want to use existing Attributor implementations, such as the base Attributor, Class Attributor or Style Attributor.
The implementation for Attributors is surprisingly simple, and its source code may be another source of understanding.
Uses a plain attribute to represent formats.
;let Width = 'width' 'width';Parchment;let imageNode = document;Width;console; // Will print <img width="10px">WidthvalueimageNode; // Will return 10pxWidth;console; // Will print <img>
Uses a classname pattern to represent formats.
;let Align = 'align' 'blot-align';Parchment;let node = document;Align;console; // Will print <div class="blot-align-right"></div>
Uses inline styles to represent formats.
;let Align = 'align' 'text-align'whitelist: 'right' 'center' 'justify' // Having no value implies left align;Parchment;let node = document;Align;console; // Will print <div style="text-align: right;"></div>
All methods are accessible from Parchment ex.
// Creates a blot given a name or DOM node.// When given just a scope, creates blot the same name as scopecreatedomNode: Node, value?: any: Blot;createblotName: string, value?: any: Blot;createscope: Scope: Blot;// Given DOM node, find corresponding Blot.// Bubbling is useful when searching for a Embed Blot with its corresponding// DOM node's descendant nodes.finddomNode: Node, bubble: boolean = false: Blot;// Search for a Blot or Attributor// When given just a scope, finds blot with same name as scopequerytagName: string, scope: Scope = Scope.ANY: BlotClass;queryblotName: string, scope: Scope = Scope.ANY: BlotClass;querydomNode: Node, scope: Scope = Scope.ANY: BlotClass;queryscope: Scope: BlotClass;queryattributorName: string, scope: Scope = Scope.ANY: Attributor;// Register Blot class definition or Attributor instanceregisterBlotClass | Attributor;