> ## Documentation Index
> Fetch the complete documentation index at: https://quickbutik.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Wrappers and Functions

> Master helper functions, data wrappers, and content manipulation in Quickbutik themes

Wrappers and functions in Quickbutik's Mustache implementation provide essential tools for transforming and manipulating data. These helper functions extend Mustache's capabilities for specific use cases like image optimization, translations, and asset linking.

<Info>
  **Prerequisites**: This guide covers the available wrapper functions. Make sure you understand [basic Mustache syntax](/theme-development/mustache-basics) and [object access patterns](/theme-development/objects-and-attributes) first.
</Info>

<Note>
  **Key Concept**: Wrappers use the `{{#function}}content{{/function}}` syntax to process and transform data
</Note>

## Available Wrappers

According to the Quickbutik platform, only the following wrappers are supported:

| Wrapper            | Purpose                                | Usage                                                                     |
| ------------------ | -------------------------------------- | ------------------------------------------------------------------------- |
| `{{#img}}`         | Image manipulation and optimization    | `{{#img}}{{product.firstimage}}_400x400{{/img}}`                          |
| `{{#lang}}`        | Text translation via Control Panel     | `{{#lang}}My text here{{/lang}}`                                          |
| `{{#assets}}`      | Link to correct path for specific file | `{{#assets}}css/style.css{{/assets}}`                                     |
| `{{#breadcrumbs}}` | Output breadcrumbs/category structure  | `{{#breadcrumbs}} {{url}} {{title}} {{^last}} {{/last}} {{/breadcrumbs}}` |
| `{{#asset_flags}}` | Return flag icon for language          | `{{#asset_flags}}{{id}}{{/asset_flags}}`                                  |

## Image Wrapper (`{{#img}}`)

The image wrapper is essential for handling product images and media optimization:

<CodeGroup>
  ```mustache Basic Image Resizing theme={null}
  <!-- Resize image to specific dimensions -->
  <img src="{{#img}}{{product.firstimage}}_400x400{{/img}}" alt="{{product.title}}">

  <!-- Different sizes for different uses -->
  <img src="{{#img}}{{product.firstimage}}_150x150{{/img}}" alt="{{product.title}}" class="thumbnail">
  <img src="{{#img}}{{product.firstimage}}_800x600{{/img}}" alt="{{product.title}}" class="main-image">
  ```

  ```mustache Product Image Gallery theme={null}
  {{#product.images}}
      <div class="image-item">
          <!-- Thumbnail -->
          <img src="{{#img}}{{image}}_100x100{{/img}}" 
               alt="{{alttext}}"
               class="thumbnail"
               onclick="showLarge('{{#img}}{{image}}_800x800{{/img}}')">
          
          <!-- Hidden large image URL for lightbox -->
          <data value="{{#img}}{{image}}_1200x1200{{/img}}"></data>
      </div>
  {{/product.images}}
  ```

  ```mustache Responsive Images theme={null}
  <!-- Different sizes for different screen sizes -->
  <picture>
      <source media="(max-width: 480px)">
      <source media="(max-width: 768px)">
      <source media="(max-width: 1024px)">
      <img src="{{#img}}{{product.firstimage}}_400x400{{/img}}" 
           alt="{{product.title}}">
  </picture>
  ```
</CodeGroup>

### Image Size Options

| Size Format | Description      | Use Case                     |
| ----------- | ---------------- | ---------------------------- |
| `_100x100`  | Square thumbnail | Product grid thumbnails      |
| `_300x200`  | Landscape card   | Product cards, lists         |
| `_400x400`  | Medium square    | Product detail thumbnails    |
| `_800x600`  | Large landscape  | Product detail main image    |
| `_1200x800` | Extra large      | Lightbox, zoom functionality |

### Settings Home Elements Images

<CodeGroup>
  ```mustache Home Elements with Images theme={null}
  {{#settings.home_elements}}
      {{#element}}
          {{#image1_link}}
              <div class="element-image">
                  <img src="{{#img}}{{image1_link}}_800x400{{/img}}" alt="{{title}}">
              </div>
          {{/image1_link}}
          
          {{#use_image2}}
              {{#image2_link}}
                  <div class="element-secondary-image">
                      <img src="{{#img}}{{image2_link}}_400x300{{/img}}" alt="{{title}}">
                  </div>
              {{/image2_link}}
          {{/use_image2}}
      {{/element}}
  {{/settings.home_elements}}
  ```
</CodeGroup>

## Language Wrapper (`{{#lang}}`)

