A fast HTML generation library
Eighty (as in eigh-ty-M-L) is a simple HTML generation library. It's an embedded domain-specific language, allowing you to write C# code which roughly resembles HTML. Programming with Eighty is just programming: HTML is represented as ordinary immutable C# values which can be passed around as usual. This makes for an approachable alternative to Razor when you don't need the complexity of a whole templating language. It's a great fit for simple web apps or command-line tools like report generators.
var html = article(@class: "readme")._(
h1(id: "Eighty")._("Eighty"),
p_(
"Eighty (as in ",
i_("eigh-ty-M-L"),
") is a simple HTML generation library."
)
);
Eighty is available from Nuget. API docs are hosted on my website.
You can read an intro to Eighty's programming model on my personal website.
Almost all of Eighty's API lives in the Html
class, which is designed to be imported with using static
. (I like to additionally import it under an alias, to minimise line noise when you need to disambiguate something.)
using Eighty;
using static Eighty.Html;
using H = Eighty.Html;
Eighty's domain-specific language adopts the following conventions:
p()
and i()
.h1(@class: "foo")
disabled
take a bool
as their argument, not a string
. button(disabled: true)
produces <button disabled></button>
Attr.Raw
factory method if you don't want this.Attr
yourself: div(("data-example", "example"), new Attr("class", "bar"))
.new Attr
and Attr.Raw
._
symbol means here are the children. _
can appear in a few places:
div_(span(), img())
creates a div
containing a span
and an img
.div(@class: "container")._(span(), img())
creates a div
with a class container
, with a span
and an img
inside it. Note that this means p()._(...)
is equivalent to p_(...)
.Html
). This just groups together siblings. _(span(), img())
creates a span
and an img
next to each other at the top level._
with self-closing tags like img
. It doesn't have a _
method or an img_
variant.p_("text<>")
will produce <p>text<></p>
.
Raw
method.Html
values are immutable and can be passed around as normal C# values, including being shared between different HTML documents. (Sharing as much of a tree as you can is often important for efficiency!)To render your Html
, use its Write
or WriteAsync
methods. (If you just want it as a string, you can call ToString()
.)
using (var writer = new StringWriter())
{
html.Write(writer);
Console.WriteLine(writer.ToString());
}
Some simple tricks make this DSL's syntax work.
p()
return a TagBuilder
object, which defines the _
method. A TagBuilder
represents an HTML tag which is waiting for its children. Calling _
assembles the tag and its children into an Html
value.
p_()
return an Html
value directly. Same goes for self-closing tags like img
Html
values with other objects using implicit conversions. In particular:
string
to Html
, so you can easily mix text with markupTagBuilder
to Html
, so you don't have to call TagBuilder._()
when a tag doesn't have any children.(string, string)
to Attr
to save keystrokes when using custom attributes._
methods are declared to take params Html[] children
. You can give a tag an arbitrary number of children, and the implicit conversions coerce each child to Html
automatically.Html
!Eighty comes bundled with a second HTML generation library called Twenty. Twenty is very fast (at least 5-10x faster than both Eighty and Razor in most cases) and generates no garbage, but it has a noisier syntax and is easier to misuse than Eighty. (It also can't be used with async
.) Twenty is a good fit when you need to render HTML really fast, but you don't want to template strings or build tags by hand. I recommend starting with Eighty, and switching to Twenty if you're sure you need the extra speed.
Twenty takes an imperative view of HTML generation, wherein HTML is written directly to the output stream. (That's why it's fast.) The balancing of tags is managed by using
statements.
To use Twenty, subclass HtmlBuilder
. This brings the various tag methods into scope, for use in Build
. You must put the (non-self-closing) tags in using
statements:
using Eighty.Twenty;
class MyHtmlBuilder : HtmlBuilder
{
protected override void Build()
{
using (article(@class: "readme"))
{
using (h1(id: "Eighty"))
Text("Eighty");
using (p())
{
Text("Eighty (as in ");
using (i())
Text("eigh-ty-M-L");
Text(") is a simple HTML generation library.");
}
}
}
}
The tag methods like div
write the opening tag to the output stream and then return an IDisposable
which writes the closing tag in its Dispose
method. It's therefore imperative (ha ha) that you don't accidentally miss out a using
statement, as that would result in a half-closed tag! You should also avoid calling Dispose
more than once.
It also means that HtmlBuilder
is not thread-safe; instances of HtmlBuilder
can only be safely accessed from one thread at a time. And it doesn't support async
, because there's no way to implement Dispose
asynchronously.