Embed Tokens & CSS Reference

Overview

Luster is embed-only. That means you make the public page on your own site, then place the Luster feature inside it with a PHP require.

Quick Mental Model

Token names are local to their template. A token only works in the template section where it is listed, even if another section has a token with the same name.

Most tokens print safe text. Tokens ending in _html, plus the form-wrapper token {input}, print real HTML because they are meant to create page markup.

Embed Overview

Note: stats.php, latest-listing.php, random-listing.php, and collective-stats.php print only the template content. If you want one outer wrapper around them, add it in your own template or page.

Snippet PHP Variables

These are PHP settings you place above the require line. They tell the embed what to show before Luster starts printing anything.

Token Syntax

All tokens use single curly braces. Write the token in your template, and Luster swaps it for the real value when the embed loads.

Listing Stats Tokens

Used by the stats_template setting, $luster_stats_template snippet variable, and public/embed/stats.php.

Related CSS: .fl-stats, .fl-stats-grid, .fl-stats-label, .fl-stats-value, .fl-stat-newmembers, .fl-stat-approved-by.

Choosing the right network conditional

Use {if_approved_by} when the same message works for both TFL and TAFL. Use {if_tfl} and {if_tafl} only when each network needs different text or a different link:

<!-- Same content for both networks — use {if_approved_by} -->
{if_approved_by}<b>Approved by:</b> {network_name}<br>{/if_approved_by}

<!-- Different content per network — use {if_tfl} and {if_tafl} -->
{if_approved_by}Approved by:
  <a href="{if_tfl}{tfl_url}{/if_tfl}{if_tafl}{tafl_url}{/if_tafl}">
    {network_name}
  </a>
{/if_approved_by}

Stats Embed Output Variables

After stats.php runs, your host page can use these PHP variables. They are already made safe for normal page output.

To use them in your page’s <head>, run the stats embed before the page starts printing HTML:

<?php
$luster_fanlisting_id = 1;
$luster_return = true;
$stats_html = require '/path/to/luster/public/embed/stats.php';
?>
<head>
  <title><?= $luster_listing_title ?> — My Site</title>
  <meta name="description" content="<?= $luster_meta_description ?>">
</head>
<body>
  <?= $stats_html ?>
</body>

Member Template Tokens

Used by the members_template setting in the members embed.

Related CSS: .fl-member-list, .fl-member-item, .fl-member-name, .fl-member-country, .fl-member-email, .fl-member-field.

Two render modes

New-style — use {each_member}...{/each_member} around the member row. Luster repeats that part for each member, while anything outside it shows once around the whole list. The page-level tokens below only work this way.

Legacy — if there is no {each_member} block, Luster treats the whole template as one member row and repeats all of it for every member. This still works, but it cannot use the page-level tokens below.

Per-Member Tokens

New-Style Only — Page-Level Tokens

Owned Listing Tokens

Used by the owned_template setting and public/embed/owned.php.

Past Fanlistings uses a separate template. When the resolved status/view is past ($luster_status = 'past' — closed + adopted-out combined), owned.php resolves a past_owned_template setting instead of owned_template. Every other status (current/upcoming/pending/closed/adopted_out/all) still uses owned_template unchanged. past_owned_template is edited on its own “Past Fanlistings” section on the Collective Templates page, but shares every loop/row token documented below — it’s a separate stored value, not a separate token set.

Related CSS: .fl-listing-list, .fl-listing-item, .fl-listing-*, .fl-listing-section, .fl-status-badge (the last one used by the built-in past_owned_template default for its Closed/Adopted Out badges).

Loops

Row Tokens

Row Conditionals

Section Tokens

Use these when your owned-listings template is split into sections, such as current, upcoming, or pending listings.

Latest & Random Listing Tokens

Latest and random listings use the same listing tokens as the owned-listings template. Put your listing design inside {each_listing}...{/each_listing} so Luster knows which part to fill in.

