DOM

Provides a domain specific language for representing HTML documents.

Examples

using Documenter.Utilities.DOM

# `DOM` does not export any HTML tags. Define the ones we actually need.
@tags div p em strong ul li

div(
    p("This ", em("is"), " a ", strong("paragraph."),
    p("And this is ", strong("another"), " one"),
    ul(
        li("and"),
        li("an"),
        li("unordered"),
        li("list")
    )
)

Notes

All the arguments passed to a node are flattened into a single vector rather than preserving any nested structure. This means that passing two vectors of nodes to a div will result in a div node with a single vector of children (the concatenation of the two vectors) rather than two vector children. The only arguments that are not flattened are nested nodes.

String arguments are automatically converted into text nodes. Text nodes do not have any children or attributes and when displayed the string is escaped using escapehtml.

Attributes

As well as plain nodes shown in the previous example, nodes can have attributes added to them using the following syntax.

div[".my-class"](
    img[:src => "foo.jpg"],
    input["#my-id", :disabled]
)

In the above example we add a class = "my-class" attribute to the div node, a src = "foo.jpg" to the img, and id = "my-id" disabled attributes to the input node.

The following syntax is supported within [...]:

tag["#id"]
tag[".class"]
tag[".class#id"]
tag[:disabled]
tag[:src => "foo.jpg"]
# ... or any combination of the above arguments.

Internal Representation

The @tags macro defines named Tag objects as follows

@tags div p em strong

expands to

const div, p, em, strong = Tag(:div), Tag(:p), Tag(:em), Tag(:strong)

These Tag objects are lightweight representations of empty HTML elements without any attributes and cannot be used to represent a complete document. To create an actual tree of HTML elements that can be rendered we need to add some attributes and/or child elements using getindex or call syntax. Applying either to a Tag object will construct a new Node object.

tag(...)      # No attributes.
tag[...]      # No children.
tag[...](...) # Has both attributes and children.

All three of the above syntaxes return a new Node object. Printing of Node objects is defined using the standard Julia display functions, so only needs a call to print to print out a valid HTML document with all nessesary text escaped.

Define a collection of Tag objects and bind them to constants with the same names.

Examples

Defined globally within a module:

@tags div ul li

Defined within the scope of a function to avoid cluttering the global namespace:

function template(args...)
    @tags div ul li
    # ...
end

A HTML node that wraps around the root node of the document and adds a DOCTYPE to it.

Represents an element within an HTML document including any textual content, children Nodes, and attributes.

This type should not be constructed directly, but instead via (...) and [...] applied to a Tag or another Node object.

Represents a empty and attribute-less HTML element.

Use @tags to define instances of this type rather than manually creating them via Tag(:tagname).

Escape characters in the provided string. This converts the following characters:

• < to <
• > to >
• & to &
• ' to '
• " to "

When no escaping is needed then the same object is returned, otherwise a new string is constructed with the characters escaped. The returned object should always be treated as an immutable copy and compared using == rather than ===.

Signatures

flatten!(f!, out, x::Atom)
flatten!(f!, out, xs)

Flatten the contents the third argument into the second after applying the function f! to the element.