RaffleX Marketplace
Log in
RaffleX Marketplace
Toggle sidebar
Reference

Template data contract

Every variable a marketplace game or block receives (contract version 2), in the preview here and on your Rafflex site. The samples are generated from the exact fixtures the preview renders with, so they never drift.

All Games Blocks
Games animate outcomes, they never invent them
Outcomes are pre-decided before your game runs. When there is nothing to reveal (the No plays scenario), plays is empty and your template must show a sensible empty state.

Using the data in JavaScript

Games do their logic in JavaScript over the injected data. The json filter turns any variable into inline JSON:

<script>
    const plays = {{ plays|json }};
    const settings = {{ settings|json }};
</script>

Tenant options

A block declares the fields a site owner can change by reading them from options with a default. Every option read becomes a field in their page builder; an option they have not set is simply missing, so your default applies in the preview and on the installed block alike.

<h2>{{ options.heading|default('Ending soon') }}</h2>
{% for competition in competitions.ending_soon|slice(0, options.limit|default(4)) %}
    <a href="{{ competition.url }}" style="background: {{ options.accent_colour|default(settings.primary_color) }};">{{ competition.title }}</a>
{% endfor %}
Field type
Option name
Text any other name
Long text body, description, intro, content, or ending _body, _description, _intro, _content
Colour colour, color, or ending _colour, _color
Image image, or ending _image
Link url, link, or ending _url, _link
Toggle starting show_, hide_, enable_, is_, has_, or ending _enabled; or a true/false default (always arrives as true or false, so a true default can be switched off)
Number count, limit, columns, or ending _count, _limit, _columns, _number; or a numeric default
Categories added by the platform whenever the template reads competitions, categories, or products; never read it (the site owner ticks categories and every competition list arrives already narrowed to them)
Repeater any option the template loops over with {% for item in options.key %}
  • Loop directly over an option to make it a repeater; each key read from the loop variable becomes a field on every item, and a list default supplies the starting items.
  • Every block that reads competitions, categories, or products gets a standard Categories filter. When the site owner ticks categories, every competitions list, categories, and products arrive already narrowed to them; with none ticked nothing is filtered. Templates never read it, so the same template works either way.
  • A toggle always arrives as true or false, so a true default can still be switched off.

Preview scenarios

The preview toolbar reseeds plays deterministically per scenario, so a state you are debugging looks identical on every reload:

Mixed
All win
All lose
Big win
No plays

Referencing uploaded media

Add files to your product's media library in the studio's Media panel, then reference each one by its tag. When a buyer installs your asset, the files map travels with it, so every reference resolves to its hosted URL. A files entry can point at an image, audio, a 3D model (.glb), or an approved library build.

<img src="{{ files['background'] }}" alt="">
<audio src="{{ files['win-jingle'] }}"></audio>
<script type="module">
    import * as THREE from "{{ files['three'] }}";
    new THREE.GLTFLoader().load("{{ files['prize-box'] }}", (gltf) => scene.add(gltf.scene));
</script>