Configure PDF Credential Generation

This guide explains how to configure the PDF credential generator using the text_elements format.

Overview

The PDF credential generator renders text elements onto a PDF template. Three standard elements are rendered by default:

• name: The learner’s name

• context: The course or Learning Path name

• date: The issue date

Each element can be customized, hidden, or supplemented with custom text elements.

Basic Configuration

A minimal configuration only requires a template:

{
    "template": "certificate-template"
}

This renders all three standard elements with default positioning.

Configuration Options

Top-Level Options

Option	Required	Description
template	Yes	The slug of the PDF template asset (from CredentialAsset).
template_multiline	No	Alternative template for multiline context names (when using \n).
defaults	No	Global defaults for all text elements (see below).
text_elements	No	Configuration for individual text elements (see below).

Global Defaults

The defaults object sets default values for all text elements:

{
    "defaults": {
        "font": "CustomFont",
        "color": "#333333",
        "size": 14,
        "char_space": 0.5,
        "uppercase": false,
        "line_height": 1.2
    }
}

Property	Default	Description
font	Helvetica	Font name (must be a CredentialAsset slug for custom fonts).
color	#000	Hex color code (3 or 6 characters, with or without #).
size	12	Font size in points.
char_space	0	Character spacing in points.
uppercase	false	Convert text to uppercase.
line_height	1.1	Line height multiplier for multiline text.

Text Elements

The text_elements object configures individual elements. Standard elements (name, context, date) have defaults and can be partially overridden:

{
    "text_elements": {
        "name": {"y": 300, "uppercase": true},
        "context": {"size": 24},
        "date": {"color": "#666666"}
    }
}

Element Properties

Property	Default	Description
text	varies	Text content with placeholder substitution.
y	varies	Vertical position (PDF coordinates from bottom).
size	(inherited)	Font size in points (inherited from defaults.size).
font	(inherited)	Font name (inherited from defaults.font).
color	(inherited)	Hex color code (inherited from defaults.color).
char_space	(inherited)	Character spacing (inherited from defaults.char_space).
uppercase	(inherited)	Convert text to uppercase (inherited from defaults.uppercase).
line_height	(inherited)	Line height multiplier for multiline text (inherited from defaults.line_height).

Standard Element Defaults

Element	Text	Y	Size
name	{name}	290	32
context	{context_name}	220	28
date	{issue_date}	120	12

Django Settings

Some element defaults can be overridden globally via Django settings:

Setting	Default	Description
LEARNING_CREDENTIALS_NAME_UPPERCASE	False	Convert name to uppercase by default.
LEARNING_CREDENTIALS_DATE_UPPERCASE	False	Convert date to uppercase by default.
LEARNING_CREDENTIALS_DATE_CHAR_SPACE	0	Default character spacing for date element.

These settings are applied before per-credential configuration, allowing you to set organization-wide defaults while still permitting overrides in individual credentials.

Placeholders

Text content supports placeholder substitution using {placeholder} syntax:

• {name} - The learner’s display name

• {context_name} - The course or Learning Path name

• {issue_date} - The localized issue date

• {verify_uuid} - The credential’s verification UUID (for third-party verification)

To include literal braces, use {{ and }}:

{
    "text": "Score: {{95%}}"
}

Hiding Elements

Standard elements can be hidden by setting their configuration to false:

{
    "text_elements": {
        "date": false
    }
}

Custom Elements

Add custom text elements by using any key other than name, context, or date. Custom elements require both text and y properties:

{
    "text_elements": {
        "award_line": {
            "text": "Awarded on {issue_date}",
            "y": 140,
            "size": 14
        },
        "institution": {
            "text": "Example University",
            "y": 80,
            "size": 10,
            "color": "#666666"
        }
    }
}

Complete Example

{
    "template": "certificate-template",
    "template_multiline": "certificate-multiline",
    "defaults": {
        "font": "OpenSans",
        "color": "#333333"
    },
    "text_elements": {
        "name": {
            "y": 300,
            "size": 36,
            "uppercase": true
        },
        "context": {
            "text": "Custom Course Name",
            "y": 230,
            "size": 24
        },
        "date": false,
        "award_line": {
            "text": "Awarded on {issue_date}",
            "y": 150,
            "size": 12,
            "color": "#666666"
        }
    }
}

This configuration:

1. Uses OpenSans font and #333333 color for all elements

2. Renders the name at y=300, size 36, in uppercase

3. Renders the context with custom text at y=230, size 24

4. Hides the default date element

5. Adds a custom “Awarded on [date]” line at y=150

Migration from Legacy Format

The legacy flat format (name_y, context_name_color, etc.) has been migrated to the new text_elements format. Existing configurations were automatically converted by migration 0007_migrate_to_text_elements_format.

Legacy to New Format Mapping

Legacy Option	New Location
font	defaults.font
context_name	text_elements.context.text
name_y	text_elements.name.y
name_color	text_elements.name.color
name_size	text_elements.name.size
name_font	text_elements.name.font
name_uppercase	text_elements.name.uppercase
context_name_y	text_elements.context.y
context_name_color	text_elements.context.color
context_name_size	text_elements.context.size
context_name_font	text_elements.context.font
issue_date_y	text_elements.date.y
issue_date_color	text_elements.date.color
issue_date_size	text_elements.date.size
issue_date_font	text_elements.date.font
issue_date_char_space	text_elements.date.char_space
issue_date_uppercase	text_elements.date.uppercase
template_two_lines	template_multiline