mweiss / elm-rte-toolkit / RichText.Config.ElementDefinition

An element definition describes how to serialize/deserialize an element, as well as what content it can have.

Element definition


type alias ElementDefinition =
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:

-- Define a paragraph element
paragraph =
    elementDefinition
        { name = "paragraph"
        , group = "block"
        , contentType = textBlock [ "inline" ]
        , toHtmlNode = paragraphToHtml
        , fromHtmlNode = htmlToParagraph
        }


type alias ElementToHtml =
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.


type alias HtmlToElement =
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.

Content type


type alias ContentType =
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:

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.

Struts

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>"