Documentation

Application

Graphic_Data_Page_Options
in package

Application

Adds a required "Instance" section to the Page options of the Gutenberg page editor.

Registers a meta box on the page post type that exposes three controls: an Instance select (None, Global, or any Instance returned by Graphic_Data_Utility::return_all_instances()), an "Include in navigation bar?" checkbox, and a navigation-bar order select (1 through 10). The selected values are persisted as the scene_location, graphic_data_page_instance_in_navbar, and scene_order post meta and registered with the REST API so the block editor can read them.

Constants

INSTANCE_META_KEY : string = 'scene_location': The meta key that stores the selected Instance for a page.
NAVBAR_META_KEY : string = 'graphic_data_page_instance_in_navbar': The meta key that stores whether the page is included in the navigation bar.
NONCE_ACTION : string = 'graphic_data_save_page_instance': The nonce action used when saving the Instance section.
NONCE_NAME : string = 'graphic_data_page_instance_nonce': The nonce field name used when saving the Instance section.
ORDER_MAX : int = 10: The highest value offered by the navigation-bar order select.
ORDER_META_KEY : string = 'scene_order': The meta key that stores the page's order within the navigation bar.
ORDER_MIN : int = 1: The lowest value offered by the navigation-bar order select.

Methods

add_instance_meta_box() : void: Register the Instance meta box on the page editor.
change_page_columns() : array<string|int, mixed>: Replace the columns shown on the Pages admin list table.
custom_page_column() : mixed: Populate custom fields for page content type in the admin screen.
enqueue_overview_scene_notice() : void: Push a dismissible block-editor notice when the page is its Instance's overview scene.
filter_instance_page_link() : string: Rewrite a page permalink to include its assigned Instance slug.
overview_scene_editor_notice() : void: Print a dismissible notice on the classic page editor when the page is its Instance's overview scene.
register_page_instance_meta() : void: Register the page meta so the block editor and REST API are aware of it.
render_instance_meta_box() : void: Render the Instance section controls.
resolve_instance_page_request() : array<string|int, mixed>: Route an `{instance_slug}/{page_slug}` request to the matching page.
save_instance_meta_box() : void: Persist the Instance section values when a page is saved.
get_instance_options() : array<string, string>: Build the list of options for the Instance select.
get_page_instance_web_slug() : string: Resolve the public URL slug of the Instance assigned to a page.
is_instance_overview_scene() : bool: Determine whether a page is the overview scene of the Instance it belongs to.
overview_scene_notice_message() : string: Build the notice text shown when a page is its Instance's overview scene.
scene_belongs_to_instance() : bool: Determine whether a published Scene with the given slug belongs to an Instance.

INSTANCE_META_KEY

The meta key that stores the selected Instance for a page.


    public
        string
    INSTANCE_META_KEY
    = 'scene_location'

NAVBAR_META_KEY

The meta key that stores whether the page is included in the navigation bar.


    public
        string
    NAVBAR_META_KEY
    = 'graphic_data_page_instance_in_navbar'

NONCE_ACTION

The nonce action used when saving the Instance section.


    public
        string
    NONCE_ACTION
    = 'graphic_data_save_page_instance'

NONCE_NAME

The nonce field name used when saving the Instance section.


    public
        string
    NONCE_NAME
    = 'graphic_data_page_instance_nonce'

ORDER_MAX

The highest value offered by the navigation-bar order select.


    public
        int
    ORDER_MAX
    = 10

ORDER_META_KEY

The meta key that stores the page's order within the navigation bar.


    public
        string
    ORDER_META_KEY
    = 'scene_order'

ORDER_MIN

The lowest value offered by the navigation-bar order select.


    public
        int
    ORDER_MIN
    = 1

add_instance_meta_box()


    public
                    add_instance_meta_box() : void

Hooked to add_meta_boxes. The box is placed in the side context with a high priority so it appears alongside the other Page options panels in the block editor.

change_page_columns()

Replace the columns shown on the Pages admin list table.


    public
                    change_page_columns(array<string|int, mixed> $columns) : array<string|int, mixed>

Filter callback for manage_page_posts_columns. Rebuilds the column set so the Pages list surfaces the Instance a page is attached to and whether the page acts as that Instance's overview scene, while keeping the checkbox, author, comments and date columns provided by WordPress core.

The scene_location and scene_overview cells are populated by change_page_columns()'s companion method custom_page_column().

Parameters

$columns : array<string|int, mixed>: Column ID => label map supplied by WordPress for the page list table.

Return values

array<string|int, mixed> —

The reordered column map:

'cb': Row selection checkbox, carried over from core.
'title': Page title.
'scene_location': Labelled "Instance"; the Instance the page belongs to.
'scene_overview': Labelled "Overview"; marks the page as its Instance's overview scene.
'author': Page author, carried over from core.
'comments': Comment count, shown as the core comments-bubble icon.
'date': Published/modified date, carried over from core.

custom_page_column()

Populate custom fields for page content type in the admin screen.


    public
                    custom_page_column(string $column, int $post_id) : mixed

Parameters

$column : string: The name of the column.
$post_id : int: The database id of the post.

enqueue_overview_scene_notice()

Push a dismissible block-editor notice when the page is its Instance's overview scene.


    public
                    enqueue_overview_scene_notice() : void

Hooked to enqueue_block_editor_assets. Adds an inline script that inserts an informational notice into the editor's core/notices store, since raw admin_notices output is not reliably shown on the block editor screen.

filter_instance_page_link()

Rewrite a page permalink to include its assigned Instance slug.


    public
                    filter_instance_page_link(string $link, int $post_id[, bool $sample = false ]) : string

