Template file structure
Directory structure
A template contains the following directories and files. This is the complete file listing of the buran production template:
template/
│
│ ── LAYOUT ─────────────────────────────────────────────────
├── _base.tpl # Main layout wrapper (includes header, content, footer)
├── _header.tpl # Full site header (logo, nav, search, cart)
├── _header-checkout.tpl # Simplified checkout header (only logo + steps)
├── _footer.tpl # Full site footer (links, contact, social)
├── _footer-checkout.tpl # Simplified checkout footer
├── _footer-usp.tpl # USP bar above footer (unique selling points)
├── _footer-sign.tpl # Copyright / footer bottom bar
├── _breadcrumbs.tpl # Breadcrumb navigation (drobecky)
├── _menu.tpl # Main navigation mega-menu
├── _bar-compare.tpl # Product comparison floating bar
│
│ ── PRODUCT LISTING ────────────────────────────────────────
├── _listing.tpl # Product card for all product grids
├── _listing_article.tpl # Article card for blog listings
├── _filter.tpl # Product filter sidebar/form definition
│
│ ── PAGE TEMPLATES ─────────────────────────────────────────
├── index.tpl # Homepage (uvodni stranka)
├── zbozi.tpl # Product detail (zbozi = goods/product)
├── zbozi_imgs.tpl # ├── product image gallery
├── zbozi_vars.tpl # ├── variant choice (size, color selectors)
├── zbozi_bar.tpl # ├── sticky buy bar (scrolls with page)
├── zbozi_komplet.tpl # ├── bundle/pack products (komplet = set)
├── zbozi_upsells.tpl # ├── upsell product recommendations
├── zbozi_dostupnost.tpl # ├── availability info (dostupnost = availability)
├── zbozi_comments.tpl # ├── product Q&A (dotazy)
├── zbozi_rating.tpl # └── product reviews/ratings (hodnoceni)
├── zbozi_admin-dostupnost.tpl # admin-facing availability overlay
├── vypis.tpl # Category listing (vypis = listing)
├── vypis_filtr.tpl # Category with sidebar filter layout
├── vypis_vyrobce.tpl # Brand product listing (vyrobce = manufacturer)
├── vypis_prani.tpl # Wishlist (prani = wishes)
├── vypis_porovnani.tpl # Product comparison page (porovnani = comparison)
├── vyhledavani.tpl # Search results (vyhledavani = search)
├── kosik.tpl # Cart router (kosik = cart/basket)
├── kosik_obsah.tpl # ├── cart contents (obsah = content)
├── kosik_udaje.tpl # ├── customer details (udaje = details)
├── kosik_dodani.tpl # ├── delivery selection (dodani = delivery)
├── kosik_souhrn.tpl # ├── order summary sidebar
├── kosik_kroky.tpl # ├── checkout step indicators
├── kosik_prazdny.tpl # ├── empty cart (prazdny = empty)
├── kosik_darky.tpl # └── gift selection (darky = gifts)
├── potvrzeni.tpl # Order confirmation (potvrzeni = confirmation)
├── objednavka.tpl # Order detail (objednavka = order)
├── objednavky.tpl # Order list
├── registrace.tpl # Registration
├── stranka.tpl # Static page (stranka = page)
├── clanek.tpl # Article/blog post (clanek = article)
├── temata.tpl # Blog topic list (temata = topics)
├── tema.tpl # Single blog topic
├── vyrobce.tpl # Brand detail page (vyrobce = manufacturer)
├── znacky.tpl # All brands grid (znacky = brands)
├── prodejna.tpl # Physical store page (prodejna = store)
├── heslo_pozadavek.tpl # Password reset request (pozadavek = request)
├── heslo_zmena.tpl # Password change (zmena = change)
├── _udaje.tpl # Shared customer details form (udaje = details)
├── _dodani.tpl # Shared delivery/shipping form (dodani = delivery)
├── _macro-accordion.tpl # Accordion expand/collapse macro
├── _macro-rating.tpl # Star rating display macro
├── 404.tpl # 404 error page
│
│ ── CONFIGURATION ──────────────────────────────────────────
├── config.json # Central template configuration (see /config)
│
│ ── CONTENT GRID XML ───────────────────────────────────────
├── content-grid/
│ ├── homepage-about-top.xml # Homepage about block (above fold)
│ ├── homepage-about.xml # Homepage about section (bottom)
│ ├── homepage-banner-products.xml # Banner + product slider combos
│ ├── homepage-blog.xml # Blog section heading/text
│ ├── homepage-text-above-brands.xml # Text block above brands slider
│ ├── footer-column-links.xml # Footer link columns
│ ├── footer-usp.xml # Footer USP bar items
│ ├── footer-usp-checkout.xml # USP bar for checkout pages
│ ├── footer-delivery-payment.xml # Footer delivery/payment logos
│ ├── header-usp.xml # Header USP bar items
│ ├── detail-usp.xml # Product detail USP items
│ ├── product-detail-callout.xml # Product detail callout boxes
│ ├── product-detail-specialtext.xml # Product detail special text
│ ├── checkout-content-info.xml # Checkout info banner
│ ├── checkout-delivery-info.xml # Delivery step info banner
│ ├── checkout-select-products.xml # Checkout cross-sell products
│ ├── checkout-select-upsells.xml # Checkout upsell products
│ ├── article-grid-text-products.xml # Article text + product grid
│ ├── page-accordion.xml # Static page FAQ accordion
│ └── search.xml # Search page content blocks
│
│ ── TRANSLATIONS ───────────────────────────────────────────
├── locale/ # Translation directories by locale
│ ├── cs_CZ/ # Czech (default)
│ ├── sk_SK/ # Slovak
│ ├── en_GB/ # English
│ ├── de_DE/ # German
│ ├── pl_PL/ # Polish
│ ├── hu_HU/ # Hungarian
│ ├── ro_RO/ # Romanian
│ ├── bg_BG/ # Bulgarian
│ ├── hr_HR/ # Croatian
│ ├── sl_SI/ # Slovenian
│ ├── es_ES/ # Spanish
│ ├── fr_FR/ # French
│ └── it_IT/ # Italian
│
│ ── SUBDIRECTORIES ─────────────────────────────────────────
├── partials/ # Reusable template fragments
│ ├── _newsletter.tpl # Newsletter subscription form
│ ├── _footer-about.tpl # Footer about/content-grid block
│ ├── _free-delivery.tpl # Free delivery progress bar
│ ├── _popup-cart.tpl # Mini cart popup (kosik popup)
│ ├── _user-menu.tpl # Logged-in user dropdown menu
│ ├── _user-register.tpl # Registration/login form partial
│ ├── _user-wish.tpl # Wishlist icon + dropdown
│ ├── _user-credits.tpl # Customer credits display
│ ├── _flags.tpl # Country/language flag icons
│ ├── _blog-menu.tpl # Blog sidebar menu
│ └── _usp.tpl # USP (unique selling points) bar
├── dialog/ # Modal dialog templates
│ ├── kosik_ok.tpl # "Added to cart" confirmation dialog
│ ├── prihlaseni.tpl # Login dialog (prihlaseni = login)
│ ├── product-comment.tpl # Product Q&A dialog
│ ├── product-compare.tpl # Compare products dialog
│ ├── product-wish.tpl # Add to wishlist dialog
│ └── _recommended-shop.tpl # Recommended regional shop dialog
├── macros/ # Twig macro files
│ └── pocet_kusu.tpl # Quantity selector macro (pocet kusu = quantity)
├── ajax/ # Templates for AJAX/dynamic responses
│ └── search.tpl # Live search results overlay
├── recenze/ # Review-related templates (recenze = reviews)
│ └── vypis.tpl # Review listing page
│
│ ── ASSETS ─────────────────────────────────────────────────
├── css/
│ ├── base.scss # Main SCSS entry point (required)
│ ├── _settings.scss # SCSS variables (optional, injected before plugins)
│ ├── settings/ # Breakpoints, colors, typography variables
│ ├── generic/ # CSS reset, box-sizing rules
│ ├── elements/ # Base HTML element styles
│ ├── objects/ # Layout objects (grid, media)
│ ├── components/ # BEM component styles (button, cartie, dialog, ...)
│ ├── tools/ # SCSS mixins and functions
│ └── utilities/ # Utility classes (spacing, visibility, colors)
├── js/ # JavaScript files (auto-concatenated alphabetically)
│ ├── _header-sticky.js # Sticky header scroll behavior
│ ├── _listing.js # Product listing interactions
│ ├── _menu.js # Navigation menu behavior
│ ├── countdowns.js # Discount countdown timers
│ ├── ga-events.js # Google Analytics 4 event tracking
│ ├── image-select.js # Image selector for variants
│ ├── kosik.js # Cart page interactions (kosik = cart)
│ ├── kosik_validace.js # Cart validation (validace = validation)
│ ├── layout.js # Global layout JS (sticky, scroll, resize)
│ ├── product.js # Product detail page JS
│ ├── product_vars.js # Variant selection JS
│ ├── swiper.js # Swiper carousel initialization
│ ├── togglers.js # Accordion/toggle UI components
│ ├── voucher.js # Voucher/coupon code handling
│ └── wish-compare.js # Wishlist and compare functionality
├── images/ # Static images and SVG sprites
│ ├── symbol-defs.svg # SVG sprite with all icons (bi-Heart, bi-Phone, ...)
│ ├── logo.svg # Shop logo
│ ├── no-gift.svg # "No gift" placeholder
│ ├── sad-face.svg # Empty state illustration
│ ├── flags/ # Country flag images
│ └── temp/ # Temporary/placeholder images
└── tests/ # Playwright E2E tests
├── init.js # Test initialization
├── browsers.json # Browser configuration
├── global/ # Global test suites
├── checkout/ # Checkout flow tests
├── newsletter/ # Newsletter tests
└── sign/ # Login/registration testsInclude relationship diagram
The _base.tpl file is the root of every page. It conditionally includes the header, the page-specific template via {% include this.template %}, and the footer. The checkout branch (kosik pages) uses simplified header/footer variants:
_base.tpl
├── [announcement bar] # top info banner (from banner repository)
├── _header-checkout.tpl # ← if on checkout (kosik) pages
│ └── kosik_kroky.tpl # checkout step indicators
├── _header.tpl # ← if on regular pages
│ ├── _menu.tpl # mega-menu navigation
│ ├── partials/_user-menu.tpl # account dropdown
│ ├── partials/_user-wish.tpl # wishlist icon
│ └── partials/_popup-cart.tpl # mini cart popup
│
├── _breadcrumbs.tpl # shown on most pages (not homepage/checkout)
├── {% include this.template %} # ← system inserts the current page file
│
│ Examples of page templates:
│ ├── zbozi.tpl (product detail)
│ │ ├── _breadcrumbs.tpl # inline breadcrumbs
│ │ ├── zbozi_imgs.tpl # image gallery
│ │ ├── zbozi_vars.tpl # variant selectors
│ │ ├── zbozi_komplet.tpl # bundle products
│ │ ├── zbozi_upsells.tpl # upsell recommendations
│ │ ├── zbozi_dostupnost.tpl # availability details
│ │ ├── zbozi_comments.tpl # Q&A section
│ │ └── zbozi_rating.tpl # reviews/ratings
│ │
│ ├── vypis.tpl (category listing)
│ │ └── uses _listing.tpl (via i:list-container)
│ │
│ ├── kosik.tpl (cart router → delegates to step sub-template)
│ │ ├── kosik_obsah.tpl ──┐
│ │ ├── kosik_udaje.tpl ──┤ each includes:
│ │ ├── kosik_dodani.tpl ──┘ └── kosik_souhrn.tpl (order summary)
│ │ ├── kosik_prazdny.tpl # empty cart
│ │ └── kosik_darky.tpl # gift selection
│ │
│ └── index.tpl (homepage)
│ ├── uses _listing.tpl (via i:list-container)
│ └── partials/_footer-about.tpl
│
├── _footer.tpl # ← if on regular pages
│ ├── partials/_newsletter.tpl # newsletter subscription
│ ├── _footer-usp.tpl # USP bar
│ └── _footer-sign.tpl # copyright bar
├── _footer-checkout.tpl # ← if on checkout pages
│
├── dialog/product-wish.tpl # wishlist dialog (if enabled)
├── dialog/product-compare.tpl # compare dialog (if enabled)
├── _bar-compare.tpl # compare floating bar (if enabled)
└── dialog/_recommended-shop.tpl # regional shop redirect dialogThe _listing.tpl file is special: it is never included directly via {% include %}. Instead, i:list-container components automatically use it to render each product card. Every page that shows a product grid (category, search, homepage sliders, upsells) uses the same _listing.tpl for consistent product card rendering. See Product listing.
Naming conventions
- Page templates (
*.tpl): each shop page has its own root file (e.g.,zbozi.tpl,vypis.tpl,kosik.tpl) - Underscore prefix (
_base.tpl,_header.tpl): files starting with_are included by other templates and never used as standalone pages - Sub-templates (
zbozi_imgs.tpl,kosik_obsah.tpl): related files share a prefix with their parent page - Macro files (
_macro-*.tpl): reusable Twig macros in the root directory; themacros/directory holds additional macro files - config.json: central template configuration file (see Configuration)
Javascript (js/*.js)
All *.js files in the js/ directory are sorted alphabetically, concatenated into one file, and minified. Files with an underscore prefix (e.g., _header-sticky.js, _listing.js, _menu.js) sort first due to alphabetical ordering, which is useful for initialization code that must run early.
CSS (css/*.css)
All *.css files in the css/ directory are sorted alphabetically, concatenated into one file, and minified. CSS is not processed further if a base.scss file exists.
SCSS (css/*.scss)
To use SASS, you must always have a base.scss file, which should import your other files.
Optionally, you can also use a _settings.scss file, which should contain variables that affect the template (primary color, font sizes, breakpoints, etc.).
During compilation, _settings.scss is injected before external plugins, so it can influence plugin behavior as well. This allows you to override properties of Foundation, Select2, and others.
sass
/* automatically generated SCSS compilation template */
@import "_settings"; /* optional */
@import "/global/plugins/..."; /* automatically added plugins */
@import "base"; /* required main file */The buran template organizes its SCSS files using an ITCSS-inspired layer structure inside css/:
| Directory | Purpose |
|---|---|
settings/ | Variables: breakpoints, colors, typography, spacing |
tools/ | SCSS mixins and functions |
generic/ | CSS reset and box-sizing rules |
elements/ | Base HTML element styles (body, headings, links) |
objects/ | Layout patterns (grid, media objects) |
components/ | BEM component styles (button, cartie, dialog, filter, listing, ...) |
utilities/ | Single-purpose utility classes (spacing, visibility, colors) |
Content grid directory
The content-grid/ directory contains XML files that define configurable content sections. Each XML file defines fields (text, image, color, links) that shop admins can fill in through the admin panel. Templates access these values via this.contentGrid('name') where name matches the XML filename without extension (e.g., footer-column-links.xml is accessed as this.contentGrid('footer-column-links')). The buran template ships with 20 content grid definitions covering homepage, footer, checkout, product detail, and article sections. See Content Grid.
Locale directory
The locale/ directory contains translation files organized by locale code (e.g., cs_CZ/, en_GB/, de_DE/). Each locale subdirectory contains an LC_MESSAGES directory with translation catalogs. The buran template supports 13 locales. These provide template-specific translations used with {% trans %} tags. System-level translations are separate.