Documentation

Quick start

From a NuGet package to your first replaced document in a few minutes.

New to Glyphplace? The tutorial and video walk through every feature.

1. Install

dotnet add package Glyphplace.Core

2. Add your license key

Copy the key from My licenses. Either pass it in code or set the GLYPHPLACE_LICENSE environment variable.

var service = new PdfFieldService(new PdfFieldOptions
{
    LicenseKey = configuration["Glyphplace:LicenseKey"],
});
Console.WriteLine(service.License.Message);   // "Licensed." / "Licensed (machine activated until …)"

Without a valid key everything works, but replaced pages carry a small "evaluation" mark and results contain a warning. The free trial key works for 30 days and processes up to 10 documents per hour (each Extract or Replace counts one; Analyze is free). Beyond that the library throws DocumentLimitException, which says when the next document can be processed. The REST API and the online Try page apply the same hourly limit to the free offer.

3. Use a template

var templates = Directory.GetFiles("templates", "*.json").Select(PdfTemplate.Load).ToList();

var result = service.Rewrite(pdfBytes, templates, current => new Dictionary<string, string?>
{
    ["name"]        = "John Smith",
    ["description"] = "First line\nSecond line",   // area field: wrapped to fit
});

4. Images and new content

Image fields replace or remove an image in its original box; placeholders add new text or images where the document has none. Create both in the Glyphplace Browser (click an image, or Draw area → New text/image placeholder).

var result = service.Replace(pdfBytes, template, new PdfChanges
{
    Texts  = { ["name"] = "John Smith", ["note"] = "Approved" },               // "note" is a text placeholder
    Images = { ["logo"] = File.ReadAllBytes("new-logo.png"),                  // replaces the image, keeps its box
               ["stamp"] = File.ReadAllBytes("approved.png"),                 // image placeholder: added
               ["old-badge"] = null },                                        // removes the image
});

PNG, JPEG and BMP are supported. A new image keeps its aspect ratio inside the box (ImageFit.Contain) or fills it (ImageFit.Stretch).

Design templates in the Studio

The Studio is the template designer in your browser – the same features as the Windows Browser, nothing to install. Open a sample PDF, click the values you need and name them, draw areas for multi-line values or new content, and accept the suggested anchors. Type new values and press Preview (or turn on Live); Check changes compares the result with the original pixel by pixel. From the Tools menu you test the template on up to 50 documents, fill a batch from CSV or JSON, generate code or build a DLL. Documents stay in memory for 30 minutes and are never stored; previews carry the evaluation mark, and downloads of filled documents count against your plan.

5. Rotation

By default new content keeps the direction of what it replaces. Set Rotation (degrees, counter-clockwise) on any field to draw its text or image in another direction. In the Browser: select the field, then Field options → Rotate new content.

template.Fields.Single(f => f.Key == "note").Rotation = 90;   // bottom to top

6. Generated code

In the Browser choose Template → Generate code (or call TemplateCodeGenerator.Generate): a C# class with one property per field for the .NET library, or a TypeScript or Python client for the REST API. Only values you change are written back; Validate() checks them first.

byte[] input = File.ReadAllBytes("document.pdf");          // or from a database, an upload, …
byte[] output = TemplatePdf.Update(service, input, document =>
{
    document.Name = "John Smith";
    document.Logo = File.ReadAllBytes("new-logo.png");
});

// Step by step, with the current values and the diagnostics:
var document = TemplatePdf.Read(service, input);              // null when the layout does not match
document!.Name = "John Smith";
ReplaceResult result = document.Apply(service, input);       // result.Pdf: the new bytes, result.Elapsed: how long it took

Every generated file starts with a ready-to-copy example for its own fields.

As a DLL: Tools → Export as .NET DLL in the Studio (or Template → Export as DLL in the Browser) compiles the class for .NET 8 or later, with the template built in and one method that takes every field as an optional parameter:

byte[] output = TemplatePdf.Fill(pdf, name: "John Smith", logo: File.ReadAllBytes("new-logo.png"));

7. Look of new content

Per field: TextColor, BackgroundColor (fills the box first, e.g. white to cover printed content), ReplacementBold, ReplacementItalic, CharacterSpacing and ReplacementFont. If the font lacks characters of a value (Cyrillic, Chinese, symbols), an installed font that has them is used and a diagnostic says which; PdfFieldOptions.FallbackFonts sets the order.

8. Validation

FieldValidation (Required, Pattern, MaxLength, Message) is checked on extracted values (warnings in ExtractResult.Diagnostics) and on new values (an error; the field is left unchanged).

9. Safe to run again

Everything Glyphplace draws is marked in the PDF with its field and value. A replaced document can be read with the same template (the exact value comes back) and replaced again – the earlier drawing is removed, not painted over. After every replacement the output is compared with the input and any change outside the fields is reported (ReplaceResult.Verification). Pages with /Rotate are supported.

An area field whose text sits or looks different from the template's sample is refused with an error and left unchanged, because the area may hold other text; give it an anchor. Set PdfFieldOptions.RefuseMovedAreas to false for layouts where that varies on purpose.

10. Many documents at once

var rows = BatchData.Read("customers.csv", template);      // columns = field keys, optional _name column
var pdfs = service.ReplaceMany(pdfBytes, template, rows).Select(r => r.Result.Pdf);
File.WriteAllBytes("all.pdf", PdfFieldService.Merge(pdfs));

CLI: Glyphplace.Cli batch form.pdf template.json customers.csv out.pdf --merge. Image columns take file paths.

11. REST API and template library

For applications not written in .NET, and to share templates in a team. Create a key per person or application under API keys; all keys of an account share its template library and monthly document quota (usage). Authenticate with Authorization: Bearer gw_….

RequestDoes
GET /api/v1/templatesList the library
GET|PUT|DELETE /api/v1/templates/{id}Read, save (new version) or delete a template (JSON body)
POST /api/v1/extractmultipart: file (PDF) and template (library id) or templateJson; without either, the layout is detected among the library's templates
POST /api/v1/replaceas extract, plus changes: {"texts":{…},"images":{key: base64|null}}; returns the PDF as base64
GET /api/v1/usageDocuments processed this month and the plan's quota
curl -H "Authorization: Bearer gw_…" -F file=@document.pdf -F template=my-layout https://your-site/api/v1/extract

.NET: new GlyphplaceApiClient(new Uri("https://your-site/"), apiKey). Each extraction or replacement counts as one document. Documents are processed in memory and not stored.

License types

TypeNetworkRenewal
Offline Never. Works in closed networks. The key contains its expiry. Download the new key after each renewal, or automate it with POST /api/license/refresh.
Online check One small request per day in the background. Keeps working for 14 days without connection. Automatic: the renewed key arrives with the daily check.
Machine activation Once per machine, then renewed in the background every few weeks. Automatic. Free a seat by deactivating a machine in the portal. In containers set PdfFieldOptions.MachineId to a stable value.

The license check never sends document content. Online modes send only the license key and a hashed machine identifier.