Random Listing

Used by random_listing_template and public/embed/random-listing.php. It shows one listing chosen at random.

Default CSS classes: .fl-random-listing, .fl-random-listing-item, .fl-random-listing-image-wrap, .fl-random-listing-image, .fl-random-listing-body, .fl-random-listing-title, .fl-random-listing-subject.

Latest Listing

Used by latest_listing_template and public/embed/latest-listing.php. It shows one listing: the newest one by open date.

Default CSS classes: .fl-latest-listing, .fl-latest-listing-item, .fl-latest-listing-image-wrap, .fl-latest-listing-image, .fl-latest-listing-body, .fl-latest-listing-title, .fl-latest-listing-subject, .fl-latest-listing-date.

Joined Listing Tokens

Used by the joined_template setting and public/embed/joined.php.

Related CSS: .fl-joined-list, .fl-joined-*, .fl-category-*.

Loops

Row Tokens

Section Tokens

Affiliate Section Tokens

Used by per-listing affiliates_section_template and collective collective_affiliates_section_template.

Related CSS: .fl-affiliate-list, .fl-affiliate-item, .fl-affiliates-section, .fl-affiliate-apply-*.

Collective Stats Tokens

Used by the collective_stats_template setting and public/embed/collective-stats.php.

Related CSS: .fl-cstats, .fl-cstats-grid, .fl-cstats-label, .fl-cstats-value, .fl-cstats-newest, .fl-cstats-random.

Template Tokens

PHP Variables

collective-stats.php also gives your page PHP variables after you include it. These are not brace tokens; use them like normal PHP variables.

Enthusiast-Compatible Aliases

These older variable names are included to make it easier to move existing Enthusiast collective pages into Luster.

Pagination Tokens

Used by per-listing pagination_template, collective pagination templates, and the shared Pagination renderer.

Related CSS: .fl-pagination-nav, .fl-page-prev, .fl-page-next, .fl-page-link, .fl-page-current, .fl-page-gap.

Form Field Wrapper Tokens

Used by field_wrapper_template, which controls the little block around each form field: label, input, hint, and error text.

Related CSS: .fl-field, .fl-label, .fl-input, .fl-select, .fl-textarea, .fl-field-hint, .fl-field-error, .fl-error.

Form Body Template Tokens

Several public forms support a fully admin-editable whole-form body template, not just the generic field wrapper above. Each {field_x} token below is the full wrapped block (label + input + hint + error, per Form Field Wrapper Tokens); {field_x_input} is the bare <input>/<select>/<textarea> only, for custom layouts. {captcha_block} / {captcha_block_input} follow the same wrapped/bare pattern for the captcha question field. All of these are edited the same way as other listing/collective templates — per-listing ones under Edit Listing → Templates, collective ones under Admin → Collective → Templates.

Join Form Template Tokens

Used by join_form_template (per-listing) / listing_default_join_form_template (global default) in public/embed/join.php. Unlike Update/Reset/KIM Reset below, this covers the entire join form in one step — there is no separate fixed PHP-rendered step.

Update Form Template Tokens

Used by update_form_template in public/embed/update.php. Covers only the sign-in step (email + password to reach the editable form). The step where a member actually edits or deletes their membership is fixed and cannot be customized, so a mistake here can never lock anyone out of updating their info — see templates/default/update.php's hardcoded signed-in branch.

Reset Form Template Tokens

Used by reset_form_template in public/embed/reset.php. Covers only the request step (email address to receive the reset link). The step where a member actually sets their new password is fixed and cannot be customized, so a mistake here can never lock anyone out of resetting their password — see templates/default/reset_confirm.php's hardcoded markup.

Contact Form Template Tokens

Used by contact_form_template in public/embed/contact.php and collective_contact_form_template (same tokens) in public/embed/collective-contact.php.

Code Submission Form Template Tokens

