Custom Twig Block

The Custom Twig Block is the most flexible block in the page builder. It lets you create completely custom layouts by defining your own variables and writing HTML with Twig templating.

How It Works

1. Add the block - In the page builder, add a "Custom Twig Block"

2. Define variables - Create the data you need (text, images, products, etc.)

3. Write your template - Use HTML and Twig syntax to display your variables

4. Save and preview - See your custom layout on the page

Creating Variables

Click "Add Variable" to create each piece of data you need. Each variable has:

• Variable Name - The name you'll use in your template (e.g., headline, products, show_banner)

• Type - What kind of data it holds

• Value - The actual content

Variable Naming Rules

• Use letters and numbers only (no spaces or special characters)

• Names are case-sensitive (Title and title are different)

• Keep names short and descriptive

• Examples: headline, button_text, featured_products, show_prices

Variable Types

Text

A single line of text.

Use for: Headlines, button text, short labels

In your template:

<h1>{{ headline }}</h1>
<a href="#">{{ button_text }}</a>

Text Area

Multiple lines of text.

Use for: Descriptions, paragraphs, longer content

In your template:

<p>{{ description }}</p>

Number

A numeric value.

Use for: Counts, prices, quantities, percentages

In your template:

<p>{{ item_count }} items available</p>
<div style="width: {{ progress }}%;"></div>

Boolean (Yes/No)

A true or false toggle.

Use for: Showing/hiding sections, enabling features

In your template:

{% if show_banner %}
  <div>Special Offer!</div>
{% endif %}

{% if show_prices %}
  <span>{{ product.price }}</span>
{% endif %}

Color

A colour picker that outputs a hex code.

Use for: Custom styling, backgrounds, text colours

In your template:

<style>
  .custom-section { background-color: {{ background_color }}; }
  .custom-title { color: {{ text_color }}; }
</style>

<div class="custom-section">
  <h2 class="custom-title">{{ title }}</h2>
</div>

Date & Time

A date and time picker.

Use for: Event dates, deadlines, announcements, scheduled times

In your template:

<p>Event Date: {{ event_date }}</p>
<p>Offer ends: {{ end_date|date('F j, Y') }}</p>
<p>Draw time: {{ draw_time|date('g:ia') }}</p>
<p>Full datetime: {{ event_datetime|date('F j, Y \\a\\t g:ia') }}</p>

URL

A web address.

Use for: Links, buttons, external resources

In your template:

<a href="{{ learn_more_url }}">Learn More</a>
<a href="{{ facebook_url }}">Follow us on Facebook</a>

Image

An image uploader.

Use for: Hero images, logos, backgrounds, icons

In your template:

<img src="{{ hero_image }}" alt="{{ title }}">
<div style="background-image: url('{{ background_image }}');"></div>

Gallery

Upload up to 20 images with drag-and-drop reordering.

Use for: Image galleries, winner photos, team members, portfolios

Gallery Item Fields:

Field	Description	Example
url	Full URL to the image	"https://..."
name	Image file name	"photo1.jpg"

In your template:

{% if my_gallery|length > 0 %}
<div class="grid grid-cols-3 gap-4">
  {% for image in my_gallery %}
    <img src="{{ image.url }}" alt="{{ image.name }}" class="rounded-lg">
  {% endfor %}
</div>
{% endif %}

Custom Fields

Define named key-value pairs for flexible data.

Use for: Contact details, metadata, configuration options, simple structured data

In your template:

