Documentation

Graphic_Data_Utility
in package

Utility functions used across the plugin

Tags
link
https://github.com/ioos/sanctuarywatch_graphicdata
since
1.0.0

Table of Contents

Methods

check_draft_overview_scene()  : void
Checks if a scene is the overview scene for an instance and - if so - if the scene has been set to draft (hint: it shouldn't be)
create_instance_dropdown_filter()  : void
Create Instance filter dropdown shown in the Scene, Modal, and Figure admin column screens.
delete_fields_transient()  : bool
Helper function to delete field values from transients
display_warning_message_if_new_post_impossible()  : void
Display warning message if add new post is not possible for custom content post type.
extract_field_values()  : mixed
Recursively extract field values from POST data based on field configuration
fields_to_transient()  : void
Store field values in a user-specific transient.
get_fields_from_transient()  : array<string|int, mixed>|false
Helper function to retrieve field values from transients.
get_filter_value()  : bool|string|int
Check if stored filter values are still valid and retrieve them if they are.
get_user_transient_key()  : string
Helper function to create a unique transient key for the current user, based on the user ID.
inject_tinymce_changes()  : void
Customizes TinyMCE editors for specific post types.
meta_get_callback()  : mixed
REST API get callback for retrieving a post meta value.
output_transient_to_js()  : void
Output transient data as JavaScript for field validation.
post_admin_notice()  : void
Displays admin notices for the following kind of custom content posts: about, instance, scene, modal, and figure.
register_custom_rest_fields()  : void
Register custom meta fields with the REST API for a given post type.
render_nonce_field()  : mixed
Add nonce field to about, modal, scene, instance, and figure custom post types.
retrieve_post_errors_warnings()  : mixed
Return data entry errors and warnings associated with custom posts.
retrieve_post_status()  : mixed
Return post status for custom posts.
return_all_instances()  : array<string|int, mixed>
Get a list of all instances, filtered for 'content_editor' role.
return_figure_icons()  : array<string|int, mixed>
Retrieve modal icon dropdown options for the figure content type.
return_icons()  : array<string|int, mixed>
Retrieves icon IDs from an SVG infographic associated with a scene.
return_instance_scenes()  : array<string|int, mixed>
Get a list of all scenes associated with an instance.
return_modal_sections()  : array<string|int, mixed>
Retrieve modal section headers for a given scene.
return_modal_tabs()  : array<string|int, mixed>
Retrieve tab titles for a given modal.
return_scene_titles()  : array<string|int, mixed>
Get scene titles for scenes sharing the same instance as a modal.
return_scenes_except_current()  : array<string|int, mixed>
Return an array of scenes, other than the current scene, for a given location.
return_scenes_figure()  : array<string|int, mixed>
Retrieve scene dropdown options for the figure content type.
sanitize_number_or_quotes_field()  : string|int
Sanitize the field value when the option is a whole number or an empty string.
string_truncate()  : string
Shorten string without cutting words midword.

Methods

check_draft_overview_scene()

Checks if a scene is the overview scene for an instance and - if so - if the scene has been set to draft (hint: it shouldn't be)

public check_draft_overview_scene() : void

The overview scene for an instance should not be in draft status, unless the instance is itself not published. The reason is that the front page tile for the instance will just redirect back to the front page of the site (if the the overview scene is set to draft). If the overview scene is set to draft then an admin notice is posted in the edit screen for the relevant scene and instance.

Return values
void —

Outputs the appropriate admin notice if necessary.

create_instance_dropdown_filter()

Create Instance filter dropdown shown in the Scene, Modal, and Figure admin column screens.

public create_instance_dropdown_filter(string $element_name) : void

Generates a dropdown filter for selecting instances with role-based access control. Content editors see only their assigned instances, while administrators and content managers see all published instances. The dropdown maintains the selected value across page loads via GET parameter or stored filter value.

Parameters
$element_name : string

The name and ID attribute for the select element. Used for form submission and DOM targeting.

Tags
since
1.0.0
global

wpdb $wpdb WordPress database abstraction object.

uses
wp_get_current_user()

Retrieves the current user object.

uses
current_user_can()

Checks user capabilities for role-based filtering.

uses
get_user_meta()

Fetches assigned instances for content editors.

uses
selected()

WordPress helper for marking selected options.

uses
esc_attr()

Escapes attribute values for security.

uses
esc_html()

Escapes output text for security.

uses
esc_html__()

Translates and escapes text.

uses

$this->get_filter_value() Retrieves stored filter value (custom method).

example

// Display instance filter with custom element name $this->create_instance_dropdown_filter('scene_instance');

security
  • Sanitizes instance IDs using absint() before SQL queries
  • Escapes all output using esc_attr() and esc_html()
  • Validates user permissions before showing filtered results
  • Prepares SQL safely by using sanitized, imploded integer arrays
access

public

Return values
void —

Outputs the HTML select element directly to the buffer.

delete_fields_transient()

Helper function to delete field values from transients

public delete_fields_transient(string $content_type) : bool
Parameters
$content_type : string

The custom content type

Return values
bool —

True if successful, false otherwise

display_warning_message_if_new_post_impossible()

Display warning message if add new post is not possible for custom content post type.

public display_warning_message_if_new_post_impossible() : void

This function display a warning message on the admin screen for a custom content type, if the underlying data necessary to create a new post of that content type is not present. This function is only currently implemented for the instance content type, but is intended to be generalized for use with scene, modal, and figure content types as well.

Tags
global

string $pagenow The current admin page filename.

global

string $typenow The current post type being viewed.

since
1.0.0
Return values
void —

Outputs HTML directly to the admin screen. No return value.

extract_field_values()

Recursively extract field values from POST data based on field configuration

public extract_field_values(array<string|int, mixed> $fields, array<string|int, mixed> &$all_fields, string $key_name) : mixed
Parameters
$fields : array<string|int, mixed>

The fields configuration array

$all_fields : array<string|int, mixed>

Reference to array where field values will be stored

$key_name : string

The base key for the associated transient, used (e.g., 'modal_error_all_fields').

fields_to_transient()

Store field values in a user-specific transient.

public fields_to_transient(string $key_name, array<string|int, mixed>|string $fields_config[, int $expiration = 1800 ]) : void

Writes field configuration data to a transient for later retrieval during field validation. Handles both array and string data types. For arrays with keys ending in 'error_all_fields', extracts nested field values; otherwise stores the data as-is. Cleans up expired transients before storing new ones.

Parameters
$key_name : string

The base key for the transient (e.g., 'modal_error_all_fields').

$fields_config : array<string|int, mixed>|string

The fields configuration array or string value to store.

$expiration : int = 1800

Optional. Time until expiration in seconds. Default 1800 (30 minutes).

Tags
since
1.0.0

get_fields_from_transient()

Helper function to retrieve field values from transients.

public get_fields_from_transient(string $content_type) : array<string|int, mixed>|false
Parameters
$content_type : string

The custom content type

Return values
array<string|int, mixed>|false —

The stored field values or false if not found

get_filter_value()

Check if stored filter values are still valid and retrieve them if they are.

public get_filter_value(string $meta_key) : bool|string|int

This function retrieves a stored filter value from user metadata and verifies if it has exceeded its expiration time. If the value has expired, it cleans up the metadata entries and returns false. Otherwise, it returns the stored value.

Parameters
$meta_key : string

The meta key to check expiration for.

Tags
since
1.0.0
access

public

Return values
bool|string|int —

False if expired or not found, the value if still valid.

get_user_transient_key()

Helper function to create a unique transient key for the current user, based on the user ID.

public get_user_transient_key(string $base_key) : string

This function is used as part of the field validation process in multiple places.

Parameters
$base_key : string

The base key for the transient

Return values
string —

The user-specific transient key

inject_tinymce_changes()

Customizes TinyMCE editors for specific post types.

public inject_tinymce_changes() : void

Runs on admin screens for 'instance', 'scene', 'modal', 'figure', and 'about' post types. For a defined set of field IDs, restricts the toolbar to bold, italic, underline, link, and unlink, and injects a style tag into the editor iframe to render body text in a sans-serif font.

Tags
since
1.0.0
Return values
void —

Returns early if not on an allowed post type screen or if the editor ID is not in the allowed fields list.

meta_get_callback()

REST API get callback for retrieving a post meta value.

public meta_get_callback(array<string|int, mixed> $object, string $field_name, WP_REST_Request $request) : mixed

Used as the get_callback by register_custom_rest_fields().

Parameters
$object : array<string|int, mixed>

The post data array containing the post 'id'.

$field_name : string

The meta field name to retrieve.

$request : WP_REST_Request

The current REST API request object.

Return values
mixed —

The single post meta value for the given field.

output_transient_to_js()

Output transient data as JavaScript for field validation.

public output_transient_to_js() : void

Retrieves user-specific transient data containing custom field values and outputs it as a JavaScript variable on post edit pages. Only runs for specific custom post types (modal, scene, instance, figure, about). The transient is deleted after being output.

Tags
since
1.0.0

post_admin_notice()

Displays admin notices for the following kind of custom content posts: about, instance, scene, modal, and figure.

public post_admin_notice() : void

Shows informational, error, or warning messages based on the status of the post. Notices are displayed only on the post type edit screen after a post has been updated.

Return values
void —

Outputs the appropriate admin notice.

register_custom_rest_fields()

Register custom meta fields with the REST API for a given post type.

public register_custom_rest_fields(string $post_type, array<string|int, string> $rest_fields) : void

Iterates through the provided field names and registers each one as a readable REST API field using the class's meta_get_callback method.

Parameters
$post_type : string

The post type slug to register the fields for.

$rest_fields : array<string|int, string>

Array of meta field names to expose via the REST API.

render_nonce_field()

Add nonce field to about, modal, scene, instance, and figure custom post types.

public render_nonce_field(WP_Post $post) : mixed
Parameters
$post : WP_Post

Current post object.

Tags
since
1.0.0

retrieve_post_errors_warnings()

Return data entry errors and warnings associated with custom posts.

public retrieve_post_errors_warnings(string $post_type, string $issue_type) : mixed

This function retrieves errors and warnings associated with custom posts of type about, instance, scene, modal, and figure. The retrieval occurs from WordPress transients, which are recorded at the moment that the post in question was saved. This function is used after that posts reloads after the save.

Parameters
$post_type : string

The custom post type.

$issue_type : string

Either 'errors' or 'warnings'.

retrieve_post_status()

Return post status for custom posts.

public retrieve_post_status(string $post_type) : mixed

This function the post status associated with custom posts of type about, instance, scene, modal, and figure. The retrieval occurs from a WordPress transient, which is recorded at the moment that the post in question was saved. This function is used after that posts reloads after the save.

Parameters
$post_type : string

The custom post type.

return_all_instances()

Get a list of all instances, filtered for 'content_editor' role.

public return_all_instances() : array<string|int, mixed>
Return values
array<string|int, mixed> —

An associative array of instance IDs and titles.

return_figure_icons()

Retrieve modal icon dropdown options for the figure content type.

public return_figure_icons(int|string $scene_id) : array<string|int, mixed>

Queries all 'modal' posts that belong to the given scene and have an 'icon_function' of 'Modal', then returns their IDs mapped to titles. The resulting array includes a leading empty entry for use as a default dropdown option.

Parameters
$scene_id : int|string

The post ID of the scene to retrieve modal icons for.

Return values
array<string|int, mixed> —

Associative array keyed by modal post ID with post titles as values. Includes a leading empty entry.

return_icons()

Retrieves icon IDs from an SVG infographic associated with a scene.

public return_icons(int $scene_id) : array<string|int, mixed>

Parses the SVG file linked to the scene's infographic meta field and extracts the IDs of all child elements within the 'icons' group element.

Parameters
$scene_id : int

The post ID of the scene.

Return values
array<string|int, mixed> —

Associative array of icon IDs where both key and value are the icon ID. Returns array with single empty key/value pair if no infographic exists or if the 'icons' element is not found in the SVG.

return_instance_scenes()

Get a list of all scenes associated with an instance.

public return_instance_scenes(int $instance_id) : array<string|int, mixed>
Parameters
$instance_id : int

The instance ID to find scenes for.

Return values
array<string|int, mixed> —

Associative array of scene IDs to scene titles, sorted alphabetically.

return_modal_sections()

Retrieve modal section headers for a given scene.

public return_modal_sections(int $scene_id) : array<string|int, mixed>

Iterates through up to six scene sections, pulling each section's post meta and collecting non-empty titles. The resulting array is sorted alphabetically and prefixed with a blank entry for use as dropdown options.

Parameters
$scene_id : int

The post ID of the scene.

Return values
array<string|int, mixed> —

Associative array keyed by section field name (e.g. 'scene_section1') with section titles as values. Includes a leading empty entry.

return_modal_tabs()

Retrieve tab titles for a given modal.

public return_modal_tabs(int|string $modal_id) : array<string|int, mixed>

Iterates through up to six tab title meta fields for the specified modal post and collects any non-empty titles. The resulting array includes a leading empty entry for use as a default dropdown option.

Parameters
$modal_id : int|string

The post ID of the modal.

Return values
array<string|int, mixed> —

Associative array keyed by tab number (1-6) with tab titles as values. Includes a leading empty entry.

return_scene_titles()

Get scene titles for scenes sharing the same instance as a modal.

public return_scene_titles(int $scene_id, int $modal_id) : array<string|int, mixed>
Parameters
$scene_id : int

The scene ID to get the title for.

$modal_id : int

The modal ID to determine the scene instance.

Return values
array<string|int, mixed> —

Associative array of scene IDs to titles with an empty option first, sorted alphabetically.

return_scenes_except_current()

Return an array of scenes, other than the current scene, for a given location.

public return_scenes_except_current(int $scene_id) : array<string|int, mixed>
Parameters
$scene_id : int

The current scene ID to exclude from results.

Return values
array<string|int, mixed> —

Associative array of scene IDs to titles with an empty option first, sorted alphabetically.

return_scenes_figure()

Retrieve scene dropdown options for the figure content type.

public return_scenes_figure(string $location) : array<string|int, mixed>

Queries all 'scene' posts whose 'scene_location' meta matches the given location and returns their IDs mapped to titles. The resulting array includes a leading empty entry for use as a default dropdown option.

Parameters
$location : string

The location value to match against the 'scene_location' meta field.

Return values
array<string|int, mixed> —

Associative array keyed by scene post ID with post titles as values. Includes a leading empty entry.

sanitize_number_or_quotes_field()

Sanitize the field value when the option is a whole number or an empty string.

public sanitize_number_or_quotes_field(mixed $value) : string|int

Returns an empty string if the value is empty, otherwise converts it to a non-negative integer using absint().

Parameters
$value : mixed

The raw field value to sanitize.

Tags
since
1.0.0
Return values
string|int —

Empty string if blank, otherwise a non-negative integer.

string_truncate()

Shorten string without cutting words midword.

public string_truncate(string $string, int $your_desired_width) : string
Parameters
$string : string

The string to be shortened.

$your_desired_width : int

The number of characters in the shortened string.

Tags
since
1.0.0
Return values
string —

The shortened string


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results