Theme File Structure

The structure of a Zid theme is designed to be intuitive and flexible, enabling easy customization and effective management of your theme's components. Grasping this structure is key to successfully implementing both the visual and functional aspects of your theme.

Contents of a Zid Theme

A Zid theme is composed of a series of Twig Templates, each housed within a .twig file serving a distinct role in the theme's design and functionality.
In Addition to Twig Templates, a Zid theme contains static assets, and optional JSON files for localization. The following hierarchy of files represent a valid Zid theme.

layout.twig: Master layout for theme structure.

header.twig: Website header section.

footer.twig: Website footer section.

templates (Directory containing page-specific templates)

404.twig: Custom 404 error page.

home.twig: Homepage layout.

search.twig: Search results layout.

products.twig: Multiple product listings.

product.twig: Single product details.

reviews.twig: Customer reviews section.

categories.twig: All product categories overview.

category.twig: Individual category details.

blogs.twig: Blog post summaries.

blog.twig: Single blog post details.

faqs.twig: FAQ section.

cart.twig: Shopping cart interface.

shipping-and-payments.twig: Shipping and payment options.

account-addresses.twig: User account addresses management.

account-orders.twig: User's order history.

account-profile.twig: User profile and settings.

modules (Modular Twig snippets for template integration)

common (Reusable Twig templates across the theme)

locals (Localization files, e.g., 'messages.en_US.yaml')

assets (Static files: CSS, JavaScript, images)

Note: For your theme to function correctly, the files and folders listed above must be included in your theme project folder.

What are Twig Templates and Data?

To understand what a Twig Template is, it is useful to draw parallels. For instance, in the context of Content Management Systems (CMS), Twig Templates resemble the common concept of web templates. In the Model-View-Controller (MVC) architecture, Twig Templates resemble the View component. Twig Templates are responsible for the presentation logic in a web application. They are infused with Twig Components, including variables and function calls. Utilizing the Twig engine, these templates are dynamically merged with relevant data to render the web pages.

In this documentation, the term data specifically refers to the structured content and variables passed into Twig templates, which are essential for customizing and displaying dynamic information on your web pages. This can include everything from user-specific details to product information. Various schemas of data objects are detailed for reference in the next chapter.

For an in-depth understanding of Twig Templates, you can explore the official Twig documentation.

A Detailed Look at Twig Templates and Folders of a Zid Theme

There are three types of Twig Templates in a Zid theme: Global, Page-specific, and Component templates. We explain those three below followed by an explanation of other folders shown in the Zid theme.

Global Templates

These three .twig files lying in the root directory are site-wide templates. They form the foundational layout of your theme, used across all pages.

layout.twig: The backbone of your theme, encapsulating other templates.

header.twig: Defines the header, including navigation and branding.

footer.twig: Outlines the footer, containing contact info, and additional links.

Page-Specific Templates

Each .twig file in the templates directory corresponds to a specific type of page or component within the store. We call these Page Templates. Each Page Template is designed to render a distinct part of the store, such as product listings (products.twig) or the shopping cart interface (cart.twig).

All templates outlined above under the templates directory are mandatory.

Twig Components/Modules

In addition to the main templates, the theme may include smaller, reusable Twig Components or Modules (stored in the modules folder). These components add specific functionalities to the Twig Templates and can be used across different parts of the theme.

Think of these as global functions that you can call from within any other Twig Template/Component.

To learn more about which Twig components we support, jump to the next section about Twig Syntax and Features.

Directories with Optional Contents

The remaining directories are mandatory and must exist in your root directory. However, it is optional whether they contain any files.

common: Common elements like banners or calls-to-action.

locals: Contains .json or .yaml files for theme localization and internationalization, e.g., messages.en_US.yaml. Please resist the urge to correct the spelling mistake in locals, otherwise the theme will not compile correctly.

locals: This directory, intentionally named 'locals' (yes, it's not a typo!), contains .json or .yaml files for theme localization and internationalization, such as messages.en_US.yaml. Remember, keeping the 'locals' spelling as-is is crucial for the correct compilation of the theme.

assets: Houses your theme's static files, such as stylesheets, scripts, and images. Zid permits the following file types for assets: .js, .ts, .css, .scss, .map, .png, .jpg, .jpeg, .gif, .svg, .woff, .woff2, .otf, .ttf, .eot.

Please ensure all template files and directories follow the naming conventions and file structure indicated. Correct implementation will ensure seamless integration with the Zid storefront and an optimal experience for end-users.

Theme File Structure

Contents of a Zid Theme#

What are Twig Templates and Data?#

A Detailed Look at Twig Templates and Folders of a Zid Theme#

Global Templates#

Page-Specific Templates#

Twig Components/Modules#