{# Access specific fields by name #}
<p>Name: {{ contact.name }}</p>
<p>Email: {{ contact.email }}</p>
<p>Phone: {{ contact.phone }}</p>

{# Or loop through all fields #}
<dl>
  {% for key, value in contact %}
    <dt>{{ key }}</dt>
    <dd>{{ value }}</dd>
  {% endfor %}
</dl>

JSON

Custom structured data for advanced use cases.

Use for: Lists of items, social links, feature lists, any repeating data

Example JSON:

[
  {"name": "Facebook", "url": "https://facebook.com/mypage", "icon": "fab fa-facebook"},
  {"name": "Instagram", "url": "https://instagram.com/mypage", "icon": "fab fa-instagram"},
  {"name": "Twitter", "url": "https://twitter.com/mypage", "icon": "fab fa-twitter"}
]

In your template:

{% for link in social_links %}
  <a href="{{ link.url }}">
    <i class="{{ link.icon }}"></i> {{ link.name }}
  </a>
{% endfor %}

Products

Pull competitions directly from your database with powerful filtering.

Selection Modes:

1. Use Filters - Automatically select products based on criteria

2. Select Specific - Manually choose exact products

Filter Options (when using filters):

Option	Description
Status	Active Only, or Inactive Only
Categories	Select one or more categories to filter by
Sliders Only	Only show products marked as featured/slider
Sort By	How to order the results (see below)
Limit	Maximum number of products to show

Sort Options:

• Ending Soon First

• Ending Last First

• Draw Date (Soonest)

• Draw Date (Latest)

• Price (Low to High)

• Price (High to Low)

• Title (A-Z)

• Title (Z-A)

• Newest First

• Manual Sort Order

Product Fields Available:

Field	Description	Example
id	Product ID	123
title	Product name	"Win a BMW M3"
subtitle	Product subtitle	"Competition of the Month"
url	Link to product page	"/product/win-a-bmw-m3"
image_url	Featured product image	Full URL to image
slider_image_url	Slider/hero image	Full URL to image
portrait_image_url	Portrait/vertical image	Full URL to image
featured_video_url	Featured video URL (if uploaded)	Full URL or null
video_embed_url	Player address for the competition's Video URL (null if none)	"https://www.youtube-nocookie.com/embed/..."
video_embed_type	"iframe" for YouTube or Vimeo, "video" for a video file	"iframe"
video_embed_mime_type	File type for a video file (null for YouTube or Vimeo)	"video/mp4"
video_embed_orientation	"portrait" for YouTube Shorts, otherwise "landscape"	"landscape"
price	Current price (formatted)	"£1.99"
price_display	Pretty current price ("Free", "50p")	"£1.99"
price_raw	Current price as a number	1.99
original_price	Original price if on sale (formatted)	"£2.99"
original_price_raw	Original price as a number	2.99
is_on_sale	Whether product is on sale	true/false
is_free	Whether the product is free to enter	true/false
cash_alt	Cash alternative (formatted)	"£50,000"
cash_alt_raw	Cash alternative as a number	50000
draw_date	Human readable draw date	"Draw On Mon Jan 5th 7:00pm"
end_date	Human readable end date	"Today 7:00pm"
draw_date_raw	ISO draw date	"2026-01-05 19:00:00"
end_date_raw	ISO end date	"2026-01-05 19:00:00"
start_date_raw	ISO start date	"2026-01-01 09:00:00"
start_date	Human readable start date	"Tomorrow 9:00am"
start_date_seconds	Seconds until the competition opens (0 once open)	7200
has_started	Whether the start date has passed	true/false
end_date_seconds	Seconds until end (for countdown)	3600
draw_date_seconds	Seconds until draw	86400
max_tickets	Total tickets available	5000
sold_tickets	Tickets sold	3421
tickets_remaining	Tickets left to sell	1579
percent_sold	Percentage of tickets sold	68.4
max_per_user	Max tickets per user (0 means no limit)	50
instant_wins	Number of instant wins	5
instant_wins_remaining	Remaining instant wins not yet won	3
game_type	Type of game	"standard"
has_ended	Whether competition ended	true/false
is_sold_out	Whether the product is sold out	true/false
is_active	Whether the product is active	true/false
is_featured	Whether the product is in the slider	true/false
winner_qty	Number of winners	1
auto_draw	Whether the draw happens automatically	true/false
leaderboard_enabled	Whether the product has a leaderboard	true/false
has_question	Whether the product has an entry question	true/false
question	The entry question text (if any)	"What colour is the sky?"
category	First category name	"Cars"
categories	All category names (array)	["Cars", "Featured"]
description	Product description	"Win this amazing..."
gallery	Array of gallery image URLs	["https://...", "https://..."]

Video with Image Fallback:

{% if product.featured_video_url %}
  <video autoplay loop muted playsinline poster="{{ product.image_url }}" class="w-full">
    <source src="{{ product.featured_video_url }}" type="video/mp4">
  </video>
{% else %}
  <img src="{{ product.image_url }}" alt="{{ product.title }}" class="w-full">
{% endif %}

Video URL Embed:

When a competition has a Video URL set in its Optional Extras, the video_embed_* fields give you everything needed to show it. YouTube and Vimeo links play in an iframe, while a direct video file plays in a video tag.

{% if product.video_embed_url %}
  {% if product.video_embed_type == 'iframe' %}
    {% if product.video_embed_orientation == 'portrait' %}
      {% set ratio = '9 / 16' %}
    {% else %}
      {% set ratio = '16 / 9' %}
    {% endif %}
    <div style="aspect-ratio: {{ ratio }}; width: 100%;">
      <iframe src="{{ product.video_embed_url }}" style="width: 100%; height: 100%; border: 0;" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen loading="lazy"></iframe>
    </div>
  {% else %}
    <video controls playsinline preload="metadata" style="width: 100%;">
      <source src="{{ product.video_embed_url }}" type="{{ product.video_embed_mime_type }}">
    </video>
  {% endif %}
{% endif %}

Scheduled Competitions (Coming Soon):

A competition with a future Start Date (Scheduler) has has_started set to false. Filtered product lists only include competitions that have started, so this is mainly useful when you pick specific competitions in a Products variable. Use start_date_seconds to count down to the opening time.

{% if not product.has_started %}
  <p>Entries open {{ product.start_date }}</p>
  <div x-data="raffleCountdown({{ product.start_date_seconds }})">
    <span x-text="time.days"></span>d
    <span x-text="pad(time.hours)"></span>h
    <span x-text="pad(time.minutes)"></span>m
    <span x-text="pad(time.seconds)"></span>s
  </div>
{% else %}
  <a href="{{ product.url }}">Enter Now</a>
{% endif %}

In your template:

{% for product in featured_products %}
  <div>
    <img src="{{ product.image_url }}" alt="{{ product.title }}">
    <h3>{{ product.title }}</h3>
    <p>{{ product.subtitle|default('') }}</p>

    {% if product.is_on_sale %}
      <span style="text-decoration: line-through;">{{ product.original_price }}</span>
      <span style="color: red;">{{ product.price }}</span>
    {% else %}
      <span>{{ product.price }}</span>
    {% endif %}

    <p>Draw: {{ product.draw_date }}</p>
    <p>Cash Alt: {{ product.cash_alt }}</p>
    <p>{{ product.sold_tickets }} / {{ product.max_tickets }} sold</p>

    <a href="{{ product.url }}">Enter Now</a>
  </div>
{% endfor %}

Winners

Display recent winners from your site.

Options:

• Number of Recent Winners - How many winners to fetch (default: 5)

Winner Fields Available:

Field	Description	Example
name	Winner's display name	"John S."
prize	What they won	"BMW M3"
product_title	Competition name	"Win a BMW M3"
product_url	Link to competition	"/product/win-a-bmw-m3"
product_image	Competition image	Full URL to image
date	Win date	"Jan 5, 2025"
date_ago	Time since win	"2 days ago"

In your template:

{% for winner in recent_winners %}
  <div>
    <img src="{{ winner.product_image }}" alt="{{ winner.product_title }}">
    <h3>{{ winner.name }}</h3>
    <p>Won: {{ winner.prize }}</p>
    <p>{{ winner.date_ago }}</p>
    <a href="{{ winner.product_url }}">View Competition</a>
  </div>
{% endfor %}

Instant Winners

Display recent instant win winners from your site.

Options:

Option	Description
Number of Winners	How many instant winners to fetch (default: 5, max: 20)
Minimum Value	Only show instant wins with prizes above this value (optional)

Note: Only fetches instant wins from the last 30 days.

Instant Winner Fields Available:

Field	Description	Example
winner_name	Winner's display name	"JohnS"
prize	Prize name/description	"£10 Site Credit"
prize_value	Prize value (formatted)	"10.00"
prize_value_raw	Prize value (number)	10.00
is_site_credit	Whether prize is site credit	true/false
product_title	Related competition name	"Win a BMW M3"
product_url	Link to competition	"/product/win-a-bmw-m3"
product_image	Competition image URL	Full URL to image
date	Win date	"Jan 5, 2025"
date_ago	Time since win	"2 hours ago"

In your template:

{% for winner in instant_winners %}
  <div>
    <img src="{{ winner.product_image }}" alt="{{ winner.product_title }}">
    <h3>{{ winner.winner_name }} won!</h3>
    <p>{{ winner.prize }}</p>
    {% if winner.prize_value %}
      <p>Value: £{{ winner.prize_value }}</p>
    {% endif %}
    <p>{{ winner.date_ago }}</p>
  </div>
{% endfor %}

User (Current Logged In)

The current visitor's account information. Returns guest data if not logged in.

User Fields Available:

Field	Description	Example
id	User ID (null if guest)	123
name	First name	"John"
last_name	Last name	"Smith"
full_name	Full name	"John Smith"
display_name	Display name (or "Guest")	"JohnS"
email	Email address	"[email protected]"
is_logged_in	Whether logged in	true/false
balance	Site credit balance (formatted)	"£25.00"
balance_raw	Site credit balance (number, 0 for guests)	25.00
cash_balance	Cash wallet balance (formatted, null for guests)	"£10.00"
cash_balance_raw	Cash wallet balance (number, 0 for guests)	10.00
total_balance	Site credit plus cash wallet (formatted, null for guests)	"£35.00"
total_balance_raw	Site credit plus cash wallet (number, 0 for guests)	35.00

In your template:

{% if user.is_logged_in %}
  <div>
    <p>Welcome back, {{ user.display_name }}!</p>
    <p>Your balance: {{ user.balance }}</p>
  </div>
{% else %}
  <div>
    <p>Please <a href="/login">log in</a> to see your balance</p>
  </div>
{% endif %}

Filters Reference

Transform your data using filters:

Filter	Example	Result
upper	{{ name|upper }}	JOHN
lower	{{ name|lower }}	john
default	{{ subtitle|default('None') }}	Fallback if empty
length	{{ products|length }}	Number of items
first	{{ products|first }}	First item
last	{{ products|last }}	Last item
join	{{ tags|join(', ') }}	Comma-separated
slice	{{ products|slice(0, 3) }}	First 3 items
trim	{{ text|trim }}	Remove whitespace
round	{{ 3.7|round }}	4
number_format	{{ 1234.5|number_format(2) }}	1,234.50
date	{{ my_date|date('M j, Y') }}	Jan 5, 2025

Complete Examples

Hero Section with Products

Variables needed:

• headline (Text): "This Week's Top Prizes"

• subheadline (Text): "Don't miss out on these amazing competitions"

• background_color (Color): #1a1a2e

• text_color (Color): #ffffff

• featured_products (Products): Filter by Featured, Limit 3

Template:

<style>
  .hero-section {
    background-color: {{ background_color }};
    color: {{ text_color }};
    padding: 60px 20px;
  }
  .hero-container {
    max-width: 1200px;
    margin: 0 auto;
    text-align: center;
  }
  .hero-title {
    font-size: 36px;
    margin-bottom: 10px;
  }
  .hero-subtitle {
    font-size: 18px;
    margin-bottom: 40px;
  }
  .hero-grid {
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    gap: 30px;
  }
  .hero-card {
    background: #16213e;
    border-radius: 12px;
    overflow: hidden;
  }
  .hero-card img {
    width: 100%;
    height: 200px;
    object-fit: cover;
  }
  .hero-card-content {
    padding: 20px;
  }
  .hero-card h3 {
    font-size: 20px;
    margin-bottom: 10px;
  }
  .hero-card .price {
    color: #4ade80;
    font-size: 24px;
    font-weight: bold;
  }
  .hero-card .date {
    color: #9ca3af;
    font-size: 14px;
  }
  .hero-card .btn {
    display: block;
    margin-top: 15px;
    background: #4ade80;
    color: #000;
    padding: 12px;
    border-radius: 8px;
    text-decoration: none;
    font-weight: bold;
  }
</style>

<section class="hero-section">
  <div class="hero-container">
    <h1 class="hero-title">{{ headline }}</h1>
    <p class="hero-subtitle">{{ subheadline }}</p>

    <div class="hero-grid">
      {% for product in featured_products %}
        <div class="hero-card">
          <img src="{{ product.image_url }}" alt="{{ product.title }}">
          <div class="hero-card-content">
            <h3>{{ product.title }}</h3>
            <p class="price">{{ product.price }}</p>
            <p class="date">{{ product.end_date }}</p>
            <a href="{{ product.url }}" class="btn">Enter Now</a>
          </div>
        </div>
      {% endfor %}
    </div>
  </div>
</section>

Winners Carousel

Variables needed:

• title (Text): "Recent Winners"

• show_title (Boolean): Yes

• recent_winners (Winners): 6 winners

Template:

<style>
  .winners-section {
    background: #0f0f23;
    padding: 50px 20px;
  }
  .winners-container {
    max-width: 1200px;
    margin: 0 auto;
  }
  .winners-title {
    color: white;
    font-size: 28px;
    text-align: center;
    margin-bottom: 30px;
  }
  .winners-scroll {
    display: flex;
    gap: 20px;
    overflow-x: auto;
    padding-bottom: 20px;
  }
  .winner-card {
    flex-shrink: 0;
    width: 220px;
    background: #1a1a3e;
    border-radius: 12px;
    padding: 20px;
    text-align: center;
  }
  .winner-card img {
    width: 100px;
    height: 100px;
    border-radius: 50%;
    object-fit: cover;
    margin: 0 auto 15px;
  }
  .winner-card h3 {
    color: white;
    font-size: 18px;
    margin-bottom: 5px;
  }
  .winner-card .prize {
    color: #4ade80;
    font-size: 16px;
    margin-bottom: 5px;
  }
  .winner-card .date {
    color: #6b7280;
    font-size: 13px;
  }
</style>

<section class="winners-section">
  <div class="winners-container">
    {% if show_title %}
      <h2 class="winners-title">{{ title }}</h2>
    {% endif %}

    <div class="winners-scroll">
      {% for winner in recent_winners %}
        <div class="winner-card">
          <img src="{{ winner.product_image }}" alt="{{ winner.product_title }}">
          <h3>{{ winner.name }}</h3>
          <p class="prize">{{ winner.prize }}</p>
          <p class="date">{{ winner.date_ago }}</p>
        </div>
      {% endfor %}
    </div>
  </div>
</section>

Promotional Banner

Variables needed:

• show_banner (Boolean): Yes

• banner_headline (Text): "Flash Sale!"

• banner_text (Text): "50% off all entries for the next 24 hours"

• banner_color (Color): #dc2626

• banner_link (URL): /competitions

Template:

<style>
  .promo-banner {
    background: {{ banner_color }};
    padding: 20px;
    text-align: center;
  }
  .promo-banner h2 {
    color: white;
    font-size: 24px;
    margin: 0 0 10px 0;
  }
  .promo-banner p {
    color: white;
    font-size: 16px;
    margin: 0 0 15px 0;
  }
  .promo-banner .btn {
    display: inline-block;
    background: white;
    color: {{ banner_color }};
    padding: 12px 30px;
    border-radius: 6px;
    text-decoration: none;
    font-weight: bold;
  }
</style>

{% if show_banner %}
<div class="promo-banner">
  <h2>{{ banner_headline }}</h2>
  <p>{{ banner_text }}</p>
  <a href="{{ banner_link }}" class="btn">Shop Now</a>
</div>
{% endif %}

Social Links Bar

Variables needed:

• social_links (JSON):

[
  {"name": "Facebook", "url": "https://facebook.com/mysite", "icon": "fab fa-facebook-f"},
  {"name": "Instagram", "url": "https://instagram.com/mysite", "icon": "fab fa-instagram"},
  {"name": "Twitter", "url": "https://twitter.com/mysite", "icon": "fab fa-twitter"},
  {"name": "TikTok", "url": "https://tiktok.com/@mysite", "icon": "fab fa-tiktok"}
]

Template:

<style>
  .social-bar {
    background: #111;
    padding: 20px;
    text-align: center;
  }
  .social-bar p {
    color: #9ca3af;
    margin-bottom: 15px;
  }
  .social-links {
    display: flex;
    justify-content: center;
    gap: 15px;
  }
  .social-link {
    display: flex;
    align-items: center;
    justify-content: center;
    width: 45px;
    height: 45px;
    background: #222;
    border-radius: 50%;
    color: white;
    text-decoration: none;
  }
  .social-link:hover {
    background: #333;
  }
</style>

<div class="social-bar">
  <p>Follow us on social media</p>
  <div class="social-links">
    {% for link in social_links %}
      <a href="{{ link.url }}" class="social-link" target="_blank">
        <i class="{{ link.icon }}"></i>
      </a>
    {% endfor %}
  </div>
</div>

Dynamic Components

Custom Twig templates have access to reusable Alpine.js components for interactive elements like countdown timers and progress bars.

Countdown Timer

Display a live countdown to the competition end time.

<div x-data="raffleCountdown({{ product.end_date_seconds }})" class="countdown">
  <span x-text="time.days"></span>d
  <span x-text="pad(time.hours)"></span>h
  <span x-text="pad(time.minutes)"></span>m
  <span x-text="pad(time.seconds)"></span>s
</div>

Note: Use end_date_seconds (not end_date_raw) to avoid timezone issues. The seconds are calculated server-side.

With ended state handling:

<div x-data="raffleCountdown({{ product.end_date_seconds }})">
  <template x-if="!hasEnded">
    <div class="countdown">
      <span x-text="time.days"></span>d
      <span x-text="pad(time.hours)"></span>h
      <span x-text="pad(time.minutes)"></span>m
      <span x-text="pad(time.seconds)"></span>s
    </div>
  </template>
  <template x-if="hasEnded">
    <span>Competition Ended</span>
  </template>
</div>

Available properties:

Property	Description
time.days	Days remaining
time.hours	Hours remaining (0-23)
time.minutes	Minutes remaining (0-59)
time.seconds	Seconds remaining (0-59)
hasEnded	Boolean, true when countdown reaches zero
pad(num)	Function to zero-pad numbers (e.g., "05")

Progress Bar

Display ticket sales progress with visual feedback.

<div x-data="raffleProgress({{ product.percent_sold }})" class="progress-bar">
  <div class="progress-fill" :style="'width:' + width + '%'"></div>
</div>
<p>{{ product.percent_sold|round(1) }}% sold</p>

Available properties:

Property	Description
percent	The percentage value (0-100)
width	Display width (minimum 3% for visibility when nearly empty)

Quick Add to Cart

Add a working "add to basket" control to a product card, with a quantity selector and loading/success/error states. The component handles adding tickets to the basket and updating the cart count for you.

<div x-data="raffleQuickAdd({
  productId: {{ product.id }},
  price: {{ product.price_raw }},
  maxTickets: {{ product.max_per_user > 0 ? product.max_per_user : 100 }},
  hasQuestion: {{ product.has_question ? 'true' : 'false' }},
  hasEnded: {{ product.has_ended ? 'true' : 'false' }}
})">
  <button @click="decrement" :disabled="tickets <= 1">-</button>
  <span x-text="tickets"></span>
  <button @click="increment" :disabled="tickets >= maxTickets">+</button>

  <button @click="addToCart" :disabled="!canAdd">
    <span x-show="!loading">Quick Add</span>
    <span x-show="loading">Adding...</span>
  </button>

  <span x-show="added" x-transition>Added!</span>
  <span x-show="error" x-text="errorMessage"></span>
