Setting Up Visual Templates

Visual templates are installed on the API server. The web client asks the API to render a saved card using one of those templates.

Fresh API installations include the example visual template for the ptcg game. Container image builds obtain the latest stable example-template release and bundle it, so startup does not need internet access. The API installs it into persistent template storage and registers it automatically. Existing files and registry records, including deactivated templates, are preserved when the container is recreated. Other games need their own compatible template.

Install a template

1. Obtain a template ZIP containing index.html, metadata.json, and any supporting CSS, images, or fonts at its root.
2. Check its metadata uses schemaVersion: 1, templateAuthor, localised name arrays, and a game internalName supported by your collection.
3. Sign in as an administrator, open Install visual templates, choose New template, select the ZIP and press Install ZIP. Create the package’s game first if it does not exist.
4. For updates, select the installed template under Installation and upload a different package version. Refresh the collection if another administrator has changed it.

The API validates packages independently and records valid templates in its database. Install a new package version to refresh its metadata. Deactivated templates remain inactive until explicitly re-registered. ZIP uploads are limited to 20 MB compressed and 50 MB expanded. Installed templates are not automatically updated. For manual installation, extract to TEMPLATES_PATH/<internalName>/ and restart the API or register the directory through POST /v1/data/visual_template/create.

Preview a card

Open the web client, enter the API address, and sign in. Choose a saved card, a visual template for the same game, and a two-letter language code such as en, ja, or fr. Select Refresh preview.

The preview runs in an isolated iframe. Template scripts and React hydration do not run; version 1 templates use static HTML, CSS, images, and fonts. Missing translations fall back to English, then the first available translation. Refresh the preview if its five-minute asset access has expired.

Set PUBLIC_URL on the API to its externally reachable origin when using an HTTPS reverse proxy. Template URLs use that origin rather than a developer’s localhost address.

Template authors

Use tcgsd:name, tcgsd:types, and other card fields in HTML text nodes. Attribute placeholders are rejected. Use relative asset paths or the /tcgsd-template-assets prefix, which the API replaces during rendering.

The version 1 metadata schema defines the package metadata. The full contract documents the registry endpoints and current limits.