Home

Awesome

Eighty

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."
    )
);

Installation

Eighty is available from Nuget. API docs are hosted on my website.

Guide

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:

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());
}

How it works

Some simple tricks make this DSL's syntax work.

  1. Methods like 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.
    • Methods like p_() return an Html value directly. Same goes for self-closing tags like img
  2. You can tersely combine Html values with other objects using implicit conversions. In particular:
    • An implicit conversion from string to Html, so you can easily mix text with markup
    • An implicit conversion from TagBuilder to Html, so you don't have to call TagBuilder._() when a tag doesn't have any children.
    • An implicit conversion from (string, string) to Attr to save keystrokes when using custom attributes.
  3. _ 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.
  4. All of the tag methods were written using code generation. There are around 25,000 lines of generated code in Html!

Twenty

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.