Bliss.Html.Core 0.4.0

Bliss.Html.Core

This library provides a simple abstraction for authoring reusable HTML components in C#.

Example

The following example demonstrates how to create a simple button component by inheriting from the HtmlElement class.

using Bliss.Html.Core;

public class BootstrapBtn : HtmlElement
{
    public BootstrapBtn(string text) : base("button", kids: new Kids { text })
    {
        Attrs.Add("class", "btn btn-primary");
    }
}

// we can create a new instance of our button component
var btn = new BootstrapBtn("Click me");

// when rendered, this will produce the following HTML string: 
// => <button class="btn btn-primary">Click me</button>

This is a slightly more complex example that demonstrates how to create a simple card component.

public class BootstrapCard : HtmlElement
{
    public BootstrapCard(string title, string body) : base("div")
    {
        Kids.Add(new HtmlElement("h5", 
            kids: new Kids { title }));
        Kids.Add(new HtmlElement("p", 
            kids: new Kids { body }));
        
        Attrs.Add("class", "card");
    }
}

// we can create a new instance of our card component
var card = new BootstrapCard("Card title", "Some quick example text to build on the card title and make up the bulk of the card's content.");

// when rendered, this will produce the following HTML string:
// => <div class="card">
//      <h5>Card title</h5>
//      <p>Some quick example text to build on the card title and make up the bulk of the card's content.</p>
//    </div>

You can also use the HtmlElement class directly for "one-off" components, like so:

var card = new HtmlElement("div", 
    attrs: new Attrs 
    { 
        { "class", "card" } 
    },
    kids: new Kids
    {
        new HtmlElement("h5", kids: new Kids { "Card title" }),
        new HtmlElement("p", kids: new Kids { "Some quick example text to build on the card title and make up the bulk of the card's content." })
    });

Rendering

Any IElement instance can be rendered to a string using the built-in BlissStringWriter class, which provides an implementation of the IWriter<string> interface:

var heading = new HtmlElement("h1", kids: new Kids { "Hello, world!" });

var writer = new BlissStringWriter();
card.WriteTo(writer);
var html = writer.ToString();

// the value of `html` will be:
// => <h1>Hello, world!</h1>

This method will be most useful when rendering a component for an email template, or for an HTML report, but this library provides most value when integrated with it's sister library, Bliss.Html.AspNetCore, which provides various integrations for working with ASP.NET Core (MVC, Razor Pages, etc.).

For example, instances of IElement can be returned directly from an ASP.NET Core controller action, by returning an instance of BlissResult:

using Bliss.Html.AspNetCore;

[Route("/")]
public class HomeController : Controller
{
    [HttpGet]
    public IActionResult Index()
    {
        var heading = new HtmlElement("h1", kids: new Kids { "Hello, world!" });
        return new BlissResult(heading);
    }
}

This will render the IElement as an HTML string to the response body, and set the Content-Type header to text/html.

Bliss.Html.AspNetCore also provides an extension method on the IHtmlHelper interface called Zap(IElement), which allows consumers to inject IElement instances directly into their Razor views:

@using Bliss.Html.AspNetCore

<h1>Hello, world!</h1>
@await Html.Zap(new BootstrapBtn("Click Me"))

Installation

This library is available as a NuGet package, which can be installed using the following command:

dotnet add package Bliss.Html.Core