</div>

Configuration (passed in when you create the component):

Option	Description
productId	The competition to add (product.id)
price	The ticket price as a number (product.price_raw), used to pick a sensible default quantity
maxTickets	The most tickets the buttons allow (defaults to 100)
hasQuestion	If the competition has an entry question, quick add is disabled (the customer must use the full product page)
hasEnded	If the competition has ended, quick add is disabled

Available properties and actions:

Property / Action	Description
tickets	The currently selected quantity
increment()	Add one ticket (up to maxTickets)
decrement()	Remove one ticket (down to 1)
addToCart()	Add the selected tickets to the basket
loading	True while the add is in progress
added	True briefly after a successful add
error	True if the add failed
errorMessage	The message to show when there is an error
canAdd	True when the control is ready to add (not loading, not ended, no question, quantity in range)

Competitions that use an entry question, or that have ended, cannot be added this way. For those, link the customer to the full product page instead.

Cart Count (Headless)

Show a live basket count, typically in a custom header or footer. It updates automatically whenever something is added to the cart (including via Quick Add above), without making extra requests.

<div x-data="raffleBasket({ initialCount: {{ cart_count }} })">
  <a href="{{ urls.basket }}">
    <svg><!-- your cart icon --></svg>
    <span x-show="hasItems" x-cloak x-transition x-text="count"></span>
  </a>
