An element definition describes how to serialize/deserialize an element, as well as what content it can have.
RichText.Internal.Definitions.ElementDefinition
A ElementDefinition
contains information on how to serialize/deserialize an editor node,
as well as describes what type of node and what children the node can have.
elementDefinition : { name : String, group : String, contentType : ContentType, toHtmlNode : ElementToHtml, fromHtmlNode : HtmlToElement, selectable : Basics.Bool } -> ElementDefinition
Defines an element. The arguments are as follows:
name
is the unique name of this type of node, usually something like "paragraph" or "heading"
group
is the group this element belongs to. Commonly, this value will be 'block' or 'inline'
This is used when validating the document and can be useful if you're defining complicated block structures
like a table or list. For example, for a markdown list, there is a 'list_item' group, and ordered lists
and unordered lists only accept children that are part of the 'list_item' group. The root
node must be of group 'root'.
contentType
describes what type of node this is, namely a block with block children, a block leaf,
a block with inline children, or an inline leaf element.
toHtmlNode
converts an element into html. This is used when rendering the document
as well as path translation and DOM validation logic.
fromHtmlNode
converts html to an element. Currently, this is only used for paste
event, but could potentially be used more generally in the future to interpret content editable
changes.
-- Define a paragraph element
paragraph =
elementDefinition
{ name = "paragraph"
, group = "block"
, contentType = textBlock [ "inline" ]
, toHtmlNode = paragraphToHtml
, fromHtmlNode = htmlToParagraph
}
RichText.Model.Element.Element -> Array RichText.Model.HtmlNode.HtmlNode -> RichText.Model.HtmlNode.HtmlNode
Type alias for defining an element serialization function.
paragraphToHtml : ElementToHtml
paragraphToHtml _ children =
ElementNode "p" [] children
Note that when defining serialization functions, children should NOT be modified in any way, otherwise it will potentially break the selection and rendering logic. This is because we pass in a placeholder to partially serialize a document in some parts of the package.
ElementDefinition -> RichText.Model.HtmlNode.HtmlNode -> Maybe ( RichText.Model.Element.Element
, Array RichText.Model.HtmlNode.HtmlNode
}
Type alias for defining an element deserialization function.
htmlToParagraph : HtmlToElement
htmlToParagraph definition node =
case node of
ElementNode name _ children ->
if name == "p" then
Just <| ( element definition [], children )
else
Nothing
_ ->
Nothing
name : ElementDefinition -> String
The name of the node this element definition defines.
name paragraph
--> "paragraph"
group : ElementDefinition -> String
The group this node belongs to
group paragraph
--> "inline"
contentType : ElementDefinition -> ContentType
Describes what type of node this is and what children it can have.
fromHtmlNode : ElementDefinition -> HtmlToElement
The deserialization function for this node. This is used for things like a paste event to derive editor nodes from HTML content.
toHtmlNode : ElementDefinition -> ElementToHtml
The serialization function for this node. This should be called internally by the editor code to determine selection, render the editor, and validate the DOM.
RichText.Internal.Definitions.ContentType
Describes what type of node can have this element, as well as what children the node can contain. It can be one of four values:
inlineLeaf
: An inline element, like an inline image or hard break.blockLeaf
: A block which does not allow children, like a horizontal rule.blockNode
: A block with block children, like a blockquote, list, or table.textBlock
: A block with inline children, like a paragraph or heading.blockLeaf : ContentType
A block leaf is a Block that does not allow child nodes, like a horizontal rule.
inlineLeaf : ContentType
An inline leaf is an InlineElement like an image or a breaking line.
blockNode : List String -> ContentType
A block node is a Block that has other block children, like a blockquote or list. The argument is the group or name of the nodes that it allows as children.
blockNode [ "list_item" ]
--> A content type for a node that only accepts child nodes who are blocks and whose is name or group is list_items.
textBlock : { allowedGroups : List String, allowedMarks : List String } -> ContentType
A text block node is a Block that has inline children, like a header or paragraph.
allowedGroups
the group or name of the nodes that it allows as children. If a list is empty, then
all groups are allowed.
allowedMarks
the name of the marks that this textblock allows. If a list is empty, then
all marks are allowed.
textBlock {allowedGroups: [ "inline" ], allowedMarks: []} --> A content type for a node that only accepts child nodes who are in the "inline" group and allows all marks
defaultElementDefinition : String -> String -> ContentType -> ElementDefinition
Creates an element definition which assumes the name of the editor node is the same as the name of the html node.
defaultElementDefinition "p" "block" (textBlock [])
--> definition which encodes to <p>...</p> and decodes from "<p>...</p>"
defaultElementToHtml : String -> RichText.Model.Element.Element -> Array RichText.Model.HtmlNode.HtmlNode -> RichText.Model.HtmlNode.HtmlNode
Creates an ElementToHtml
function that will encode a node to the tag specified. Any
string attributes are converted to attributes on the node
defaultElementToHtml "p"
--> returns a function which encodes to "<p>...</p>"
defaultHtmlToElement : String -> ElementDefinition -> RichText.Model.HtmlNode.HtmlNode -> Maybe ( RichText.Model.Element.Element, Array RichText.Model.HtmlNode.HtmlNode )
Creates an HtmlToElement
function that will decode a node from tag specified.
defaultHtmlToElement "p"
--> returns a function which decodes from "<p>...</p>"