Used by codes_submit_form_template in public/embed/codes-submit.php (per-listing) and collective_codes_submit_form_template in public/embed/collective-codes-submit.php (site-wide).

Affiliate Application Form Template Tokens

Used by affiliate_apply_form_template in public/embed/affiliate-apply.php (per-listing) and collective_affiliate_apply_form_template (site-wide).

Collective Adoption Form Template Tokens

Used by collective_adoption_form_template in public/embed/adopt.php. Requires the Adoption add-on. There is no per-listing variant — the visitor picks which listing to apply for from a dropdown inside the form.

Success Template Tokens

Used by public form success/action confirmation templates.

Related CSS: .fl-success, .fl-success-body, .fl-success-actions.

Success Value Tokens

Success Conditionals

Codes Template Tokens

Used by per-listing codes_template and collective collective_codes_template in public/embed/codes.php. Both are fully admin-editable and render through the same code.

Related CSS: .fl-codes, .fl-code-group, .fl-code-group-label, .fl-code-list, .fl-code-item, .fl-code-image, .fl-code-caption.

Loops

Shell Tokens

Group Tokens

Row Tokens

Conditionals

News Feed Template Tokens

Used by per-listing newsfeed_template and collective collective_newsfeed_template. Requires the News Feed add-on.

Related CSS: .fl-newsfeed, .fl-newsfeed-item, .fl-newsfeed-header, .fl-newsfeed-title, .fl-newsfeed-date, .fl-newsfeed-body, .fl-newsfeed-meta, .fl-newsfeed-categories, .fl-newsfeed-category-tag, .fl-newsfeed-img.

Wishlist Template Tokens

Used by collective wishlist_template and public/embed/wishlist.php. Requires the Wishlist add-on.

Related CSS: .fl-wishlist-group, .fl-wishlist-list, .fl-wishlist-item, .fl-wishlist-image, .fl-wishlist-info, .fl-wishlist-subject, .fl-wishlist-type-badge.

Loops

Using any of the three type-scoped loops switches the template into sectioned mode — put each one under its own heading rather than relying on {item_type} to sort them visually. Row tokens below work identically inside any of the four loops.

Shell Tokens

Row Tokens

KIM Templates

The KIM add-on has separate editable templates for its lists and forms. You can edit them in Admin → Collective → Templates under the KIM group. If you leave one blank, Luster uses its built-in version.

KIM Signup Form Template

Used by kim_signup_form_template in public/embed/kim-signup.php. Covers the entire sign-up form in one step.

KIM List — Overview Template

Used by collective_kim_list_overview_template for the main KIM list page, where visitors see all fanlistings that have KIM sign-ups.

KIM List — Subject Page Template

Used by collective_kim_list_subject_template for one fanlisting’s KIM member list.

KIM Update Form Template

Used by kim_update_form_template for the KIM update form. The regular field tokens print the whole field block; the _input versions print just the form control when you want to build your own layout.

KIM Reset Form Template

Used by kim_reset_form_template when kim-reset.php is embedded and the template string is non-empty. Covers only the email-entry step. The step where a member actually sets their new password is fixed and cannot be customized, so a mistake here can never lock anyone out of resetting their password — see templates/default/addons/kim/reset-confirm.php's hardcoded markup.

Legacy KIM Member Row Template

kim_member_template is the older fallback for KIM member rows. New setups should use collective_kim_list_subject_template, which gives you more control over the whole subject page.

Collective Update Form Template Tokens

Used by collective_update_form_template. Controls the email-request step (Step 1) of embed/collective-update.php, where the member submits their email to receive a verification link. Edit in Admin → Collective → Templates.

Step 2 (the update form with name, URL, country, password fields, and listing checkboxes) is PHP-rendered and not template-controlled.

Join Rules Gate Body Template Tokens