</div>

Available properties:

Property	Description
count	The current number of items in the basket
hasItems	True when there is at least one item

The cart_count and urls variables used here come from the custom header and footer Twig templates (the Layout templates), not the page builder block. Use raffleBasket there. The raffleQuickAdd component above works anywhere you render a product, including page builder blocks. See Header and Footer Variables for everything available in those templates.

Complete Card with Dynamic Components

Variables needed:

• products (Products): Filter by Active, Limit 6

Template:

<style>
  .dynamic-card {
    background: #1a1a2e;
    border-radius: 12px;
    overflow: hidden;
  }
  .dynamic-card img {
    width: 100%;
    height: 200px;
    object-fit: cover;
  }
  .dynamic-card-body {
    padding: 20px;
  }
  .dynamic-card h3 {
    color: white;
    margin: 0 0 10px;
    font-size: 18px;
  }
  .dynamic-card .price {
    color: #4ade80;
    font-size: 24px;
    font-weight: bold;
  }
  .dynamic-card .countdown {
    display: flex;
    gap: 8px;
    color: #9ca3af;
    font-size: 14px;
    margin: 15px 0;
  }
  .dynamic-card .countdown span {
    background: #16213e;
    padding: 4px 8px;
    border-radius: 4px;
  }
  .dynamic-card .progress-bar {
    height: 8px;
    background: #374151;
    border-radius: 4px;
    overflow: hidden;
    margin-top: 15px;
  }
  .dynamic-card .progress-fill {
    height: 100%;
    background: #4ade80;
    border-radius: 4px;
    transition: width 0.3s ease;
  }
  .dynamic-card .stats {
    color: #9ca3af;
    font-size: 12px;
    margin-top: 8px;
  }
  .dynamic-card .badge {
    display: inline-block;
    background: #fbbf24;
    color: #000;
    padding: 4px 8px;
    border-radius: 4px;
    font-size: 12px;
    font-weight: bold;
    margin-top: 10px;
  }
  .dynamic-card .btn {
    display: block;
    margin-top: 15px;
    background: #4ade80;
    color: #000;
    padding: 12px;
    border-radius: 8px;
    text-decoration: none;
    font-weight: bold;
    text-align: center;
  }
  .dynamic-grid {
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    gap: 20px;
    max-width: 1200px;
    margin: 0 auto;
    padding: 40px 20px;
  }
