Comma DOM
Introduction
Comma DOM is the Document Object Model controlled by CommaJS. There is nothing special or different between the regular HTML DOM and Comma DOM except that elements inside the Comma DOM needs to be registered with CommaJS.
For example, to add a div to a page using Javascript you would write:
document.createElement("div");
To add a div to a CommaJS document:
BlockNode.CreateNew(_document, "div");
The reason for this is that CommaJS is a controller that manages the interaction between the nodes and the users.
Nodes in CommaJS assume a role inside the document that is independent from the tag used. For example, you may decide to have a TextNode (the CommaJS node that manages text) that uses a div tag and another TextNode that uses span. Which one to use depends only on the HTML that you need.
When designing your own plugins just focus on the HTML, CSS, and Javascript you need first. Which CommaJS node to use for each tag will become obvious.
Document and Nodes
The example above should have raised a couple of questions: what is a BlockNode and what is _document? As the name suggests, _document is an object representing the CommaJS document itself. Just like the HTML DOM, a CommaJS document is a tree of nodes. Although you can create a CommaJS node using any HTML tag, there are only three types of nodes in CommaJS:
BlockNode
InlineNode
TextNode
A TextNode is the editable unit of a CommaJS document. It can contain only editable text.
A BlockNode and an InlineNode can contain anything but editable text. The difference between an InlineNode and a BlockNode is that InlineNode is forced by CommaJS to be surrounded by TextNodes.
In the following example you can think of div as a BlockNode, span as a TextNode, and img as an InlineNode:
<div>
<span>text one</span><img src="..."><span>text two</span>
</div>
If a user deletes any content around the img tag - for example deletes 'text two' on the right - we should preserve the span element on the right (our TextNode) because the user may still need to add some content.
This is something that is completely transparent and entirely managed by CommaJS. You just have to choose the right node for your needs.
Example: Mentions
When configuring the
mentions plugin, define the
FormatMention function that will format the mention the way you want it to appear in your document.
FormatMention is defined as:
FormatMention: (entry, commaInlineNode) => { }
entry is any object you passed to the mentions plugin on search. For example, let's assume that entry is a contact defined as:
{
firstName: "Robert",
lastName: "Plant",
photo: ".../photo.jpg"
}
The second parameter, commaInlineNode, is the empty InlineNode that will contain the actual mention in the document. Let's now assume we want to format our mention as an image with the name of the contact on the right side. FormatMention would look something like this:
FormatMention: (entry, commaInlineNode) => {
let _document = commaInlineNode.document;
let contactFullName = entry.firstName + " " + entry.lastName;
let contactPhotoUrl = entry.photo;
let image = TextNode.CreateNew(_document, "img", "", undefined, [{name: "src", value: contactPhotoUrl }, {name: "class", value: "any-class-if-needed" }]);
commaInlineNode.Append(image);
let name = TextNode.CreateNew(_document, "span", contactFullName, undefined, [{name: "class", value: "any-class-if-needed" }]);
commaInlineNode.Append(name);
}
Notice that we used TextNode to create an img element. This is completely fine since the mention is contained inside an InlineNode, which is not editable. Also, img tags do not have content. In this case, TextNode just registers elements in the CommaJS document.
Let's now assume that onMouseOver, we want to change the background of the mention to red. The mentions plugin accepts as options two other functions beside FormatMention as options: OnMouseOver and OnMouseOut. This is what you would need to do:
OnMouseOver: (entry, commaInlineNode) => {
let el = commaInlineNode.domElement;
el.style.backgroundColor = "red";
},
OnMouseOut: (entry, commaInlineNode) => {
let el = commaInlineNode.domElement;
el.style.backgroundColor = "";
}
As you can see, once registered with CommaJS, you can manage nodes like normal javascript elements.