Handle multi-language content and translations via the Control Panel:

<CodeGroup>
  ```mustache Basic Translation theme={null}
  <!-- Simple text translation -->
  <h1>{{#lang}}Welcome to our store{{/lang}}</h1>
  <button>{{#lang}}Add to Cart{{/lang}}</button>
  <p>{{#lang}}Free shipping on orders over $50{{/lang}}</p>
  ```

  ```mustache Dynamic Content Translation theme={null}
  <!-- Translate dynamic content with context -->
  <div class="product-status">
      {{#product.soldOut}}
          <span class="out-of-stock">{{#lang}}Out of Stock{{/lang}}</span>
      {{/product.soldOut}}
      
      {{^product.soldOut}}
          <span class="in-stock">{{#lang}}In Stock{{/lang}}</span>
      {{/product.soldOut}}
  </div>

  <div class="basket-info">
      {{#basket.isEmpty}}
          <p>{{#lang}}Your cart is empty{{/lang}}</p>
      {{/basket.isEmpty}}
      
      {{^basket.isEmpty}}
          <p>{{basket.items_count}} {{#lang}}items in cart{{/lang}}</p>
      {{/basket.isEmpty}}
  </div>
  ```

  ```mustache Form Labels and Messages theme={null}
  <!-- Translate form elements -->
  <form class="contact-form">
      <label for="name">{{#lang}}Name{{/lang}} *</label>
      <input type="text" id="name" placeholder="{{#lang}}Enter your name{{/lang}}">
      
      <label for="email">{{#lang}}Email{{/lang}} *</label>
      <input type="email" id="email" placeholder="{{#lang}}Enter your email{{/lang}}">
      
      <label for="message">{{#lang}}Message{{/lang}}</label>
      <textarea id="message" placeholder="{{#lang}}Write your message here{{/lang}}"></textarea>
      
      <button type="submit">{{#lang}}Send Message{{/lang}}</button>
  </form>
  ```
</CodeGroup>

### Navigation and UI Translation

<CodeGroup>
  ```mustache Navigation Translation theme={null}
  <!-- Translate navigation elements -->
  <nav class="main-navigation">
      {{#linklist.main}}
          <a href="{{url}}" class="nav-link {{#current}}active{{/current}}">
              {{#lang}}{{name}}{{/lang}}
          </a>
      {{/linklist.main}}
  </nav>

  <!-- Translate common UI elements -->
  <div class="user-actions">
      {{#shop.login_active}}
          {{#user.logged_in}}
              <a href="{{user.login_url}}">{{#lang}}My Account{{/lang}}</a>
          {{/user.logged_in}}
          
          {{^user.logged_in}}
              <a href="{{user.login_url}}">{{#lang}}Log In{{/lang}}</a>
          {{/user.logged_in}}
      {{/shop.login_active}}
  </div>
  ```
</CodeGroup>

## Assets Wrapper (`{{#assets}}`)

Link to correct paths for theme files like CSS, JavaScript, and other assets:

<CodeGroup>
  ```mustache CSS and JavaScript Assets theme={null}
  <!-- Link to theme CSS files -->
  <link rel="stylesheet" href="{{#assets}}css/style.css{{/assets}}">
  <link rel="stylesheet" href="{{#assets}}css/responsive.css{{/assets}}">

  <!-- Link to theme JavaScript files -->
  <script src="{{#assets}}js/main.js{{/assets}}"></script>
  <script src="{{#assets}}js/cart.js{{/assets}}"></script>
  ```

  ```mustache Image and Font Assets theme={null}
  <!-- Link to theme images -->
  <img src="{{#assets}}images/logo.png{{/assets}}" alt="{{shop.name}}">
  <img src="{{#assets}}images/placeholder.jpg{{/assets}}" alt="{{#lang}}No image available{{/lang}}">

  <!-- Link to theme fonts -->
  <link rel="preload" href="{{#assets}}fonts/custom-font.woff2{{/assets}}" as="font" type="font/woff2" crossorigin>
  ```

  ```mustache Icon and Resource Assets theme={null}
  <!-- Link to theme icons -->
  <link rel="icon" href="{{#assets}}images/favicon.ico{{/assets}}">
  <link rel="apple-touch-icon" href="{{#assets}}images/apple-touch-icon.png{{/assets}}">

  <!-- Link to other theme resources -->
  <link rel="manifest" href="{{#assets}}manifest.json{{/assets}}">
  ```
</CodeGroup>

## Breadcrumbs Wrapper (`{{#breadcrumbs}}`)

