Simplia Templates

Appearance

Simplia TemplatesTemplate Documentation

Complete guide to building templates for Simplia e-shop

Getting Started
HTML Elements
Components

Getting Started

Step-by-step guide to building your first template with real production examples.

Twig Syntax

Templates use extended Twig syntax with support for custom components and filters.

HTML Elements

Custom HTML elements for images, videos, maps, banners, and dynamic content.

Object Types

Complete reference of all available objects and their attributes.

Repositories

Query products, categories, articles, and other entities.

For AI Agents ​

This documentation is optimized for machine consumption. The following resources are available for AI agents:

  • llms.txt — documentation index in LLM-friendly format
  • llms-full.txt — complete documentation in a single file for LLM consumption
  • Glossary — Czech-to-English mapping of all code identifiers (filenames, variables, URL paths, filters)

Claude Code plugin ​

The shop-templates plugin gives Claude Code the template rules, this documentation and the tpl command (validate the template, lint its CSS, run its tests, print preview URLs). Install it with:

bash
claude plugin marketplace add https://tpldoc.simplia.cz/claude/marketplace.json
claude plugin install shop-templates@simplia-templates

Outside a Simplia shop environment, tpl works against the template's tpltest host and reads these environment variables:

VariableValue
TPL_BASE_URLthe template's tpltest URL, e.g. https://<hash>-tpltest.simpliashop.cz
TPL_LAYOUT_DIRthe local directory with the template files (the directory you edit)
TPL_LAYOUT_CODEthe template code
TPL_TOKENthe template API token of the tpltest host, issued by IS from the shared template-api/secret (needed by tpl validate)
TPL_BACKENDoptional: remote or local; chosen automatically when unset

To exercise /_/template/validate in a local shop env, put {"template-api/secret": "<value>"} into the eshop root credentials.json (merged by CredentialsStore in LOCAL_DEV when CREDENTIALS_STORE_URL is set) and compute the token as HMAC-SHA256(<value>, "template-api|" + <LAYOUT value>), hex.

Run tpl help for the commands and tpl info to check the setup.

Key Concepts ​

  • Templates use Twital — a Twig syntax extension that adds custom XML elements
  • The i: prefix denotes Simplia components (<i:img>, <i:list-container>, <i:facebook-share>, ...)
  • Template files have the .tpl extension and follow the directory structure described in File Structure
  • Central template configuration is in config.json (see Configuration)

Template Development Workflow ​

  1. Connect via SFTP to the development environment (see SFTP)
  2. Edit templates in your editor with SFTP upload
  3. Preview changes on tpltest (test version of the template)
  4. Publish via the e-shop admin interface