Globals

Textstem globals are items of content available anywhere at any time, such as a phone number, a footer menu or a site-wide notice. Editors manage them in the admin under Globals; each is a GlobalOption row with a key, a value, a type and a group.

A global's type sets how its value is stored, the input editors use in the admin, and what you get back when you read it:

Name Underlying data type Input editor Returned value
string Text Text box String
html HTML Rich text editor String of HTML
number Number Number field Float
boolean 0 or 1 Yes/no toggle Integer, 0 or 1
json JSON JSON editor Array (empty if the JSON is invalid)
array JSON array JSON editor Array
list JSON array of label and value pairs Rows of name and value fields Array of ['label' => …, 'value' => …]
pages JSON array of page IDs Page picker Collection of WranglerPage models (id, title, menu_name, url and more), in the order picked

Every value is kept as text in the value column; the type converts it when it's read.

Reading globals

Every public page shares an array of globals with its views as $globals, keyed by the global's key, already converted by its type. In PHP, use the Textstem facade:

use Medialight\Textstem\Facades\Textstem;

$phone = Textstem::globalVal('phone', '');   // globalVar() is the same

Lazy globals

All globals are loaded into a memory cache the first time one is asked for in a request. A global marked Load only when needed in the admin (stored as order = 1) is left out of that bulk load and of $globals; it is fetched only when you ask for it by key with Textstem::globalVal(). Use this for large values most pages don't need.

Use Cases

To create a custom menu, a pages global can be used. For example, a global called footer-menu could hold a special list of pages to be shown on every page. The page layout might include something like this:

<nav class="-mb-6 columns-2 sm:flex sm:justify-center sm:space-x-12" aria-label="Footer">
    @foreach($globals['footer-menu'] ?? [] as $item)
        <div class="pb-6">
            <a href="{{ $item->url }}" class="text-sm leading-6 text-gray-600 hover:text-gray-900">{{ $item->title }}</a>
        </div>
    @endforeach
</nav>

Creating New Types

To create a new type, add a class to app/Domain/Globals/Types/, named {TypeName}Type and extending Medialight\Textstem\Domain\Globals\GlobalType. It appears in the admin's type list straight away, and a host-app type with the same name as a package type replaces it.

The class needs a static make() method that takes the stored string and returns an instance, and a $control naming the input editors use. For example, a type that stores a position as two numbers:

<?php

namespace App\Domain\Globals\Types;

use Medialight\Textstem\Domain\Globals\GlobalType;

class PositionType extends GlobalType
{
    public $control = 'json';

    public static function make(?string $src = '')
    {
        $value = json_decode($src ?: '[]', true);

        return new self(
            value: is_array($value) ? array_map('floatval', array_slice($value, 0, 2)) : [0.0, 0.0],
            original: $src ?? '',
            type: 'position'
        );
    }

    public function toString()
    {
        return json_encode($this->value);
    }
}

value() returns what templates receive (override it to return something richer, as the pages type does), and toString() how the value is shown as text.

$control must be one of the inputs the Globals editor knows: text, boolean, richtext, json, list, number, pages_collection or array (which also uses the JSON editor). Any other value gets no editor at all.

See also: Globals, in the User Guide, for managing globals in the admin.
esc