DigitalPublications.Episerver 1.0.6

Digital Publications

Digital Publications is a .NET library for converting documents to JSON, HTML and PDF.

Licensing

This package requires a valid license, which can be purchasable by contacting HiQ. The license should preferably be placed in the root folder of the project, and be named digipub_episerver_license.xml.

Usage

1. Create a new instance of the DigitalPublications class and include a path to a valid license as an argument to the constructor.
2. Call its function ParseDocument to convert a document and place the output JSON-file in a target directory. Parameters are: path to document to convert, byte array of the document to convert, destination folder name, destination folder name (needs to be unique, so file ID is a good idea). The returned value is of the data type ParsedDocument, which is easily used to generate the HTML in your views.
3. Use the returned ParsedDocument object in your views to build your HTML.

Below is an example of how to implement a basic backend and frontend in Episerver:

Example Backend:

public ActionResult Index(DigiPubTestPage currentPage, int page = 1)
{
    var file = currentPage.Document;
    var filePath = _urlResolver.GetUrl(file);
    MediaData media;
    byte[] blobBytes = { };

    if (_contentLoader.TryGet(file, out media))
    {
        blobBytes = _blobFactory.GetBlob(media.BinaryData.ID).ReadAllBytes();
    }

            

    string licensePath = Path.Combine(Path.GetDirectoryName(AppDomain.CurrentDomain.BaseDirectory), @"digipub_episerver_license.xml");

    var DP = new DocumentParser(licensePath);
    var parsedDocument = DP.Parse(filePath, blobBytes, "digipub", file.ID.ToString());

    if (parsedDocument == null)
    {
        return View(new DigiPubTestPageViewModel(currentPage)); 
    }

    var sourcePath = "/digipub/" + file.ID;
    var pdfPath = sourcePath + "/" + Path.GetFileNameWithoutExtension(filePath) + ".pdf";

    var model = new DigiPubTestPageViewModel(currentPage)
    {
        ParsedDocument = parsedDocument,
        SourcePath = sourcePath,
        PDFPath = pdfPath
    };

    return View(model);
}

Example Frontend:

@using EpiserverTestSiteAlloy
@model DigiPubTestPageViewModel
@{
    var tocPageCounter = 1;
}

@if (Model.ParsedDocument != null)
{
    <div class="digipub TOC-enabled">
        <div class="digipub-summary">
            <div class="digipub-introduction">
                <h1 class="digipub-introduction-heading">
                    Introduktionstext
                </h1>
                <p>
                    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
                </p>
            </div>
            <div class="digipub-document-information">
                <h2 class="digipub-document-information-heading">Dokumentinformation</h2>
                <p>Typ av publikation: Goda råd</p>
                <p>Publicerade: 2019</p>
                <p>Avsändare: Försäkringsavdelningen</p>
                <p>Antal sidor vid utskrift: 9</p>
                <div class="digipub-document-information-buttons">
                    <a class="create-pdf" href="@Model.PDFPath" target="_blank">Skapa PDF</a>
                    <a class="print" href="javascript:var pdfWindow = window.open('@Html.Raw(Model.PDFPath)');pdfWindow.print();">Skriv ut</a>
                </div>
            </div>
        </div>
        <div class="digipub-content-grid">

            <div class="digipub-table-of-contents">
                <h2>Innehållsförteckning</h2>
                @RenderTableOfContents(Model.ParsedDocument.ToC, tocPageCounter)
            </div>
            <div class="digipub-content">
                @foreach (var element in Model.ParsedDocument.Elements)
                {
                    if (element is BulletListElement)
                    {
                        var bulletListElement = (BulletListElement)element;
                        <ul style="list-style-type:disc">
                            @foreach (var item in bulletListElement.Items)
                            {
                                <li>
                                    @RenderElement(item)
                                </li>
                            }
                        </ul>
                    }
                    else if (element is NumberListElement)
                    {
                        var numberListElement = (NumberListElement)element;
                        <ol type="1">
                            @foreach (var item in numberListElement.Items)
                            {
                                <li>
                                    @RenderElement(item)
                                </li>
                            }
                        </ol>
                    }
                    else if (element is TableElement)
                    {
                        var tableElement = (TableElement)element;
                        if (tableElement.Rows == null)
                        {
                            break;
                        }
                        <table border="1">
                            @foreach (var row in tableElement.Rows)
                            {
                                <tr>
                                    @foreach (var cell in row.Cells)
                                    {
                                        <td>
                                            @RenderElement(cell)
                                        </td>
                                    }
                                </tr>
                            }
                        </table>
                    }
                    else
                    {
                        @RenderElement(element)
                    }
                }

                <div class="navigation-buttons">
                    <a class="navigation-button @(Model.Page <= 1 ? "disabled" : "")" id="btn-page-previous" @(Model.Page > 1 ? "href=?page=" + (Model.Page - 1) : "")>Föregående kapitel</a>
                    <a class="navigation-button @(Model.Page >= Model.TotalPages ? "disabled" : "")" id="btn-page-next" @(Model.Page < Model.TotalPages ? "href=?page=" + (Model.Page + 1) : "")>Nästa kapitel</a>
                </div>
            </div>
        </div>
    </div>
}

