Scryber Configuration and Extension

Scryber provides a comprehensive configuration and extension system that allows you to customize behavior, add custom components, integrate with external systems, and implement code-behind logic for PDF templates.

Overview

This documentation covers the complete architecture for extending and configuring Scryber:

Document Configuration

Applies to individual document templates

Processing Instructions - Document-level parser configuration via XML processing instructions
DOM and Event Handling - Directly accessing content and responding to document remote file request events
Document Controllers - Code-behind functionality with outlets and actions
Working in Code - Building and modifying component trees directly with the object model and typed style values.

Core Engine Configuration

Applies to all documents within the application or process.

Configuration Files - JSON-based application configuration file (such as scrybersettings.json) with sections for.
- Namespace Registration - Mapping XML namespaces to .NET assemblies
- Image Factories - Custom image loading from databases, APIs, or other sources
- Font Configuration - Registering custom fonts and managing font loading

Extension Mechanisms

Applies to any number of applications or processes

Custom Components - Creating reusable PDF components with custom namespaces

In the Code

How the library works, a documents’ lifecycle and creating and setting standard values.

Library Architecture - An overview of the libraries, important namespaces and class hierarchies, and the strategies used for parsing; layout; and rendering.
Working in Code - Details many of the standard classes used and ways to create component trees, set typed style values, and safely parse CSS-like values from configuration.

Integration

Complete Integration Example - All extension mechanisms working together
Best Practices - Guidelines, troubleshooting, and performance considerations

Quick Start

Basic Configuration

{
  "Scryber": {
    "Parsing": {
      "Namespaces": [ /* Custom component namespaces */ ]
    },
    "Fonts": {
      "Register": [ /* Custom fonts */ ]
    },
    "Imaging": {
      "Factories": [ /* Custom image loaders */ ]
    }
  }
}

Using Processing Instructions

<?xml version='1.0' encoding='utf-8' ?>
<?scryber parser-mode='Strict' 
          log-level='Warnings'
          controller='MyNamespace.MyController, MyAssembly' ?>
<html xmlns='http://www.w3.org/1999/xhtml'>
    <!-- Document content -->
</html>

Creating a Controller

public class MyController
{
    [PDFOutlet(Required = true)]
    public Label TitleLabel { get; set; }
    
    public void Init(InitContext context)
    {
        TitleLabel.Text = "Generated at " + DateTime.Now;
    }
}

Initializing the configuration in Scryber.Core

Extension Points Summary

Extension Point	Purpose	Configuration
Processing Instructions	Document-level settings	`<?scryber ... ?>`
Controllers	Code-behind with outlets/actions	`controller='Type, Assembly'`
Custom Components	Reusable widgets	Namespace registration
Image Factories	Custom image sources	`Imaging:Factories[]`
Font Registration	Custom fonts	`Fonts:Register[]`
Namespaces	Component discovery	`Parsing:Namespaces[]`

Architecture Principles

Dependency Injection - Configuration via IScryberConfigurationService
Lazy Loading - Types, assemblies, fonts loaded on-demand
Caching - Reflected definitions cached for performance
Thread Safety - Configuration access protected with locks
Convention over Configuration - Sensible defaults, explicit overrides

Next Steps

Start with Processing Instructions for document-level configuration
Learn Document Controllers for code-behind functionality
Create Custom Components for reusable elements
See the Complete Integration Example for everything working together

Documentation Version: 1.0
Last Updated: February 2026
Target: Scryber.Core 6.x / 7.x