Primix SDK Integration

Tagixo Primix integration is provided by ccast/tagixo-primix.

When to choose the Primix SDK

Use the Primix adapter when:

• your editorial UI already lives in Primix
• you want the builder exposed as a Primix page or resource page
• you want Tagixo persistence to remain in your application models

The SDK does not replace your content model. It connects Tagixo to a Primix host.

Install and register the plugin

In your Primix panel provider, register the plugin:

use Ccast\TagixoPrimix\TagixoPrimixPlugin;

$panel->plugin(
    TagixoPrimixPlugin::make()->withMediaGallery()
);

This wires the builder routes and Primix-side integration pieces. It does NOT copy the builder JS/CSS bundle into your public/ directory — that is a separate publish step (see below).

Asset publication

The ccast/tagixo core package ships its own pre-built dist/ directory (builder.js, builder.css, fonts, …). Consumer apps publish those assets verbatim:

php artisan vendor:publish --tag=tagixo-assets --force

This copies the bundle into public/vendor/tagixo/. The Primix layout view references them with asset('vendor/tagixo/builder.js') — there is no @vite() call, no manifest lookup, no npm/Vite toolchain required in the consumer app.

Re-run on every Tagixo upgrade with --force to refresh stale assets. Stable filenames mean the SDK Blade can reference them directly without manifest indirection.

LiVue (not Livewire) is the reactivity layer Primix uses — keep that in mind if you mix examples from Filament docs.

Bridge trait pattern

Tagixo integration is split across two traits:

• Ccast\Tagixo\Concerns\InteractsWithVisualBuilder — framework-agnostic builder lifecycle (mount, load, save, dispatch). Ships in core. Do not modify.
• Ccast\TagixoPrimix\Concerns\InteractsWithVisualBuilderPrimix — Primix-side bridge that adapts the abstract hooks to LiVue dispatch + Primix notifications.

The abstract BuilderPage and PrimixVisualBuilderPage classes already use both traits. You typically extend those rather than re-applying the traits yourself. This separation is what keeps your content portable across SDKs — switching to Filament means swapping the bridge trait, not rewriting the page class structure.

Builder page types

The SDK gives you two main abstractions:

• Ccast\TagixoPrimix\Pages\BuilderPage
• Ccast\TagixoPrimix\Pages\PrimixVisualBuilderPage

Use the first for standalone Primix pages. Use the second for resource-bound editing.

Standalone Primix page

Use Ccast\TagixoPrimix\Pages\BuilderPage when the builder is not tied to a specific resource record.

You must implement:

• getContext()
• loadStructure()
• saveStructure()

Minimal example:

use App\Models\MarketingPage;
use Ccast\TagixoPrimix\Pages\BuilderPage;

class LandingPageBuilder extends BuilderPage
{
    public function getContext(): string
    {
        return 'page';
    }

    public function loadStructure(): ?string
    {
        return MarketingPage::query()->where('slug', 'home')->value('content')
            ? json_encode(MarketingPage::query()->where('slug', 'home')->value('content'))
            : null;
    }

    public function saveStructure(string $structure): void
    {
        $decoded = json_decode($structure, true);

        $page = MarketingPage::query()->firstOrFail();
        $page->update([
            'content' => $decoded,
        ]);
    }
}

loadStructure() and saveStructure() operate on a JSON string. Your model can still store the decoded array.

Resource-bound Primix page

Use Ccast\TagixoPrimix\Pages\PrimixVisualBuilderPage for model-backed resource editing.

Typical flow:

1. Resolve resource record.
2. Authorize access.
3. Initialize builder.
4. Load/save JSON from the model.

Minimal shape:

use Ccast\TagixoPrimix\Pages\PrimixVisualBuilderPage;

class EditMarketingPageBuilder extends PrimixVisualBuilderPage
{
    protected static string $resource = MarketingPageResource::class;

    public function getContext(): string
    {
        return 'page';
    }

    public function loadStructure(): ?string
    {
        return $this->record->content
            ? json_encode($this->record->content)
            : null;
    }

    public function saveStructure(string $structure): void
    {
        $this->record->update([
            'content' => json_decode($structure, true),
        ]);
    }
}

CLI helper

Generate starter page class:

php artisan make:primix-builder-page MarketingPage --context=page

The command gives you a scaffold, but you still need to implement real persistence and authorization.

Preview behavior

You can override preview URL behavior in resource pages by implementing getPreviewUrl().

Use this when your content already has a public frontend route and you want the builder toolbar to open that canonical preview directly.

Page builder layout frame pattern

For context=page, your host SDK can expose a single editing screen with three scopes:

• Header
• Page Body
• Footer

Recommended behavior:

1. show header/footer around the page canvas as preview frames
2. keep only one scope editable at a time
3. save Page Body back to the page record
4. save Header/Footer back to the source layout section
5. clearly indicate when a section is inherited from the global default layout

This pattern should stay page-only.

Do not apply the same layout-frame editing model to form, mail, or PDF builders unless you intentionally design a different abstraction around them.

Notes for form context

Primix resource pages can exclude irrelevant canvas PropTypes (for example submit behavior controlled by host resource logic).

The SDK already exposes an excludedCanvasPropTypes() hook for this purpose.

Recommended Primix architecture

Keep responsibilities separated:

• Primix page class: host integration, authorization, record resolution
• application service/repository: persistence and render-cache rebuild
• Tagixo: builder state, render logic, registries, canvas metadata

What to avoid

• putting heavy persistence logic directly in the page class
• duplicating render logic inside Primix resources
• storing only rendered HTML and discarding raw builder JSON
• assuming Primix changes the core Tagixo payload contract

If you follow that separation, you can move from standalone to Primix, or from Primix to another host, without rewriting your content model.