Add-ons · Developer reference

An add-on is a separate WordPress plugin that extends Hype5 Theater without modifying it. It announces itself with a manifest and then uses the plugin's filters to add layouts, page sections, content-type options, labels and templates. This page describes the manifest and each extension point as implemented; the hooks themselves are listed in Hooks.

Registering an add-on

add_filter('hype5_addons', function (array $addons, string $host): array {
    $addons[] = [
        'slug'          => 'my-addon',          // required: ^[a-z][a-z0-9-]{1,63}$
        'name'          => 'My add-on',         // required
        'version'       => '1.0.0',             // required
        'supports'      => ['theater'],         // required: must contain 'theater'
        'requires_host' => '0.6.17',            // optional minimum Hype5 Theater version
    ];
    return $addons;
}, 10, 2);

add_action('hype5/theater/ready', function (array $host): void {
    // $host = ['version' => '0.6.17', 'host' => 'theater']
    // Register your filters here.
});

Discovery runs on init at priority 30; register the hype5_addons filter earlier (for example when your plugin loads). Invalid manifests are ignored. Registered add-ons are listed in Settings → Integrations of the Hype5 app (and on the classic Add-ons screen for users without the app), each marked Compatible or Requires a newer host version according to requires_host. Compatibility is informational: the plugin does not block an incompatible add-on, so check the version yourself.

An add-on that adds its own admin page under the Hype5 Theater menu (add_submenu_page( 'hype5-theater', … )) keeps it in the menu: for users of the Hype5 app the page is listed under Hype5 Theater, after an entry that opens the app, and its page hook keeps the hype5-theater_page_ prefix.

Layouts

Each presentation family has a set of layout variants. Families: production, person, person_gallery, current_productions, past_productions, productions, people, cast, gallery, schedule, global_schedule, meta, visitor, video, partners, articles.

add_filter('hype5/theater/layouts/cast', function (array $layouts): array {
    $layouts['columns'] = [
        'key'               => 'columns',
        'label_key'         => 'layout.cast.columns',   // register this label too
        'label'             => 'Columns',
        'preview'           => ['component' => 'cast', 'variant' => 'columns'],
        'supported_options' => ['style_mode'],
        'template'          => 'production.cast',       // a registered template key
        'defaults'          => [],                      // display defaults applied when chosen
        'available'         => true,                    // required: unavailable layouts are not accepted
    ];
    return $layouts;
});

Always set available to true; a layout without it is not accepted in shortcodes, Appearance or Display.
template is the template key used when the layout is chosen; without it the family's standard template is used. For productions and people the default is collections.{family}.{key}.
defaults are display values that apply when this layout is chosen and nothing more specific is set.
Removing a core variant from the array removes it from the choices.

The chosen key is exposed to templates as $display['{family}_layout'], so a shared template can branch on it.

If your add-on is deactivated, stored choices of its layouts are kept and shown as Add-on value in Appearance and Display; the public output uses the next valid value in the precedence chain (for example the global or built-in layout).

Sections

Single production and person pages are composed of sections. Production sections: important_info, introduction, schedule, cast, gallery, media, visitor, partners, articles, links. Person sections: biography, current_productions, past_productions, gallery.

add_filter('hype5/theater/production/sections', function (array $sections): array {
    $sections['education'] = [
        'key'                => 'education',
        'label_key'          => 'education.materials',
        'renderer'           => 'my_addon_render_education',   // callable(array $atts): string
        'default_order'      => 95,
        'default_enabled'    => true,
        'supported_contexts' => ['single'],
    ];
    return $sections;
});

function my_addon_render_education(array $atts): string {
    $id = (int) ($atts['id'] ?? 0);
    // Return escaped HTML; return '' to render nothing.
    return '';
}

The renderer receives the render attributes, always including id (the production or person shown); in the full page composition they also contain the effective display options. It returns HTML.
New sections join the default order by default_order (core sections use 0, 10, 20 …). Administrators can reorder and hide them in Appearance and per record.
Sections of a password-protected production are not rendered until the password is entered. A renderer that reads data of other records must apply its own visibility checks.

Content-type options

Add options to the visitor information, partner, article or accessibility lists:

add_filter('hype5/theater/vocabulary/partner', function (array $types): array {
    $types['my_addon_media_partner'] = __('Media partner', 'my-addon');
    return $types;
});

Keys are stored on productions; use a prefix that will not clash. Add-on options appear read-only in Vocabularies. When the add-on is inactive, stored keys are kept and editors show them as unavailable. Public pages then show the general label for visitor rows and partners, no type label for articles, and no marker for accessibility features.

Labels and templates

Register public texts with hype5/theater/labels (Labels).
Register templates with hype5/theater/templates (Template overrides). The resolver looks for template files only in the theme folders and in the plugin's templates/ folder, not in the add-on's directory.

Saved row data

Repeatable rows of a production (files, videos, audio links, external galleries, partners, articles, links, visitor rows, information rows) are stored as arrays in post meta. An add-on may store extra keys on a row. When a row is edited or moved in the Hype5 app or the classic editor, its stored extra keys are kept (the editors never send or clean them, and native keys always win); an unchanged row is kept as stored; a removed row is removed with its extra keys.

What add-ons cannot change

Presentation hooks do not change queries, visibility rules or stored data. Hype5 Theater does not provide modules for ticket sales, seating, maps or other services; an add-on that integrates such a service owns that functionality.

Registering an add-on #

Layouts #

Sections #

Content-type options #

Labels and templates #

Saved row data #

What add-ons cannot change #