Vtpl

Vtpl is a PHP template engine that maps CSS selectors to PHP variables and code, keeping HTML markup untouched while injecting dynamic content.

What is Vtpl?

Vtpl is a PHP template engine that acts as a binding language between PHP and HTML, using CSS selectors instead of traditional placeholder tags like {$variable}. It takes an HTML file and a .tpl file with selector = value pairs, and produces PHP-rendered HTML output. The engine runs on PHP and is designed so that when the frontend design changes, the same template logic automatically applies to the new HTML files. The approach was created to support CMS architectures such as Vvveb, where any HTML page can be themed without breaking dynamic content rendering.

Key Features

• CSS selector binding — Templates map CSS selectors such as div#id > span.class a to PHP variables or code, so the HTML doesn't need placeholder tags.
• Multiple insertion modifiers — Supports innerHTML, outerHTML, before, prepend, after, and append to control exactly where dynamic content is inserted.
• DOM manipulation commands — Includes deleteAllButFirst to remove mockup duplicates, hide when a variable is false, delete to remove elements, and attribute injection via modifiers like |href.
• Import (from) command — The from(homepage.html|selector) command copies HTML sections from other templates, letting you reuse headers and footers across pages.
• Placeholders and wildcards — Placeholders such as @@__innerText__@@ and @@__data-v-product-(*)__@@ extract attribute values and text into PHP code, and [data-v-product-*] = $product[...] maps matching elements to array keys.
• Filters — HTML attributes like data-v-filter-ucfirst pass element content through PHP functions such as ucfirst, letting designers apply formatting without editing templates.
• JSON attributes and macros — Attributes like data-v-myjson='{var:...}' are parsed into PHP arrays, and macros (@@macro myFunction(...)) invoke PHP functions at compile time, with built-in if and if class macros.
• Debug console — Setting the global VTPL_DEBUG constant to true shows a console at the bottom of the page listing all insert operations performed on the HTML.

Who should use Vtpl?

• Backend PHP developers — Build data-driven pages without leaving PHP tags in the markup, and automatically apply logic to redesigned HTML files.
• Frontend developers — Maintain clean HTML/CSS mockups since dynamic bindings live in separate .tpl files.
• CMS or theme developers — Create systems where any HTML page can be themed without breaking dynamic content, as demonstrated by the Vvveb CMS.
• Designers working with frontend teams — Apply filters and conditions directly in HTML attributes (data-v-filter-*, data-v-if) without touching template code.

What can you do with Vtpl?

• Iterate over lists — Use deleteAllButFirst to strip mockup duplicates, then bind each remaining element to data with a single selector template.
• Reuse page sections — Use from(homepage.html|div#top > div.header) to inject the same header markup into every page template.
• Inject content into attributes — Map elements to href, title, or other attribute modifiers with a|href = "www.thewebsite.com".
• Pass PHP data to JavaScript — Use {$this.date_created} interpolation to output a PHP string into a script, or a whole PHP array as JSON.

How does Vtpl work?

Write a template file with selector = value lines. The Vtpl engine parses the HTML, matches each CSS selector against the DOM, and replaces the selected elements with the specified PHP code or variables. The result is a compiled PHP file where the dynamic content is inlined at the matched nodes, ready to be executed by the PHP runtime. If VTPL_DEBUG is enabled, the engine logs every insertion so you can verify which selectors matched.

Alternatives

• Twig — a PHP template engine that uses {{ variable }} syntax and includes template inheritance, compiled caching, and a sandbox.
• Mustache — a logic-less template engine available in PHP that uses {{variable}} tags and works across many languages.

FAQ

What does Vtpl do?

Vtpl is a PHP template engine that binds PHP variables and code to HTML elements using CSS selectors, so the HTML source remains free of placeholder tags. It parses a .tpl file of selector = value rules and generates PHP output.

Does Vtpl require changing the HTML?

No. Vtpl is designed to leave HTML untouched. Instead of putting {$variable} inside the markup, you write CSS selectors in an external template file, and the engine injects PHP code into matching nodes.

What are @@__name__@@ placeholders?

Placeholders like @@__href__@@ or @@__data-size__@@ let you pass the current element's attribute values, inner text, or matching wildcards into the PHP code being inserted. For example, src = ... getScaledImage('@@__src__@@', '@@__data-size__@@') reads attributes from an <img> tag.

Does Vtpl have default macros?

Yes, Vtpl includes built-in macros for conditional rendering: data-v-if="condition" shows an element only if the condition is true, and data-v-class-if-premium="condition" adds a class conditionally.

How do I debug Vtpl?

Define the global constant VTPL_DEBUG as true, and a console appears at the bottom of the page listing every insert operation made on the HTML, which helps you see which selectors matched and what was injected.