DigitalPublications.Episerver 1.0.9

.NET Standard 2.0
Install-Package DigitalPublications.Episerver -Version 1.0.9
dotnet add package DigitalPublications.Episerver --version 1.0.9
<PackageReference Include="DigitalPublications.Episerver" Version="1.0.9" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add DigitalPublications.Episerver --version 1.0.9
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: DigitalPublications.Episerver, 1.0.9"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install DigitalPublications.Episerver as a Cake Addin
#addin nuget:?package=DigitalPublications.Episerver&version=1.0.9

// Install DigitalPublications.Episerver as a Cake Tool
#tool nuget:?package=DigitalPublications.Episerver&version=1.0.9
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

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.

Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows
.NET Core netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.0 netstandard2.1
.NET Framework net461 net462 net463 net47 net471 net472 net48
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen40 tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.9 90 5/10/2022
1.0.7 75 5/9/2022
1.0.6 76 5/5/2022
1.0.3 217 6/4/2021

Added support for footnotes per page if document has no H1