Output breadcrumbs/category structure regardless of the current page:

<CodeGroup>
  ```mustache Basic Breadcrumbs theme={null}
  <!-- Simple breadcrumb navigation -->
  <nav class="breadcrumbs">
      {{#breadcrumbs}}
          <a href="{{url}}">{{title}}</a>
          {{^last}} > {{/last}}
      {{/breadcrumbs}}
  </nav>
  ```

  ```mustache Styled Breadcrumbs theme={null}
  <!-- Enhanced breadcrumb navigation with styling -->
  <nav class="breadcrumb-navigation" aria-label="{{#lang}}Breadcrumb{{/lang}}">
      <ol class="breadcrumb-list">
          {{#breadcrumbs}}
          <li class="breadcrumb-item {{#last}}current{{/last}}">
              {{#last}}
                  <span aria-current="page">{{title}}</span>
              {{/last}}
              {{^last}}
                  <a href="{{url}}">{{title}}</a>
              {{/last}}
          </li>
          {{/breadcrumbs}}
      </ol>
  </nav>
  ```

  ```mustache Breadcrumbs with Icons theme={null}
  <!-- Breadcrumbs with separators and icons -->
  <nav class="breadcrumbs-with-icons">
      {{#breadcrumbs}}
          <span class="breadcrumb-item">
              {{^last}}
                  <a href="{{url}}" class="breadcrumb-link">
                      <span>{{title}}</span>
                  </a>
                  <i class="breadcrumb-separator">›</i>
              {{/last}}
              {{#last}}
                  <span class="breadcrumb-current">{{title}}</span>
              {{/last}}
          </span>
      {{/breadcrumbs}}
  </nav>
  ```
</CodeGroup>

### Breadcrumb Properties

Within the `{{#breadcrumbs}}` loop:

| Property | Type    | Description                                        |
| -------- | ------- | -------------------------------------------------- |
| `url`    | String  | Link URL for the breadcrumb item                   |
| `title`  | String  | Display text for the breadcrumb item               |
| `last`   | Boolean | True if this is the last (current) breadcrumb item |

## Asset Flags Wrapper (`{{#asset_flags}}`)

Return flag icons for languages (used within the languages loop):

<CodeGroup>
  ```mustache Language Selector with Flags theme={null}
  {{#shop.app.languages}}
  <div class="language-selector">
      <h4>{{#lang}}Choose Language{{/lang}}</h4>
      {{#shop.languages}}
      <a href="{{url}}" class="language-option">
          <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" 
               alt="{{id}}" 
               class="flag">
          {{id}}
      </a>
      {{/shop.languages}}
  </div>
  {{/shop.app.languages}}
  ```

  ```mustache Compact Language Switcher theme={null}
  {{#shop.app.languages}}
  <div class="lang-switcher">
      {{#shop.languages}}
      <a href="{{url}}" class="lang-link" title="{{id}}">
          <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" alt="{{id}}">
      </a>
      {{/shop.languages}}
  </div>
  {{/shop.app.languages}}
  ```

  ```mustache Language Dropdown theme={null}
  {{#shop.app.languages}}
  <div class="language-dropdown">
      <button class="language-toggle">
          {{#shop.languages}}
              {{#current}}
                  <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" alt="{{id}}">
                  {{id}}
              {{/current}}
          {{/shop.languages}}
      </button>
      
      <div class="language-options">
          {{#shop.languages}}
          <a href="{{url}}" class="language-option">
              <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" alt="{{id}}">
              {{id}}
          </a>
          {{/shop.languages}}
      </div>
  </div>
  {{/shop.app.languages}}
  ```
</CodeGroup>

## Combining Wrappers

### Complete Examples with Multiple Wrappers