</style>

<div class="dynamic-grid">
  {% for product in products %}
    <div class="dynamic-card">
      <img src="{{ product.image_url }}" alt="{{ product.title }}">
      <div class="dynamic-card-body">
        <h3>{{ product.title }}</h3>
        <p class="price">{{ product.price }}</p>

        <!-- Live Countdown Timer -->
        <div x-data="raffleCountdown({{ product.end_date_seconds }})" class="countdown">
          <span x-text="time.days + 'd'"></span>
          <span x-text="pad(time.hours) + 'h'"></span>
          <span x-text="pad(time.minutes) + 'm'"></span>
          <span x-text="pad(time.seconds) + 's'"></span>
        </div>

        <!-- Progress Bar -->
        <div x-data="raffleProgress({{ product.percent_sold }})" class="progress-bar">
          <div class="progress-fill" :style="'width:' + width + '%'"></div>
        </div>
        <p class="stats">{{ product.sold_tickets }}/{{ product.max_tickets }} tickets sold</p>

        <!-- Instant Wins Badge -->
        {% if product.instant_wins > 0 %}
          <span class="badge">{{ product.instant_wins }} Instant Wins ({{ product.instant_wins_remaining }} left)</span>
        {% endif %}

        <a href="{{ product.url }}" class="btn">Enter Now</a>
      </div>
    </div>
  {% endfor %}
