Tagixo Docs

Developer Documentation for Laravel, SDK integrations, and extensibility

Back to Website Start Setup

Core Integration

Data Models and Global Variables

Expose reusable tokens and model metadata cleanly so editors can build without hardcoding everything.

9 min read Route: /documentation/data-models-and-global-variables

Data Models and Global Variables

Two pieces of metadata make advanced integrations much more maintainable:

  • registered data models
  • global variables

They solve different problems and should not be mixed together.

Data models

Registered data models tell Tagixo which Eloquent models are allowed to appear in model-aware builder flows.

Register them through config or runtime registration:

'models' => [
    App\Models\Post::class,
    App\Models\Product::class,
]

or:

Tagixo::registerModels([
    App\Models\Post::class,
]);

What model registration unlocks

Once models are registered, the builder can expose:

  • model lists
  • model attribute metadata
  • bound model context in bootstrap
  • model-aware props such as select/mapping controls

Relevant endpoints:

  • GET /tagixo/builder/models
  • GET /tagixo/builder/models/{key}/attributes

bound_model in bootstrap

The bootstrap endpoint accepts an optional bound_model query parameter:

GET /tagixo/builder/bootstrap?context=page&bound_model=post

Use this when the current editing experience is attached to a known model type and you want the builder to resolve that context explicitly.

Model exposure rules

Only register models that editors should be able to inspect.

Do not expose:

  • internal-only models
  • models with sensitive attribute sets
  • models whose attribute shape is unstable and undocumented

Treat model registration as part of your product boundary, not just as developer convenience.

Global variables

Global variables are reusable tokens that can be referenced from Props through the variable picker system.

Typical categories:

  • colors
  • text fragments
  • numbers with units
  • shared links
  • image assets

The builder bootstrap payload exposes them under globalVariables.

Relevant endpoints:

  • GET /tagixo/builder/global-variables
  • PUT /tagixo/builder/global-variables
  • POST /tagixo/builder/global-variables

Site-wide theme typography

The Global Variables modal also exposes two reserved-key singleton rows that hold site-wide typography defaults applied to every rendered page:

  • body_typography (type typography) — base font family, size, color, line-height, etc., for body text, links, lists, blockquotes.
  • heading_typography (type heading_typography) — per-level (H1…H6) font settings.

They appear as "Body" and "Headings" accordion panels at the top of the modal. Unlike the five user-added categories, they are singletons: no + Add, no delete, no list. Saving uses the same endpoint as everything else (POST /tagixo/builder/global-variables); the backend upserts by reserved key.

How the cascade works:

  1. The renderer emits theme CSS scoped to .vb-body and .vb-body h1…h6 inside the page <head> (via PageRenderer::generateGlobalVariablesCss).
  2. Per-page body props (set by clicking the Body in the canvas → "Body Properties" drawer) emit CSS at the same selectors, but later in the source order — so per-page wins on equal specificity.
  3. Per-module overrides (e.g. an explicit heading_typography.color on a single Heading module) emit at the module's own data-component-id selector — higher specificity, wins.

Result: set body and heading fonts once for the brand, and every new Text / Heading module picks them up automatically. Per-page or per-module overrides remain possible without code changes.

FontManager automatically adds the theme font families to the page's <link rel="stylesheet"> Google Fonts emit, so the fonts load even before any module on the page references them.

Why global variables matter

Without global variables, editors hardcode values repeatedly.

That leads to:

  • inconsistent colors
  • duplicated links
  • repeated copy changes across many pages
  • difficult brand updates

With global variables, you can centralize reusable tokens and let Props opt into them with variablePicker(...).

Example variable-aware Prop

use Ccast\Tagixo\Core\Props\ColorProp;

ColorProp::make('color')
    ->setLabel('Text color')
    ->variablePicker('color');

The Prop still has a normal stored value shape, but the UI can now reference a managed variable.

Recommended governance

Global variables should be managed intentionally:

  1. define naming conventions
  2. separate editor-facing names from internal keys
  3. group tokens by function
  4. document which variables are safe for general use

Example groups:

  • brand
  • layout
  • content
  • links

Common mistakes

  • treating data models as content variables
  • exposing too many models to the editor
  • creating dozens of near-duplicate global variables
  • allowing random variable names with no governance
  • forgetting to test variable-backed Props in preview and render output

Practical recommendation

Use data models for runtime-aware content structures. Use global variables for reusable design and content tokens.

If those two concepts stay separate, your integration remains much easier to scale.