Quill Delta to HTML Converter

Converts Quill's Delta format to XML or HTML (insert ops only) with properly nested lists. This is a c# port of the javascript version by nozer.

Quickstart

Install with package manager:

Install-Package Quill.Delta

or with nuget:

nuget install Quill.Delta

Or with dotnet:

dotnet add package Quill.Delta

Quill.Delta can also be installed from nuget.org.

Usage

using Quill.Delta;
using Newtonsoft.Json.Linq;

var deltaOps = JArray.Parse(@"[
    {insert: ""Hello\n""},
    {insert: ""This is colorful"", attributes: {color: '#f00'}}
]");
var htmlConverter = new HtmlConverter(deltaOps);
string html = htmlConverter.Convert();

var xmlConverter = new XmlConverter(deltaOps);
XmlDocument xml = xmlConverter.Convert();

Configuration

HtmlConverter and XmlConverter take an configuration options object as the second (optional) argument. The HtmlConverterOptions and XmlConverterOptions objects share the following properties:

HtmlConverter has the following extra properties:

XmlConverter has the following extra properties:

Rendering Quill Formats

You can customize the rendering of Quill formats by registering to the render events before calling the Convert() method.

There are BeforeRender and AfterRender events and they are called multiple times before and after rendering each group. A group is one of:

• continuous sets of inline elements
• a video element
• list elements
• block elements (header, code-block, blockquote, align, indent, and direction)

BeforeRender event is called with raw operation objects for you to generate and return your own html. If you return an empty value, the system will return its own generated html.

AfterRender event is called with generated xml/html for you to inspect, maybe make some changes and return your modified or original html.

Following shows the parameter formats for beforeRender event:

op object will have the following format:

{
    insert: {
        type: '', // one of 'text' | 'image' | 'video' | 'formula',
        value: '' // some string value
    },
    attributes: {
        // ... quill delta attributes
    }
}

Rendering Inline Styles

If you are rendering to HTML that you intend to include in an email, using classes and a style sheet are not recommended, as not all browsers support style sheets. Quill.Delta supports rendering inline styles instead. The easiest way to enable this is to pass the option InlineStyles: new InlineStyles().

You can customize styles by setting the properties of the InlineStyles object:

var fontDic = new Dictionary<string, string>() {
    { "serif": "font-family: Georgia, Times New Roman, serif" },
    { "monospace": "font-family: Monaco, Courier New, monospace" }
}
var sizeDic = new Dictionary<string, string>() {
      { "small": "font-size: 0.75em" },
      { "large": "font-size: 1.5em" },
      { "huge": "font-size: 2.5em" }
};
new InlineStyles {
    Font = InlineStyles.MakeLookup(fontDic),
    Size = InlineStyles.MakeLookup(sizeDic),
    Indent = (value, op) =>
    {
        int indentSize = Int32.Parse(value) * 3;
        var side = op.Attributes != null &&
            op.Attributes.Direction == DirectionType.Rtl ? "right" : "left";
        return "padding-" + side + ":" + indentSize + "em";
    },
    Direction = (value, op) =>
    {
        if (value == "rtl")
        {
            var hasAlign = op.Attributes != null && op.Attributes.Align.HasValue;
            return $"direction:rtl{(hasAlign ? "" : "; text-align:inherit")}";
        }
        return null;
    }
};

Keys to this object are the names of attributes from Quill. The values are either a simple lookup table (like in the 'font' example above) used to map values to styles, or a fn(value, op) which returns a style string.

Rendering Custom Blot Formats

You need to tell system how to render your custom blot by suppliing the CustomRenderer handler in the XmlConverterOptions or HtmlConverterOptions.

If you would like your custom blot to be rendered as a block (not inside another block or grouped as part of inlines), then add renderAsBlock: true to its attributes.

Example:

using Newtonsoft.Json.Linq;
using Quill.Delta;

var ops = JArray.Parse(@"[
    {insert: {'my-blot': {id: 2, text: 'xyz'}}, attributes: {renderAsBlock: true|false}}
]");

var opts = new HtmlConverterOptions
{
    // customOp is your custom blot op
    // contextOp is the block op that wraps this op, if any.
    // If, for example, your custom blot is located inside a list item,
    // then contextOp would provide that op.
    CustomRenderer = (DeltaInsertOp op, DeltaInsertOp contextOp)
    {
        var insert = (InsertDataCustom)op.Insert;
        if (insert.CustomType == "my-blot")
        {
            var val = (JObject)insert.Value;
            return $"<span id=\"{val["id"]}\">{val["text"]}</span>";
        }
        else
        {
            return "Unmanaged custom blot!";
        }
    }
};
var converter = new HtmlConverter(ops, opts);
string html = converter.Convert();

customOp object will have the following format:

{
    insert: {
        type: string // whatever you specified as key for insert, in above example: 'my-blot'
        value: any // value for the custom blot
    },
    attributes: {
        // ... any attributes custom blot may have
    }
}

Advanced Custom Rendering Using Grouped Ops

If you want to do the full rendering yourself, you can do so by getting the processed & grouped ops.

var groupedOps = converter.GetGroupedOps();

Each element in groupedOps array will be an instance of the following types:

BlotBlock represents custom blots with renderAsBlock:true property pair in its attributes

See above for DeltaInsertOp properties.

Local Development

Hacking on Quill.Delta is easy! To quickly get started clone the repo:

$ git clone https://github.com/blushingpenguin/Quill.Delta.git
$ cd Quill.Delta

To compile the code and run the tests just open the solution in Visual Studio 2017 Community Edition. To generate a code coverage report run cover.bat from the solution directory.