</div>

Tips

• Start simple - Begin with a few variables and expand as needed

• Use meaningful names - hero_headline is clearer than text1

• Test with real data - Make sure your products/winners display correctly

• Use conditionals - Hide empty sections with {% if variable %}...{% endif %}

• Use the default filter - Handle empty values gracefully: {{ subtitle|default('') }}

Need Help?

Copy this documentation along with your question and share it with an AI assistant (like ChatGPT or Claude). The AI can help you write templates, troubleshoot issues, and create custom layouts.

---

AI Context

For AI Assistants: This documents the RaffleX Custom Twig Block for page builder. Help users create custom HTML layouts.

Block Capabilities:

• User defines variables via admin repeater

• User writes HTML + Twig in code editor

• Output renders on frontend

Variable Types: text, textarea, number, boolean, color, date & time, url, image, gallery, key_value (custom fields), json, products, winners, instant_winners, user

Products Variable:

• Filter mode: status (active/inactive), categories (multi-select), featured toggle, sort options, limit

• Specific mode: manually select products by ID

• Returns array with: id, title, subtitle, slug, url, image_url, featured_video_url, video_embed_url, video_embed_type, video_embed_mime_type, video_embed_orientation, slider_image_url, portrait_image_url, price, price_raw, price_display, original_price, original_price_raw, is_on_sale, is_free, has_question, question, cash_alt, cash_alt_raw, draw_date, end_date, start_date, start_date_raw, start_date_seconds, has_started, draw_date_raw, end_date_raw, end_date_seconds, draw_date_seconds, max_tickets, sold_tickets, tickets_remaining, percent_sold, max_per_user, instant_wins, instant_wins_remaining, game_type, has_ended, is_sold_out, is_active, is_featured, auto_draw, leaderboard_enabled, simple_max_ticket, winner_qty, category, categories, description, gallery