@helper RenderToCElement(ToCLevel element, int depthIndex, int tocPageCounter)
{
    if (depthIndex > 3)
    {
        return;
    }
    foreach (var child in element.Children)
    {
        RenderToCElement(child, depthIndex + 1, tocPageCounter);
    }
    if (element.Name == "")
    {
        return;
    }

    if (depthIndex == 1 && element.Children.Count > 0)
    {
        <li id="table-of-contents-chapter-@element.Id" class="table-of-contents-chapter accordion @(tocPageCounter == Model.Page ? "digipub-accordion-active" : "")" aria-expanded="false">
            <div class="accordion-title">
                <a class="accordion-title-text" href="?page=@(tocPageCounter)#chapter-@(element.Id)">@element.Name</a>
                <button class="toc-expand" type="button" aria-controls="table-of-contents-chapter-@(tocPageCounter).@depthIndex"></button>
            </div>
            <ul class="chapter-level-@depthIndex @(depthIndex == 1 ? "panel" : "")">
                @foreach (var childElement in element.Children)
                {
                    @RenderToCElement(childElement, depthIndex + 1, tocPageCounter)
                }
            </ul>
        </li>
    }
    else
    {
        <li id="table-of-contents-chapter-@element.Id" class="table-of-contents-chapter">
            <a class="accordion-title-text" href="?page=@(tocPageCounter)#chapter-@(element.Id)">@element.Name</a>
            @if (element.Children.Count > 0)
            {
                <ul class="chapter-level-@depthIndex @(depthIndex == 1 ? "panel" : "")">
                    @foreach (var childElement in element.Children)
                    {
                        @RenderToCElement(childElement, depthIndex + 1, tocPageCounter)
                    }
                </ul>
            }
        </li>
    }
}

@helper RenderTableOfContents(ToCLevel ToC, int tocPageCounter)
{
    <ul class="table-of-contents">
        @foreach (var element in ToC.Children)
        {
            @RenderToCElement(element, 1, tocPageCounter);
            tocPageCounter++;
        }
    </ul>
}

@helper RenderElement(DocumentElement element)
{
    if (element is HeadingElement)
    {
        var headingElement = (HeadingElement)element;
        var headingLevel = Math.Max(1, Math.Min(headingElement.Level, 6));
        <a id="chapter-@element.Id" class="anchor"></a>
        @Html.Raw(string.Format("<h{0} {1}>{2}</h{0}>", headingLevel, headingElement.Justification != null ? "class='justify-" + headingElement.Justification + "'" : "", headingElement.Text))
    }
    else if (element is ParagraphElement)
    {
        var paragraphElement = (ParagraphElement)element;
        <p @Html.Raw(string.Format("{0}", paragraphElement.Justification != null ? "class='justify-" + paragraphElement.Justification + "'" : ""))>@(Html.Raw(paragraphElement.Text))</p>
    }
    else if (element is ImageElement)
    {
        var imageElement = (ImageElement)element;
        <img src="@string.Format("{0}/{1}", Model.SourcePath, imageElement.Src)" width="@(imageElement.width)" height="@(imageElement.height)" />
    }
    else if (element is BlipElement)
    {
        var blipElement = (BlipElement)element;
        <img src="@string.Format("{0}/{1}", Model.SourcePath, blipElement.Src)" width="@(blipElement.width)" height="@(blipElement.height)" />
    }
}

<script src="~/Static/js/digipub.js"></script>

Pagination

If you want to implement pagination in your view and split the document into pages based on top level headings, you can use the included function SplitDocElementsIntoPages, which takes the list of Elements as parameter.

Below is an example of Backend with Pagination:

public ActionResult Index(DigiPubTestPage currentPage, int page = 1)
{
    var file = currentPage.Document;
    var filePath = _urlResolver.GetUrl(file);
    MediaData media;
    byte[] blobBytes = { };

    if (_contentLoader.TryGet(file, out media))
    {
        blobBytes = _blobFactory.GetBlob(media.BinaryData.ID).ReadAllBytes();
    }

            

    string licensePath = Path.Combine(Path.GetDirectoryName(AppDomain.CurrentDomain.BaseDirectory), @"digipub_episerver_license.xml");

    var DP = new DocumentParser(licensePath);
    var parsedDocument = DP.Parse(filePath, blobBytes, "digipub", file.ID.ToString());

    if (parsedDocument == null)
    {
        return View(new DigiPubTestPageViewModel(currentPage)); 
    }

    var pageList = DP.SplitDocElementsIntoPages(parsedDocument.Elements);

    if (page > 0 && page <= pageList.Count)
        parsedDocument.Elements = pageList[page - 1];
    else
    {
        parsedDocument.Elements = pageList[0];
    }

    var sourcePath = "/digipub/" + file.ID;
    var pdfPath = sourcePath + "/" + Path.GetFileNameWithoutExtension(filePath) + ".pdf";

    var model = new DigiPubTestPageViewModel(currentPage)
    {
        PageList = pageList,
        ParsedDocument = parsedDocument,
        Page = page,
        TotalPages = pageList.Count,
        SourcePath = sourcePath,
        PDFPath = pdfPath
    };

    return View(model);
}

Extras

Default stylesheets and scripts

To get going quickly with some styling, there are basic stylesheets and scripts you can use. These are not currently hosted anywhere however. Contact HiQ if you want these sent to you.

License validation

There is an attribute class included in the package called ValidateDigipubLicenseAttribute. Use this attribute on your ContentReference property for the document to be parsed to receive license errors in directly edit view. This notifies editors if the license expires or is invalid for some reason.

Example:

[ValidateDigipubLicense]
public virtual ContentReference Document { get; set; }

Parse directly to HTML

You can parse your document directly to a HTML string by calling the method ParseAsHtml. Note that this method is currently not supporting documents with images.