Class MLA (Media Library Assistant) Data provides database and template file access for MLA needs

The _template functions are inspired by the book "WordPress 3 Plugin Development Essentials." Templates separate HTML markup from PHP code for easier maintenance and localization.

package Media Library Assistant
since 0.1

 Methods

Initialization function, similar to __construct()

initialize() 

since 0.1

Get the total number of attachment posts

mla_count_list_table_items(array $request, int $offset, int $count) : integer

since 0.30

Parameters

$request

array

Query variables, e.g., from $_REQUEST

$offset

int

(optional) number of rows to skip over to reach desired page

$count

int

(optional) number of rows on each page

Returns

integerNumber of attachment posts

Returns information about an attachment's parent, if found

mla_fetch_attachment_parent_data(int $parent_id) : array

since 0.1

Parameters

$parent_id

int

post ID of attachment's parent, if any

Returns

arrayParent information; post_date, post_title and post_type

Find Featured Image and inserted image/link references to an attachment

mla_fetch_attachment_references(int $ID, int $parent) : array

Searches all post and page content to see if the attachment is used as a Featured Image or inserted in the post as an image or link.

since 0.1

Parameters

$ID

int

post ID of attachment

$parent

int

post ID of attachment's parent, if any

Returns

arrayReference information; see $references array comments

Finds the value of a key in a possibily nested array structure

mla_find_array_element(string $needle, array $haystack, string $option, boolean $keep_existing) : string

Used primarily to extract fields from the _wp_attachment_metadata custom field. Could also be used with the ID3 metadata exposed in WordPress 3.6 and later.

since 1.30

Parameters

$needle

string

key value, e.g. array1.array2.element

$haystack

array

PHP nested arrays

$option

string

format option 'text'|'single'|'export'|'array'|'multi'

$keep_existing

boolean

keep existing values - for 'multi' option

Returns

stringvalue matching key(.key ...) or ''

Invalidates the $mla_galleries or $galleries array and cached values

mla_flush_mla_galleries(string $option_name) : void

since 1.00

Parameters

$option_name

string

name of the gallery's cache/option variable

Retrieve an Attachment array given a $post_id

mla_get_attachment_by_id(int $post_id) : NULL | array

The (associative) array will contain every field that can be found in the posts and postmeta tables, and all references to the attachment.

since 0.1
uses \global\$post

Parameters

$post_id

int

The ID of the attachment post

Returns

NULLarrayNULL on failure else associative array

Analyze a template, returning an array of the place holders it contains

mla_get_template_placeholders(string $tpl) : array

since 0.90

Parameters

$tpl

string

A formatting string containing [+placeholders+]

Returns

arrayPlaceholder information: each entry is an array with ['prefix'] => string, ['value'] => string, ['option'] => string 'single'|'export'

Load an HTML template from a file

mla_load_template(string $source, string $type) : string | array | false | NULL

Loads a template to a string or a multi-part template to an array. Multi-part templates are divided by comments of the form , where "key" becomes the key part of the array.

since 0.1

Parameters

$source

string

Complete path and name of the template file, option name or the raw template

$type

string

Optional type of template source; 'file' (default), 'option', 'string'

Returns

stringarrayfalseNULLstring for files that do not contain template divider comments, array for files containing template divider comments, false if file or option does not exist, NULL if file could not be loaded.

Expand a template, replacing place holders with their values

mla_parse_template(string $tpl, array $hash) : string

A simple parsing function for basic templating.

since 0.1

Parameters

$tpl

string

A formatting string containing [+placeholders+]

$hash

array

An associative array containing keys and values e.g. array('key' => 'value')

Returns

stringPlaceholders corresponding to the keys of the hash will be replaced with their values

Retrieve attachment objects for list table display

mla_query_list_table_items(array $request, int $offset, int $count) : array

Supports prepare_items in class-mla-list-table.php. Modeled after wp_edit_attachments_query in wp-admin/post.php

since 0.1

Parameters

$request

array

query parameters from web page, usually found in $_REQUEST

$offset

int

number of rows to skip over to reach desired page

$count

int

number of rows on each page

Returns

arrayattachment objects (posts) including parent data, meta data and references

Retrieve attachment objects for the WordPress Media Manager

mla_query_media_modal_items(array $request, int $offset, int $count) : array

Supports month-year and taxonomy-term filters as well as the enhanced search box

since 1.20

Parameters

$request

array

query parameters from Media Manager

$offset

int

number of rows to skip over to reach desired page

$count

int

number of rows on each page

Returns

arrayattachment objects (posts)

Adds a JOIN clause, if required, to handle sorting/searching on custom fields or ALT Text

mla_query_posts_join_filter(string $join_clause) : string

Defined as public because it's a filter.

since 0.30

Parameters

$join_clause

string

query clause before modification

Returns

stringquery clause after "LEFT JOIN view ON post_id" item modification

Adds a ORDERBY clause, if required

mla_query_posts_orderby_filter(string $orderby_clause) : string

Expands the range of sort options because the logic in WP_Query is limited. Defined as public because it's a filter.

since 0.30

Parameters

$orderby_clause

string

query clause before modification

Returns

stringupdated query clause

Adds a keyword search to the WHERE clause, if required

mla_query_posts_search_filter(string $search_string, object $query_object) : string