Used by the per-listing and global rules body text (rendered via RulesBodyRenderer, called from public/embed/rules-gate.php). The body auto-detects whether it's an HTML template (contains HTML tags or {gate_button}) or legacy plain text (numbered lines become an ordered list, other lines become paragraphs). Edit per-listing at Edit Listing → Rules, or the global default at Admin → Collective → Templates.

Join Rules Gate Behavior Notes

Unlike KIM (which shows a visible in-page error when its add-on isn't installed), rules-gate.php fails open silently: if the Rules add-on is uninstalled or its table is unreachable, the embed falls back to any global rules, then to returning an empty string if there's nothing to show. Nothing is shown to the visitor either way — there's no error message.

Baseline Stylesheet

Luster includes a small starter stylesheet at public/assets/css/default/style.css. It makes embeds readable while still letting your site’s design stay in charge.

One-time setup

Every host page needs one PHP line above the embed require, added once per page (most sites put it in a shared header file):

<?php defined('LUSTER_EMBED') || define('LUSTER_EMBED', '/path/to/luster/public/embed'); require_once dirname(LUSTER_EMBED) . '/../vendor/autoload.php'; Luster\Core\View::serveEmbedAsset(); ?>

The Admin → Embed Codes wizard generates this line for you with your real install path already filled in — copy it from there rather than typing it by hand. It loads Composer's autoloader and registers a small handler, View::serveEmbedAsset(), that intercepts two special query-string requests on the current page: the stylesheet link below, and any uploaded listing/affiliate/code/wishlist image an embed prints. Both are served this way instead of as direct links so a public page never reveals your server's real install path in a URL a visitor can see.

Linking the stylesheet

With the setup line in place, load the stylesheet through the current page itself rather than a direct path:

<link rel="stylesheet" href="?luster_css">

Recommended load order

Load your site’s normal CSS first, then Luster’s CSS, then any extra CSS you write just for Luster embeds:

<!-- 1. Your site's normal stylesheet -->
<link rel="stylesheet" href="/style.css">

<!-- 2. Luster baseline -->
<link rel="stylesheet" href="?luster_css">

<!-- 3. Your Luster overrides (optional) -->
<link rel="stylesheet" href="/my-luster-overrides.css">

CSS Custom Properties

These are theme settings. Change them in your own stylesheet to adjust many Luster embed colors and borders at once.

CSS Classes

Use .fl-embed--... classes when you want your CSS to affect one kind of embed without changing the rest.

Root & Scope Classes

Global Utility Classes

Category Navigation Classes

Note: #fl-owned-cat and #fl-joined-cat are element IDs (not classes) used on the category select elements. Target them with #fl-owned-cat or #fl-joined-cat if you need to style the selects directly.

Pagination Classes

Form Classes

Success messages use .fl-success, .fl-success-body, .fl-success-actions, and (for messages that show a bulleted rundown, like collective update) .fl-success-list.

Member Classes

Stats Classes

Affiliate Classes

Owned Listing Classes

Joined Listing Classes

Collective Stats Classes

Codes Classes

News Feed Classes

KIM Classes

Join Rules Gate Classes

Wishlist Classes

Collective Update Classes

The "permanently delete my membership(s)" option uses the general .fl-field--danger / .fl-label-danger classes, not a collective-update-specific class.

Common Styling Recipes

These are small copy-paste examples for common styling changes.

Style one embed type

.fl-embed--members .fl-member-list {
  margin-top: 1rem;
}

Style every embed form

.fl-embed .fl-form {
  display: grid;
  gap: 0.75rem;
}

Change the whole Luster embed color system

:root {
  --fl-link-color: #8a3ffc;
  --fl-link-hover: #5f249f;
  --fl-border-color: #d8c7ff;
}

Style joined listing images

.fl-embed--joined .fl-joined-image {
  width: 88px;
  height: 31px;
  object-fit: cover;
}

Style owned listing images

.fl-embed--owned .fl-listing-image {
  max-width: 120px;
  height: auto;
}