whatxml
v1.4.0
Published
Construct XML (or (X)HTML) with LiveScript function calls
Downloads
7
Maintainers
anReadme
whatxml
XML/HTML templating with LiveScript's cascade syntax.
"What XML?" None, ever again.
x = whatxml \html
.. \head
.. \title ._ "My page"
..self-closing \link rel : \stylesheet type : \text/css href : \main.css
.. \body
.. \p ._ (.content)
console.log x.to-string { content : "Here's a paragraph." }→
<html><head><title>My page</title><link rel="stylesheet" type="text/css" href="main.css" /></head><body><p>Here's a paragraph.</p></body></html>API summary
.. <string> [<attr-object>]adds a tag (with optional attributes)..self-closing <string> [<attr-object>]same, but a self-closing tag.. <object>sets attributes.._ <string>adds text..raw <string>adds text (without escaping it)..comment <string>adds a comment
to-string recursively renders that tag's tree.
Any of the setters can also take a function parameter which is called with the
value passed to to-string. It is expected to return the value that should be
inserted at that point. (See § Templating.)
API tutorial
Basics
Create a root tag, call it with a string to create child tags, with
an object to add attributes or call _ to add text between the tags.
gandalf = whatxml \person # Create a root tag.
.. { profession : \wizard } # Set an attribute.
.. \name # Add a child node.
.._ "Gandalf" # Put text in it.
console.log gandalf.to-string!<person profession="wizard"><name>Gandalf</name></person>Handy shortcut: When creating a tag, pass attributes as an object.
t = whatxml \tower lean : "3.99"
.. \place city : "Pisa", country : "Italy"
console.log t.to-string!<tower lean="3.99"><place city="Pisa" country="Italy"></place></tower>Add self-closing tags and comments.
x = whatxml \a
..self-closing \b
..comment "what"
console.log x.to-string!<a><b /><!--what--></a>You can have stand-alone attributes without a value by setting them to
true. (It's invalid XML, but fine in HTML.)
whatxml \input { +selected }
..to-string! |> console.log<input selected></input>Setting an attribute to another value overwrites the previous value. Setting
attributes to false, null or undefined removes that attribute, if
present.
Text is escaped automatically, but you can bypass that with raw if
you have ready-escaped text (e.g. from marked).
greeting = whatxml \p
.._ "What's up <3"
console.log greeting.to-string!
x = whatxml \p
..raw "<em>I know this is > properly escaped already</em>"
console.log x.to-string!<p>What's up <3</p>
<p><em>I know this is > properly escaped already</em></p>You can also have multiple top-level tags:
x = whatxml!
.. \a
.. \b
console.log x.to-string!<a></a><b></b>Templating
To generate content based on data, you can pass a function to any setter
call. When a tag's to-string is called, the functions passed to its setters
before are called with its arguments to produce the final value.
link = whatxml \a href : (.href)
.._ (.name.to-upper-case!)
console.log link.to-string name : \google href : "https://google.com"
console.log link.to-string name : \runescape href : "http://runescape.com"<a href="https://google.com">GOOGLE</a>
<a href="http://runescape.com">RUNESCAPE</a>Limitations
Check your XML comments are valid by the XML spec: They may not contain
two consecutive hyphens (--). Whatxml doesn't check for you.
CDATA-sections and XML declarations (<?xml version="1.0"?> and such)
aren't explicitly supported, but you can happily add them using raw.
Related libraries
Whatxml aims to be a serious general-purpose XML/HTML templating engine for LiveScript's syntax.
Existing attempts have their flaws:
live-templcame closest to my goals, but objects in nested arrays cannot represent comments, raw text data or self-closing tags. It also has no templating.create-xml-lsis based on nested objects, so it can't represent two tags with the same name on the same level of nesting…htmlssupports only the base HTML tag set. Templating code is stringly typed and compiled separately.