Winners Variable:

• Set count of recent winners to fetch

• Returns array with: name, prize, product_title, product_url, product_image, date, date_ago

Instant Winners Variable:

• Set count of recent instant winners to fetch (default: 5, max: 20)

• Optional minimum value filter

• Only fetches wins from last 30 days

• Returns array with: winner_name, prize, prize_value, prize_value_raw, is_site_credit, product_title, product_url, product_image, date, date_ago

User Variable:

• Returns current logged-in user data, or guest data if not authenticated

• Returns object with: id, name, last_name, full_name, display_name, email, is_logged_in, balance, balance_raw (site credit), cash_balance, cash_balance_raw, total_balance, total_balance_raw (site credit plus cash wallet)

Gallery Variable:

• Up to 20 images with reordering

• Returns array with: url, name

Available Twig Tags: if, for, set

Available Filters: upper, lower, date, number_format, default, length, first, last, join, slice, round, trim, escape

Dynamic Alpine Components:

• raffleCountdown(seconds) - Live countdown timer. Pass end_date_seconds (server-calculated). Properties: time.days, time.hours, time.minutes, time.seconds, hasEnded, pad(num)

• raffleProgress(percent) - Progress bar. Properties: percent, width (min 3% for visibility)

• raffleQuickAdd(config) - Add-to-basket control with quantity selector. Config: productId, price (use price_raw), maxTickets (default 100), hasQuestion, hasEnded. Properties/actions: tickets, increment(), decrement(), addToCart(), loading, added, error, errorMessage, canAdd. Disabled when the competition has an entry question or has ended.