Filter callback for page_link. When a published page has a real Instance selected in its scene_location meta, its permalink becomes {home_url}/{instance_slug}/{page_slug}/. Pages with no Instance (or a none/global selection), unpublished pages, and pages whose Instance has no slug keep the default permalink.

Parameters

$link : string: The page's default permalink.
$post_id : int: The page ID.
$sample : bool = false: Whether this is a sample (draft) permalink. Unused.

Return values

string —

The Instance-scoped permalink, or the original link.

overview_scene_editor_notice()

Print a dismissible notice on the classic page editor when the page is its Instance's overview scene.


    public
                    overview_scene_editor_notice() : void

Hooked to admin_notices. The block editor relocates raw admin_notices markup into a hidden container, so this path is limited to the classic editor; enqueue_overview_scene_notice() covers the block editor.

register_page_instance_meta()


    public
                    register_page_instance_meta() : void

Hooked to init.

render_instance_meta_box()

Render the Instance section controls.


    public
                    render_instance_meta_box(WP_Post $post) : void

Outputs the required Instance select, the "Include in navigation bar?" checkbox, and the navigation-bar order select, pre-filled with any previously saved values. The order select is only shown while the checkbox is checked (handled with a CSS :has() rule so it toggles live without JavaScript).

Parameters

$post : WP_Post: The page being edited.

resolve_instance_page_request()

Route an `{instance_slug}/{page_slug}` request to the matching page.


    public
                    resolve_instance_page_request(array<string|int, mixed> $query_vars) : array<string|int, mixed>

Filter callback for request. The Scene custom post type registers a catch-all rewrite rule that maps every two-segment URL to post_type=scene&name={segment2}&instance_slug={segment1}. This callback inspects that resolved query: if no published Scene in the named Instance owns the slug, but a published page does carry that slug and is assigned to the Instance whose instance_slug matches the first segment, the query is redirected to that page. All other requests pass through untouched so Scene routing is unaffected.

Parameters

$query_vars : array<string|int, mixed>: The query vars produced by rewrite matching.

Return values

array<string|int, mixed> —

The original query vars, or array( 'page_id' => ... ).

save_instance_meta_box()

Persist the Instance section values when a page is saved.


    public
                    save_instance_meta_box(int $post_id) : void

Hooked to save_post_page. Validates the nonce, capability, and request context before writing the scene_location, graphic_data_page_instance_in_navbar, and scene_order post meta. Unrecognised Instance values fall back to none, and an out-of-range order falls back to the lowest allowed value.

Parameters

$post_id : int: The ID of the page being saved.

get_instance_options()

Build the list of options for the Instance select.


    private
                    get_instance_options() : array<string, string>

The list always starts with None (the default) and Global, followed by every Instance returned by Graphic_Data_Utility::return_all_instances(), keyed by Instance ID. The blank placeholder entry that return_all_instances() seeds its result with is skipped.

Return values

array<string, string> —

Associative array of option value => option label.

get_page_instance_web_slug()

Resolve the public URL slug of the Instance assigned to a page.


    private
                    get_page_instance_web_slug(int $post_id) : string

Reads the page's scene_location meta and, when it holds a real Instance ID (not none or global), returns that Instance's instance_slug meta with any surrounding slashes trimmed. Returns an empty string when no Instance is assigned, the referenced post is not an Instance, or the Instance has no slug.

Parameters

$post_id : int: The page ID.

Return values

string —

The Instance URL slug, or '' when the page has no Instance.

is_instance_overview_scene()

Determine whether a page is the overview scene of the Instance it belongs to.


    private
                    is_instance_overview_scene(int $post_id) : bool

A page points at an Instance through its scene_location meta, and that Instance names a single overview scene through its instance_overview_scene meta. When the two match, the page doubles as the Instance's landing page.

Parameters

$post_id : int: The page ID to test.

Return values

bool —

True when the page is its Instance's overview scene, false otherwise.

overview_scene_notice_message()

Build the notice text shown when a page is its Instance's overview scene.


    private
                    overview_scene_notice_message(int $post_id) : string

Parameters

$post_id : int: The page the notice is about.

Return values

string —

Translated, human-readable message naming the Instance where possible.

scene_belongs_to_instance()

Determine whether a published Scene with the given slug belongs to an Instance.


    private
                    scene_belongs_to_instance(string $scene_slug, string $instance_slug) : bool

Used to decide whether an {instance_slug}/{slug} request should stay on the Scene routing path or fall through to page routing.

Parameters

$scene_slug : string: The Scene post slug (second URL segment).
$instance_slug : string: The Instance URL slug (first URL segment).

Return values

bool —

True when a published Scene with that slug is assigned to the Instance whose instance_slug matches $instance_slug.

Graphic_Data_Page_Options in package Application

Table of Contents

Constants

Methods

Constants

INSTANCE_META_KEY

NAVBAR_META_KEY

NONCE_ACTION

NONCE_NAME

ORDER_MAX

ORDER_META_KEY

ORDER_MIN

Methods

add_instance_meta_box()

Tags

change_page_columns()

Parameters

Tags

Return values

custom_page_column()

Parameters

Tags

enqueue_overview_scene_notice()

Tags

filter_instance_page_link()

Parameters

Tags

Return values

overview_scene_editor_notice()

Tags

register_page_instance_meta()

Tags

render_instance_meta_box()

Parameters

Tags

resolve_instance_page_request()

Parameters

Tags

Return values

save_instance_meta_box()

Parameters

Tags

get_instance_options()

Tags

Return values

get_page_instance_web_slug()

Parameters

Tags

Return values

is_instance_overview_scene()

Parameters

Tags

Return values

overview_scene_notice_message()

Parameters

Tags

Return values

scene_belongs_to_instance()

Parameters

Tags

Return values

Graphic_Data_Page_Options
in package

Application