Defined as public because it's a filter.

since 0.60

Parameters

$search_string

string

query clause before modification

$query_object

object

WP_Query object

Returns

stringquery clause after keyword search addition

Adds a WHERE clause for detached items

mla_query_posts_where_filter(string $where_clause) : string

Modeled after _edit_attachments_query_helper in wp-admin/post.php. Defined as public because it's a filter.

since 0.1

Parameters

$where_clause

string

query clause before modification

Returns

stringquery clause after "detached" item modification

Invalidates $mla_galleries and $galleries arrays and cached values after post, page or attachment updates

mla_save_post_action(integer $post_id) : void

since 1.00

Parameters

$post_id

integer

ID of post/page/attachment; not used at this time

Update a single item; change the meta data for a single attachment.

mla_update_single_item(int $post_id, array $new_data, array $tax_input, array $tax_actions) : array

since 0.1

Parameters

$post_id

int

The ID of the attachment to be updated

$new_data

array

Field name => value pairs

$tax_input

array

Optional taxonomy term values, default null

$tax_actions

array

Optional taxonomy actions (add, remove, replace), default null

Returns

arraysuccess/failure message and NULL content

Builds the $mla_galleries or $galleries array

_build_mla_galleries(string $option_name, array $galleries_array, string $shortcode, boolean $exclude_revisions) : boolean

since 0.70

Parameters

$option_name

string

name of the gallery's cache/option variable

$galleries_array

array

by reference to the private static galleries array variable

$shortcode

string

the shortcode to be searched for and processed

$exclude_revisions

boolean

true to exclude revisions from the search

Returns

booleantrue if the galleries array is not empty

Add filters, run query, remove filters

_execute_list_table_query(array $request) : object

since 0.30

Parameters

$request

array

query parameters from web page, usually found in $_REQUEST

Returns

objectWP_Query object with query results

Format printable version of binary data

_hex_dump(string $data, integer $limit, \intger $bytes_per_row) : string

since 0.90

Parameters

$data

string

Binary data

$limit

integer

Bytes to format, default = 0 (all bytes)

$bytes_per_row

\intger

Bytes to format on each line

Returns

stringPrintable representation of $data

Sanitize and expand query arguments from request variables

_prepare_list_table_query(array $raw_request, int $offset, int $count) : array

Prepare the arguments for WP_Query. Modeled after wp_edit_attachments_query in wp-admin/post.php

since 0.1

Parameters

$raw_request

array

query parameters from web page, usually found in $_REQUEST

$offset

int

Optional number of rows (default 0) to skip over to reach desired page

$count

int

Optional number of rows on each page (0 = all rows, default)

Returns

arrayrevised arguments suitable for WP_Query

Remove tags from a term ids list

_remove_tags(array $terms_before, array $tags, object $taxonomy_obj) : array

since 0.40

Parameters

$terms_before

array

The term ids currently assigned

$tags

array

| string The term ids (array) or names (string) to remove

$taxonomy_obj

object

The taxonomy object

Returns

arrayTerm ids of the surviving tags

Search the $mla_galleries or $galleries array

_search_mla_galleries(array $galleries_array, int $attachment_id) : array

since 0.70

Parameters

$galleries_array

array

by reference to the private static galleries array variable

$attachment_id

int

the attachment ID to be searched for and processed

Returns

arrayAll posts/pages with one or more galleries that include the attachment. The array key is the parent_post ID; each entry contains post_title and post_type.

 Properties

 

Objects containing [gallery] shortcodes

$galleries : array

This array contains all of the objects containing one or more [gallery] shortcodes and array(s) of which attachments each [gallery] contains. The arrays are built once each page load and cached for subsequent calls.

The outer array is keyed by post_id. It contains an associative array with: ['parent_title'] post_title of the gallery parent, ['parent_type'] 'post' or 'page' or the custom post_type of the gallery parent, ['results'] array ( ID => ID ) of attachments appearing in ANY of the parent's galleries. ['galleries'] array of [gallery] entries numbered from one (1), containing: galleries[X]['query'] contains a string with the arguments of the [gallery], galleries[X]['results'] contains an array ( ID ) of post_ids for the objects in the gallery.

since 0.70
 

Provides a unique name for the ALT Text SQL VIEW

$mla_alt_text_view : array

since 0.40
 

Objects containing [mla_gallery] shortcodes

$mla_galleries : array

This array contains all of the objects containing one or more [mla_gallery] shortcodes and array(s) of which attachments each [mla_gallery] contains. The arrays are built once each page load and cached for subsequent calls.

since 0.70
 

Cache the results of mla_count_list_table_items for reuse in mla_query_list_table_items

$mla_list_table_items : array

since 1.40
 

WP_Query filter "parameters"

$query_parameters : array

This array defines parameters for the query's join, where and orderby filters. The parameters are set up in the _prepare_list_table_query function, and any further logic required to translate those values is contained in the filters.

Array index values are: use_postmeta_view, postmeta_key, postmeta_value, patterns, detached, orderby, order, mla-metavalue, debug, s, mla_search_connector, mla_search_fields, sentence, exact

since 0.30

 Constants

 

Provides a unique suffix for the ALT Text SQL VIEW

MLA_ALT_TEXT_VIEW_SUFFIX 

since 0.40