• raffleBasket(config) - Headless live cart count for custom headers/footers. Config: initialCount (use cart_count, available in the header/footer Layout Twig context, not the page builder block). Properties: count, hasItems. Updates automatically on cart changes, no extra requests.

• Usage: <div x-data="raffleCountdown({{ product.end_date_seconds }})">

Key notes:

1. Prices are pre-formatted with currency symbols (e.g., "£1.99")

2. Dates like draw_date and end_date are human-readable strings

3. Use |default() for optional fields

4. HTML is auto-escaped for security

5. Use a <style> block before HTML for styling (can include Twig variables for dynamic colours)

6. FontAwesome icons are available (e.g., fab fa-facebook)

7. Use end_date_seconds for countdown timers (server-calculated seconds), end_date for display

8. Filtered product lists only include competitions that have started. Use has_started and start_date_seconds to show a coming soon countdown for specifically selected competitions

Copyable Template Starter:

<style>
  .custom-section {
    padding: 40px 20px;
    background: #1a1a2e;
  }
  .custom-container {
    max-width: 1200px;
    margin: 0 auto;
  }
  .custom-title {
    color: white;
    font-size: 28px;
    text-align: center;
    margin-bottom: 30px;
  }
  .custom-grid {
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    gap: 20px;
  }
  .custom-card {
    background: #16213e;
    border-radius: 8px;
    padding: 20px;
    text-align: center;
  }
  .custom-card img {
    width: 100%;
    border-radius: 8px;
    margin-bottom: 15px;
  }
  .custom-card h3 {
    color: white;
    font-size: 18px;
    margin-bottom: 10px;
  }
  .custom-card .price {
    color: #4ade80;
    font-size: 20px;
    font-weight: bold;
    margin-bottom: 10px;
  }
  .custom-card .date {
    color: #9ca3af;
    font-size: 14px;
    margin-bottom: 15px;
  }
  .custom-card .btn {
    display: inline-block;
    background: #4ade80;
    color: #000;
    padding: 10px 20px;
    border-radius: 6px;
    text-decoration: none;
    font-weight: bold;
  }
</style>

<section class="custom-section">
  <div class="custom-container">
    <h2 class="custom-title">{{ title }}</h2>

    <div class="custom-grid">
      {% for product in products %}
        <div class="custom-card">
          <img src="{{ product.image_url }}" alt="{{ product.title }}">
          <h3>{{ product.title }}</h3>
          <p class="price">{{ product.price }}</p>
          <p class="date">{{ product.end_date }}</p>
          <a href="{{ product.url }}" class="btn">Enter Now</a>
        </div>
      {% endfor %}
    </div>
  </div>
</section>

---

See also:

• Settings Variables for the global settings available in all Twig templates

• Custom Twig Product Grid for building custom competition cards

• Custom Twig Slider for building a custom hero section