Token Management Best Practices

Once you have more than a handful of sites and tokens, structure matters. This guide collects the patterns that have worked for us and our agency partners.

Naming conventions

Pattern	Example	Why
lowercase_snake_case	hero_title, pricing_cta_label	Matches WordPress option-key conventions; avoids escaping issues
section_purpose_specifier	home_hero_title, home_hero_subtitle, pricing_pro_cta	Sortable in the UI; obvious at a glance which page they belong to
Reserved suffixes	_label, _url, _image_id, _html	Indicates field type — labels are short, URLs are validated, HTML is sanitized via wp_kses_post
Avoid	text1, headline_v2_NEW, tmp_homepage	Unmaintainable beyond 50 tokens

Rule of thumb: the token-key should answer “where on the site does this appear?” without having to look up.

Section organization

Hubbee groups tokens by section. Sections become headers in the editor and folders in the activity log. Recommended sections:

• general — site-wide footer, header, branding
• home — homepage sections
• pricing — pricing-page tokens
• about — company info
• legal — terms, privacy, imprint links
• seo — meta-titles, meta-descriptions, OG-tags
• forms — contact forms, success/error messages
• <page-slug> — dedicated section per landing page

Per-token sections are stored in the SaaS only — WordPress doesn’t care, but your editors do.

Field types — choose wisely

Type	Use for	Renders as
text	Short plain text (titles, labels, button text)	Sanitized via sanitize_text_field
textarea	Multi-line plain text (descriptions, addresses)	sanitize_textarea_field (preserves newlines)
richtext	HTML formatting (paragraphs with bold/italic/links)	wp_kses_post (allows safe inline HTML)

Anti-pattern: using richtext everywhere “just in case.” Stick to text for short labels — fewer XSS vectors, less editor confusion.

Versioning — your roll-back insurance

Every push increments the token’s version. The plugin only accepts higher versions, so:

• Out-of-order pushes are rejected (good — prevents stale overwrites)
• You can roll back: re-publish the previous value with a higher version number, the plugin treats it as the latest
• The activity stream shows every version with diff + author + timestamp

Best practice: every meaningful edit gets its own commit-style description in the dashboard. Use the description field as you would a git commit message.

Multi-locale strategy

Two patterns:

Pattern A — locale-suffixed tokens (simple sites, few locales)

hero_title_de
hero_title_en

• Pro: explicit, easy to find each translation
• Con: requires templating logic ({% if locale == 'de' %} ... {% endif %})

Pattern B — locale-aware values per token (recommended)

• One token-definition hero_title
• Multiple values: locale = '' (default), locale = 'de_DE', locale = 'en_US'
• Plugin auto-selects based on get_locale() at render-time
• Falls back to the default-locale value if the requested locale is missing

Pattern B is what Hubbee is designed for — use it unless you have a strong reason not to.

Push strategy

Use case	How
One-site-only edit	Open the site → tokens → edit → save
Same change to all sites in a workspace	Workspace tokens → edit → Push to all
Same change to a subset (e.g., all DACH-region client sites)	Site Groups → select group → push
Time-zoned launch (Black Friday at midnight Berlin)	Schedule Boards (Pro/Agency plan) — push runs server-side at the scheduled minute
Roll-back	Activity → click the previous version → Re-publish

When NOT to use tokens

Tokens are for content that:

• Repeats across multiple sites, OR
• Needs centralized review/translation, OR
• Changes frequently and you want audit trail

Tokens are not for:

• Per-page-instance unique content — that lives in WordPress’s normal post/page tables. Hubbee’s Asset Library (backgrounds, elements, text effects) is a separate channel for visual building blocks.
• Sensitive secrets — tokens are visible to all workspace members. For API keys: per-site wp-config.php constants.
• Binary files — use the WordPress Media Library + push the URL as a text token.

Auditing

Workspace → Activity shows:

• Every push (who, when, which site(s), result)
• Every token-definition change (added, renamed, deleted)
• Every value edit with diff

For agencies: this is your client-billing artifact. “We pushed 47 content updates across your 12 sites this month.” Exportable as CSV.

Cleanup

Tokens you no longer use accumulate. Twice a year:

1. Workspace → Tokens → filter by last edit > 6 months ago
2. Check on a sample site whether the rendered location still uses the token (CMD+F in the rendered HTML, or check Elementor templates)
3. Delete unused token-definitions — the plugin removes the local copy on the next push-cycle

Tip: before bulk-delete, export the workspace (Account → Data Export). One-click backup.