Annotations

Annotations in Doconut work in two directions: users draw them in the browser widget and the server persists them per page, or your code builds them programmatically and loads them into an open session. Either way they render on the pages and can be burned into PDF/PNG exports.

Annotation support is gated by the Annotation license capability (granted automatically under an active Temporary license).

Enable the annotation UI

Annotation is a Viewer module, not a standalone toolbar. The complete page must include the Viewer resources, Viewer toolbar, Viewer mount, and initialized objViewer; the Annotation Ribbon is then mounted and attached to that same instance.

Emit the annotation bundles alongside the viewer bundles — they are license-gated, so the tags only appear when the capability is available:

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss     = true,
    IncludeAnnotationCss = true   // jquery-ui.min.css + annotationBar.css
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery             = true,
    IncludeViewerScripts      = true,
    IncludeAnnotationScripts  = true, // jquery-ui, raphael.js, annotation.js
    IncludeAnnotationBar      = true  // the embedded annotation ribbon
}))

Keep the complete Viewer composition visible in the markup:

<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer controls, including the button that opens Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

The Annotation bundle generates the Ribbon DOM inside annBarMount; you do not need to copy its buttons or dialog markup. Initialize docViewer first, then create the Ribbon only when the server confirms that Annotation is licensed:

<script>
    let annBar = null;
    let currentToken = '';

    const objViewer = $('#div_ctlDoc').docViewer({
        BasePath: '/',
        ResPath: 'doconut-res/images',
        onAnnLoaded:    () => annBar?.handleAnnLoaded(),
        onAnnSaved:     () => annBar?.handleAnnSaved(),
        onAnnSaveError: () => annBar?.handleAnnSaveError(),
        onAnnClosed:    () => annBar?.handleAnnClosed(),
        onError:        (message) => console.error('Viewer error:', message)
    });

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        onStatus: (message) => console.log(message),
        onToast: (message, type) => console.log(type, message),
        onLayout: () => requestAnimationFrame(() => objViewer.Refit())
    });
    annBar.attach(objViewer);
        </text>
    }
</script>

Without the capability, ReferenceScripts leaves out the Ribbon's script, so the server-side if keeps an unguarded doconutAnnotationBar(...) call from breaking the page.

Saving from the Ribbon posts data through the middleware (AnnSave), which stores it in the document session per page. Loading (AnnLoad) happens automatically when a page with annotations renders. The four onAnn* callbacks keep the Ribbon synchronized with the viewer lifecycle.

Open and close it from any host-owned Viewer toolbar:

annBar.open();
annBar.close();

The public Ribbon API is:

onStatus, onToast, onLayout, onEditStart, and onEditEnd are optional host callbacks. The endpoints object can additionally provide exportPdf, exportPng, imageUpload, and imageList; controls without a configured endpoint remain hidden. For the combined Viewer, Search, and Annotation startup sequence, see Quick Start.

The annotation bundle adds the browser authoring tools, but the data still belongs to the server-side document session identified by the token. Reopening the source creates a new session; persist the XML or encoded annotation envelope in your application if annotations must survive beyond the session lifetime.

Two kinds of callback, wired two ways

The annotation code uses two callback styles, and each fails silently when wired the other way:

• onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed are options of docViewer({...}), like every viewer callback.
• Created, Changed, Deleted, and Properties are global functions found by name: the viewer id prefixed to the event. For the viewer in #div_ctlDoc the id is ctlDoc, so the functions are ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted, and ctlDoc_Properties. A misspelled or renamed function is simply never called.

SaveAnnotations() does not return whether it saved: the result arrives through onAnnSaved or onAnnSaveError. Code that reads its return value never clears its "unsaved changes" flag.

Build annotations in C#

Get a manager bound to the open session, add annotations, and load them (with using Doconut.Annotations; for the types and using System.Drawing; for Rectangle/Color):

app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // Bound to the open session's page dimensions
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // One stamp per page
    for (int page = 1; page <= pageCount; page++)
    {
        manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
            $"PAGE {page}", 28, 4, Color.Maroon)
        {
            Opacity = 60,
            Rotate  = -8
        });
    }

    manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
        "Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));

    // Load into the session — the widget fetches them via AnnLoad and the
    // renderer burns them into image/PDF exports.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Annotation types

All types live in Doconut.Annotations and inherit from BaseAnnotation (page number + bounding Rectangle):

The AnnotationManager API

Viewer mirrors the load/read operations against a session: LoadAnnotationData(token, manager) or LoadAnnotationData(token, encodedData) (the Base64 wire envelope from GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Export with annotations burned in

// PDF of all pages with annotations rendered onto them
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
    return Results.File(pdf, "application/pdf", "export.pdf");
});

// Or a ZIP of per-page PNGs
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
    return Results.File(zip, "application/zip", "annotations-png.zip");
});

Exports use the same burner as on-screen rendering, so what users see is what the file contains — except for image annotations, described next.

Image annotations on an intranet host export as "Image blocked"

The viewer and the export fetch an ImageAnnotation's image from different places:

When the server fetches an image to burn it in, it refuses addresses that point back into private networks: loopback (localhost, 127.0.0.1), 0.0.0.0, link-local (169.254.x.x), the private ranges 10.x, 172.16–31.x, and 192.168.x, carrier-grade NAT (100.64.0.0/10), and IPv6 link-local and unique-local addresses. This protects the server from being used to reach internal systems through a crafted image URL, and there is no switch to turn it off.

A relative image URL resolves against the host of the current request, so on localhost, on an intranet server, or on any site reached through a private address, the image shows in the viewer and the export contains the placeholder instead. That is the guard working, not a rendering failure. If exports must contain the image, serve it from a host with a public address and use an absolute URL. A host name that cannot be resolved is refused the same way; any other download failure draws the URL and the error message in red where the image would be.

Persistence workflow

1. Open the document and obtain its token.
2. Load previously stored XML or encoded data into that token.
3. Let the widget read and edit the session annotations.
4. Retrieve XML with GetAnnotationXML(token) when your application decides to persist.
5. Export PDF/PNG when a flattened deliverable is required.
6. Close the document session.

Do not use the opaque viewer token as a permanent annotation identifier. Associate persisted annotation data with your own document and version identifiers.

Security and rendering notes

• Annotation requests use the same session/token security as page requests.
• Validate and control any user-supplied image URL to avoid server-side request forgery.
• Exports apply the same license/custom-watermark decision as on-screen page rendering.
• Large freehand payloads and high-resolution exports increase memory use; test realistic documents and zoom values.

Troubleshooting