<CodeGroup>
  ```mustache Product Card with All Wrappers theme={null}
  <div class="product-card">
      <!-- Product image with optimization -->
      <div class="product-image">
          {{#product.firstimage}}
              <img src="{{#img}}{{product.firstimage}}_300x300{{/img}}" alt="{{product.title}}">
          {{/product.firstimage}}
          {{^product.firstimage}}
              <img src="{{#assets}}images/no-image.png{{/assets}}" alt="{{#lang}}No image available{{/lang}}">
          {{/product.firstimage}}
      </div>
      
      <!-- Product information with translations -->
      <div class="product-info">
          <h3>{{product.title}}</h3>
          <p class="price">{{product.price}}</p>
          
          {{#product.soldOut}}
              <span class="status out-of-stock">{{#lang}}Out of Stock{{/lang}}</span>
          {{/product.soldOut}}
          
          {{^product.soldOut}}
              <button class="add-to-cart">{{#lang}}Add to Cart{{/lang}}</button>
          {{/product.soldOut}}
      </div>
  </div>
  ```

  ```mustache Complete Page Template theme={null}
  <!DOCTYPE html>
  <html>
  <head>
      <title>{{seo.title}}</title>
      <meta name="description" content="{{seo.description}}">
      
      <!-- Theme assets -->
      <link rel="stylesheet" href="{{#assets}}css/style.css{{/assets}}">
      <link rel="icon" href="{{#assets}}images/favicon.ico{{/assets}}">
  </head>
  <body>
      <header class="site-header">
          <!-- Logo -->
          <div class="logo">
              <a href="{{shop.url}}">
                  <img src="{{#assets}}images/logo.png{{/assets}}" alt="{{shop.name}}">
              </a>
          </div>
          
          <!-- Language selector -->
          {{#shop.app.languages}}
          <div class="language-selector">
              {{#shop.languages}}
              <a href="{{url}}">
                  <img src="{{#asset_flags}}{{id}}{{/asset_flags}}" alt="{{id}}">
              </a>
              {{/shop.languages}}
          </div>
          {{/shop.app.languages}}
          
          <!-- User account -->
          {{#shop.login_active}}
          <div class="account-links">
              {{#user.logged_in}}
                  <a href="{{user.login_url}}">{{#lang}}My Account{{/lang}}</a>
              {{/user.logged_in}}
              {{^user.logged_in}}
                  <a href="{{user.login_url}}">{{#lang}}Log In{{/lang}}</a>
              {{/user.logged_in}}
          </div>
          {{/shop.login_active}}
      </header>
      
      <!-- Breadcrumbs -->
      <nav class="breadcrumbs">
          {{#breadcrumbs}}
              <a href="{{url}}">{{title}}</a>
              {{^last}} > {{/last}}
          {{/breadcrumbs}}
      </nav>
      
      <main class="main-content">
          <!-- Page content here -->
      </main>
      
      <footer class="site-footer">
          <p>&copy; {{shop.name}}. {{#lang}}All rights reserved{{/lang}}.</p>
      </footer>
      
      <!-- Theme JavaScript -->
      <script src="{{#assets}}js/main.js{{/assets}}"></script>
  </body>
  </html>
  ```
</CodeGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Image Optimization" icon="image">
    Always use the `{{#img}}` wrapper with appropriate dimensions for optimal performance
  </Card>

  <Card title="Translation Consistency" icon="language">
    Wrap all user-facing text with `{{#lang}}` for proper multi-language support
  </Card>

  <Card title="Asset Management" icon="folder">
    Use `{{#assets}}` for all theme files to ensure correct paths across environments
  </Card>

  <Card title="Breadcrumb Navigation" icon="map">
    Implement breadcrumbs for better user navigation and SEO benefits
  </Card>
</CardGroup>

## Common Patterns

### Error Handling and Fallbacks

<CodeGroup>
  ```mustache Image Fallbacks theme={null}
  <!-- Product image with fallback -->
  {{#product.firstimage}}
      <img src="{{#img}}{{product.firstimage}}_400x400{{/img}}" alt="{{product.title}}">
  {{/product.firstimage}}
  {{^product.firstimage}}
      <img src="{{#assets}}images/placeholder.jpg{{/assets}}" alt="{{#lang}}No image available{{/lang}}">
  {{/product.firstimage}}
  ```

  ```mustache Content Fallbacks theme={null}
  <!-- Content with translation fallback -->
  {{#shop.contact_text}}
      <div class="contact-content">
          {{&shop.contact_text}}
      </div>
  {{/shop.contact_text}}
  {{^shop.contact_text}}
      <div class="contact-content">
          <p>{{#lang}}Contact information not available{{/lang}}</p>
      </div>
  {{/shop.contact_text}}
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Global Objects" icon="globe" href="/theme-development/global/shop">
    Learn how to use wrappers with global object data
  </Card>

  <Card title="Product Pages" icon="box" href="/theme-development/pages/product">
    Apply wrappers in product page templates
  </Card>

  <Card title="Template Structure" icon="file-code" href="/theme-development/template-structure">
    Understand how wrappers fit into overall theme architecture
  </Card>

  <Card title="Best Practices" icon="star" href="/theme-development/advanced/best-practices">
    Follow coding standards and optimization guidelines
  </Card>
</CardGroup>