Templates

A template is a class and a view. The class describes the kind of document – title, retention, permission, signer –, the view its content. Anvil adds the layout: header with name or logo, footer with document number and page, typography and the signature block.

namespace App\Documents;

use Anvil\Documents\Document;
use Anvil\Documents\DocumentTemplate;
use Anvil\Documents\RetentionRule;

final class IssueReceipt extends DocumentTemplate
{
    public function key(): string { return 'issue-receipt'; }

    public function title(): string { return lang('Iam.documents.issueTitle'); }

    public function view(): string { return 'App\Views\documents\issue_receipt'; }

    // Three years after the exit of the person (an anchor date set later).
    public function retention(): RetentionRule { return RetentionRule::afterAnchor(36); }

    // Text the signer confirms (checkbox above the signature, printed in the PDF).
    public function confirmation(): ?string { return 'I have received the items listed.'; }

    // Permission to create, hand over and void documents of the template.
    public function permission(): string { return 'receipts.manage'; }

    public function signerName(array $data): string { return $data['person']['name'] ?? ''; }

    // In the transaction of the signature.
    public function signed(Document $document): void
    {
        foreach ($document->data['items'] as $item) {
            service('idoitAssignments')->assign($item['uuid'], $document->data['person']['uuid']);
        }
    }
}

Methods

Method	Required	Default	Purpose
`key()`	yes		unique key, `[a-z][a-z0-9.-]{1,99}`; stored with every document
`title()`	yes		name of the kind; default title of documents
`view()`	yes		namespaced view of the content, see Writing the view
`retention()`	yes		how long documents are kept, see Retention
`version()`		`1`	stored with every document; raise it when the view changes in a way that matters for signed documents
`requiresSignature()`		`true`	`false`: completed without signature (`finalise()`)
`confirmation()`		`null`	text the signer must confirm (checkbox)
`permission()`		`documents.manage`	permission to create, hand over and void
`signerName(array $data)`		`$data['signer']`	proposed name of the signer, can be corrected on the signing page
`signed(Document $document)`		nothing	runs in the transaction of the signature or finalisation

Registering

public array $documentTemplates = [IssueReceipt::class, ReturnReceipt::class];

Templates are registered explicitly. Keys must be unique; an invalid or duplicate key throws an InvalidArgumentException. Their permissions appear in the role editor under Documents.

The key is stored with every document: don’t change it once documents exist, and keep templates registered as long as documents of them are kept.

Branding

Setting	Default	Purpose
`$documentBrand`	`Anvil`	name in the header and footer
`$documentLogo`	`null`	PNG or JPEG file (at most 500 KB) in the header, embedded into the PDF; `null` shows the name

The logo is read from the file system and embedded; a file that is missing, too large or of another type is ignored and the name is shown.

signed()

signed() runs inside the transaction of the signature: if it throws, the signature is rolled back and the document stays a draft. Typical uses:

queue write-backs to other systems (e.g. assign items in a CMDB),
change the status of the owner record,
send a notification.

Queue work that talks to other systems (e.g. through an outbox) instead of calling them directly, so a slow or failing system does not block the signature.