MLA / HTML STATIC KEEPERS – clickety-clack.click

[mla_gallery]

Enhanced version of the WordPress [gallery] shortcode.

Title: subscribe-shortcuts-astute-graphics-2019-(2)

Title: widthscribe-astute-graphics-shortcuts

Title: stylism-astute-graphics-shortcuts

Title: texurino-astute-graphics-shortcuts

1 2 3 Next »


[mla_gallery  itemtag="div" icontag="div" captiontag="p" columns="4" posts_per_page=4 size_class=medium attachment_category="astute-atc" attachment_tag="" post_mime_type=application/pdf  mla_target="_blank" post_parent=all link=file  mla_caption="{+title+}"]
<br> mla_caption='<a href="{+file_url+}" target="_blank" class="mlagallerycaption" rel="noopener">Title: {+title+}</a>'
[/mla_gallery]
<div class="mlagalleryprevnxt-nav">
[mla_gallery itemtag="div" icontag="div" captiontag="p" columns="4" posts_per_page=4  size_class=medium attachment_category="astute-atc" attachment_tag="" post_mime_type=application/pdf post_parent=all  mla_target="_self" link=file mla_margin="520px"  mla_output="paginate_links,prev_next"][/mla_gallery]
</div>

VERSION II

Title: video-property-end-ful-inout

Title: video-property-mid-ful-inout

Title: video-property-start-ful-inout




<div class="video-gallery woof">[mla_gallery  itemtag="div" icontag="div" captiontag="p" columns="4" posts_per_page=12 size_class=medium attachment_category="bumperv3" attachment_tag="" post_mime_type="image,video" link=file  mla_target="_blank" post_parent=all  mla_link_attributes='rel="shadowbox{sbalbum-{+instance+}};player=img"' mla_caption="{+title+}"]
<br> mla_caption='<a href="{+file_url+}" target="_blank" class="mlagallerycaption kg-video-js-skin" rel="noopener">Title: {+title+}</a>'
[/mla_gallery]
<div class="mlagalleryprevnxt-nav">
[mla_gallery itemtag="div" icontag="div" captiontag="p" columns="4" posts_per_page=12  size_class=medium attachment_category="bumperv3" attachment_tag="" post_mime_type="image,video" post_parent=all  mla_target="_self" link=file mla_margin="520px"  mla_output="paginate_links,prev_next"][/mla_gallery]
</div>
</div>

Creating Thumbnails (pdfs) w/ MLA

You can try using MLA’s thumbnail generation function to correct the problem:

Navigate to the Media/Assistant admin submenu.
Check the box to the left of the document.
Pull down the “Bulk actions” list, select “Thumbnail” and click “Apply.
Leave the “Type (o) WP” selection in place.
You may have to change the “Existing items” selection to “Delete”, but try first with the “Keep” default.
Click “Generate Thumbnails”.

>PULL DOWN ‘HELP TAB’ for more settings

Complete documentation

MLA Gallery Shortcode

The [mla_gallery] shortcode is used in a post, page or custom post type to add a gallery of images and/or other Media Library items (such as PDF documents). MLA Gallery is a superset of the

[gallery]
shortcode in the WordPress core; it is compatible with

[gallery]
and provides many enhancements. These include:

Full support for WordPress categories, tags and custom taxonomies. You can select items with any of the taxonomy parameters documented in the WP_Query class.
Support for all post_mime_type values, not just images.
Media Library items need not be "attached" to the post. You can build a gallery with any combination of items in the Library using taxonomy terms, custom fields and more.
Control over the styles, markup and content of each gallery using the Style and Markup Templates documented below.
Access to a wide range of content using the Attachment-specific and Field-level Substitution parameters documented below. A powerful Content Template facility lets you assemble content from multiple sources and vary the results depending on which data elements contain non-empty values for a given gallery item.
You can combine [mla_gallery] data selection with other popular gallery-generating plugins to get the best of both.

Option/Parameter Documentation Sources

If you're new to Media Library Assistant and the [mla_gallery] shortcode you should read through the material in the MLA Gallery Examples section.

All of the options/parameters documented for the

[gallery]
shortcode are supported by the [mla_gallery] shortcode; you can find them in the

Substitution Parameters

Substitution parameters are a powerful way to add general and attachment-specific values to the gallery display. For example, if you code "mla_rollover_text='{+date+} : {+description+}', the rollover text will contain the upload date, a colon, and the full description of each gallery item. There are dozens of parameter names like `date` and `description` divided in several categories:

Gallery-specific	values that are known at the beginning of shortcode processing and remain the same for the entire shortcode, such as the ID and URL of the post/page in which the shortcode appears
Style	values that are known when the gallery-specific CSS inline styles are composed just before gallery output begins
Markup	values that are known at the beginning of gallery output processing and remain the same for the entire gallery
Attachment-specific	values that change for each item in the gallery, such as Title and Caption
Field-level	values from sources like shortcode parameters, query arguments, custom fields, taxonomy terms and attachment metadata. There are many, many values to choose from as well as options to reformat values and select array elements. You are encouraged to explore them.
Content Template	lets you compose a value from multiple substitution parameters and test for empty values, choose among two or more alternatives or suppress output entirely

Click on any of the category names in the above table to go to the Documentation section describing the names available in that category and how to use them.

To use a substitution parameter in your shortcode, simply add "{+" before the substitution parameter name and add "+}" after the name. Note that the enclosing delimiters are different than those used in Style and Markup templates, since the WordPress shortcode parser reserves square brackets ("[" and "]") for its own use. Also, because square brackets are reserved, you must substitute curly braces for square brackets if your parameter values require them. For example, if your shortcode parameter is mla_link_attributes='rel="shadowbox{sbalbum-{+instance+}};player=img"', the actual attribute added to the link will be rel="shadowbox[sbalbum-1];player=img". If you must code a curly brace in a parameter value, preface it with two backslash characters, e.g., "\\{" or "\\}".

Entering Long/Complex Shortcodes

The [mla_gallery] shortcode has many parameters and some of them have a complex syntax; it can be a challenge to build a correct shortcode. The WordPress Shortcode API has a number of limitations that make techniques such as entering HTML or splitting shortcode parameters across multiple lines difficult. If you have trouble with your shortcode, such as an "Invalid mla_gallery tax_query" message, try these rules to correct the problem:

Use the Text tab of the post/page editor, not the Visual tab.
Enter the entire shortcode on one line; do not break it up - that confuses the WordPress shortcode parser.
Put "<code></code>" tags around the entire shortcode. Recent versions of WordPress mangle special characters like "=>" in the query if you don't add the tags.
Use the alternative "enclosing shortcode" syntax detailed below.

When embedding the shortcode in the body of a post, be very careful when coding parameters such as tax_query, meta_query or date_query; they must be a valid PHP array specification. Splitting your query over multiple lines or using the "Visual" editor will introduce HTML markup and escape sequences that can render your query invalid. MLA can clean up some of the damage, but if your query fails use the "mla_debug=true" parameter to see if your query has been corrupted. Look for the "mla_debug attribute_errors" entry in the debug output; it will often list the parts of the shortcode parameters that couldn’t be parsed.

IMPORTANT: Beginning with version 4.0, WordPress changed the way it handles shortcode parameters. Using angle brackets, e.g., the => characters in a shortcode will often return "Invalid mla_gallery tax_query" errors. To prevent this: 1) add "<code></code>" tags around your shortcode, 2) use an escape sequence like "=>" in your query or 3) use the enclosing shortcode syntax.

MLA also supports an alternative syntax that can help you avoid parsing problems with long shortcodes; the "enclosing shortcode" syntax. You can read all about it in the WordPress Shortcode API documentation, but the basic idea is simple. Instead of coding your parameters inside the shortcode square brackets:

[mla_gallery post_parent=all post_mime_type=image/png link=file]

You code the parameters between opening and closing shortcode delimiters:

[mla_gallery]post_parent=all post_mime_type=image/png link=file[/mla_gallery]

WordPress parses the second, "enclosing" syntax in a different way that can eliminate some problems and make your shortcode easier to understand. For example, you can split your shortcode over multiple lines:

[mla_gallery]
tax_query="
array(
array(
'taxonomy' => 'attachment_category',
'field' => 'id',
'terms' => array(11, 12)
)
)"
post_mime_type=image/png link=file
[/mla_gallery]

For simple [mla_gallery] shortcodes, code your parameters within the shortcode square brackets and follow the rules above. For more complex shortcodes, the enclosing syntax can avoid many of the limitations WordPress imposes on shortcode parsing.

Gallery Display Style

Two [mla_gallery] parameters provide a way to apply custom style and markup templates to your [mla_gallery] display. These parameters replace the default style and/or markup templates with templates you define on the "MLA Gallery" tab of the Settings page. On the "MLA Gallery" tab you can also select one of your custom templates to replace the built-in default template for all [mla_gallery] shortcodes the do not contain one of these parameters.

mla_style	replaces the default style template for an `[mla_gallery]` shortcode. You can code "none" to suppress the addition of CSS inline styles entirely, or code "theme" to let your theme use the `use_default_gallery_style` filter to make the decision.
mla_markup	replaces the default markup template for an `[mla_gallery]` shortcode

Four [mla_gallery] parameters provide control over the placement, size and spacing of gallery items without requiring the use of custom Style templates.

columns	specifies the number of columns. The gallery will include a break tag at the end of each row and calculate the column width as appropriate. The default value is 3. If columns is set to 0, no row breaks will be included.
mla_float	specifies the CSS float attribute of the ".gallery-item" style. Acceptable values are "left", "none", "right"; the default value is "right" if current locale is RTL, "left" on LTR (left-to-right inline flow, e.g., English).
mla_margin	specifies the CSS margin property of the ".gallery-item" style. The default value is "1.5%", a percent of the total gallery width. You can also specify any dimension value, e.g., "10px" or "2em", as well as the "auto" or "inherit" values. Finally, you can specify "none", which will remove the margin property from the styles template altogether.
mla_itemwidth	specifies the CSS width attribute of the ".gallery-item" style. You can specify a percent of the total gallery width, e.g., "33.3%". You can also specify any dimension value, e.g., "10px" or "2em", as well as the "auto" or "inherit" values. You can specify "none", which will remove the width property from the styles template altogether. Two additional values, "calculate" (the default) and "exact", calculate the width automatically, based on the "columns" and "mla_margin" values. For "calculate", the width is calculated by dividing 100% by the number of columns, then subtracting twice the margin. For example, the default value is (floor(1000/3)/10) - ( 2.0 * 1.5 ) = 30.3%. Adding in the left and right margins makes each column 33.3% and the total width will be 99.9% For the "exact" value, the calculation is the same but the margin is ignored, so the width value would be 33.3%.

These parameters are only important if the gallery thumbnails are too large to fit within the width of the page on which they appear. For example, if you code [mla_gallery size=full], the browser will automatically scale down large images to fit within the width attribute (in percent) of the ".gallery-item" style. The default 1.5% margin will ensure that the images do not overlap; you can increase it to add more space between the gallery items. You can also reduce the itemwidth parameter to increase the left and right space between the items.

The default margin and width calculations try to make the total width of each row as close to 100% as possible, but never exceed 100% due to rounding errors. If you have more advanced style and format needs, you can define custom style and/or markup templates. You can code mla_style=none to suppress inline styles entirely and use a separate stylesheet to control the format of the gallery. You can also code mla_style=theme, if your theme supports it, to use the theme's stylesheet to control the format of the gallery.

Three parameters provide control over the XHTML tags used to enclose each part of the gallery items.

itemtag	the name of the XHTML tag used to enclose each item in the gallery. The default is "dl"; if your theme supports HTML5, the default is "figure".
icontag	the name of the XHTML tag used to enclose each thumbnail icon in the gallery. The default is "dt"; if your theme supports HTML5, the default is "div".
captiontag	the name of the XHTML tag used to enclose each caption. The default is "dd"; if your theme supports HTML5, the default is "figcaption".

These parameters work together to change the gallery markup. For example, to change the gallery markup to use div, span and p tags:

[gallery itemtag="div" icontag="span" captiontag="p"]

Gallery Display Content

Twelve [mla_gallery] parameters provide an easy way to control the contents of gallery items without requiring the use of custom Markup templates.

mla_output	completely replaces gallery output with links to the "previous" or "next" item/page or pagination links. Complete documentation is in the section below.
mla_rollover_text	adds the HTML "title" attribute in the hyperlink for each gallery item. This is the attachment title text displayed when the mouse rolls or hovers over the gallery thumbnail. Note that as of WordPress 3.7 there is no default "title" attribute; for older WordPress versions this parameter will replace the default "title".
mla_target	adds an HTML "target" attribute to the hyperlink for each gallery item; see below.
mla_link_attributes	adds one or more HTML attributes to the hyperlink for each gallery item; see below.
mla_link_class	adds an HTML "class" attribute to the hyperlink for each gallery item.
mla_link_href	replaces the HTML "href" attribute in the hyperlink for each gallery item; see below.
mla_link_text	replaces the thumbnail image or attachment title text displayed for each gallery item.
mla_image_attributes	adds one or more HTML attributes to the "img" tag of the thumbnail image or icon displayed for each gallery item. Note that if you include an "alt" or "class" attribute in this parameter it will override and replace the corresponding attribute already present in the tag, including any "mla_image_class" or "mla_image_alt" value.
mla_image_class	adds one or more values to the HTML "class" attribute in the "img" tag of the thumbnail image or icon displayed for each gallery item. Existing class values are retained, not replaced.
mla_image_alt	replaces the HTML "alt" attribute in the "img" tag of the thumbnail image or icon displayed for each gallery item.
mla_caption	replaces the attachment caption text displayed beneath the thumbnail of each gallery item.
mla_nolink_text	replaces the empty string displayed when there are no gallery items or no pagination link.

The "mla_target" parameter accepts any value and adds an HTML "target" attribute to the hyperlink with that value. For example, if you code mla_target="_blank" the item will open in a new window or tab. You can also use "_self", "_parent", "_top" or the "framename" of a named frame.

All but the "mla_target" parameter support the Markup, Attachment-specific, Field-level and Content Template substitution parameters defined for Markup Templates. For example, if you code mla_rollover_text='{+date+} : {+description+}', the rollover text will contain the upload date, a colon, and the full description of each gallery item. Simply add "{+" before the substitution parameter name and add "+}" after the name. Note that the enclosing delimiters are different than those used in the templates, since the WordPress shortcode parser reserves square brackets ("[" and "]") for its own use.

The "mla_link_href" parameter is a great way to change the destination your gallery item links to or add arguments to the link for later processing. For example, to make a gallery item link back to the page/post it is attached to, you can code: mla_link_href='{+site_url+}/?page_id={+parent+}'. You can also add arguments to the link, e.g., mla_link_href='{+link_url+}?myarg1=myvalue1&myarg2=myvalue2'. Note the use of the HTML entity name "&" to put an ampersand in the value; the WordPress "visual" post editor will replace "&", "<" and ">" with "&", "<" and ">" whether you like it not. The only markup parameter modified by this parameter is "link". Other markup parameters such as "pagelink", "filelink" and "link_url" are not modified.

The "mla_link_attributes" and "mla_image_attributes" parameters accept any value and adds it to the "<a>" or "<img>" tags for the gallery item. For example, you can create a Shadowbox JS (plugin) album by adding mla_link_attributes='rel="shadowbox{sbalbum-{+instance+}};player=img"' to your shortcode query (note the use of single quotes around the parameter value and the double quotes within the parameter). IMPORTANT: since the shortcode parser reserves square brackets ("[" and "]") for its own use, you must substitute curly braces for square brackets if your attributes require brackets (as this example does). In this case, the actual attribute added to the link will be rel="shadowbox[sbalbum-1];player=img". If you must code a curly brace in your attribute value, preface it with two backslash characters, e.g., "\\{" or "\\}". If you code an attribute already present in the tag, your value will override the existing value.

The "mla_caption" parameter can be used, for example, to replace the default caption to a hyperlink containing the item's Title You can code something like this:

[mla_gallery size=icon post_mime_type=application/pdf post_parent=all link=file] mla_caption='<a href="{+file_url+}" target="_blank">{+title+}</a>' [/mla_gallery]

Note the use of the alternative "enclosing shortcode" syntax in this example, which avoids the WordPress issues with including HTML markup in shortcode parameters.

Thumbnail Substitution Support, mla_viewer

This solution supports dynamic thumbnail image generation for PDF and Postscript documents on your site's server. You can also assign a "Featured Image" to any Media Library item. For non-image items such as Microsoft Office documents the featured image will replace the MIME-type icon or document title in an [mla_gallery] display. Simply go to the Media/Edit Media screen, scroll down to the "Featured Image" meta box and select an image as you would for a post or page.

WordPress 4.7 added thumbnail generation for PDF documents, and these "native thumbnail images" will automatically be used when available. You can also use MLA's thumbnail generation support (in the Media/Assistant Bulk Actions) to create native thumbnails for older documents.

The dynamic thumbnail image generation for PDF and Postscript documents uses the PHP Imagick class, which requires ImageMagick and Ghostscript to be installed on your server. If you need help installing them, look at this PDF Thumbnails support topic. If you don't have them on your server you can still use the Featured Image support to supply thumbnails for your non-image items.

Ten [mla_gallery] parameters provide an easy way to simulate thumbnail images for the non-image file types.

mla_viewer	must be "true" or "single" to enable thumbnail substitution. Use "true" unless you experience generation failures due to memory limitations on your server. Use "single" to generate one thumbnail at a time, which may be slower but requires less memory. You can add ",required" to bypass the WordPress-generated native PDF thumbnails; MLA's Featured Image or a dynamically-generated thumbnail will always be used when ",required" is present.
mla_viewer_extensions	a comma-delimited list of the file extensions to be processed; the default is "ai,eps,pdf,ps" (do not include the dot (".") preceding the file extension). You may add or remove extensions (when support for additional types becomes available).
mla_viewer_limit	the upper limit in megabytes (default none) on the size of the file to be processed. You can set this to avoid processing large documents if performance becomes an issue.
mla_viewer_width	the maximum width in pixels (default "150") of the thumbnail image. The height (unless also specified) will be adjusted to maintain the page proportions.
mla_viewer_height	the maximum height in pixels (default "0") of the thumbnail image. The width (unless also specified) will be adjusted to maintain the page proportions.
mla_viewer_best_fit	retain page proportions (default "false") when both height and width are explicitly stated. If "false", the image will be stretched as required to exactly fit the height and width. If "true", the image will be reduced in size to fit within the bounds, but proportions will be preserved. For example, a typical page is 612 pixels wide and 792 pixels tall. If you set width and height to 300 and set best_fit to true, the thumbnail will be reduced to 231 pixels wide by 300 pixels tall.
size	You can use `size` as an alternative to `mla_viewer_width` and/or `mla_viewer_height` to set the image dimensions from one of the intermediate sizes your site supports, e.g., "medium" or "large" (but not "full"). If `size` is present and `mla_viewer_best_fit` is not, `mla_viewer_best_fit` will be set to "true".
mla_viewer_page	the page number (default "1") to be used for the thumbnail image. If the page does not exist for a particular document the first page will be used instead.
mla_viewer_resolution	the pixels/inch resolution (default 72) of the page before reduction. If you set this to a higher number, such as 300, you will improve thumbnail quality at the expense of additional processing time.
mla_viewer_quality	the compression quality (default 90) of the final page. You can set this to a value between 1 and 100 to get smaller files at the expense of image quality; 1 is smallest/worst and 100 is largest/best.
mla_viewer_type	the MIME type, "image/jpeg" or "image/png", (default image/jpeg) of the final thumbnail. You can, for example, set this to "image/png" to retain a transparent background instead of the white jpeg background.

When this feature is active, gallery items for which WordPress can generate a thumbnail image are not altered. If WordPress generation fails, the "Featured Image" will be used, if one is specified for the item. If the item does not have a Featured Image, supported file/MIME types (see mla_viewer_extensions) will have a gallery thumbnail generated dynamically. If all else fails, the thumbnail is replaced by an "img" html tag whose "src" attribute contains a url reference to the appropriate icon for the file/MIME type.

Five options in the Settings/Media Library Assistant MLA Gallery tab allow control over mla_viewer operation:

Enable thumbnail substitution
Check this option to allow the "mla_viewer" to generate thumbnail images for PDF documents. Thumbnails are generated dynamically, each time the item appears in an [mla_gallery] display.
NOTE: If Imagick and/or Ghostscript support is not present a warning message will be displayed below the option checkbox.
Enable Featured Images
Check this option to extend Featured Image support to all Media Library items. The Featured Image can be used as a thumbnail image for the item in an [mla_gallery] display.
Enable Featured Image Generation
Check this option to enable the "Thumbnail" generation action in the Media/Assistant submenu Bulk Actions dropdown. The Thumbnail generation action lets you add Featured Image items by generating an image for non-image files such as PDF documents.
Enable explicit Ghostscript check
Check this option to enable the explicit check for Ghostscript support required for thumbnail generation. If your Ghostscript software is in a non-standard location, unchecking this option bypasses the check. Bad things can happen if Ghostscript is missing but ImageMagick is present, so leave this option checked unless you know it is safe to turn it off.
Ghostscript path
If your Ghostscript software is in a non-standard location, enter the full path and name of the executable here. The value you enter will be used as-is and the search for Ghostscript in the usual locations will be bypassed.

Order, Orderby

The Orderby parameter specifies which database field(s) are used to sort the gallery. You can sort the gallery by one or more of these values (there is additional information on some of these values in the Codex WP_Query class reference):

none	No order.
ID	Order by post id. Note capitalization.
author	Order by author (id, not display name).
date	Order by date uploaded.
description, content	Order by attachment description.
title	Order by attachment title.
caption, excerpt	Order by attachment caption.
slug, name	Order by attachment name.
modified	Order by last modified date.
parent	Order by post/page parent id.
menu_order	Order by page order.
mime_type	Order by attachment MIME type.
comment_count	Order by number of comments.
rand	Random order.
<keyname>, meta_value, meta_value_num	Order by custom field value. Note that a 'meta_key=keyname' must also be present in the query. For example, to sort by a custom field called "Publication Date" and display the most recent items first, code `[mla_gallery meta_key="Publication Date" orderby=meta_value order=DESC]`
post__in	Preserve order given in the ids, include or post__in array.

You can sort on more than one value, e.g., orderby="author, date DESC" and you can specify ASC/DESC on a value by value basis. NOTE: multiple orderby values are separated by commas, not spaces. This is a change from WP_Query.

The order parameter (default ASC) can give an ASC/DESC default for any value that doesn't have a specific choice. For example, orderby="author, date DESC, mime_type" order=ASC is the same as orderby="author ASC, date DESC, mime_type ASC".

Size

The Size parameter specifies the image size to use for the thumbnail display; "thumbnail" is the default value. You can also substitute an appropriate icon for some or all items or replace the thumbnail image with the item title.

thumbnail, medium, large, full	For image types, the size of the image you want to display. For non-image types the title of the item will be displayed.
(other registered size)	For image types, any additional image size that was registered with add_image_size(). If the specified size is not available or if the attachment is not an image the title of the item will be displayed.
icon	Display an appropriate 60x60 (or 64x64) pixel thumbnail for image items and an appropriate icon for non-image items such as PDF or text files. If, however, a non-image item has a "Featured Image" it will replace the icon.
icon_feature	Display an appropriate 60x60 (or 64x64) pixel icon for ALL items, image and non-image. If, however, an item has a "Featured Image" it will replace the icon.
icon_only	Display an appropriate 60x60 (or 64x64) pixel icon for ALL items, image and non-image.
none	Suppress thumbnail display and substitute the title of the item.

Link

The Link parameter specifies the target and type of link from the gallery item to the attachment or other destination. You can also specify a non-hyperlink treatment for the item.

permalink, post	Link to the attachment's "media page". This is the default value.
file, full	Link directly to the attachment file. See also the "Transfer by Item Name" section just below.
download	Link to the MLA "Transfer by Item Name" feature for this attachment with `mla_disposition=attachment`. Forces a file download instead of opening the file in the browser. See the "Transfer by Item Name" section just below.
thumbnail, medium, large	For image attachments, the size of the image file you want to link to.
(other registered size)	For image attachments, any additional image size that was registered with add_image_size(). If the specified size is not available or if the attachment is not an image, the link will go directly to the attachment file.
span	Substitutes a `<span></span>` tag for the hyperlink tag. You can use the "mla_link_attributes" and "mla_link_class" parameters to add attributes to the `<span>` tag. You can use the "mla_link_text" parameter to customize the text within the span.
none	Eliminates the hyperlink tag surrounding the thumbnail image or text. You can use the "mla_link_text" parameter to customize the contents.

Note that the handling of `link=file` and `link=download` values can be altered by specifying mla_named_transfer=true as described in the next section.

Transfer by Item Name

The "mla_named_transfer" parameter activates a different approach to handling the link=file and link=download values. If you code mla_named_transfer=true each item will be identified by its post_name value instead of its directory and file name. When the gallery item link is clicked the post_name will be used to locate the file and send it to the browser. When used with link=download a file download is performed, otherwise the file will be opened in the browser.

The links generated for mla_named_transfer items are of the form:

http://mysite.com/wp-admin/admin-ajax.php?action=mla_named_transfer&mla_item=item-name&mla_disposition=inline

Where the query arguments are:

action	must be "mla_named_transfer".
mla_item	is the post_name/slug value for the item. This is the last, editable part of the item’s permalink.
mla_disposition	selects a "forced download" ( use "download" or "attachment" ) or "open in the bowser" ( use "file", "view" or "inline" ).
mla_debug	add `mla_debug=log` to send diagnostic information to the error log. If you add `mla_debug=log` as a shortcode parameter it will be added to these links as well.

This alternate approach provides a small measure of security by obscuring the directory structure used to locate the file. It also makes it possible to generate SEO-friendly "pretty links" and use the

Include, Exclude

include	comma separated attachment IDs to show only the information from these attachments.
exclude	comma separated attachment IDs excludes the information from these attachments. Please note that include and exclude cannot be used together.

You can add post_parent=all to include or exclude attachments regardless of which post or page they are attached to. You can add post_mime_type=all to include or exclude attachments of all MIME types, not just images.

Post ID, "ids", Post Parent

The "id" parameter lets you specify a post ID for your query. The gallery will display images which are attached to that post. If the "id" parameter is not specified, the [mla_gallery] behavior differs from the

[gallery]

behavior. If your query uses taxonomy or custom field parameters, "author", "author_name" or "s" (search term), then the query will NOT be restricted to items attached to the current post. This lets you build a gallery with any combination of Media Library items that match the parameters.

The "ids" parameter lets you specify a list of item/attachment IDs. The attachment(s) matching the "ids" values will be displayed in the order specified by the list.

You can use the "post_parent" to override the default behavior. If you set "post_parent" to a specific post ID, only the items attached to that post are displayed. You can also specify multiple values separated by commas, e.g., post_parent=1,2,3. There are four additional values available:

none	all the unattached items are displayed, i.e., items with post_parent equal to zero (0)
current	only the items attached to the current post/page are displayed, i.e., the post/page that contains the shortcode
any	all the attached items are displayed, i.e., items with post_parent not equal to zero (0)
all	all of the items are displayed, i.e., post_parent is ignored

For example, [mla_gallery tag="artisan"] will display all images having the specified tag value, regardless of which post (if any) they are attached to. If you use [mla_gallery tag="artisan" post_parent="current"] it will display images having the specified tag value only if they are attached to the current post.

Author, Author Name

You can query by author's id or "Username", the value used to log in to the site. In the database this is the "user_nicename" column (not the "display_name" column). For example, if you log in as "john" and your id is 2 you can code:

[mla_gallery author=2]
[mla_gallery author_name='john']

Multiple author ID values are allowed, but only one author name value can be entered.

Category Parameters

The Category parameters search in the WordPress core "Categories" taxonomy. Remember to use post_parent=current if you want to restrict your query to items attached to the current post. Category parameters supported by WP_Query are:

cat (int)	use category id.
category, category_name (string)	use category slug (NOT name). As a convenience, MLA allows "category" as a synonym for "category_name".
category__and (array)	use category id.
category__in (array)	use category id.
category__not_in (array)	use category id.

More information and examples can be found on the

Tag Parameters

The Tag parameters search in the WordPress core "Tags" taxonomy. Remember to use post_parent=current if you want to restrict your query to items attached to the current post.

More information and examples can be found on the

Simple Taxonomy Parameters

The [mla_gallery] shortcode supports the simple "{tax} (string)" values (deprecated as of WordPress version 3.1) as well as the more powerful "tax_query" value. Use these queries for your custom taxonomies (and for the MLA attachment_category and attachment_tag taxonomies); use the above Category and Tag parameters for the WordPress-provided taxonomies. If you do use a tax_query for Categories and Tags, the slug values are "category" and "post_tag".

For simple queries, enter the custom taxonomy name and the term(s) that must be matched, e.g.:

[mla_gallery attachment_category='separate-category,another-category']

Note that you should use the name/slug strings for taxonomy and terms, not the "title" strings. You can often use the "title" strings if they can be "sanitized" to the slug, but this is not always reliable. If you are using the "Att. Tag" taxonomy built in to MLA then your shortcode should be something like:

[mla_gallery attachment_tag=artisan]

In this example, "attachment_tag" is the WordPress taxonomy name/slug for the taxonomy. If you're using "Att. Category", the slug would be "attachment_category".

The default behavior of the simple taxonomy query will match any of the terms in the list. A special value lets you find items that have no assigned terms in the taxonomy. For example, to find items that have no Att. Tags you can code:

[mla_gallery attachment_tag=no.terms.assigned]

If you have two or more simple taxonomy queries, they will be joined by "AND". MLA enhances the simple taxonomy query form by providing three additional parameters:

tax_relation	SQL operator to join multiple taxonomy queries; can be "AND" (the default) or "OR".
tax_operator	SQL operator to join the terms within each taxonomy; can be "IN" (the default), "NOT IN" or "AND".
tax_include_children	whether or not to include children for hierarchical taxonomies; can be "true" (the default) or "false".

If you specify any of these parameters, MLA will convert your query to the more powerful "tax_query" form, searching on the "slug" field and using the operator you specify. For example, a query for two terms in which both terms must match would be coded as:

[mla_gallery attachment_category='separate-category,another-category' tax_operator=AND tax_include_children=false]

If you code two or more simple taxonomy queries, the items selected must contain the terms in all of the taxonomies; they are joined by "AND". If you want to include items that match the terms in any of the taxonomies you can add tax_relation="OR". For example, a query to match either an attachment_category or an attachment_tag would be coded as:

[mla_gallery attachment_category='some-category' attachment_tag="a-tag" tax_relation=OR]

Note that the default tax_include_children value is true, matching the default WordPress setting. If your tax_operator is "AND", you will almost certainly want to change this setting.

Compound Taxonomy Queries, "tax_input"

You can combine taxonomies and terms into a single parameter; tax_input. This is most often used to process selections made in the for controls that contain multiple taxonomies. The parameter value can be one or more items consisting of the taxonomy slug and a term_id or slug, separated by a period. For example, "animal.34" or "vegetable.carrot".

This example has a simple form to pick a term from two taxonomies and display a gallery with the items assigned to the selected term:

<form id="animal-vegetable-form" method="post" action="."> [mla_term_list taxonomy="animal,vegetable" mla_output=dropdown] <input id="animal-vegetable-form-submit" name="animal_vegetable_form_submit" type="submit" value="Search" /> </form> [mla_gallery tax_input={+template:({+request:tax_input.animal-vegetable+}|animal.invalid-slug}+}]

In the example, animal.invalid-slug is a taxonomy.term combination that does not exist. It causes the gallery display to be suppressed until a selection is made in the dropdown control.

Taxonomy Queries, the "tax_query"

More complex queries can be specified by using WP_Query's "tax_query", e.g.:

[mla_gallery] tax_query="array( array( 'taxonomy' => 'attachment_tag', 'field' => 'slug', 'terms' => 'artisan' ) )" [/mla_gallery]

[mla_gallery] tax_query="array( array( 'taxonomy' => 'attachment_category', 'field' => 'id', 'terms' => array(11, 12) ) )" post_parent=current post_mime_type=all [/mla_gallery]

The first example is equivalent to the simple query attachment_tag=artisan. The second example matches items of all MIME types, attached to the current post, having an attachment_category ID of 11 or 12. Both examples use the "enclosing shortcode" format to avoid problems WordPress has in parsing parameters with special characters such as =>.

When embedding the shortcode in the body of a post, be very careful when coding the tax_query; it must be a valid PHP array specification. Read and follow the rules and guidelines in the "Entering Long/Complex Shortcodes" Documentation section to get the results you want.

A special "terms" value, "no.terms.assigned" lets you find items that have no assigned terms in the taxonomy. For example, to find items that have no Att. Tags you can code:

[mla_gallery] tax_query="array( array( 'taxonomy' => 'attachment_tag', 'field' => 'id', 'terms' => 'no.terms.assigned' 'operator' => 'NOT IN' ) )" [/mla_gallery]

In addition to 'terms' => 'no.terms.assigned' you must code 'field' => 'id' and 'operator' => 'NOT IN' to get the proper results. The example uses use the "enclosing shortcode" format to avoid problems WordPress has in parsing parameters with special characters such as =>.

Remember to use post_parent=current if you want to restrict your query to items attached to the current post.

Taxonomy term keyword(s) search

Searching for keywords within the names of taxonomy terms is a completely different way to find items based on taxonomy information. Instead of matching on a slug or term-id value you can match on all or part of the term Title. The shortcode parameters in this section give you all the power of the "Terms Search" feature on the Media/Assistant submenu table, as described in the "Terms Search - filtering on taxonomy term names" Documentation section. Here are the shortcode parameters that correspond to the controls on the "Search Terms" popup window:

mla_terms_taxonomies	A comma-separated list of the taxonomy or taxonomies in which to search. Enter the slug(s) for one or more of the taxonomies registered for Media Library items, e.g., attachment_category or attachment_tag. If this parameter is omitted or empty, default taxonomies are specified in the Taxonomy Support section of the General tab.
mla_terms_phrases	The word(s) or phrase(s) you are searching for. Prepending a word or quoted phrase with a hyphen will exclude items matching that value, e.g., 'pillow -sofa' will return items containing 'pillow' but not 'sofa'.
mla_phrase_delimiter	A single character that separates the phrases within a term in `mla_terms_phrases`. The default delimiter is a space (' ').
mla_negative_delimiter	A single character that encloses the negative (excluded) phrases within a term in `mla_terms_phrases`. The default delimiter is a slash ('/').
mla_phrase_connector	If you enter multiple phrases (separated by the `mla_phrase_delimiter`) in the `mla_terms_phrases` parameter, this parameter controls how they are connected. Choose from OR to require that any one of the phrases must match for the search to succeed, or AND (the default) to require that all of the phrases must match.
mla_term_delimiter	A single character that separates the terms in `mla_terms_phrases`. The default delimiter is a comma (',') since term names can contain spaces.
mla_term_connector	If you enter multiple terms (separated by the `mla_term_delimiter`) in the `mla_terms_phrases` parameter, this parameter controls how they are connected. Choose from OR (the default) to require that any one of the terms must match for the search to succeed, or AND to require that all of the terms must match.
whole_word	Add `whole_word=true` to require that each of the words entered must match a whole word in taxonomy terms. This is equivalent to putting quotes around each of the words in your search.
sentence	Add `sentence=true` to require that all of the words entered must match in sequence. This is equivalent to putting quotes around all of the words in your search.
exact	Add `exact=true` to require that each phrase must match the entire text of a term name.

Post MIME Type

For compatibility with the WordPress

[gallery]
shortcode, this parameter defaults to post_mime_type=image. You can override the default to, for example, display PDF documents (post_mime_type=application/pdf) or all MIME types (post_mime_type=all). You can select several MIME types with a comma-separated list, e.g., post_mime_type='audio,video'. Wildcard specifications are also supported. For example, post_mime_type='*/mpeg' to select audio and video mpeg formats or post_mime_type='application/*ms*' to select all Microsoft application formats (Word, Excel, etc.).

Post Type, Post Status

For compatibility with the WordPress

[gallery]
shortcode, these parameters default to post_type=attachment, post_status=inherit. You can override the defaults to, for example, display items in the trash (post_status=trash). You can specify more than one value in a comma-separated list, e.g., post_type="post,page".

You can change the post_type parameter to compose a "gallery" of WordPress objects such as posts, pages and custom post types. For example, to display a gallery of the published posts in a particular category you can code something like:

[mla_gallery category=some-term post_type=post post_status=publish post_mime_type=all post_parent=all]

Note that you must also change the post_status post_mime_type and post_parent because the default values for those parameters are set for Media Library image items.

For posts, pages and custom post types some of the other data values are used in slightly different ways:

Title	Taken from the Title of the item.
Caption	Taken from the Excerpt of the item.
ALT Text	Not used.
Description	Taken from the Content of the item.
Thumbnail	Taken from the Featured Image of the item, if set. You can use the `size` parameter to display any of the available image sizes. If no Featured Image is set, the Title will be used instead.
Page Link (link=page)	Taken from the "guid", or "short form" of the link to the item.
File Link (link=file)	Taken from the permalink to the item.

You can find all the parameter values and more examples in the WP_Query class reference

Pagination Parameters

Pagination parameters let you divide your [mla_gallery] display into two or more pages when the display includes a large number of items. These parameters work with MLA's to make it easy to construct multi-page galleries without resorting to PHP templates and code in your theme.

nopaging	The `[mla_gallery]` shortcode supplies `nopaging=true` as a default parameter. If you are working with a template that supports pagination you can replace this with specific values for "numberposts", "posts_per_page", "posts_per_archive_page", "paged" and/or "offset" . You can also pass "paged=current" to suppress the "nopaging" default; "current" will be replaced by the appropriate value (`get_query_var('paged')` or `get_query_var('page')`).
numberposts, posts_per_page	the number of items to display on each gallery page.
posts_per_archive_page	number of items to show per page - on archive pages only. Over-rides posts_per_page on posts/pages where `is_archive()` or `is_search()` is true for the post/page in which the shortcode occurs. Note that search results will not display gallery images.
paged	number of page. Show the items that would normally show up just on page X. The "paged=current" parameter is useful for "paginated single posts" (i.e. posts that include the `<!--nextpage-->` Quicktag one or more times). Simply make two or more copies of your `[mla_gallery]` shortcode separated by the Quicktag and include the "paged=current' in each copy. For true pagination it is better to use the "mla_paginate_current" parameter.
offset	the number of terms to skip over before starting the current gallery page. This parameter is usually derived automatically from the more useful "mla_paginate_current" parameter.
mla_paginate_current	the "current" gallery page; defaults to one (1) if not specified. MLA will usually manage this for you, looking for this parameter in the HTML $_REQUEST array if it is not coded in the gallery shortcode.
mla_page_parameter	the name of the parameter containing the current page number; default "mla_paginate_current". You can change the name if you need multiple paginated galleries on one post/page. If you use this parameter, make sure you add it to the gallery shortcode and all pagination shortcodes for that gallery, and use the same unique value in all shortcodes for the specific gallery.
mla_paginate_total	the highest page number you want to display; defaults to (total items / posts_per_page) if not specified, which is usually what you want.

The task of dividing a large [mla_gallery] into two or more pages is supported by MLA's . For more information and examples, go to that section of the Documentation.

Simple Date Parameters

The [mla_gallery] shortcode supports five parameters for filtering the gallery display by year, month, week and day. For more complex date and time filters, see the "date query" feature in the next section below.

year	the 4-digit year by which to filter the gallery, e.g., `year=2021`.
monthnum	the month number (from 1 to 12) by which to filter the gallery.
w	the week of the year (from 0 to 53) by which to filter the gallery. Uses the MySQL WEEK command. The mode is dependent on the “start_of_week” option.
day	the day of the month (from 1 to 31) by which to filter the gallery.
m	the 6-digit year and month by which to filter the gallery, e.g., `m=202101`.

These five parameters always use the "Uploaded on" date, stored in the post_date column of the wp_posts database table. Remember to use post_parent=current if you want to restrict your query to items attached to the current post.

Date and Time Queries, the "date query"

The [mla_gallery] shortcode supports the "date_query" parameter introduced in WordPress Version 3.7. You can use a date_query to filter your gallery based on the 'post_date', 'post_date_gmt', 'post_modified', 'post_modified_gmt', 'comment_date', or 'comment_date_gmt' database columns (although the column names include "post", the same columns are used for attachments).

As the Codex date_query documentation suggests, "before" and "after" values can use any of the PHP strtotime()-compatible string values, which are quite powerful. For example, you can use relative values such as 'after' => 'second tuesday of last month'. Careful study of the PHP documentation can be most rewarding. You can use mla_debug=true to see how PHP and WordPress translate your query to specific date-time values.

When embedding the shortcode in the body of a post, be very careful when coding the date_query; it must be a valid PHP array specification. Read and follow the rules and guidelines in the "Entering Long/Complex Shortcodes" Documentation section to get the results you want.

Remember to use post_parent=current if you want to restrict your query to items attached to the current post.

Simple Custom Field Parameters

The [mla_gallery] shortcode supports the simple custom field parameters:

meta_key (string)	Custom field key.
meta_value (string)	Custom field value; string-based comparison.
meta_value_num (number)	Custom field value; numeric comparison.
meta_compare (string)	Operator to test the 'meta_value'. Possible values are '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'NOT EXISTS', 'REGEXP', 'NOT REGEXP' or 'RLIKE'. Default value is '='.

IMPORTANT: Beginning with version 4.0, WordPress changed the way it handles shortcode parameters. Using angle brackets, e.g., the >= characters in a shortcode will often return "Invalid mla_gallery tax_query" errors. To prevent this: 1) add "<code></code>" tags around your shortcode, 2) use an escape sequence like ">=" in your query or 3) use the enclosing shortcode syntax. You can find more information in the "Entering Long/Complex Shortcodes" Documentation section.

Remember to use post_parent=current if you want to restrict your query to items attached to the current post.

Custom Field Queries, the "meta_query"

The [mla_gallery] shortcode supports the more powerful "WP_Query meta_query" parameters made available as of WordPress 3.1.

When embedding the shortcode in the body of a post, be very careful when coding the meta_query; it must be a valid PHP array specification. Read and follow the rules and guidelines in the "Entering Long/Complex Shortcodes" Documentation section to get the results you want.

Remember to use post_parent=current if you want to restrict your query to items attached to the current post.

Keyword(s) Search

The search parameter ("s=keyword") will perform a keyword search. By default, the search includes the "post_title" and "post_content" (Description) fields but not the "post_excerpt" (Caption) field. All of the words you enter in the parameter must match for the search to succeed. An SQL "LIKE" clause for each word is composed and added to the search criteria.

You can match on multi-word phrases in a variety of ways. These are described in detail, with examples, in the "Entering Words and Phrases" portion of the "Terms Search - filtering on taxonomy term names" Documentation section. You can also use the whole_word=true, sentence=true and exact=true parameters to change the matching logic used in the [mla_gallery] shortcode.

You can search for Media Library items and parent posts/pages by their ID value(s). If all of the values in the search field are numeric (and unquoted) they will be interpreted as ID values. To search for items attached to one or more parent posts/pages, enter the ID of the parent(s). If you want to search for a numeric value in the text fields, surround it with quotes.

You can use the mla_search_connector and mla_search_fields parameters to extend the search to other fields and to relax the requirement that all phrases must match. Here are all of the parameters that control keyword searching:

s	The word(s) or phrase(s) you are searching for. Prepending a word or quoted phrase with a hyphen will exclude items matching that value, e.g., 'pillow -sofa' will return items containing 'pillow' but not 'sofa'.
mla_search_fields	The fields in which to search. Choose from title, name, excerpt, content, alt-text, file, terms.
mla_negative_delimiter	A single character that encloses the negative (excluded) phrases in the search string. The default delimiter is a slash ('/'), e.g., 'pillow /sofa/' will return items containing 'pillow' but not 'sofa'.
mla_terms_taxonomies	If you include 'terms' in `mla_search_fields`, you can add a comma-separated list of the taxonomy or taxonomies in which to search. Enter the slug(s) for one or more of the taxonomies registered for Media Library items, e.g., attachment_category or attachment_tag. If this parameter is omitted or empty, default taxonomies are specified in the Taxonomy Support section of the General tab.
mla_search_connector	Choose from OR to require that any one of the phrases must match for the search to succeed, or AND (the default) to require that all of the phrases must match.
whole_word	Add `whole_word=true` to require that each of the words entered must match a whole word in taxonomy terms. This is equivalent to putting quotes around each of the words in your search. Note that this option only affects the "terms" portion of the search. WordPress does not support a whole word search in any of the other search fields.
sentence	Add `sentence=true` to require that all of the words entered must match in sequence. This is equivalent to putting quotes around all of the words in your search.
exact	Add `exact=true` to require that the entire field content must match the search text.

The mla_search_fields=terms feature is a simple way to extend the search to the terms assigned to Media Library items. If searching on taxonomy terms is your primary goal, consider the more powerful "

Caching Parameters

For applications that have very large numbers of attachments and taxonomy terms, there are three caching parameters that may improve the performance of your [mla_gallery] shortcodes. All of them default to "true", but you can set them to "false" to avoid some database access.

cache_results	Post information cache.
update_post_meta_cache	Post meta information cache.
update_post_term_cache	Post term information cache.

In general you won't need these, since adding to the cache is the right thing to do, but they may be useful in specific circumstances. An example of such circumstances might be when using an [mla_gallery] to retrieve a simple list of thumbnails and links, but in which no other information about the items will be used and the taxonomy and meta data won't be needed. By not loading this information, you can save some time from the extra unnecessary SQL queries.

Debugging Output

The "mla_debug" parameter controls the display of information about the query parameters and SQL statements used to retrieve gallery items. If you code mla_debug=true you will see a lot of information added to the post or page containing the gallery. Of course, this parameter should ONLY be used in a development/debugging environment; it's quite ugly.

If you code mla_debug=log all of the information will be written to the error log. You can use the MLA Debug Tab to view and download the information in the error log.

Look for the "mla_debug attribute_errors" entry in the debug output; it will often list the parts of the shortcode parameters that couldn’t be parsed. If you see "[mla_gallery in this entry you probably used the enclosing shortcode format in that shortcode but did not add the "[/mla_gallery]" delimiter to an earlier shortcode.

MLA Gallery Filters and Actions (Hooks)

The [mla_gallery] shortcode supports a comprehensive set of filters and actions that give you complete control over gallery composition from PHP code in your theme or in another plugin. An example of using the hooks from a simple, stand-alone plugin can be found in the Documentation/Example Plugins submenu. You can find the example plugin here: MLA Gallery Hooks Example. To run the example:

Click on the link above or go to top of the Documentation tab and click on the "Example Plugins" button.
Hover over "MLA Gallery Hooks Example" in the Name column, then click the "Install" rollover action.
Go to the Plugins/Installed Plugins screen and activate the "MLA Gallery Hooks Example" plugin.
Edit the code to, for example, uncomment the error_log() calls so you can see what is passed to the hooks you are interested in.
Create a new [mla_gallery] shortcode or modify an existing shortcode, adding the my_filter="all custom" parameter to activate the example output.
View the post or page on which the modified shortcode appears to see a list of each item's custom fields appended to the gallery captions.

The example code documents each hook with comments in the filter/action function that intercepts each hook. Generally, each part of the gallery supports three hooks: 1) a "values" hook, which lets you record or update the substitution values for that gallery part, 2) a "template" hook, which lets you record/update the template used to generate the HTML markup, and 3) a "parse" hook which lets you modify or replace the markup generated for a gallery part. The current hooks are:

mla_raw_gallery_attributes	called at the beginning of the gallery, before the attributes pass through the logic that handles the 'mla_page_parameter' and "request:" prefix processing.
mla_gallery_attributes, mla_gallery_arguments	called at the beginning of the gallery. You can record/modify shortcode parameter values before (attributes) or after (arguments) they are combined with all the defaults.
mla_gallery_initial_content	called just after the `mla_gallery_attributes` filter, so you can inspect/modify any content enclosed by the `[mla_gallery]content[\mla_gallery]` "enclosing" shortcode format.
mla_gallery_query_attributes, mla_gallery_query_arguments	called just before the `WP_Query->query()` call that selects gallery items, with query parameters before or after they are combined with defaults.
mla_gallery_wp_query_object	called just after the `WP_Query->query()` call, so you can inspect/record the results.
mla_gallery_the_attachments	called after the `WP_Query->query()` is performed, so you can inspect/record the results or return a modified array of items satisfying the query.
mla_gallery_alt_shortcode_blacklist	called after the `mla_gallery_wp_query_object` filter, so you can inspect/modify the list of parameters to be removed from those passed to the alternative gallery shortcode.
mla_gallery_alt_shortcode_attributes	called after the `mla_gallery_wp_query_object` filter, so you can inspect/modify the parameters passed to the alternative gallery shortcode.
mla_gallery_alt_shortcode_ids	called after the `mla_gallery_wp_query_object` filter, so you can inspect/modify the ID values or the entire `mla_alt_shortcode_ids` parameter passed to the alternative gallery shortcode.
mla_gallery_final_content	called after the `mla_gallery_wp_query_object` filter, so you can inspect/modify any content enclosed by the `[mla_gallery]content[\mla_gallery]` "enclosing" shortcode format before it is passed to the alternative gallery shortcode.
mla_gallery_end_alt_shortcode	called after the alternative gallery shortcode has been processed, so you can perform cleanup or other final actions.
use_mla_gallery_style	allow or suppress the inclusion of CSS styles in the gallery output.
mla_gallery_style	an old filter retained for compatibility with earlier MLA versions.
mla_gallery_style_values, mla_gallery_style_template, mla_gallery_style_parse	for manipulating the Style template.
mla_gallery_pagination_values	for manipulating the markup values used in pagination controls.
mla_gallery_open_values, mla_gallery_open_template, mla_gallery_open_parse	for manipulating the "Open" part of the Markup template.
mla_gallery_row_open_values, mla_gallery_row_open_template, mla_gallery_row_open_parse	for manipulating the "Row Open" part of the Markup template.
mla_gallery_initial_item_values, mla_gallery_item_values, mla_gallery_item_template, mla_gallery_item_parse	for manipulating the "Item" part of the Markup template.
mla_gallery_row_close_values, mla_gallery_row_close_template, mla_gallery_row_close_parse	for manipulating the "Row Close" part of the Markup template.
mla_gallery_close_values, mla_gallery_close_template, mla_gallery_close_parse	for manipulating the "Close" part of the Markup template.

MLA Gallery Examples

As you can tell from the number of parameters available, the [mla_gallery] shortcode is powerful, but it can be complex. The examples in this section show several of the more popular applications, taken from topics in the MLA Support Forum.

Simple Examples

[mla_gallery] - will display all the images "attached" to the current post/page.
[mla_gallery ids="1,3,2,4"] - will display specific images on any post/page. The numbers are the ID values of the images. You can use the "Add Media..." popup window and "Create Gallery" to get the list, then change the shortcode name to "mla_gallery" if you want to add other [mla_gallery] specific parameters.
[mla_gallery post_parent=all] - will display all the images in your Media Library.
[mla_gallery post_parent=all post_mime_type=application/pdf] - will display all the PDF documents in your Media Library. Since PDF documents are not images, the title of the document will display in place of the thumbnail image.
[mla_gallery post_parent=all post_mime_type="audio,video"] - will display all the audio and video documents in your Media Library.
[mla_gallery post_parent=all post_mime_type=application/pdf size=icon link=file] - will display all the PDF documents in your Media Library. The "PDF icon" will display in place of the thumbnail. When the icon is clicked, the document itself will be displayed in the browser.

Perhaps the most popular Media Library Assistant feature is the ability to assign category and tag values to Media Library Items and use the values to filter a gallery display. "Categories" and "Tags" are built-in WordPress "taxonomies" and have been used for a long time to organize posts and pages. WordPress does not have built-in support for using them with attachments and that was one of the original motivations for MLA.

With MLA you can extend Categories and Tags support to attachments. MLA also provides two additional taxonomies for your convenience, Att. Categories and Att. Tags. Because of the way WordPress works, using Categories and Tags for attachments as well as posts and pages can be complicated, so many people find that using the separate Att. Categories and Att. Tags is more convenient.

To use a taxonomy you must create one or more "terms" within it. For example, you could create terms in the Category taxonomy like "Big Dog" and "Little Dog". For each term, WordPress automatically creates a "slug", e.g., "big-dog" and "little-dog" for the previous examples. Removing capital letters, spaces and punctuation makes it easier to organize and search the database. It's the slug you can use in [mla_gallery] shortcodes. To "display the attachments that have been assigned to a single category/tag", use the term's slug; for the four taxonomies we've discussed:

Categories: [mla_gallery category_name=big-dog]
Tags: [mla_gallery tag=big-dog]
Att. Categories: [mla_gallery attachment_category=big-dog]
Att. Tags: [mla_gallery attachment_tag=big-dog]

The category_name example does not follow the general rule of "taxonomy-slug = term-slug" because it was created long ago, when Categories and Tags were the only taxonomies allowed. The tag example does not follow the rule, either, since the actual taxonomy-slug is "post_tag", not "tag".

A Paginated Gallery

If your gallery display includes a large number of items it may be useful to divide the display into "pages" with a fixed upper limit of items per page. The section explains several ways to do that; here is one example. Put both of these shortcodes on a post or page to display a paginated gallery:

[mla_gallery attachment_category=big-dog posts_per_page=12]

[mla_gallery attachment_category=big-dog posts_per_page=12 mla_output="paginate_links,prev_next"]

Note that two shortcodes are required; one for the gallery display and a second one for the pagination controls. The first [mla_gallery] displays the images assigned to attachment_category=big-dog and displays a maximum of 12 images at once. The second [mla_gallery] has exactly the same data selection parameter and posts per page parameter; that's essential to match up with the first shortcode. It adds one more parameter, mla_output. This parameter changes the display from a set of images to a set of pagination controls.

MLA will add and manage a "current page" parameter of its own so the two shortcodes stay in synch as you navigate from page to page. That's all there is to it.

Search Form and Gallery

A common alternative to the taxonomy filtering in the previous examples is a keyword-based search. This example shows a simple HTML form with a text box and a button to run the search. The user can enter one or more words to search for in the Title or Description of Media Library items, then click "Search" to display a gallery of matching images:

<form id="mla-search-form" action="." method="post"> <input id="mla-search-box" name="search-string" type="text" value="" /> <input id="submit" name="submit" type="submit" value="Search" /> </form>

[mla_gallery s="{+template:({+request:search-string+}|a-bad-term)+}" mla_nolink_text="Enter a search value above to display gallery."]

In this example the name="search-string" parameter is passed from the form to the s="{+request:search-string+}... parameter in the shortcode. As in the Cloud and Gallery example a Content Template is used to supply a-bad-term before the form is completed, which displays an empty gallery because it doesn't match anything. You can find more information on the s= parameter and other search parameters in the Keyword(s) Search section.

As in the Cloud and Gallery example, paginating your gallery display requires a slight modification of the [mla_gallery] shortcode (at the bottom of the next example) and adding a second [mla_gallery] shortcode (in the middle of the next example) to display the pagination controls:

<form id="mla-search-form" action="." method="post"> <input id="mla-search-box" name="search-string" type="text" value="" /> <input id="submit" name="submit" type="submit" value="Search" /> </form>

[mla_gallery s="{+template:({+request:search-string+}|a-bad-term)+}" posts_per_page=12 mla_output="paginate_links,prev_next" mla_link_href="{+page_url+}?search-string={+request:search-string+}"]

[mla_gallery s="{+template:({+request:search-string+}|a-bad-term)+}" mla_nolink_text="Enter a search value above to display gallery." posts_per_page=12]

The posts_per_page=12 parameter has been added to the gallery display shortcode (the third shortcode). A new [mla_gallery] is added to display the pagination controls. The data selection parameter (s="{+request:search-string+}...) and posts_per_page=12 parameter match the gallery display shortcode below it. The mla_output parameter displays the pagination controls. Finally, the mla_link_href="{+page_url+}?search-string={+request:search-string+}" parameter is added so the pagination controls pass the search-string from page to page.

Go to Top

Support for Alternative Gallery Output, e.g., Pagination

The [mla_gallery] shortcode can be used to provide "Previous" and "Next" links that support moving among the individual items in a gallery or among gallery "pages". For example, if you have many items with a specific Att. Category or Att. Tag value you can build a single-image page with links to the previous/next item having that value. You can also build a page that shows a large gallery in groups, or "gallery pages", of ten items with links to the previous/next ten items or links to all of the gallery pages of items having that value. Finally, you can get a set of links to all pages in the gallery or links around the current page ( e.g.: « Previous 1 ... 3 4 5 6 7 ... 9 Next » ).

IMPORTANT: Pagination controls are an alternative output, not an additional output. One shortcode can generate either a gallery display or pagination controls. You will need two or more shortcodes to get both the gallery and the controls.

The `mla_output` parameter

The "mla_output" parameter determines the type of output the shortcode will return. Explanation and examples of each output type are given later in this section. You can choose from seven values:

gallery	The default value; returns the traditional gallery of image thumbnails, captions, etc.
next_link	returns a link to the next gallery item. The optional ",wrap" qualifier determines what happens at the end of the gallery. If you omit the qualifier, an empty string is returned for the "next_link" from the last item in the gallery. If you code the ",wrap" qualifier, the "next_link" from the last item will be to the first gallery item.
current_link	returns a link to the current gallery item. This gives you an easy way to provide a visual indication of where you are within the overall gallery. The "span" and "none" link formats are often used with this mla_output type.
previous_link	returns a link to the previous gallery item. The optional ",wrap" qualifier determines what happens at the beginning of the gallery. If you omit the qualifier, an empty string is returned for the "previous_link" from the first gallery item. If you code the ",wrap" qualifier, "previous_link" from the first gallery item will be to the last gallery item.
next_page	returns a link to the next "page" of gallery items. The optional ",wrap" or ",last" qualifiers determine what happens at the end of the gallery. If you omit the qualifier, an empty string is returned for the "next_page" if there are no more items in the gallery. If you code the ",wrap" qualifier, the "next_page" from the last page of items will be to the first page of gallery items. If you code the ",last" qualifier, the "next_page" link will return to/remain on the last page of gallery items.
previous_page	returns a link to the previous "page" of gallery items. The optional ",wrap" or ",first" qualifiers determine what happens at the beginning of the gallery. If you omit the qualifier, an empty string is returned for the "previous_link" from the first page of gallery items. If you code the ",wrap" qualifier, "previous_page" from the first page of gallery items will be to the last page of gallery items. If you code the ",first" qualifier, the "previous_link" link will return to/remain on the first page of gallery items.
paginate_links	returns a link to gallery items at the start and end of the list and to pages around the current "gallery page" ( e.g.: « Previous 1 ... 3 4 5 6 7 ... 9 Next » ). The optional ",show_all" qualifier will show all of the gallery pages instead of a short list around the current page. The optional ",prev_next" qualifier will include the "« Previous" and "Next »" portions of the link list.

Next and previous gallery items; the `next_link` and `previous_link` output types

WordPress provides functions that generate links to the "next/previous image attached to the current post." These are not useful when your Media Library items are not images or are not attached to a specific post or page. If, for example, you use an [mla_gallery] shortcode to build a gallery of items with a specific Att. Tag value you can use the next_link and previous_link output types to move through single-item pages for the gallery. You will need one more parameter to specify the "current item" in the gallery:

id	(optional) the ID of the "current" gallery item. If you omit this parameter, the default value is the ID of the current "post". The default value is only useful if you are enhancing the PHP code of the "image.php" template for the "Attachment Page" associated with a Media Library item.

The next or previous link returned is drawn from the attachment-specific "link" substitution parameter for the next or previous gallery item. This means you can use all of the Gallery Display Content parameters to control each element of the link. For example, you can code mla_rollover_text='← Previous' to replace the thumbnail image with a generic text link to the "previous_link" item. You can also add HTML arguments to the link to pass values along from one page to the next.

Here is a more complete example of two standard WordPress pages, "Sample Gallery" and "Single Sample", that work together. The "Sample Gallery" page displays a gallery of all items assigned to the Att.Tags "sample" term. The "Single Sample" page displays the full-size image for a "sample" item and has links to move back and forth through all the items assigned to the term. The Sample Gallery page contains:

[mla_gallery attachment_tag="sample" mla_caption="{+title+}" mla_link_href="/single-sample/?current_id={+attachment_ID+}&attachment_tag={+query:attachment_tag+}"]

In this example /single-sample/, the URL portion of the link, is the "Permalink" WordPress generates from the page title. If your Permalink structure is different you will have to adjust this element. Note the use of attachment_tag={+query:attachment_tag+} in the href to pass the tag value from the gallery page to the Single Sample page. The Single Sample page has three [mla_gallery] shortcodes; one to display the image and two for the "Previous Sample" and "Next Sample" links:

[mla_gallery columns=1 ids="{+request:current_id+}" size=medium]

<div style="clear: both; float: left"> [mla_gallery mla_output="previous_link,wrap" mla_link_text='← Previous Sample' attachment_tag="{+request:attachment_tag+}" id="{+request:current_id+}" mla_rollover_text="{+title+}" mla_link_href="{+page_url+}?current_id={+attachment_ID+}&attachment_tag={+query:attachment_tag+}"] </div> <div style="float: right"> [mla_gallery mla_output="next_link,wrap" mla_link_text='Next Sample →' attachment_tag="{+request:attachment_tag+}" id="{+request:current_id+}" mla_rollover_text="{+title+}" mla_link_href="{+page_url+}?current_id={+attachment_ID+}&attachment_tag={+query:attachment_tag+}"] </div>

Consider the following points:

The "ids" parameter in the first [mla_gallery] takes the "current_id" value (for the single image to be displayed) from the link's query arguments (in the PHP $_REQUEST array). This is passed from the Sample Gallery page and updated in the previous/next link.
The "id" parameters in the second and third [mla_gallery] take the "current_id" value from the $_REQUEST array. In these "galleries" the "current_id" is the item from which "previous" and "next" are calculated.
The "attachment_tag" parameters in the second and third [mla_gallery] take the their value from the $_REQUEST array as well. The Att. Tag value is used to reconstruct the original gallery for the previous/next calculation, keeping the navigation within the bounds of the selected term.

This example shows the power of the substitution parameters and in particular the "query" and "request" prefixes that can be used to pass information into an [mla_gallery] and from one page to the next. All of this without modifying PHP templates or requiring other code modifications!

Next and previous gallery pages; the `next_page` and `previous_page` output types

WordPress provides functions that generate links to the "next/previous set of posts within the current query." These are not useful because the "current query" is for posts/pages, not Media Library items. What's needed is a way to paginate an [mla_gallery] shortcode on a single post or page. If, for example, you use an [mla_gallery] shortcode to build a gallery of items with a specific Att. Tag value you can use the next_page and previous_page output types to move through the gallery in groups of, say, ten items per "gallery page".

WordPress uses the "paged" parameter to indicate the current "set of posts within the current query." To avoid built-in WordPress logic that uses this parameter, MLA has its own "mla_paginate_current" parameter to indicate the current set of items within the gallery (the current gallery page). MLA will automatically manage this parameter for you, but you can also use it explicitly to handle special cases.

An example of the `next_page` and `previous_page` output types

Expanding the "attachment tag gallery" example, you can select images using the MLA Att. Tag taxonomy and divide the gallery into fixed-size pages. Following the main gallery shortcode are two additional shortcodes for the previous/next page links:

[mla_gallery attachment_tag="sample" posts_per_page=10 mla_caption="{+title+}"]

<div style="clear: both; float: left"> [mla_gallery attachment_tag="sample" posts_per_page=10 mla_output="previous_page,first" mla_link_text='← Previous Gallery Page' mla_rollover_text="Previous or first page for this tag"] </div> <div style="float: right"> [mla_gallery attachment_tag="sample" posts_per_page=10 mla_output="next_page,last" mla_link_text='← Next Gallery Page' mla_rollover_text="Next or last page for this tag"] </div>

This example is simpler that the earlier single-item paging example because the "current page" handling is done by MLA, and the "sample" tag value is hard-coded. You could also develop a generic "Att. Tag" gallery page and pass the tag value in the URI for that page (as in the single-item pagination example earlier in this section).

Page selection parameters for `next_page` and `previous_page` output types

Use the following parameters to specify the size of each gallery page and the current gallery page:

posts_per_page	sets the number of gallery items on each gallery "page"
numberposts	synonym for "posts_per_page"
mla_paginate_current	the "current" gallery page; defaults to one (1) if not specified. MLA will usually manage this for you, adding it to the hyperlinks for the previous and next gallery pages. MLA will look for this parameter in the HTML $_REQUEST array if it is not coded in the gallery shortcode.
mla_page_parameter	the name of the parameter containing the current page number; default "mla_paginate_current". You can change the name if you need multiple paginated galleries on one post/page. If you use this parameter, make sure you add it to the gallery shortcode and all pagination shortcodes for that gallery, and use the same unique value in all shortcodes for the specific gallery.
mla_paginate_total	the highest page number you want to display; defaults to (total items / posts_per_page) if not specified, which is usually what you want.
mla_paginate_rows	If you have some other way of computing the total number of items you want to paginate you can use `mla_paginate_rows` to simplify your shortcode parameters and avoid redundant database access. If, for example, you want pagination controls for a gallery that you know has fifty items you can code `[mla_gallery mla_output=paginate_links mla_paginate_rows=50]` and then add any other page selection or gallery display content parameters you need.
offset, paged	DO NOT USE THESE PARAMETERS; THEY WILL BREAK MLA PAGINATION

For most applications, "posts_per_page" is the only pagination parameter you need to specify. Make sure this parameter is the same for your main gallery shortcode and for the pagination shortcodes that go with it. Also, make sure you use exactly the same item selection and sorting parameters in both shortcodes.

Gallery Display Content parameters for `next_page` and `previous_page` output types

The next or previous link returned can use the following Gallery Display Content parameters to control each element of the link:

mla_link_attributes	adds one or more HTML attributes to the hyperlink
mla_link_class	adds one or more classes to those already defined for the hyperlink
mla_link_href	replaces the HTML "href" attribute in the hyperlink
mla_link_text	replaces the link text
mla_prev_text	the "previous page" text (default "« Previous"); an alternative to "mla_link_text" for `mla_output=previous_page`
mla_next_text	the "next page" text (default "Next »") an alternative to "mla_link_text" for `mla_output=next_page`
mla_nolink_text	replaces the empty string displayed when there is no link and link text, e.g., no previous or next page link
mla_rollover_text	replaces the HTML "title" attribute in the hyperlink. This is the text displayed when the mouse rolls or hovers over the link text
mla_target	adds an HTML "target" attribute to the hyperlink

Markup Substitution Parameters for `next_page` and `previous_page` output types

You can use any of the in your next/previous page links (since the links are at the "gallery page" level, the attachment-specific substitution parameters are not available). The following additional substitution parameters are available for the next_page and previous_page output types:

current_page	the number of the current page
new_page	the number of the new (previous or next) page; zero for paginate_links
last_page	the number of the last/highest/maximum page
posts_per_page	the number of items on each gallery page
found_rows	the number of items in the gallery
current_offset	the number of items skipped before the current page
new_offset	the number of items skipped before the new page
current_page_text	'mla_paginate_current="[+current_page+]"'
new_page_text	'mla_paginate_current="[+new_page+]"'
last_page_text	'mla_paginate_total="[+last_page+]"'
posts_per_page_text	'posts_per_page="[+posts_per_page+]"'
scheme	the HTTP protocol used to access the page; usually "http://" but might be "https://"
http_host	contents of the Host: header of the current request; usually a domain name such as "mysite.com" or an IP address
request_uri	the URI given to access the page, e.g., "wordpress/2013/06/sample-post" or "wordpress/tag-gallery-page?attachment_tag=sample". MLA manages pagination by adding the "mla_paginate_current" query parameter to the URI value
new_url	concatenation of scheme + http_host + request_uri

Generalized paginated link list; the `paginate_links` output type

WordPress provides a function that "can be used to create paginated link list for any area." The "paginate_links" output type is modeled on this function and lets you generate a list of links for moving among "gallery pages".

The Page Selection Parameters, Gallery Display Content Parameters and Markup Substitution Parameters defined above also apply to the "paginate_links" output type. There are five additional parameters unique to this output type.

Specific parameters for the `paginate_links` output type

mla_end_size	How many numbers (default 1) appear on either the start and the end list edges
mla_mid_size	How many numbers (default 2) appear to either side of current page, but not including current page
mla_prev_text	the "previous page" text (default "« Previous") , which appears when the ",prev_next" qualifier is added to the output_type
mla_next_text	the "next page" text (default "Next »") , which appears when the ",prev_next" qualifier is added to the output_type
mla_paginate_type	the format of the return value. "plain" (the default) returns a string with links separated by the newline character. "list" returns an unordered (ul) HTML list.

If you code the ",show_all" qualifier, most of the above parameters have no effect; the "mla_paginate_type" parameter is the exception.

An example of the `paginate_links` output type

Expanding the "attachment tag gallery" example, you can select images using the MLA Att. Tag taxonomy and divide the gallery into fixed-size pages. Following the main gallery shortcode is the second shortcode for the list of page links:

[mla_gallery attachment_tag="sample" posts_per_page=10 mla_caption="{+title+}"]

[mla_gallery attachment_tag="sample" posts_per_page=10 mla_output="paginate_links,prev_next" mla_nolink_text='No Gallery Pages']

This example is even simpler that the two earlier examples because there's just one additional [mla_gallery] shortcode for pagination links.

Go to Top

Support for Other Gallery-generating Shortcodes

The [mla_gallery] shortcode can be used in combination with other gallery-generating shortcodes to give you the data selection power of [mla_gallery] and the formatting/display power of popular alternatives such as the WordPress.com Jetpack Carousel and Tiled Galleries modules. Any shortcode that accepts "ids=" or a similar parameter listing the attachment ID values for the gallery can be used. Two parameters implement this feature:

mla_alt_shortcode	the name of the shortcode to be called for gallery format and display. You can code "mla_gallery" (recommended) or "no" to disable the alternate shortcode processing.
mla_alt_ids_name	(optional, default "ids") the name of the parameter used to pass a list of attachment ID values to the alternate shortcode
mla_alt_ids_template	(optional) a Content Template for the entire parameter value passed to the alternate shortcode. When processing the template, the list of ID values is available as the `{+alt_ids+}` substitution parameter. See the example below.
mla_alt_ids_value	(optional) an item-specific substitution parameter, Content Template or other alternative for the attachment ID value(s) passed to the alternate shortcode. It is applied once for each item selected for the gallery, and all the item-specific substitution parameters are available to be used.

For example, if you want to select images using the MLA Att. Category taxonomy but want to display a "Tiled Mosaic" gallery, you can code:

[mla_gallery attachment_category=vegetable tax_operator="NOT IN" mla_alt_shortcode=gallery type="rectangular" mla_alt_ids_name=include]

This example selects all the images that are "NOT IN" the Att. Category "vegetable". The selected images are passed to the

[gallery]

shortcode in an "include" parameter, along with the "type=rectangular" parameter. The result is as if you had coded:

[gallery include="1,2,3" type="rectangular"]

In the above example, the mla_alt_ids_name=include parameter isn't really necessary, since the

[gallery]

shortcode accepts the "ids" parameter. It was included in the example just to show how the "mla_alt_ids_name" might be used for some other shortcode that requires a different name for the parameter.

You can pass any parameters you need through the [mla_gallery] shortcode and on to the alternate shortcode you're using. Here's another example, using the Photonic Gallery plugin:

[mla_gallery attachment_tag=fauna orderby=rand mla_alt_shortcode=gallery type=default style=strip-below slideshow_height=320 slide_size=medium]

Here, [mla_gallery] selects the images with an Att. Tag of "fauna" and sorts them in a random order. It then calls on the

[gallery]

shortcode (which Photonic also uses), as if you had coded:

[gallery ids="3,1,4,2,7" type=default style=strip-below slideshow_height=320 slide_size=medium]

Photonic recognizes the type=default parameter and takes over, using the other three parameters to format its results. This example is a less convenient but more flexible alternative to the native Photonic support built-in to [mla_gallery] (see next section).

The next example selects one PDF document at random and uses the PDF Embedder plugin to display the document content. The mla_alt_ids_name and mla_alt_ids_value parameters change the "ids" and attachment ID defaults to the "url" and file URL values expected by the [pdf-embedder] shortcode.

[mla_gallery post_mime_type="application/pdf" orderby=rand numberposts=1 mla_alt_shortcode=pdf-embedder mla_alt_ids_name=url mla_alt_ids_value="{+filelink_url+}"]

The next example selects items assigned to a taxonomy term and uses the Shortcodes Ultimate plugin's Custom gallery shortcode to display the gallery with a lightbox enhancement. The mla_alt_ids_name and mla_alt_ids_template parameters change the "ids" and attachment ID defaults to the "source" and "media:" values expected by the [su_custom_gallery] shortcode.

[mla_gallery attachment_category=accipitridae link="lightbox" mla_alt_shortcode="su_custom_gallery" mla_alt_ids_name="source" mla_alt_ids_template="media: {+alt_ids+}"]

You can also use the "enclosing shortcode" form if the alternate shortcode, such as Fullscreen Galleria's "fsg_link", requires it. You would code this form as:

[mla_gallery ids="1,2,3" mla_alt_shortcode=fsg_link mla_alt_ids_name=include class=button]View the gallery[/mla_gallery]

If you mix the self-closing and enclosing versions of [mla_gallery] on one post/page you must use the "xhtml-style closing shortcodes like [mla_gallery /]" for the self-closing shortcodes.

NOTE: When you use "mla_alt_shortcode" to pass format/display responsibility off to another shortcode you will lose the [mla_gallery] Gallery Display Style (e.g. "mla_float") and Gallery Display Content (e.g. "mla_caption") parameters. There is no reliable way for [mla_gallery] to pass this information on to the other shortcode you've specified.

Go to Top

Support for the “Photonic Gallery for Flickr, Picasa, SmugMug, 500px and Instagram” Plugin

The Photonic Gallery for Flickr, Picasa, SmugMug, 500px and Instagram plugin adds several new parameters to the [mla_gallery] shortcode to enhance your galleries. All you have to do is install the plugin, then add a "style=" parameter to your [mla_gallery] shortcode to use the Photonic styling and markup in place of the native [mla_gallery] style and markup templates.

You can use the "Photonic" screen of the Insert Media dialog to build the display portion of your shortcode parameters. After you click "Insert into post", change the shortcode name from "gallery" to "mla_gallery" and add the query parameters you need to select the attachments for the gallery. The [mla_gallery] code will compile the list of attachments for your gallery, then hand control over to Photonic to format the results.

Go to Top

Support for the “Real Media Library” Plugin

The WordPress Real Media Library: Media Library Folder & File Manager plugin helps you with media management. Organize thousands of uploaded files into folders, collections and galleries. You can add parameters to the [mla_gallery] shortcode to filter the gallery display by RML folder, collection or gallery ID. There are three [mla_gallery] shortcode parameters for this purpose:

mla_rml_folder	the name of the RML folder, collection or gallery from which to source items gor the gallery display. You can find the ID of a folder easily in your media library. Simply select a folder, afterwards click the three-dots icon in the folder toolbar. A dialog opens and in the bottom right corner you can find a number which represents the folder ID.
mla_rml_include_children	"false" (the default) to restrict the potential items to the specific folder or gallery named in the `mla_rml_folder` parameter. Set it to "true" to include items in folders contained in the specific folder or collection named in the shortcode.
mla_allow_rml	(optional) "false" (the default) to remove the RML parameters from `[mla_gallery]` database queries. "true" to preserve the parameters. This parameter is only useful for performance testing purposes. It is automatically set to "true" if the `mla_rml_folder` parameter is present. You can safely ignore it.

You can use the other [mla_gallery] data selection parameters to further refine your query. For example, you can use post_mime_type=application/pdf to display only the PDF documents in a folder, or use application_category=abc to display only the images assigned to Att. Category "abc" in an RML gallery.

Go to Top

Style and Markup Templates

The Style and Markup templates give you great flexibility for the content and format of each [mla_gallery] or [mla_tag_cloud] (list and grid formats). You can define as many templates as you need.

Style templates provide gallery-specific (or cloud-specific) CSS inline styles (you can code mla_style=none to suppress the addition of CSS inline styles entirely). Markup templates provide the HTML markup for 1) the beginning of the gallery, 2) the beginning of each row, 3) each gallery item, 4) the end of each row and 5) the end of the gallery. The attachment-specific markup parameters let you choose among most of the attachment fields, not just the caption.

The MLA Gallery tab on the Settings page lets you add, change and delete custom templates. The default templates are also displayed on this tab for easy reference. You can find a custom template example with step-by-step instructions in below.

In a template, substitution parameters are surrounded by opening ('[+') and closing ('+]') delimiters to separate them from the template text; see the default templates for many examples.

Argument Substitution Parameters

A markup template can include default values for any of the shortcode parameters and values you define for your own use, e.g., you can add columns=1 to the arguments section to change the MLA default value whenever the template is used. The argument substitution parameter(s) you define in the markup template are treated as if you had added them to the shortcode that uses the template, but parameters you actually use in the shortcode will overide the default values you code in the arguments section. For example, if the arguments section of your "blue-table" markup template looks like:

columns=1 div-class=blue div-id=id3

and your shortcode is

[mla_gallery mla_markup=blue-table div-id=ID5]

the end result will be as if you had coded

[mla_gallery mla_markup=blue-table div-id=ID5 columns=1 div-class=blue]

The custom parameters you code in the arguments section become part of the shortcode parameters. To access them in your template or in other shortcode parameters you must use the 'query:' prefix, e.g., [+query:div-class+] in the template or {+query:div-id+} in another shortcode parameter.

In the arguments section you can separate the parameters with one or more spaces or you can code them on separate lines. If your parameter value includes spaces you must enclose it in single or double quotes.

Gallery-specific Substitution Parameters

Gallery-specific substitution parameters are known at the beginning of shortcode processing and they do not change during processing. They can be used, for example, in any of the data selection parameters to change the items selected for the gallery based on information about the post/page on which the gallery appears. The gallery-specific substitution parameters are:

site_url	absolute URL to the site directory, without trailing slash
base_url	absolute URL to the upload directory, without trailing slash
base_dir	absolute (full) path to the upload directory, without trailing slash
instance	starts at '1', incremented for each additional shortcode in the post/page
selector	"mla_gallery-{$instance}", e.g., mla_gallery-1
page_ID, id	the `ID` value of the post/page in which the gallery appears
page_author	the `post_author` value of the post/page in which the gallery appears
page_date	the `post_date` value of the post/page in which the gallery appears
page_content	the `post_content` value of the post/page in which the gallery appears
page_title	the `post_title` value of the post/page in which the gallery appears
page_excerpt	the `post_excerpt` value of the post/page in which the gallery appears
page_status	the `post_status` value of the post/page in which the gallery appears
page_name	the `post_name` value of the post/page in which the gallery appears
page_modified	the `post_modified` value of the post/page in which the gallery appears
page_parent	the `post_parent` value of the post/page in which the gallery appears
page_guid	the `post_guid` value of the post/page in which the gallery appears
page_type	the `post_type` value of the post/page in which the gallery appears
page_mime_type	the `post_mime_type` value of the post/page in which the gallery appears
page_url	absolute URL to the page or post on which the gallery appears, if any, with trailing slash

Go to Top

Substitution parameters for style templates

All of the gallery-specific substitution parameters are available for use in style templates. These additional substitution parameters are also available:

mla_style	shortcode parameter, default = 'default'
mla_markup	shortcode parameter, default = 'default'
itemtag	shortcode parameter, default = 'dl', or 'figure' for HTML5 themes
icontag	shortcode parameter, default = 'dt', or 'div' for HTML5 themes
captiontag	shortcode parameter, default = 'dd', or 'figcaption' for HTML5 themes
columns	shortcode parameter, default = '3'
itemwidth	shortcode parameter, default is calculated by dividing 100% by the number of columns and subtracting twice the margin value, e.g., 30.3% for three columns and a margin value of 1.5%. Can also contain other dimensional values such as '10px' or CSS-specific values like 'auto' or 'inherit'.
margin	shortcode parameter, default = '1.5%'. Can also contain other dimensional values such as '10px' or CSS-specific values like 'auto' or 'inherit'.
float	'right' if current locale is RTL, 'left' if not
size_class	shortcode 'size' parameter, default = 'thumbnail'
found_rows	the total number of items in the gallery before considering pagination parameters
current_rows	the number of items in the current page of the gallery, considering any pagination parameters
max_num_pages	the number of pages in the gallery

Go to Top

Substitution parameters for markup templates

All of the

Go to Top

Attachment-specific substitution parameters for the markup template Item part

These substitution parameters are only available in the "Item" part of the markup template, since they require an attachment for their data source. In addition to the parameters in the list below, you can use any of the Data sources for custom field mapping (except "None", "Metadata" and "Template").

You may need to append one of the format options to the name depending on the context in which the substitution parameter is used. If you need both the native format and the altered format, simply wrap the altered format in a content template, e.g., [+template:([+width,commas+])+]. The template will prevent the native value from being over-written with the formatted value.

The item-level substitution parameter names are:

index	starts at '1', incremented for each attachment in the gallery
last_in_row	set to "last_in_row" for the last item in each full gallery row, and to an empty string for all other items in the row. If the gallery ends with a partial row, the last_in_row parameter is not set.
caption	if captiontag is not empty, contains caption/post_excerpt
captiontag_content	if both captiontag and caption are not empty, contains the complete HTML markup for the caption. This can be used to omit empty tags (as it is in the default template).
excerpt	always contains post_excerpt
attachment_ID	attachment post ID
mime_type	attachment post_mime_type
menu_order	attachment menu_order
date	attachment post_date
modified	attachment post_modified
parent	attachment post_parent (ID)
parent_name	post_name of the parent, or an empty string
parent_title	post_title of the parent, or '(unattached)'
parent_type	'post', 'page' or custom post type of the parent
parent_date	upload date of the parent
parent_permalink	permalink to the parent
title	attachment post_title
slug	attachment post_name
width	width in pixels, for image types
height	height in pixels, for image types
orientation	"portrait" (height > width) or "landscape", for image types; empty for non-image types
image_meta	image metadata, for image types
image_alt	ALT text, for image types. If there are multiple values (unlikely) only the first value is available. If you need to process multiple values, use the field-level data source "alt_text".
base_file	path and file name relative to uploads directory
path	path portion of base_file
file	file name portion of base_file
description	attachment post_content
file_url	attachment guid; full path and file name in URL format
author_id	attachment post_author
author	author display_name, or 'unknown'
link	hyperlink to the attachment page (default) or file (shortcode 'link' parameter = "file")
pagelink	always contains a hyperlink to the attachment page
filelink	always contains a hyperlink to the attachment file
downloadlink	always contains a hyperlink to the MLA file downloader for this attachment
transferlink	always contains a hyperlink to the Transfer by Item Name handler for this attachment
link_url	the URL portion of link
pagelink_url	the URL portion of pagelink
filelink_url	the URL portion of filelink
downloadlink_url	the URL portion of downloadlink
transferlink_url	the URL portion of transferlink
thumbnail_content	complete content of the gallery item link. This will either be an "<img ... >" tag or a text string for non-image items
thumbnail_width	for image/icon items, width of the gallery image/icon
thumbnail_height	for image/icon items, height of the gallery image/icon
thumbnail_url	for image/icon items, URL of the gallery image/icon

Field-level substitution parameters for the markup template Item part

You can use the in the item part to draw data from a wide variety of sources and format it as required. See that section of the Documentation for more information.

Go to Top

A Table-based Style and Markup Template Example

Here's a small example that shows a gallery using <table> markup. The Item markup section shows how to use the "terms", "custom", "iptc" and "exif" substitution parameters.

Style Template

<style type='text/css'> #[+selector+] { margin: auto; } #[+selector+] .gallery-row { float: [+float+]; margin-top: 10px; border-top: 1px solid #ddd; text-align: center; width: [+itemwidth+]%; } #[+selector+] .gallery-row td.gallery-icon { width: 60; height: 60; vertical-align: top; } #[+selector+] .gallery-row .gallery-icon img { border: 2px solid #cfcfcf; } #[+selector+] .gallery-caption { margin-left: 0; vertical-align: top; } </style>

Markup Template

Open	`<table id='[+selector+]' class='gallery galleryid-[+id+] gallery-columns-[+columns+] gallery-size-[+size_class+]'>`
Row Open	`<tr class='gallery-row'>`
Item	`<td class='gallery-icon'> [+link+] </td> <td class='wp-caption-text gallery-caption'> <strong>[+title+]</strong><br /> [+description+]<br /> [+date+] [+custom:client,single+] [+terms:category+] [+iptc:caption-or-abstract+] [+iptc:2#025,single+] [+exif:Artist+] </td>`
Row Close	`</tr>`
Close	`</table>`

To create the custom templates, follow the steps below. To define the custom style template:

Navigate to the Settings/Media Library Assistant MLA Gallery tab.
Scroll down to the bottom of the "Style Templates" section where you can see a blank "Name:" text box. Give your template a name, such as "table-style".
Copy the template above and paste it into the "Styles:" text box.
Review the content to make sure all the HTML and CSS markup is valid and not corrupted by the copy process.
Scroll to the bottom of the page and click "Save Changes" to save your new style template.

Markup templates are a bit more complicated because they have five parts, but the process is similar. To define the custom markup template:

Navigate to the Settings/Media Library Assistant MLA Gallery tab.
Scroll down to the bottom of the "Markup Templates" section where you can see a blank "Name:" text box. Give your template a name, such as "table-markup".
Copy the template parts from the above example and paste them into the corresponding part text boxes.
Review the content to make sure all the HTML and CSS markup is valid and not corrupted by the copy process.
Scroll to the bottom of the page and click "Save Changes" to save your new markup template.

Once you have defined and saved your custom templates you can change your shortcode to use the templates:

[mla_gallery ... mla_style=table-style mla_markup=table-markup]

It's a bit of work, but you only have to do it once.

[mla_tag_cloud]

Enhanced version of the WordPress Tag Cloud.

aileron brill browsers-tag CDN-tag cheat-sheets-tag cineware CODING-tag command-line copy-sites-tag cross domain css-grid css-tag custom editor style-tag ddns-tag debug-tag Design-tag do-it-yourself-tag essential-grid-ptag file-permissions flexbox font-types-web-tag fontawesome-tag FONTS-tag gallerypage-tag google analytics 4 google tag manager htaccess IDE javascript-tag keyboard-shortcuts-tag lightbox-tag line-numbers MAC main-spiffy-category-tag match-braces multisite-tag neumorphism-tag no-brace-hover npm-tag nsp-code-tag OnPageInsertedWPDiscuz optimizations Overviews-tag permalinks-tag postie pre-loaders rainbow-braces rest-api-tag screenshot segoe ui sencha-tag SEO-tag site-controls suhosin-tag svg-tag sw3-tag syntax-highlight-tag theme development-tag Tools-tag unifont Virtualbox VSCODE-tag WEBSITES-tag Wordpress User Profiles-tag WORDPRESS-tag wp-plugins-tag wp-video-tag wpcli-tag ZSH-tag

Complete documentation

MLA Tag Cloud Shortcode

The [mla_tag_cloud] shortcode function displays a list of taxonomy terms in what is called a 'tag cloud', where the size of each term is determined by how many times that particular term has been assigned to Media Library items (attachments). The cloud works with both flat (e.g., Att. Tags) and hierarchical taxonomies (e.g., Att. Categories) MLA Tag Cloud provides many enhancements to the basic "cloud" display. These include:

Full support for WordPress categories, tags and custom taxonomies. You can select from any taxonomy or list of taxonomies defined in your site.
Several display formats, including "flat", "list" and "grid" (modeled after the [mla_gallery] display).
Complete support for paginated clouds; display hundreds or thousands of terms in manageable groups.
Control over the styles, markup and content of each cloud using Style and Markup Templates. You can customize the "list" and "grid" formats to suit any need.
Access to a wide range of content using the term-specific and Field-level Substitution parameters. A powerful Content Template facility lets you assemble content from multiple sources and vary the results depending on which data elements contain non-empty values for a given term.
Display Style and Display Content parameters for easy customization of the cloud display and the destination of the links behind each term.
A comprehensive set of filters gives you access to each step of the cloud generation process from PHP code in your theme or other plugins.

The [mla_tag_cloud] shortcode has many parameters and some of them have a complex syntax; it can be a challenge to build a correct shortcode. The WordPress Shortcode API has a number of limitations that make techniques such as entering HTML or splitting shortcode parameters across multiple lines difficult. Read and follow the rules and guidelines in the "Entering Long/Complex Shortcodes" Documentation section to get the results you want.

Many of the [mla_tag_cloud] concepts and shortcode parameters are modeled after the [mla_gallery] shortcode, so the learning curve is short. Differences and parameters unique to the cloud are given in the sections below.

Debugging Output

The "mla_debug" parameter controls the display of information about the query parameters and SQL statements used to retrieve tag cloud items. If you code mla_debug=true you will see a lot of information added to the post or page containing the cloud. Of course, this parameter should ONLY be used in a development/debugging environment; it's quite ugly.

If you code mla_debug=log all of the information will be written to the error log. You can use the MLA Debug Tab to view and download the information in the error log.

Look for the "mla_debug attribute_errors" entry in the debug output; it will often list the parts of the shortcode parameters that couldn’t be parsed. If you see "[mla_gallery" in this entry you probably used the enclosing shortcode format in that shortcode but did not add the "[/mla_gallery]" delimiter to an earlier shortcode.

MLA Tag Cloud Filters (Hooks)

The [mla_tag_cloud] shortcode supports a comprehensive set of filters that give you complete control over cloud composition from PHP code in your theme or in another plugin. An example of using the hooks from a simple, stand-alone plugin can be found in the Documentation/Example Plugins submenu. You can find the example plugin here: MLA Tag Cloud Hooks Example. To run the example:

Click on the link above or go to top of the Documentation tab and click on the "Example Plugins" button.
Hover over "MLA Tag Cloud Hooks Example" in the Name column, then click the "Install" rollover action.
Go to the Plugins/Installed Plugins screen and activate the "MLA Tag Cloud Hooks Example" plugin.
Create a new [mla_tag_cloud] shortcode or modify an existing shortcode, adding the my_filter="color cloud" parameter to activate the example output.
View the post or page on which the modified shortcode appears to see a tag cloud with a range of colors applied to the terms.

The example code documents each hook with comments in the filter/action function that intercepts the hook. Generally, each part of the cloud supports three hooks: 1) a "values" hook, which lets you record or update the substitution values for that cloud part, 2) a "template" hook, which lets you record/update the template used to generate the HTML markup, and 3) a "parse" hook which lets you modify or replace the markup generated for a cloud part. The current hooks are:

mla_tag_cloud_raw_attributes	called at the beginning of the cloud, before the attributes pass through the logic that handles the 'mla_page_parameter' and "request:" prefix processing.
mla_tag_cloud_attributes, mla_tag_cloud_arguments	called at the beginning of the cloud generation. You can record/modify shortcode parameter values before (attributes) or after (arguments) they are combined with all the defaults.
mla_get_terms_query_attributes, mla_get_terms_query_arguments	called just before the `WP_Query->query()` call that selects gallery items, with query parameters before or after they are combined with defaults.
mla_get_terms_clauses	gives you a final opportunity to inspect or modify the SQL clauses for the data selection process.
mla_get_terms_query_results	called just after the `$wpdb->get_results` call, so you can inspect/record or modify the results.
mla_tag_cloud_scale	called as the scaled_count (size) of each term is calculated, so you can modify the results.
use_mla_tag_cloud_style	allow or suppress the inclusion of CSS styles in the tag cloud output.
mla_tag_cloud_style_values, mla_tag_cloud_style_template, mla_tag_cloud_style_parse	for manipulating the Style template.
mla_tag_cloud_open_values, mla_tag_cloud_open_template, mla_tag_cloud_open_parse	for manipulating the "Open" part of the Markup template used in a "list" or "grid" cloud.
mla_tag_cloud_row_open_values, mla_tag_cloud_row_open_template, mla_tag_cloud_row_open_parse	for manipulating the "Row Open" part of the Markup template used in a "grid" cloud.
mla_tag_cloud_item_values, mla_tag_cloud_item_template, mla_tag_cloud_item_parse	for manipulating the "Item" part of the Markup template used in a "list" or "grid" cloud.
mla_tag_cloud_row_close_values, mla_tag_cloud_row_close_template, mla_tag_cloud_row_close_parse	for manipulating the "Row Close" part of the Markup template used in a "grid" cloud.
mla_tag_cloud_close_values, mla_tag_cloud_close_template, mla_tag_cloud_close_parse	for manipulating the "Close" part of the Markup template used in a "list" or "grid" cloud.

[mla_term_list]

Provides flat or hierarchical lists, dropdown controls and checkbox lists of taxonomy terms.

Complete documentation

MLA Term List Shortcode

The [mla_term_list] shortcode function displays hierarchical taxonomy terms in a variety of formats; link lists, dropdown controls and checkbox lists. The list works with both flat (e.g., Att. Tags) and hierarchical taxonomies (e.g., Att. Categories) MLA Term List enhancements for lists and controls include:

Full support for WordPress categories, tags and custom taxonomies. You can select from any taxonomy or list of taxonomies defined in your site.
Several display formats, including "flat", "list", "dropdown" and "checklist".
Control over the styles, markup and content of each list using Style and Markup Templates. You can customize the "list" formats to suit any need.
Access to a wide range of content using the term-specific and Field-level Substitution parameters. A powerful Content Template facility lets you assemble content from multiple sources and vary the results depending on which data elements contain non-empty values for a given term.
Display Style and Display Content parameters for easy customization of the list display and the destination/value behind each term.
A comprehensive set of filters gives you access to each step of the list generation process from PHP code in your theme or other plugins.

The [mla_term_list] shortcode has many parameters and some of them have a complex syntax; it can be a challenge to build a correct shortcode. The WordPress Shortcode API has a number of limitations that make techniques such as entering HTML or splitting shortcode parameters across multiple lines difficult. Read and follow the rules and guidelines in the "Entering Long/Complex Shortcodes" Documentation section to get the results you want.

Many of the [mla_term_list] concepts and shortcode parameters are modeled after the [mla_gallery] and [mla_tag_cloud] shortcodes, so the learning curve is shorter. Differences and parameters unique to the list are given in the sections below.

Term List Output Formats

The default term list output is an unordered list of term names surrounded by hyperlinks. The terms' display format is determined by the "mla_output" parameter:

flat	Returns a sequence of hyperlink tags without further HTML markup. The "separator" parameter content (default, one newline character) is inserted between each hyperlink.
list	Returns hyperlinks enclosed by one of the HTML list tags; unordered (<ul></ul>, the default tag value) or definitions (<dl></dl>), which allow for each term to have a "caption". The "itemtag", "termtag" and "captiontag" parameters customize the list markup. If the "captiontag" parameter is present the list tag will be definitions (<dl></dl>).
ulist	Returns hyperlinks enclosed by HTML unordered list tags (<ul></ul>). The "itemtag" and "termtag" parameters customize the list markup. "ulist" is the default output format value.
olist	Returns hyperlinks enclosed by HTML ordered list tags (<ol></ol>). The "itemtag" and "termtag" parameters customize the list markup.
dlist	Returns hyperlinks enclosed by HTML definition list tags (<dl></dl>), which allow for each term to have a "caption". The "itemtag", "termtag" and "captiontag" parameters customize the list markup.
dropdown	Returns an HTML "select" control with a sequence of HTML "option" tags.
checklist	Returns HTML "input", "type=checkbox" elements enclosed by HTML unordered list tags (<ul></ul>). The "itemtag" and "termtag" parameters customize the list markup.
array	Returns a PHP array of list hyperlinks. This output format is not available through the shortcode; it is allowed when the `MLAShortcodes::mla_term_list()` function is called directly from your theme or plugin PHP code.

The list, dropdown and checklist formats can be extensively customized by using custom .

Term List Output Structure

The "hierarchical" parameter determines the overall structure of the list:

hierarchical=false	display terms without regard to parent/child relationships.
hierarchical=true	display terms in a nested/indented structure where child terms are placed immediately after their parent. This is the default value. If you code multiple taxonomies in the same shortcode, each taxonomy will generate its own separate list or control.
hierarchical=combine	display terms from multiple taxnomies in a single nested/indented structure.

The hierarchical display is enhanced by a number of data selection parameters that let you select and display portions of the hierarchy, e.g., a single root/parent term and all of its children.

Term List Item Parameters

Each item in the list comprises a term name, a hyperlink surrounding the term name and a "title" attribute (Rollover Text) displayed when the cursor hovers over the term name hyperlink. The following parameters customize item content and markup:

show_count	Show how many items are assigned to the term. Values "true" or "false" (default).
current_item	Identifies the current/selected item(s) in the list. An integer value will be interpreted as a term id and anything else as a term slug. It will be ignored if it does not match an item in the list. Multiple values are allowed, separated by commas.
mla_item_parameter	The name of the parameter containing the current item value; default "current_item". You can change the name if you need multiple lists on one post/page.
active_item_class	The class attribute for the "active" item(s) in the list as determined by the "current_item" parameter (if specified); default "mla_active_item". An item is "active" if it or any of its child items are the current item.
current_item_class	The class attribute for the current item in the list as determined by the "current_item" parameter (if specified); default "mla_current_item".

The Item parameters are an easy way to customize the content and markup for each list item. For the array, flat and list formats you can also use the additional list item parameters in the next section.

Term List Item Parameters (Array, Flat and List)

The following parameters customize item content and markup:

separator	The text/space between terms. Default '\n' (whitespace)
single_text	The text for the "title" attribute (Rollover Text) when the count value is one; default "%d item". If you change the default, don't forget to include the "%d" placeholder.
multiple_text	The text for the "title" attribute (Rollover Text) when the count value is zero or more than one; default "%d items". If you change the default, don't forget to include the "%d" placeholder.
link	Chooses the destination of the item hyperlink; details in the next section below.

The Item parameters are an easy way to customize the content and markup for each list item. For the list formats you can also use the

Term List Item Link Values (Array, Flat and List)

The Link parameter specifies the target and type of link from the list term/item to the item's archive page, edit page or other destination. You can also specify a non-hyperlink treatment for each item. These values only apply to the hyperlinks generated for the "array", "flat" and "list" output formats.

current	Link back to the current post/page with a query argument, `current_item`, set to the term_id of the selected term. "current" is the default item link value.
view	Link to the term's "archive page". Support for archive pages, or "tag archives", is theme-dependent. There is an introduction to tag archives in the WordPress Codex at the bottom of the `wp_tag_cloud` Function Reference.
edit	Link to the term's "edit tag/category" admin screen. This is only useful if the user is logged in and has the appropriate role or capabilities for accessing the edit screen.
(mla_link_href)	Link to a custom destination, typically another post/page. If the "mla_link_href" parameter is present the value of the "link" parameter is ignored. See the example later in this section for more details.
span	Substitutes a `<span></span>` tag for the hyperlink tag. You can use the "mla_link_attributes" and "mla_link_class" parameters to add attributes to the `<span>` tag. You can use the "mla_link_text" parameter to customize the text within the span.
none	Eliminates the hyperlink tag surrounding the item text. You can use the "mla_link_text" parameter to customize the contents.

Using the "mla_link_href" parameter to completely replace the link destination URL is a common and useful choice. With this parameter you can use the term list to select a term and then go to another post/page that uses that selection as part of an [mla_gallery] shortcode. The example later in this section uses this technique.

Term List Display Style (List, Dropdown and Checklist)

Two parameters provide a way to apply custom style and markup templates to your [mla_term_list] display. These parameters replace the default style and/or markup templates with templates you define on the "Shortcodes" tab of the Settings page. Templates are supported for the "list", "dropdown" and "checklist" list formats.

mla_style	replaces the default style template for an `[mla_term_list]` shortcode. You can code "none" to suppress the addition of CSS inline styles entirely.
mla_markup	replaces the default markup template for an `[mla_term_list]` shortcode

Term List Display Style (List and Checklist)

Three parameters provide control over the XHTML tags used to enclose each part of the list items. These parameters are used in the "list" output formats as follows:

itemtag	the name of the XHTML tag used to begin the list; the default depends on the output format (list/ulist, olist, dlist). When an explicit "captiontag" parameter is added to "list" format, the default is "dl".
termtag	the name of the XHTML tag used to enclose each term in the list; the default is "li". When an explicit "captiontag" parameter is added, the default is "dt".
captiontag	the name of the XHTML tag used to enclose each caption. For "dlist" format, the default is "dd". To add a caption in "list" format you must enter an explicit "captiontag=dd" parameter to the shortcode.

Term List Display Style (Dropdown)

Three parameters provide control over the XHTML tags used to enclose each part of the dropdown control items.

itemtag	the name of the XHTML tag used to name the control; the default is "select".
termtag	the name of the XHTML tag used to name each term in the control; the default is "item".
mla_multi_select	The default, "false", specifies that only one value can be selected. If set to "true", it specifies that multiple options can be selected at once.

These parameters give you some control over the markup used for the list and its elements. For more complex applications you can use style and markup templates to gain complete control over the list display.

Term List Display Content (Array, Flat and List)

Eight parameters provide an easy way to control the contents of list items without requiring the use of custom Markup templates.

mla_link_attributes	adds one or more HTML attributes to the hyperlink for each item; see below
mla_link_class	adds one or more classes to any already defined for the hyperlink
mla_link_href	replaces the HTML "href" attribute in the hyperlink for each item; see below
mla_link_text	replaces the term name text displayed for each item
mla_nolink_text	replaces the empty string displayed when there are no list items
mla_rollover_text	replaces the HTML "title" attribute in the hyperlink for each item. This is the attachment title text displayed when the mouse rolls or hovers over the term name
mla_caption	replaces the caption text displayed beneath each item. The caption appears for "dlist" items and for "list" items when the "captiontag" parameter is present.
mla_target	adds an HTML "target" attribute to the hyperlink for each gallery item; see below

The "mla_link_href" parameter is a great way to change the destination your list item links to and/or add arguments to the link for later processing. For example, to make a gallery item link back to the current page/post you can code: mla_link_href='{+page_url+}'. You can also add arguments to the link, e.g., mla_link_href='{+page_url+}?firstarg=value1&myarg=myvalue'. Note the use of the HTML entity name "&" to put an ampersand in the value; the WordPress "visual" post editor will replace "&", "<" and ">" with "&", "<" and ">" whether you like it not. The only markup parameters modified by this parameter are "link_url" and "thelink". The markup parameters "currentlink", "viewlink" and "editlink" are not modified.

Term List Display Content (Dropdown and Checklist)

Dropdown and Checklist formats do not generate hyperlinks; they generate HTML input controls that return the content of value attributes. Eight parameters provide an easy way to control the contents of items without requiring the use of custom Markup templates.

mla_control_name	replaces the `tax_input[[+taxonomy+]][]` (default) name attribute in the input tag for the control(s). Useful for adding multiple dropdown controls for the same taxonomy to a post/page and for dropdown controls containing terms from multiple taxonomies.
mla_option_text	replaces the term name (default) text displayed for each option
mla_option_value	replaces the term_id (default) value returned for each option. For dropdown controls containing terms from multiple taxonomies, the default is `[+taxonomy+].[+term_id+]`.
hide_if_empty	If false (default), display a control with "option_none" text & value. If true, display mla_nolink_text or nothing.
mla_nolink_text	replaces the entire control with text/markup; default empty
option_all_text	Text to display for showing an 'all terms' option. Default will not show an option to select 'all terms'.
option_all_value	Control value for 'all terms' option. Default zero. Numeric values are used for the term_id; text values for the slug.
option_none_text	Text to display for showing a 'no terms' option. Default will not show an option to select 'no terms'.
option_none_value	Control value for 'no terms' option. Default -1. Numeric values are used for the term_id; text values for the slug.

The mla_option_value parameter is the most commonly-used. For example, to return the term slug instead of the term id you would code mla_option_value="{+slug+}".

Dropdown controls containing terms from multiple taxonomies (flat or hierarchical) require special handling because the name= attribute appears once for the entire control, not once for each term within the control. To associate each term with its taxonomy both values are encoded in the value= attribute in the term's option tag. Here is an example for two "flat" taxonomies:

[mla_term_list taxonomy="animal,vegetable" mla_output=dropdown]

The above shortcode generates the HTML below (some class attributes removed for clarity).

<select name="tax_input[animal-vegetable][]" class="term-list-taxonomy-animal-vegetable" id="mla_term_list-1"> <option class="term-list-dropdown-term level-0" value="animal.12">Dog</option> <option class="term-list-dropdown-term level-0" value="animal.13">Cat</option> <option class="term-list-dropdown-term level-0" value="vegetable.33">Carrot</option> <option class="term-list-dropdown-term level-0" value="vegetable.35">Apple</option> </select>

In the above example, to return the term slug instead of the term id you would add mla_option_value="{+taxonomy+}.{+slug+}" to the shortcode.

If you use the default control name, the [mla_gallery] shortcode’s tax_input parameter can convert the compound value(s) returned in the tax_input array to the appropriate taxonomy-specific entries. For example, the animal.12 value can be handled as if it was animal=12. For the above example, the corresponding [mla_gallery] shortcode parameter would be tax_input="{+request:tax_input.animal-vegetable+}". See the section for more information.

You could use the mla_control_name shortcode parameter to move the selected term out of the default tax_input array to a separate query argument and then process the returned value in your own PHP code.

Term List Other Parameters

mla_debug	controls debug log output; default false. See below for details.
echo	This does not apply to the shortcode; it is allowed when the `MLAShortcodes::mla_term_list()` function is called directly from your theme or plugin PHP code. If `echo=false` content generated by the function is returned to the caller; false is the default value. If `echo=true` content is echoed to the browser and nothing is returned.

The "mla_debug" parameter controls the display of information about the query parameters and SQL statements used to retrieve list items. If you code mla_debug=true you will see a lot of information added to the post or page containing the list. Of course, this parameter should ONLY be used in a development/debugging environment; it's quite ugly.

If you code mla_debug=log all of the information will be written to the error log. You can use the MLA Debug Tab to view and download the information in the error log.

Term List Data Selection Parameters

The data selection parameters specify which taxonomy (or taxonomies) the terms are taken from, which terms are returned for the list and the order in which the terms are returned:

taxonomy	The taxonomy or taxonomies to retrieve terms from; default 'post_tag'. Use the name/slug of each taxonomy, not the display name, e.g., 'post_tag', 'category', 'attachment_tag', or 'attachment_category'. You can specify multiple taxonomies as a comma-separated string or (if you are calling `MLAShortcodes::mla_term_list()` function directly from your theme or plugin PHP code) as an array.
post_mime_type	The MIME type(s) of the items to include in the term-specific counts. The default is "all", which avoids the additional database effort required to filter by MIME type. You can override the default to, for example, display PDF documents (`post_mime_type=application/pdf`) or all image MIME types (`post_mime_type=image`). You can select several MIME types with a comma-separated list, e.g., `post_mime_type='audio,video'`. Wildcard specifications are also supported. For example, `post_mime_type='/mpeg'` to select audio and video mpeg formats or `post_mime_type='application/ms*'` to select all Microsoft application formats (Word, Excel, etc.).
post_type	The post type(s) of the items to include in the term-specific counts. The default is "attachment". You can override the default if you want to count other types for which the taxonomy is registered, e.g., "post" to count Posts in the "category" and "post_tag" taxonomies. The Codex Page documents other post type values. Make sure your "post_status" and "post_type" values are consistent, e.g., use `post_type="attachment,post" post_status="inherit,publish"` together.
post_status	The post status value(s) of the items to include in the term-specific counts. The default is "inherit", which counts attachments (Media Library Items). You can override the default if you want to count other values, e.g., "publish" to count published Posts in the "category" and "post_tag" taxonomies. If you code "private" and the user is not logged in, "private" will be removed. The Codex page documents other post status values.
ids	A comma-separated list of attachment ID values for an item-specific list. Only those terms assigned to the attachment(s) in the list will be included. You can have one or more IDs and you can include assigned terms from one or more taxonomies. Do not use the "include" parameter if you use the "ids" parameter.
no_count	The default, "false", computes a term-specific count of the number of attachments assigned to that term. If you have a large number of terms and/or attachments, this can take a long time. You can code "true" to omit the attachment-counting process. If you do that, the "post_mime_type", "post_type", "post_status", "minimum", "number" and "orderby=count" parameters are also ignored, since they require counting the attachments. You can code "internal" to skip the explicit attachment-counting process and use the WordPress-maintained "count" database values. If you code `no_count=internal`, the "post_mime_type", "post_type" and "post_status" paramerters are ignored, since they require a separate subquery to filter the list by post-specific values.
include	A comma-separated list of term ids (not names or slugs) to include. Only the terms in this list that are used in the taxonomies you specified will be retrieved.
exclude	A comma-separated list of term ids (not names or slugs) to exclude from the returned values.
parent	Get direct children of this term id (only terms whose explicit parent is this value). If 0 is passed, only top-level terms are returned.
minimum	The minimum number of attachments that must be associated with the term for the term to be included. For example, "minimum=1" will omit "empty" terms.
number	The maximum number of "most popular" terms to return. The default, zero, returns them all. Terms are sorted by "count DESC, id ASC" to apply this constraint.
orderby	The sort order of the retrieved terms. Can be one or more of "count", "id" (term_id), "name" (the default), "none", "random", or "slug". If you install and activate the Simple Custom Post Order plugin you can code "term_order" to sort the cloud into the "drag and drop" order supported by that plugin. Or, if you install and activate the Simple Taxonomy Ordering plugin you can code "tax_position" to sort the cloud into the "drag and drop" order supported by that plugin.
order	Can be "ASC" (ascending, the default) or "DESC" (descending). Note that DESC is not supported for `orderby=tax_position`.
preserve_case	Preserve upper- and lower-case distinctions when sorting by name. The default, "false", specifies a case-insensitive sort order.
pad_counts	True to include the count of all children in their parents' count. The default, "false", does not include children in their parents' count. The "pad_counts" parameter is only applied to the first (or only) taxonomy you specify, and that taxonomy must be hierarchical to see any difference in the counts.

Term List Data Selection Parameters (Hierarchical Output)

When the list is organized by the term hierarchy (hierarchical=true) four parameters can be used to trim the tree and display a subset of the terms:

child_of	Display all terms that are descendants (i.e. children & grandchildren) of the term identified by its term_id; default empty
exclude_tree	Comma/space-separated string of term_id values to exclude along with all of their descendant terms. If `include` is non-empty, `exclude_tree` is ignored. Default empty.
include_tree	Comma/space-separated string of term_id values to include along with all of their descendant terms. Default empty.
depth	The maximum depth of parent/child relationships; default 0/False to display all levels

You can use these parameters with multiple [mla_term_list] shortcodes to navigate large hierarchical taxonomies. For example, define a control that shows only root terms ( parent=0 ) with a control that shows the children of a specific root term ( child_of={+current_item+} ).

Term List Substitution Parameters

Substitution parameters are a powerful way to add general and attachment-specific values to the list display. For example, if you code "mla_link_href="{+page_url+}?current_slug={+slug+}&current_name={+name,url+}", the hyperlinks behind each list term will contain the page URL, the current term slug and the term name encoded in url format. There are many parameter names like `page_url` and `slug` divided in several categories:

List-specific	values that are known at the beginning of shortcode processing and remain the same for the entire shortcode, such as the ID and URL of the post/page in which the shortcode appears
Style	values that are known when the list-specific CSS inline styles are composed just before list output begins
Markup	values that are known at the beginning of list output processing and remain the same for the entire list
Item-specific	values that change for each term/item in the list, such as Name and Description
Field-level	additional values from sources like query arguments and shortcode parameters. The "request:" and "query:" field-level prefixes can be used in the list. The other prefixes are attachment-specific and have no meaning in a list
Content Template	lets you compose a value from multiple substitution parameters and test for empty values, choose among two or more alternatives or suppress output entirely

The following paragraphs go into more detail about each category and the parameter names within them.

list-specific substitution parameters are known at the beginning of shortcode processing and they do not change during processing. They can be used, for example, in any of the data selection parameters to change the items selected for the list based on information about the post/page on which the list appears. The list-specific substitution parameters are:

site_url	absolute URL to the site directory, without trailing slash
base_url	absolute URL to the upload directory, without trailing slash
base_dir	absolute (full) path to the upload directory, without trailing slash
instance	starts at '1', incremented for each additional shortcode in the post/page
selector	"mla_term_list-{$instance}", e.g., mla_term_list-1
page_ID, id	the `ID` value of the post/page in which the list appears
page_author	the `post_author` value of the post/page in which the list appears
page_date	the `post_date` value of the post/page in which the list appears
page_content	the `post_content` value of the post/page in which the list appears
page_title	the `post_title` value of the post/page in which the list appears
page_excerpt	the `post_excerpt` value of the post/page in which the list appears
page_status	the `post_status` value of the post/page in which the list appears
page_name	the `post_name` value of the post/page in which the list appears
page_modified	the `post_modified` value of the post/page in which the list appears
page_guid	the `post_guid` value of the post/page in which the list appears
page_type	the `post_type` value of the post/page in which the list appears
page_url	absolute URL to the page or post on which the list appears, if any, with trailing slash

Style and Markup templates give you great flexibility for the content and format of each [mla_term_list] when you use the "list", "dropdown" and "checklist" output formats. You can define as many templates as you need.

Style templates provide list-specific CSS inline styles (you can code mla_style=none to suppress the addition of CSS inline styles entirely). Markup templates provide the HTML markup for the beginning of the list, each list item and the end of the list. Additional "Child" template parts provide optional markup for the opening, each item and the close of sublists for child terms.

The Shortcodes tab on the Settings page lets you add, change and delete custom templates. The default templates are also displayed on this tab for easy reference.

There are two default templates for the "list" format; "term-list-ul" and "term-list-dl". As the names imply, the "term-list-dl" default is used for the "dlist" output format or when the "captiontag" parameter is present in the shortcode. If you name a custom Markup template in your shortcode, it will be used whether the "captiontag" is present or not.

The following field-level substitution parameters are available in the Style template and any of the Markup template sections:

request	The parameters defined in the `$_REQUEST` array; the "query strings" sent from the browser. The PHP $_REQUEST variable is a superglobal Array that contains the contents of both $_GET, $_POST and $_COOKIE arrays.
query	The parameters defined in the `[mla_term_list]` shortcode. For example, if your shortcode is `[mla_term_list taxonomy=attachment_tag div-class=some_class]` you can access the parameters as `[+query:taxonomy+]` and `[+query:div-class+]` respectively. You can define your own parameters, e.g., "div-class"; they will be accessible as field-level data but will otherwise be ignored.
template	A Content Template, which lets you compose a value from multiple substitution parameters and test for empty values, choosing among two or more alternatives or suppressing output entirely. See the Content Templates section for details. Note that the formatting option is not supported for content templates.

Term list substitution parameters for the Style template are:

mla_output	shortcode parameter, default = 'ulist'
mla_style	shortcode parameter, default = 'term-list'
mla_markup	shortcode parameter, default = 'term-list-ul', '-dl', '-dropdown' or '-checklist' depending on the list output format
taxonomy	the slug of the taxonomy on which the list is based. Multiple taxonomy slugs are joined with a dash to form a single value.
current_item	the current/selected item in the list, as entered in the shortcode parameters.
itemtag	shortcode parameter, default = 'ul', 'ol', or 'dl' if the "captiontag" parameter is present.
termtag	shortcode parameter, default = 'li', or 'dd' if the "captiontag" parameter is present.
captiontag	shortcode parameter, default = '', i.e., no caption tag value.
itemtag_attributes	HTML attribute value(s) added to the item tag
itemtag_class	HTML class names(s) added to the item tag
itemtag_id	HTML "id" attribute value for the item tag
all_found_rows	the number of terms retrieved for the list before "pruning" by the Hierarchical Output Data Selection parameters
found_rows	the number of terms retrieved for the list, after any "pruning"
separator	The text/space between tags
single_text	Rollover Text when the count value is one
multiple_text	Rollover Text when the count value is zero or more than one
echo	whether the output is echoed directly to the browser (true) or returned to the caller (false). For a shortcode, always false.
link	the destination name of the item hyperlink, default 'view'

Term list substitution parameters for the Markup template are available in all of the template sections. All of the list-specific substitution parameters and the substitution parameters for Style templates are available for use in markup templates. Three substitution parameters are added or modified for the markup template:

current_level	the parent/child relationship "depth", starting at zero for root terms
itemtag_class	the 'children' class is added for all but the root level
itemtag_id	the term's parent id is added for all but the root level

There are also

Term list item-specific substitution parameters for the Markup template are available in the "Item" and "Child Item" sections of the template. They include all of the parameters defined above (for the Style and Markup templates) Additional item-specific parameters are:

key	set to the "tags" array key/index value. Only useful if the `mla_get_terms_query_results()` filter has altered the array keys.
term_id	the term id
name	the term display name
slug	the term slug
term_group	the term group
term_taxonomy_id	the term-taxonomy id
taxonomy	the primary taxonomy for this term
description	the term description, if any
parent	the direct parent of the term
count	the number of attachments associated with the term
link_url	the URL portion of "thelink" (below). Derived from editlink_url, termlink_url or mla_link_href.
currentlink_url	URL of the current post/page plus a "current_item=term_id" query argument
editlink_url	URL of the term's "edit category/tag" page
termlink_url	URL of the term's archive page
children	HTML markup for the current term's children, if any
caption	if captiontag is not empty, contains term description or the mla_caption value
link_attributes	link attributes, if any, drawn from the mla_target, mla_link_attributes and mla_link_class parameters
active_item_class	set to the value of the `active_item_class` parameter (default "mla_active_item") for the active item(s) in the list as determined by the "current_item" parameter, and to an empty string for all other items in the list. An item is "active" if it or any of its child items are the current item.
current_item_class	set to the value of the `current_item_class` parameter (default "mla_current_item") for the current item in the list as determined by the "current_item" parameter, and to an empty string for all other items in the list.
rollover_text	the "title" attribute value, drawn from single_text/multiple_text or the mla_rollover_text parameters
link_style	the CSS "style" attribute, drawn from the font_size and unit parameters
link_text	the text enclosed by the hyperlink, drawn from the term name or mla_link_text parameter
thelink	full hyperlink to the chosen destination as determined by the "link" and "mla_link_href" parameters
currentlink	full hyperlink to the current page with a term-specific query argument, including all the Display Content parameters
editlink	full hyperlink to the term's "edit category/tag" page, including all the Display Content parameters
termlink	full hyperlink to the term's archive page, including all the Display Content parameters

MLA Term List Examples

Here is a simple example of a dropdown control for the Att. Categories taxonomy:

<form id="mla-text-form" action="." method="post" class="row"> <strong>Att. Categories</strong> [mla_term_list taxonomy=attachment_category mla_output=dropdown mla_option_value="{+slug+}" show_count=true pad_counts=false ]


<input id="text-form-submit" name="text_form_submit" type="submit" value="Search" />

</form>
<h3>Gallery</h3>

[mla_gallery]

attachment_category="{+template:({+request:tax_input.attachment_category+}|no-term-selected)+}"

posts_per_page=3 mla_output="paginate_links,prev_next"

mla_link_href='{+new_url+}?mla_paginate_current={+new_page+}&tax_input[attachment_category]={+query:attachment_category,url+}'

[/mla_gallery]

[mla_gallery attachment_category="{+template:({+request:tax_input.attachment_category+}|no-term-selected)+}" posts_per_page=3 mla_caption="{+title+} : {+description+}" mla_nolink_text="<br>Select a term to display the gallery.<br>"]

As you can see, the key is passing the selected term from the form to the gallery shortcodes. By default, the [mla_term_list] shortcode collects all of its results in the tax_input array, keyed by taxonomy slug. The example combines this with an invalid term slug so the gallery will be empty until a term is selected in the dropdown. Note that the pagination shortcode uses the “enclosing shortcode” format so HTML characters in the mla_link_href parameter are not corrupted by the WordPress shortcode parsing process.

You can experiment with a category checklist format by simply changing mla_output=dropdown to mla_output=checklist in the [mla_term_list] shortcode. You will also see that the term you select doesn’t “stick” in the dropdown control when the page is refreshed with the gallery display. That is one motivation for the MLA UI Elements Example plugin. You can use that example plugin to improve the user experience after you have got the basic application going.

MLA Term List Filters (Hooks)

The [mla_term_list] shortcode supports a comprehensive set of filters that give you complete control over list composition from PHP code in your theme or in another plugin. An example of using the hooks from a simple, stand-alone plugin can be found in the Documentation/Example Plugins submenu. You can find the example plugin here: MLA Term List Hooks Example. To run the example:

Click on the link above or go to top of the Documentation tab and click on the "Example Plugins" button.
Hover over "MLA Term List Hooks Example" in the Name column, then click the "Install" rollover action.
Go to the Plugins/Installed Plugins screen and activate the "MLA Term List Hooks Example" plugin.
Create a new [mla_term_list] shortcode or modify an existing shortcode, adding the my_filter="color list" parameter to activate the example output.
View the post or page on which the modified shortcode appears to see a term list with a range of colors applied to the terms.

The example code documents each hook with comments in the filter/action function that intercepts the hook. Generally, each part of the list supports three hooks: 1) a "values" hook, which lets you record or update the substitution values for that list part, 2) a "template" hook, which lets you record/update the template used to generate the HTML markup, and 3) a "parse" hook which lets you modify or replace the markup generated for a list part. The current hooks are:

mla_term_list_raw_attributes	called at the beginning of the cloud, before the attributes pass through the logic that handles the 'mla_page_parameter' and "request:" prefix processing.
mla_term_list_attributes, mla_term_list_arguments	called at the beginning of the cloud generation. You can record/modify shortcode parameter values before (attributes) or after (arguments) they are combined with all the defaults.
mla_get_terms_query_attributes, mla_get_terms_query_arguments	called just before the `WP_Query->query()` call that selects gallery items, with query parameters before or after they are combined with defaults.
mla_get_terms_clauses	gives you a final opportunity to inspect or modify the SQL clauses for the data selection process.
mla_get_terms_query_results	called just after the `$wpdb->get_results` call, so you can inspect/record or modify the results.
use_mla_term_list_style	allow or suppress the inclusion of CSS styles in the tag cloud output.
mla_term_list_style_values, mla_term_list_style_template, mla_term_list_style_parse	for manipulating the Style template.
mla_term_list_open_values, mla_term_list_open_template, mla_term_list_open_parse	for manipulating the "Open" part of the Markup template used in a "list", "dropdown" or "checklist" term list.
mla_term_list_item_values, mla_term_list_item_template, mla_term_list_item_parse	for manipulating the "Item" part of the Markup template used in a "list", "dropdown" or "checklist" term list.
mla_term_list_close_values, mla_term_list_close_template, mla_term_list_close_parse	for manipulating the "Close" part of the Markup template used in a "list", "dropdown" or "checklist" term list.

Support for the “Real Media Library” Plugin

The WordPress Real Media Library: Media Library Folder & File Manager plugin helps you with media management. Organize thousands of uploaded files into folders, collections and galleries. You can add parameters to the [mla_gallery] shortcode to filter the gallery display by RML folder, collection or gallery ID. There are three [ mla_gallery] shortcode parameters for this purpose:

mla_rml_folder	the name of the RML folder, collection or gallery from which to source items gor the gallery display. You can find the ID of a folder easily in your media library. Simply select a folder, afterwards click the three-dots icon in the folder toolbar. A dialog opens and in the bottom right corner you can find a number which represents the folder ID.
mla_rml_include_children	"false" (the default) to restrict the potential items to the specific folder or gallery named in the `mla_rml_folder` parameter. Set it to "true" to include items in folders contained in the specific folder or collection named in the shortcode.
mla_allow_rml	(optional) "false" (the default) to remove the RML parameters from `[mla_gallery]` database queries. "true" to preserve the parameters. This parameter is only useful for performance testing purposes. It is automatically set to "true" if the `mla_rml_folder` parameter is present. You can safely ignore it.

You can use the other [mla_gallery] data selection parameters to further refine your query. For example, you can use post_mime_type=application/pdf to display only the PDF documents in a folder, or use application_category=abc to display only the images assigned to Att. Category "abc" in an RML gallery.

Support for the “Admin Columns” Plugin

The Admin Columns plugin allows you to customize columns on several admin-mode screens, including the MLA Media/Assistant submenu screen. All you have to do is install the plugin; MLA will detect its presence and automatically register the Media/Assistant submenu screen for support. With Admin Columns, you can:

Reorder columns with a simple drag & drop interface.
Re-size columns to give more or less space to a column.
Remove (not just hide) columns from the submenu table.
Add new columns for custom fields and additional information.
The Admin Columns "Pro" version adds support for inline editing, ACF fields and other capabilities.
The Admin Columns "Pro" version adds support for exporting Media/Assistant table values to CSV-format files.

When Admin Columns is present you will see a new "Edit Columns" button just above the Media/Assistant submenu table. Click the button to go to the Settings/Admin Columns configuration screen. There you will see "Media Library Assistant" added to the "Others:" list. Click on it to see the configuration of the Media/Assistant submenu screen.

You can find detailed configuration instructions at the Admin Columns web site Documentation page.

When you have completed your configuration changes, click "Update Media Library Assistant" in the Store Settings metabox at the top-right of the screen. You can also click "Restore Media Library Assistant columns" to remove your changes and go back to the MLA default settings. Click the "View" button at the right of the Media Library Assistant heading to return to the Media/Assistant submenu screen and see your changes.

General Processing Options

In this tab you can find a number of options for controlling the plugin’s operation. Scroll down to find options for Where-used Reporting, Taxonomy Support, Media/Assistant Table Defaults and Media Manager Enhancements. Be sure to click "Save Changes" at the bottom of the tab to save any changes you make.

Shortcodes made available by this plugin:

[mla_gallery] - enhanced version of the WordPress [gallery] shortcode. For complete documentation click here.
[mla_tag_cloud] - enhanced version of the WordPress Tag Cloud. For complete documentation click here.
[mla_term_list] - provides flat or hierarchical lists, dropdown controls and checkbox lists of taxonomy terms. For complete documentation click here.

MLA Shortcode Options

In this tab you can view the default style and markup templates. You can also define additional templates and use the mla_style and mla_markup parameters to apply them in your [mla_gallery] shortcodes.

You can find more information about shortcode templates and how MLA and WordPress use them in the Style and Markup Templates section of the Documentation or by clicking the "Help" tab in the upper-right corner of this screen.

Description

The Media Library Assistant provides several enhancements for managing the Media Library, including:

The [mla_gallery] shortcode, used in a post, page or custom post type to add a gallery of images and/or other Media Library items (such as PDF documents). MLA Gallery is a superset of the WordPress [gallery] shortcode; it is compatible with [gallery] and provides many enhancements. These include: 1) full query and display support for WordPress categories, tags, custom taxonomies and custom fields, 2) support for all post_mime_type values, not just images 3) media Library items need not be “attached” to the post, and 4) control over the styles, markup and content of each gallery using Style and Markup Templates. Twenty-eight hooks are provided for complete gallery customization from your theme or plugin code.
The [mla_tag_cloud] shortcode, used in a post, page, custom post type or widget to display the “most used” terms in your Media Library where the size of each term is determined by how many times that particular term has been assigned to Media Library items. Twenty-five hooks are provided for complete cloud customization from your theme or plugin code.
The [mla_term_list] shortcode, used in a post, page, custom post type or widget to display hierarchical (and flat) taxonomy terms in list, dropdown control or checklist formats. Twenty hooks are provided for complete list customization from your theme or plugin code.
Powerful Content Templates, which let you compose a value from multiple data sources, mix literal text with data values, test for empty values and choose among two or more alternatives or suppress output entirely.
Attachment metadata such as file size, image dimensions and where-used information can be assigned to WordPress custom fields. You can then use the custom fields in your [mla_gallery] display and you can add custom fields as sortable, searchable columns in the Media/Assistant submenu table. You can also modify the WordPress _wp_attachment_metadata contents to suit your needs.
IPTC, EXIF (including GPS), XMP and PDF metadata can be assigned to standard WordPress fields, taxonomy terms and custom fields. You can update all existing attachments from the Settings page IPTC/EXIF tab, groups of existing attachments with a Bulk Action or one existing attachment from the Edit Media/Edit Single Item screen. Display IPTC, EXIF, XMP and PDF metadata with [mla_gallery] custom templates. Twelve hooks provided for complete mapping customization from your theme or plugin code.
Support for WPML and Polylang multi-language CMS plugins.
Complete control over Post MIME Types, File Upload extensions/MIME Types and file type icon images. Fifty four (54) additional upload types, 112 file type icon images and a searchable list of over 1,500 file extension/MIME type associations.
Integrates with Photonic Gallery, Jetpack and other plugins, so you can add slideshows, thumbnail strips and special effects to your [mla_gallery] galleries.
Enhanced Search Media box. Search can be extended to the name/slug, ALT text and caption fields. The connector between search terms can be “and” or “or”. Search by attachment ID or Parent ID is supported, and you can search on keywords in the taxonomy terms assigned to Media Library items. Works in the Media Manager Modal Window, too.
Where-used reporting shows which posts use a media item as the “featured image”, an inserted image or link, an entry in a [gallery] and/or an entry in an [mla_gallery].
Complete support for ALL taxonomies, including the standard Categories and Tags, your custom taxonomies and the Assistant’s pre-defined Att. Categories and Att. Tags. You can add taxonomy columns to the Assistant listing, filter on any taxonomy, assign terms and list the attachments for a term.
Taxonomy and custom field support in the ATTACHMENT DETAILS pane of the Media Manager Modal Window.
An inline “Bulk Edit” area; update author, parent and custom fields, add, remove or replace taxonomy terms for several attachments at once. Works on the Media/Add New screen as well.
An inline “Quick Edit” action for many common fields and for custom fields
Displays more attachment information such as parent information, file URL and image metadata.
Allows you to edit the post_parent, the menu_order and to “unattach” items
Provides additional view filters for MIME types and taxonomies
Provides many more listing columns (more than 20) to choose from

The Assistant is designed to work like the standard Media Library pages, so the learning curve is short and gentle. Contextual help is provided on every new screen to highlight new features.
In this section, scroll down to see highlights from the documentation, including new and unique plugin features

NOTE: Complete documentation is included in the Documentation tab on the Settings/Media Library Assistant admin screen and the drop-down “Help” content in the admin screens.

THE EXAMPLE PLUGINS

The MLA example plugins have been developed to illustrate practical applications that use the hooks MLA provides to enhance the admin-mode screens and front-end content produced by the MLA shortcodes. Most of the examples are drawn from topics in the MLA Support Forum.

The Documentation/Example Plugins submenu lets you browse the list of MLA example plugins, install or update them in the Plugins/Installed Plugins area and see which examples you have already installed. To activate, deactivate or delete the plugins you must go to the Plugins/Installed Plugins admin submenu.

The Example plugins submenu lists all of the MLA example plugins and identifies those already in the Installed Plugins area. In the submenu:

the “Screen Options” dropdown area lets you choose which columns to display and how many items appear on each page
the “Help” dropdown area gives you a brief explanation of the submenu content and functions
the “Search Plugins” text box lets you filter the display to items containing one or more keywords or phrases
bulk and rollover actions are provided to install or update example plugins
the table can be sorted by any of the displayed columns

Once you have installed an example plugin you can use the WordPress Plugins/Editor submenu to view the source code and (with extreme caution) make small changes to the code. Be very careful if you choose to modify the code! Making changes to active plugins is not recommended. If your changes cause a fatal error, the plugin will be automatically deactivated. It is much safer to download the file(s) or use FTP access to your site to modify the code offline in a more robust HTML/PHP editor.

You can use the “Download” rollover action to download a plugin to your local system. Once you have made your modifications you can copy the plugin to a compressed file (ZIP archive) and then upload it to your server with the Plugins/Add New (Upload Plugin) admin submenu.

If you do make changes to the example plugin code the best practice is to save the modified file(s) under a different name, so your changes won’t be lost in a future update. If you want to retain the file name, consider changing the version number, e.g. adding 100 to the MLA value, so you can more easily identify the plugins you have modified.

MLA TERM LIST SHORTCODE

Full support for WordPress categories, tags and custom taxonomies. You can select from any taxonomy or list of taxonomies defined in your site.
Several display formats, including “flat”, “list”, “dropdown” and “checklist”.
Control over the styles, markup and content of each list using Style and Markup Templates. You can customize the “list” formats to suit any need.
Access to a wide range of content using the term-specific and Field-level Substitution parameters. A powerful Content Template facility lets you assemble content from multiple sources and vary the results depending on which data elements contain non-empty values for a given term.
Display Style and Display Content parameters for easy customization of the list display and the destination/value behind each term.
A comprehensive set of filters gives you access to each step of the list generation process from PHP code in your theme or other plugins.

The [mla_term_list] shortcode has many parameters and some of them have a complex syntax; it can be a challenge to build a correct shortcode. The WordPress Shortcode API has a number of limitations that make techniques such as entering HTML or splitting shortcode parameters across multiple lines difficult. Read and follow the rules and guidelines in the “Entering Long/Complex Shortcodes” Documentation section to get the results you want.

Many of the [mla_term_list] concepts and shortcode parameters are modeled after the [mla_gallery] and [mla_tag_cloud] shortcodes, so the learning curve is shorter. Differences and parameters unique to the list are given in the sections below.

Items, Translations and Terms

Each Media Library item can have one or more “translations”. The item translations are linked and they use the same file in the Media Library. The linkage lets us know that “¡Hola Mundo!” (Spanish), “Bonjour Monde” (French) and “Hello world!” (English) are all translations of the same post/page. Post/page translation is optional; some posts/pages may not be defined for all languages. The language of the first translation entered for a post/page is noted as the “source language”.

Taxonomy terms can also have one or more translations, which are also linked. The linkage lets us know that “Accesorio Categoría” (Spanish), “Catégorie Attachement” (French) and “Attachment Category” (English) are all translations of the same term. Term translation is optional; some terms may not be defined for all languages. The language of the first translation entered for a term is noted as the “source language”.

When an item is uploaded to the Media Library it is assigned to the current language (note: avoid uploading items when you are in “All Languages”/”Show all languages” mode; bad things happen). WPML provides an option to duplicate the new item in all active languages; Polylang does not. MLA makes it easy to add translations to additional languages with the Translations column on the Media/Assistant submenu table. For Polylang, MLA provides Quick Translate and Bulk Translate actions as well.

Assigning language-specific terms to items with multiple translations can be complex. MLA’s Term Assignment logic assures that every term you assign on any of the editing screens (Media/Add New Bulk Edit, Media/Edit, Media/Assistant Quick Edit and Bulk Edit, Media Manager ATTACHMENT DETAILS pane) will be matched to the language of each item and translation. MLA’s Term Synchronization logic ensures that changes made in one translation are replicated to all other translations that have an equivalent language-specific term.
Shortcode Support

The [mla_gallery] shortcode selects items using the WordPress WP_Query class. Both WPML and Polylang use the hooks provided by WP_Query to return items in the current language. If you use taxonomy parameters in your shortcode you must make sure that the term name, slug or other value is in the same language as the post/page in which it is embedded. This is easily done when the post/page content is translated from one language to another.

The [mla_tag_cloud] shortcode selects terms using the WordPress wpdb class. MLA adds language qualifiers to the database queries that compose the cloud so all terms displated are appropriate for the current language. No special coding or shortcode modification is required.

Media/Assistant submenu table

Two columns are added to the table when WPML or Polylang is active:

Language – displays the language of the item. This column is only present when “All languages/Show all languages” is selected in the admin toolbar at the top of the screen.
“Translations” – displays the translation status of the item in all active languages. The column header displays the flag icon for the language. The column content will have a checkmark icon for the item’s language, a pencil icon for an existing translation or a plus icon for a translation that does not exist. You can click any icon to go directly to the Media/Edit Media screen for that translation. If you click a plus icon, a new translation will be created and initialized with content and terms from the current item and you will go to the Media/Edit Media screen for the new translation.

When Polylang is active, several additional features are available:

A Language dropdown control is added to the Quick Edit and Bulk Edit areas. You can change the language of one or more items by selecting a new value in the dropdown and clicking Update. The new language must not have an exising translation; if a translation already exists the change will be ignored.
Translation status links are added to the Quick Edit area, just below the Language dropdown control. If you click one of the pencil/plus translation status links, a new Quick Edit area will open for the translation you selected. A new translation is created if you click a plus status icon.
A Quick Translate rollover action can be added to each item (the default option setting is “unchecked”). If you activate this option, when you click the “Quick Translate” rollover action for an item the Quick Translate area opens, showing the Language dropdown control and the translation status links. From there, click “Set Language” to change the language assigned to the item or click one of the pencil/plus translation status links. A new Quick Edit area will open for the translation you selected. A new translation is created if you click a plus status icon.
A Translate action is added to the Bulk Actions dropdown control. If you click the box next to one or more items, select Translate in the Bulk Actions dropdown and click Apply, the Bulk Translate area will open. The center column contains a checkbox for each active language and an “All Languages” checkbox. Check the box(es) for the languages you want and then click “Bulk Translate”. The Media/Assistant submenu table will be refreshed to display only the items you selected in the language(s) you selected. Existing translations will be displayed, and new translations will be created as needed so every item has a translation in every language selected.

Term Management

Taxonomy terms are language-specific, and making sure the right terms are assigned to all items and translations can be a challenge. Terms can change when an item is updated in any of five ways:

Individual edit – this is the full-screen Media/Edit Media submenu provided by WordPress. Taxonomies are displayed and updated in meta boxes along the right side of the screen. When “Update” is clicked whatever terms have been selected/entered are assigned to the item; they replace any old assignments.
Media Manager Modal Window – this is the popup window provided by WordPress’ “Add Media” and “Select Featured Image” features. Taxonomies are displayed and updated in the ATTACHMENT DETAILS meta boxes along the right side of the window. Whatever terms are selected/entered here are assigned to the item; they replace any old assignments.
Quick Edit – this is a row-level action on the Media/Assistant screen. When “Update” is clicked whatever terms have been selected/entered are assigned to the item; they replace any old assignments.
Bulk edit – this is a bulk action on the Media/Assistant screen, and is also available on the Media/Upload New Media screen. In the Bulk Edit area, terms can be added or removed or all terms can be replaced. The bulk edit can be applied to multiple item translations in one or more languages.
IPTC/EXIF Metadata Mapping – this is done by defining rules in the “Taxonomy term mapping” section of the IPTC & EXIF Processing Options. The mapping rules can be run when new items are added to the Media Library, from the Settings/Media Library Assistant IPTC/EXIF tab, from the Media/Assistant Bulk Edit area or from the Media/Edit Media submenu screen.

When terms change in any of the above ways there are two tasks that require rules:

How should language-specific terms be assigned to items selected? This is “Term Assignment”.
How should terms assigned to one translation of an item be used to update other translations of the same item? This is “Term Synchronization”.

The Media Manager popup modal window showing additional filters for date and taxonomy terms. Also shows the enhanced Search Media box and the full-function taxonomy support in the ATTACHMENT DETAILS area.Contributors & Developers

FAQ
- How can I sort the Media/Assistant submenu table on values such as File Size?
  
  You can add support for many attachment metadata values such as file size by visiting the Custom Fields tab on the Settings page. There you can define a rule that maps the data to a WordPress custom field and check the “MLA Column” box to make that field a sortable column in the Media/Assistant submenu table. You can also use the field in your - mla_gallery - shortcodes. For example, this shortcode displays a gallery of the ten largest images in the “general” category, with a custom caption:
  
  `[ mla_gallery category="general" mla_caption="{+caption+}
  {+custom:File Size+}" meta_key="File Size" orderby="meta_value" order="DESC" numberposts=10 ]
How can I use Categories, Tags and custom taxonomies to select images for display in my posts and pages?

The powerful [mla_gallery] shortcode supports almost all of the query flexibility provided by the WP_Query class. You can find complete documentation in the Settings/Media Library Assistant Documentation tab. A simple example is in the preceding question. Here’s an example that displays PDF documents with Att. Category “fauna” or Att. Tag “animal”:
```
&#91;mla_gallery post_mime_type="application/pdf" size=icon mla_caption="{+title+}" tax_query="array(array('taxonomy'=>'attachment_category','field'=>'slug','terms'=>'fauna'),array('taxonomy'=>'attachment_tag','field'=>'slug','terms'=>'animal'),'relation'=>'OR')"&#93;
```
Can I use mla_gallery for attachments other than images?

Yes! The mla_gallery shortcode supports all MIME types when you add the post_mime_type parameter to your query. You can build a gallery of your PDF documents, plain text files and other attachments. You can mix images and other MIME types in the same gallery, too. Here’s an example that displays a gallery of PDF documents, using Imagick and Ghostscript to show the first page of each document as a thumbnail:
```
&#91;mla_gallery post_mime_type=application/pdf post_parent=all link=file mla_viewer=true columns=1 orderby=date order=desc&#93;
```
Can I attach an image to more than one post or page?

No; that’s a structural limitation of the WordPress database. However, you can use Categories, Tags and custom taxonomies to organize your images and associate them with posts and pages in any way you like. The [mla_gallery] shortcode makes it easy. You can also use the ids= parameter to compose a gallery from a list of specific images.
Can the Assistant use the standard WordPress post Categories and Tags?

Yes! You can activate or deactivate support for Categories and Tags at any time by visiting the Media Library Assistant Settings page.
Do I have to use the WordPress post Categories and Tags?

No! The Assistant supplies pre-defined Att. Categories and Att. Tags; these are WordPress custom taxonomies, with all of the API support that implies. You can activate or deactivate the pre-defined taxonomies at any time by visiting the Media Library Assistant Settings page.
Can I add my own custom taxonomies to the Assistant?

Yes. Any custom taxonomy you register with the Attachment post type will appear in the Assistant UI. Use the Media Library Assistant Settings page to add support for your taxonomies to the Assistant UI.
Can I use Jetpack Tiled Gallery or a lightbox plugin to display my gallery?

You can use other gallery-generating shortcodes to give you the data selection power of [mla_gallery] and the formatting/display power of popular alternatives such as the WordPress.com Jetpack Carousel and Tiled Galleries modules. Any shortcode that accepts “ids=” or a similar parameter listing the attachment ID values for the gallery can be used. Here’s an example of a Jetpack Tiled gallery for everything except vegetables:
```
&#91;mla_gallery attachment_category=vegetable tax_operator="NOT IN" mla_alt_shortcode=gallery type="rectangular"&#93;
```
Most lightbox plugins use HTML class= and/or rel= tags to activate their features.[mla_gallery` lets you add this tag information to your gallery output. Here’s an example that opens PDF documents in a shadowbox using Easy Fancybox:
```
&#91;mla_gallery post_mime_type=application/pdf post_parent=all link=file size=icon mla_caption='<a class="fancybox-iframe fancybox-pdf" href={+filelink_url+} target=_blank>{+title+}</a>' mla_link_attributes='class="fancybox-pdf fancybox-iframe"'&#93;
```
Why don’t the “Posts” counts in the taxonomy edit screens match the search results when you click on them?

This is a known WordPress problem with multiple support tickets already in Trac, e.g.,
Ticket #20708(closed defect (bug): duplicate) Wrong posts count in taxonomy table,
Ticket #14084(assigned defect (bug)) Custom taxonomy count includes draft & trashed posts,
and Ticket #14076(closed defect (bug): duplicate) Misleading post count on taxonomy screen.

For example, if you add Tags support to the Assistant and then assign tag values to your attachments, the “Posts” column in the “Tags” edit screen under the Posts admin section includes attachments in the count. If you click on the number in that column, only posts and pages are displayed. There are similar issues with custom post types and taxonomies (whether you use the Assistant or not). The “Attachments” column in the edit screens added by the Assistant shows the correct count because it works in a different way.
How do I “unattach” an item?

Hover over the item you want to modify and click the “Edit” or “Quick Edit” action. Set the ID portion of the Parent Info field to zero (0), then click “Update” to record your changes. If you change your mind, click “Cancel” to return to the main page without recording any changes. You can also click the “Select” button to bring up a list of posts//pages and select one to be the new parent for the item. The “Set Parent” link in the Media/Assistant submenu table also supports changing the parent and unattaching an item.
The Media/Assistant submenu seems sluggish; is there anything I can do to make it faster?

Some of the MLA features such as where-used reporting and ALT Text sorting/searching require a lot of database processing. If this is an issue for you, go to the Settings page and adjust the “Where-used database access tuning” settings. For any where-used category you can enable or disable processing. For the “Gallery in” and “MLA Gallery in” you can also choose to update the results on every page load or to cache the results for fifteen minutes between updates. The cache is also flushed automatically when posts, pages or attachments are inserted or updated.
Do custom templates and option settings survive version upgrades?

Rest assured, custom templates and all of your option settings persist unchanged whenever you update to a new MLA version.

You can also back a backup of your templates and settings from the Settings/Media Library Assistant General tab. Scroll to the bottom of the page and click “Export ALL Settings” to create a backup file. You can create as many files as you like; they are date and time stamped so you can restore the one you want later.

In addition, you can deactivate and even delete the plugin without losing the settings. They will be there when you reinstall and activate in the future.

You can permanently delete the settings and (optionally) the backup files if you are removing MLA for good. The “Uninstall (Delete)” Plugin Settings section of the General tab enables these options.
Are other language versions available?

Not many, but all of the internationalization work in the plugin source code has been completed and there is a Portable Object Template (.POT) available in the “/languages” directory. I don’t have working knowledge of anything but English, but if you’d like to volunteer to produce a translation, I would be delighted to work with you to make it happen. Have a look at the “MLA Internationalization Guide.pdf” file in the languages directory and get in touch.
What’s in the “phpDocs” directory and do I need it?

All of the MLA source code has been annotated with “DocBlocks”, a special type of comment used by phpDocumentor to generate API documentation. If you’d like a deeper understanding of the code, navigate to the [MLA phpDocs web page](http://davidlingren.com/assets/phpDocs/index.html) and have a look. Note that these pages require JavaScript for much of their functionality.

Screenshots

The Media/Assistant submenu table showing the available columns, including "Featured in", "Inserted in", "Att. Categories" and "Att. Tags"; also shows the Quick Edit area.

The Media/Assistant submenu table showing the Bulk Edit area with taxonomy Add, Remove and Replace options; also shows the tags suggestion popup.

A typical edit taxonomy page, showing the "Attachments" column.

The enhanced Edit page showing additional fields, categories and tags.

The Settings page General tab, where you can customize support of Att. Categories, Att. Tags and other taxonomies, where-used reporting and the default sort order.

The Settings page MLA Gallery tab, where you can add custom style and markup templates for [mla_gallery] shortcode output.

The Settings page IPTC & EXIF Processing Options screen, where you can map image metadata to standard fields (e.g. caption), taxonomy terms and custom fields.

The Settings page Custom Field Processing Options screen, where you can map attachment metadata to custom fields for display in [mla_gallery] shortcodes and as sortable, searchable columns in the Media/Assistant submenu.

SUPPORT FOR THE “ADMIN COLUMNS” PLUGIN

The [Admin Columns plugin](https://wordpress.org/plugins/codepress-admin-columns/) allows you to customize columns on several admin-mode screens, including the MLA Media/Assistant submenu screen. All you have to do is install the plugin; MLA will detect its presence and automatically register the Media/Assistant submenu screen for support. With Admin Columns, you can:

Reorder columns with a simple drag & drop interface.
Re-size columns to give more or less space to a column.
Remove (not just hide) columns from the submenu table.
Add new columns for custom fields and additional information.
The Admin Columns “Pro” version adds support for ACF fields and other capabilities.

When Admin Columns is present you will see a new “Edit Columns” button just above the Media/Assistant submenu table. Click the button to go to the Settings/Admin Columns configuration screen. There you will see “Media Library Assistant” added to the “Others:” list. Click on it to see the configuration of the Media/Assistant submenu screen.

You can find detailed configuration instructions at the [Admin Columns web site Documentation page](http://admincolumns.com/documentation/).

When you have completed your configuration changes, click “Update Media Library Assistant” in the Store Settings metabox at the top-right of the screen. You can also click “Restore Media Library Assistant columns” to remove your changes and go back to the MLA default settings. Click the “View” button at the right of the Media Library Assistant heading to return to the Media/Assistant submenu screen and see your changes.

WPML & POLYLANG MULTILINGUAL SUPPORT; THE MLA LANGUAGE TAB

Media Library Assistant provides integrates support for two popular “Multilanguage/ Multilingual/ Internationalization” plugins; [WPML](https://wpml.org/) and [Polylang](https://wordpress.org/plugins/polylang/). These plugins let you write posts and pages in multiple languages and make it easy for a visitor to select the language in which to view your site. MLA works with the plugins to make language-specific Media library items easy to create and manage.

MLA detects the presence of either plugin and automatically adds several features that work with them:

Language-specific filtering of the [mla_gallery] and [mla_tag_cloud] shortcodes.
Media/Assistant submenu table enhancements for displaying and managing item translations.
Term Assignment and Term Synchronization, to match terms to language-specific items and automatically keep all translations for an item in synch.
Term Mapping Replication, to manage the terms created when mapping taxonomy terms from IPTC/EXIF metadata.

“Media Library Assistant” is open source software. The following people have contributed to this plugin.

ACKNOWLEDGEMENTS

Media Library Assistant includes many images drawn (with permission) from the [Crystal Project Icons](http://www.softicons.com/free-icons/system-icons/crystal-project-icons-by-everaldo-coelho), created by [Everaldo Coelho](http://www.everaldo.com/), founder of [Yellowicon](http://www.yellowicon.com/).

Many thanks to Aurovrata Venet, Il’ya Karastel and Kristian Adolfsson for testing and advising on the multilingual support features!

Field-level Substitution Parameters

Field-level substitution parameters let you access query arguments, custom fields, taxonomy terms and attachment metadata for display in an MLA gallery or in an MLA tag cloud. You can also use them in IPTC/EXIF or Custom Field mapping rules. For field-level parameters, the value you code within the surrounding the ('[+' and '+]' or '{+' and '+}') delimiters has three parts; the prefix, the field name (or template content) and, if desired, an option/format value.

prefix defines which type of field-level data you are accessing. It must immediately follow the opening ('[+' or '{+') delimiter and end with a colon (':'). There can be no spaces in this part of the parameter.

field name

defines which field-level data element you are accessing. It must immediately follow the colon (':'). There can be no spaces between the colon and the field name. Spaces are allowed within the field name to accommodate custom field names that contain them.

Compound names are used to access elements within arrays, e.g., sizes.thumbnail.file is used to specify the file name for the thumbnail version of an image. You can also use a "*" placeholder to denote "all elements at this level" and return an array of lower-level elements. For example, you can code sizes.*.file to return an array of file names for all of the image's intermediate sizes.

For the "template" prefix, the field name is replaced by the template content; see the Content Templates section for details.

option/format value if present, immediately follows the field name using a comma (,) separator and ends with the closing delimiter ('+]' or '+}'). There can be no spaces in this part of the parameter.

The next sections define each of the prefix and option/format values.

Prefix values

There are fourteen prefix values for field-level parameters. Prefix values must be coded as shown; all lowercase letters.

request The parameters defined in the $_REQUEST array; the "query strings" sent from the browser. The PHP $_REQUEST variable is a superglobal Array that contains the contents of both $_GET, $_POST and $_COOKIE arrays. It can be used to collect data sent with both the GET and POST methods. For example, if the URL is http://www.mysite.com/mypage?myarg=myvalue you can access the query string as [+request:myarg+], which has the value "myvalue".

query The parameters defined in the [mla_gallery] shortcode. For example, if your shortcode is [mla_gallery attachment_tag=my-tag div-class=some_class] you can access the parameters as [+query:attachment_tag+] and [+query:div-class+] respectively. Only the parameters actually present in the shortcode are accessible; default values for parameters not actually present are not available. You can define your own parameters, e.g., "div-class"; they will be accessible as field-level data but will otherwise be ignored.

custom

WordPress Custom Fields, which you can define and populate on the Edit Media screen or map from various sources on the Settings/Media Library Assistant Custom and IPTC/EXIF tabs. The field name, or key, can contain spaces and some punctuation characters. You cannot use the plus sign ('+') in a field name you want to use with [mla_gallery]. Custom field names are case-sensitive; "client" and "Client" are not the same.

For custom fields only, the ",raw" option bypasses the code to sanitize the returned value. Use this option to allow HTML tags to be returned from a custom field.

One special custom "pseudo-value" is available; ALL_CUSTOM ([+custom:ALL_CUSTOM+]). This returns a string representation of all custom field values. You can use this pseudo-values to quickly examine which fields are populated for a given Media Library item and what its values are.

The ALL_CUSTOM value is altered in two ways. First, values of more than 256 characters are truncated to 256 characters. This prevents large fields from dominating the display. Second, array values are shown '(ARRAY)'.

terms

WordPress Category, tag or custom taxonomy terms. For this category, you code the name of the taxonomy as the field name. The term(s) associated with the attachment will be displayed in the [mla_gallery]. Note that you must use the name/slug string for taxonomy, not the "title" string. For example, use "attachment_category" or "attachment_tag", not "Att. Category" or "Attachment Category".

You can change the term field by adding the field name in parentheses after the taxonomy name. For example, [+terms:attachment_category(slug)+] or [+terms:attachment_category(term_id)+].

You can access fields from a specific term, independent of terms assigned to an item, with a compound name. Append the term slug to the taxonomy slug separated by a period ("."), e.g. [+terms:attachment_category.my-term(term_id)+].

Field-level option/format values

You can use a field-level option or format value to specify the treatment of fields with multiple values or to change the format of a field for display/mapping purposes. If no option/format value is present, fields with multiple values are formatted as a comma-delimited text list. The option/format value, if present, immediately follows the field name using a comma (,) separator and ends with the closing delimiter ('+]' or '+}'). There can be no spaces in this part of the parameter.

Three "option" values change the treatment of fields with multiple values:

,single	If this option is present, only the first value of the field will be returned. Use this option to limit the data returned for a custom field, taxonomy or metadata field that can have many values. For example, if you code `[+meta:sizes.thumbnail,single+]` the result will be "20120313-ASK_5605-150x150.jpg".
,export	If this option is present, the PHP `var_export` function is used to return a string representation of all the elements in an array field. For example, if you code `[+meta:sizes.thumbnail,export+]` the result will be "array ('file' => '20120313-ASK_5605-150x150.jpg', 'width' => 150, 'height' => 150, 'mime-type' => 'image/jpeg', )".
,unpack	If this option is present, the top-level elements in an array field will be expanded; lower-level arrays will be denoted by a placeholder. For example, if you code `[+meta:sizes,unpack+]` the result will be "array ( 'thumbnail' => '(ARRAY)', 'medium' => '(ARRAY)', 'large' => '(ARRAY)', 'post-thumbnail' => '(ARRAY)', )".

Eight "format" values help you reformat fields or encode them for use in HTML attributes and tags:

,raw	If you want to avoid filtering a value through the WordPress `sanitize_text_field()` function you can add the ",raw" option. This is helpful when, for example, you are using a field that contains HTML markup such as a hyperlink.
,commas	For numeric data source parameters such as "file_size" you can add the ",commas" option to format the value for display purposes.
,attr	If you use a substitution parameter in an HTML attribute such as the `title` attribute of a hyperlink (`a`) or `img` tag you can add the ",attr" option to encode the <, >, &, " and ' (less than, greater than, ampersand, double quote and single quote) characters.
,url	If you use a substitution parameter in an HTML `href` attribute such as a hyperlink (`a`) or `img` tag you can add the ",url" option to convert special characters such as quotes, spaces and ampersands to their URL-encoded equivalents.
,substr(s,l)	If you need to limit the length of a value or extract a portion of it the ",substr" option will return part of the value. This option accepts one or two parameters, "start" (s) and "length" (l). The first character in the value is at position zero (0) so, for example, ",substr(2,3)" would return "cde" from a value of "abcdef". You can find complete information on "start" and "length", including the effect of negative values, at: http://php.net/manual/en/function.substr.php.
,str_replace(s,r)	Replace all occurrences of the "search" string (s) with the "replacement" string (r). If search and replacement are arrays, then str_replace() takes a value from each array and uses them to search and replace on subject. If replace has fewer values than search, then an empty string is used for the rest of replacement values. If search is an array and replace is a string, then this replacement string is used for every value of search. You can find complete information on "search" and "replacement", including examples, at: http://php.net/manual/en/function.str-replace.php. To specify an array argument enclose the argument in braces ( "{" and "}" ) and separate elements with spaces. For example, `,str_replace( {',' '-'}, {' ' '_'} )` will change commas to spaces and dashes to underscores, while `,str_replace( {',' '-'}, ' ' )` will change both commas and dashes to spaces.
,kbmb(t,k,m,p)	Some data values, e.g., file size, are better expressed in kilobytes and megabytes. The "kbmb" format provides this conversion. There are four optional arguments; "t" (threshold), "k" (kilobyte suffix), "m" (megabyte suffix) and "p" (precision). The threshold argument (default 10240; ten kilobytes) sets the dividing amount between bytes and kilobytes. For example, a value of 1536 bytes would display as "1,536", not "1.50 KB" and 15360 bytes would display as "15.5 KB". The "k" and "m" arguments replace the default " KB" and/or " MB" suffix displayed following the numeric value. The "p" argument is the number of decimal places in the result, e.g., a value of 287,709 with a threshold of 1024 displays as "281", "281.0", "280.97", "280.966", or "280.9658" for precisions 0, 1, 2, 3 and 4.
,fraction(f,s)	Many of the EXIF metadata fields are expressed as "rational" quantities, i.e., separate numerator and denominator values separated by a slash. For example, `[+exif:ExposureTime+]` can be expressed as "1/200" seconds. The "fraction" format converts these to a more useful format. There two optional arguments; "f" (format_string)and "s" (show_fractions). The "format_string" (default "2") can either be the number of decimal places desired or a sprintf()-style format specification. For example, `[+exif:ExposureTime,fraction(4)+]` will display 7/6 as "+1.1667". A format specification such as '%1$.2f' will display 7/6 as "1.17". Numbers between -1 and +1, i.e. true fractions, will display in their original form, e.g., "1/6". If the optional "show_fractions" (default true) argument is "false" fractional values will convert to a decimal equivalent. For example, fraction(4,false) will display 1/6 as "+0.1667", and `[+exif:ExposureTime,fraction( '%1$.2f', false )+]` will display 1/6 as "0.17".
,timestamp(f,m)	Many date and time values such as `[+meta:image_meta.created_timestamp+]` are stored as a UNIX timestamp. The ",timestamp" format converts a timestamp into a variety of date and/or time string formats, using the PHP date() function. Details on the "f" (format string) argument can be found at: http://php.net/manual/en/function.date.php. The default format string is "d/m/Y H:i:s", e.g., "31/12/2014 23:59:00" (just before midnight on new year's eve). You could code `[+meta:image_meta.created_timestamp,timestamp('j F, Y')+]` to display "31 December, 2014". The "m" (modifier) argument is optional. If present and set to "i18n" the displayed value will be localized using the site's locale value. If the "m" (modifier) argument is set to "age" it will return a human-readable difference between the source value and the current date/time. In this case you must also code "%s" in the format string, e.g., `[+meta:image_meta.created_timestamp,timestamp('%s ago')+]` to display something like "2 months ago".
,date(f,m)	Many EXIF date and time values such as DateTimeOriginal and DateTimeDigitized are stored as strings with a format of "YYYY:MM:DD HH:MM:SS". You can parse this format and just about any English textual datetime description into a Unix timestamp, then format the result by using the ",date" format. This format first uses the PHP strtotime() function, then the date() function. The "Supported Date and Time Formats" can be found at: http://php.net/manual/en/datetime.formats.php. The default "f" (format string) argument is "d/m/Y H:i:s", e.g., "31/12/2014 23:59:00" (just before midnight on new year's eve). You could code `[+exif:DateTimeOriginal,date('j F, Y')+]` to display "31 December, 2014". The "m" (modifier) argument is optional. If present and set to "i18n" the displayed value will be localized using the site's locale value. If the "m" (modifier) argument is set to "age" it will return a human-readable difference between the source value and the current date/time. In this case you must also code "%s" in the format string, e.g., `[+exif:DateTimeOriginal,date('%s ago')+]` to display something like "2 months ago".

Three values let you use powerful regular expressions to apply patterns to any data source, extracting or replacing pieces of it. These three values are explained in detail, with examples, in the Regular Expression Features section below. They are:

,match(p)	This format/option value looks for a match of its pattern (and optional subpatterns) in the data source. If a match is found, that portion of the data source is returned. If the pattern is not matched an empty value is returned. Any pattern or subpattern matches found are stored for later access using the "matches:" prefix.
,extract(p,v)	This format/option value looks for a match of its pattern (and optional subpatterns) (the p paremeter) in the data source. Any pattern or subpattern matches found are stored for later access using the "matches:" prefix. An empty value is returned by default but this can be changed with the optional second (v) parameter.
,replace(p,r,v)	This format/option value looks for a match of its pattern (p) (and optional subpatterns) in the data source. By default, if a match is found, the replacement (r) pattern is used to return a modified version of the data source. If the pattern is not matched the original data source value is returned. The default can be changed with the optional third (v) parameter.

Go to Top

Field-level data sources

Each Media Library attachment item has a row in the "posts" database table that records information such as the Title, Author and Parent post/page. It also has an "attached file" with attributes like the file name and file size. All of this information and more is available as "field-level data sources" that can be used for [mla_gallery] or mapping purposes. The data sources are:

post_id, ID	the value stored in the attachment's "posts" database row.
post_author	the value stored in the attachment's "posts" database row.
post_date	the value stored in the attachment's "posts" database row.
post_date_gmt	the value stored in the attachment's "posts" database row.
post_content	the value stored in the attachment's "posts" database row.
post_title	the value stored in the attachment's "posts" database row.
post_excerpt	the value stored in the attachment's "posts" database row.
post_status	the value stored in the attachment's "posts" database row.
comment_status	the value stored in the attachment's "posts" database row.
ping_status	the value stored in the attachment's "posts" database row.
post_name	the value stored in the attachment's "posts" database row.
post_modified	the value stored in the attachment's "posts" database row.
post_modified_gmt	the value stored in the attachment's "posts" database row.
post_content_filtered	the value stored in the attachment's "posts" database row.
parent, post_parent	the value stored in the attachment's "posts" database row.
guid	the value stored in the attachment's "posts" database row.
menu_order	the value stored in the attachment's "posts" database row.
mime_type, post_mime_type	the value stored in the attachment's "posts" database row.
comment_count	the value stored in the attachment's "posts" database row.
alt_text	ALT text, for image types. If there are multiple values (unlikely) they will be returned as a comma-separated list. You can use the ",single" or ",export" option values to change that.
site_url	absolute URL to the site directory, without trailing slash.
base_url	absolute URL to the upload directory, without trailing slash.
base_dir	absolute (full) path to the upload directory, without trailing slash.
absolute_path	complete path portion of the attachment file, e.g., C:/site/wordpress/wp-content/uploads/2012/11/
absolute_file_name	complete path and file name of the attachment file, e.g., C:/site/wordpress/wp-content/uploads/2012/11/filename.ext
base_file	relative path (within uploads directory) and file name of the attachment file, e.g., 2012/11/image.jpg
path	path portion of the base_file value, e.g., 2012/11/
file_name	file name and extension portion of the base_file value, e.g., image.jpg
name_only	file name portion of the base_file value, e.g., image
extension	extension portion of the base_file value, e.g., jpg
file_size	file size in bytes
upload_date	date and time attachment was added to the Media Library
dimensions	for image types, width x height, e.g., 1024x768
pixels	for image types, size in pixels, e.g., 307200 for a 640x480 image
width	for image types, width in pixels
height	for image types, height in pixels
orientation	"portrait" (height > width) or "landscape", for image types; empty for non-image types
hwstring_small	HTML dimensions of a "small" image, i.e., 128 or less width, 96 or less height. Not computed for images uploaded in WordPress 3.5 and later.
size_keys	image size names for thumbnail versions of the image, e.g., "thumbnail, medium, large"
size_names	image file names for thumbnail versions of the image, e.g., "image-150x150.jpg, image-300x225.jpg, image-600x288.jpg"
size_bytes	file size in bytes for thumbnail versions of the image, e.g., "5127, 11829, 33968"
size_pixels	image size in pixels for thumbnail versions of the image, e.g., "22500, 67500, 172800"
size_dimensions	image dimensions for thumbnail versions of the image, e.g., "150x150, 300x225, 600x288"
size_name[size]	image file name for a specific thumbnail version, e.g., size_name[medium] = "image-300x225.jpg"; set to empty string if the specified size does not exist. There will be a [size] choice for every thumbnail version registered with WordPress for the site.
size_bytes[size]	file size in bytes for a specific thumbnail version, e.g., size_bytes[medium] = "11829"
size_pixels[size]	image size in pixels for a specific thumbnail version, e.g., size_pixels[medium] = "67500"
size_dimensions[size]	image dimensions for a specific thumbnail version, e.g., size_dimensions[medium] = "300x225"; set to empty string if the specified size does not exist. There will be a [size] choice for every thumbnail version registered with WordPress for the site.
parent_date	for "attached" (post_parent not zero) objects, "published on" date of the parent object
parent_type	for "attached" (post_parent not zero) objects, post type of the parent object
parent_title	for "attached" (post_parent not zero) objects, post title of the parent object
parent_issues	summary of parent status (only) "issues", e.g., bad parent, invalid parent, unattached
reference_issues	summary of all reference and parent status "issues", e.g., orphan, bad parent, invalid parent, unattached
featured_in	the title, post/page type and id number of each post/page for which this item is the "featured image"
featured_in_title	the title of each post/page for which this item is the "featured image"
inserted_in	the title, post/page type and id number of each post/page where this item is inserted in the post/page content
inserted_in_title	the title of each post/page where this item is inserted in the post/page content
gallery_in	the title, post/page type and id number of each post/page where this item appears in a [gallery] shortcode
gallery_in_title	the title of each post/page where this item appears in a [gallery] shortcode
mla_gallery_in	the title, post/page type and id number of each post/page where this item appears in an `[mla_gallery]` shortcode
mla_gallery_in_title	the title of each post/page where this item appears in an `[mla_gallery]` shortcode
aperture	for image types, the value stored in WordPress "image_meta" array
credit	for image types, the value stored in WordPress "image_meta" array
camera	for image types, the value stored in WordPress "image_meta" array
caption	for image types, the value stored in WordPress "image_meta" array
created_timestamp	for image types, the value stored in WordPress "image_meta" array
copyright	for image types, the value stored in WordPress "image_meta" array
focal_length	for image types, the value stored in WordPress "image_meta" array
iso	for image types, the value stored in WordPress "image_meta" array
shutter_speed	for image types, the value stored in WordPress "image_meta" array
title	for image types, the value stored in WordPress "image_meta" array

Go to Top

Field-level IPTC Identifiers and Friendly Names

IPTC Photo Metadata provides data about photographs and the values can be processed by software. Each individual metadata entity is called a property and they are grouped into Administrative, Descriptive and Rights-related properties. IPTC Photo Metadata properties have photo specific definitions that are widely supported by imaging software. You can find complete documentation of IPTC properites at the IPTC Photo Metadata Standard 2019.1 web site.

The IPTC specification defines all of the allowed fields and organizes them into "Records" and "DataSets" (fields). When you use the "iptc:" prefix to source a field-level substitution parameter you can specify the field you want in either of two ways. First you can use the Record number and DataSet tag, such as "2#005" for Record 2, DataSet 005; this is the "Object Name" DataSet. Second, you can use the Friendly Name, such as "object-name". The MLA Friendly Name values differ in some cases from the names in the IPTC specification but the table below should be easy to follow.

Envelope Record
model-version	1#000	2 octet binary IIM version number
destination	1#005	Max 1024 characters of Destination (ISO routing information); repeatable
file-format	1#020	2 octet binary file format number, see IPTC-NAA V4 Appendix A
file-format-version	1#022	2 octet binary file format version number
service-identifier	1#030	Max 10 characters of Service Identifier and product
envelope-number	1#040	8 Character Envelope Number
product-id	1#050	Max 32 characters subset of provider's overall service; repeatable
envelope-priority	1#060	1 numeric character of envelope handling priority (not urgency)
date-sent	1#070	8 numeric characters of Date Sent by service - CCYYMMDD
time-sent	1#080	11 characters of Time Sent by service - HHMMSS±HHMM
coded-character-set	1#090	Max 32 characters of control functions, etc.
uno	1#100	14 to 80 characters of eternal, globally unique identification for objects
arm-identifier	1#120	2 octet binary Abstract Relationship Model Identifier
arm-version	1#122	2 octet binary Abstract Relationship Model Version
Application Record
record-version	2#000	2 octet binary Information Interchange Model, Part II version number
object-type-reference	2#003	3 to 67 Characters of Object Type Reference number and optional text
object-attribute-reference	2#004	3 to 67 Characters of Object Attribute Reference number and optional text; repeatable
object-name	2#005	Max 64 characters of the object name or shorthand reference
edit-status	2#007	Max 64 characters of the status of the objectdata
editorial-update	2#008	2 numeric characters of the type of update this object provides
urgency	2#010	1 numeric character of the editorial urgency of content
subject-reference	2#012	13 to 236 characters of a structured definition of the subject matter; repeatable
category	2#015	Max 3 characters of the subject of the objectdata, DEPRECATED
supplemental-category	2#020	Max 32 characters (each) of further refinement of subject, DEPRECATED; repeatable
fixture-identifier	2#022	Max 32 characters identifying recurring, predictable content
keywords	2#025	Max 64 characters (each) of tags; repeatable
content-location-code	2#026	3 characters of ISO3166 country code or IPTC-assigned code; repeatable
content-location-name	2#027	Max 64 characters of publishable country/geographical location name; repeatable
release-date	2#030	8 numeric characters of Release Date (earliest use) - CCYYMMDD
release-time	2#035	11 characters of Release Time (earliest use) - HHMMSS±HHMM
expiration-date	2#037	8 numeric characters of Expiration Date (latest use) - CCYYMDD
expiration-time	2#038	11 characters of Expiration Time (latest use) - HHMMSS±HHMM
special-instructions	2#040	Max 256 Characters of editorial instructions, e.g., embargoes and warnings
action-advised	2#042	2 numeric characters of type of action this object provides to a previous object
reference-service	2#045	Max 10 characters of the Service ID (1#030) of a prior envelope; repeatable
reference-date	2#047	8 numeric characters of prior envelope Reference Date (1#070) - CCYYMMDD; repeatable
reference-number	2#050	8 characters of prior envelope Reference Number (1#040); repeatable
date-created	2#055	8 numeric characters of intellectual content Date Created - CCYYMMDD
time-created	2#060	11 characters of intellectual content Time Created - HHMMSS±HHMM
digital-creation-date	2#062	8 numeric characters of digital representation creation date - CCYYMMDD
digital-creation-time	2#063	11 characters of digital representation creation time - HHMMSS±HHMM
originating-program	2#065	Max 32 characters of the program used to create the objectdata
program-version	2#070	Program Version - Max 10 characters of the version of the program used to create the objectdata
object-cycle	2#075	1 character where a=morning, p=evening, b=both
by-line	2#080	Max 32 Characters of the name of the objectdata creator, e.g., the writer, photographer; repeatable
by-line-title	2#085	Max 32 characters of the title of the objectdata creator; repeatable
city	2#090	Max 32 Characters of the city of objectdata origin
sub-location	2#092	Max 32 Characters of the location within the city of objectdata origin
province-or-state	2#095	Max 32 Characters of the objectdata origin Province or State
country-or-primary-location-code	2#100	3 characters of ISO3166 or IPTC-assigned code for Country of objectdata origin
country-or-primary-location-name	2#101	Max 64 characters of publishable country/geographical location name; repeatable
original-transmission-reference	2#103	Max 32 characters of a code representing the location of original transmission
headline	2#105	Max 256 Characters of a publishable entry providing a synopsis of the contents of the objectdata
credit	2#110	Max 32 Characters that identifies the provider of the objectdata (Vs. the owner/creator)
source	2#115	Max 32 Characters that identifies the original owner of the intellectual content
copyright-notice	2#116	Max 128 Characters that contains any necessary copyright notice
contact	2#118	Max 128 characters that identifies the person or organization which can provide further background information; repeatable
caption-or-abstract	2#120	Max 2000 Characters of a textual description of the objectdata
caption-writer-or-editor	2#122	Max 32 Characters that the identifies the person involved in the writing, editing or correcting the objectdata or caption/abstract; repeatable
rasterized-caption	2#125	7360 binary octets of the rasterized caption - 1 bit per pixel, 460x128-pixel image
image-type	2#130	2 characters of color composition type and information
image-orientation	2#131	1 alphabetic character indicating the image area layout - P=portrait, L=landscape, S=square
language-identifier	2#135	2 or 3 alphabetic characters containing the major national language of the object, according to the ISO 639:1988 codes
audio-type	2#150	2 characters identifying monaural/stereo and exact type of audio content
audio-sampling-rate	2#151	6 numeric characters representing the audio sampling rate in hertz (Hz)
audio-sampling-resolution	2#152	2 numeric characters representing the number of bits in each audio sample
audio-duration	2#153	6 numeric characters of the Audio Duration - HHMMSS
audio-outcue	2#154	Max 64 characters of the content of the end of an audio objectdata
objectdata-preview-file-format	2#200	2 octet binary file format of the ObjectData Preview
objectdata-preview-file-format-version	2#201	2 octet binary particular version of the ObjectData Preview File Format
objectdata-preview-data	2#202	Max 256000 binary octets containing the ObjectData Preview data
Pre ObjectData Descriptor Record
size-mode	7#010	1 numeric character - 0=objectdata size not known, 1=objectdata size known at beginning of transfer
max-subfile-size	7#020	4 octet binary maximum subfile dataset(s) size
objectdata-size-announced	7#090	4 octet binary objectdata size if known at beginning of transfer
maximum-objectdata-size	7#095	4 octet binary largest possible objectdata size
ObjectData
subfile	8#010	Subfile DataSet containing the objectdata itself; repeatable
Post ObjectData Descriptor Record
confirmed-objectdata-size	9#010	4 octet binary total objectdata size

Go to Top

Field-level enhanced EXIF CAMERA values

The EXIF specification defines many "Tags Relating to Picture-taking Conditions". Some of these are processed by WordPress and added to the "image_meta" array (as aperture, camera, focal_length, iso, shutter_speed). The field-level values in this section supplement those values and provide convenient access to additional values as well.

The native format of this data is somewhat complicated, so MLA converts the most common elements into more convenient formats. For example, "rational" values are expressed as decimal equivalents or converted to forms more often seen in photographic applications. You can use the enhanced values as-is or use them in a Content Template to compose the format(s) you need. You can access the native values with the names defined in the EXIF specification, e.g., "ExposureTime". The enhanced values are provided in the "CAMERA" array and accessed with compound names, e.g., "CAMERA.ExposureTime". The MLA enhanced values are:

Field	Example	Content
ExposureTime	1.04, 1/250	Exposure time, given in seconds.
ShutterSpeed (from ExposureTime)	1.04, 1/250	Derived from ExposureTime and more often converted to the more useful "one over something" format.
FNumber	7.1, 8	The F Number.
ExposureBiasValue	-1, +1/3	The exposure bias. The unit is the APEX value, usually in the range of -99.99 to 99.99.
Flash	no, yes	The "flash fired" portion of the flash status.
FocalLength	420, 500	The actual focal length of the lens, in mm. It is not converted to the focal length of a 35mm film camera.

The EXIF specification defines several "Other Tags" with more information about each image; these tags are not recognized by the PHP exif_read_data() function. The MLA enhanced values for "Other Tags" are:

Field	Example	Content
ImageUniqueID		an identifier assigned uniquely to each image. It is recorded as an ASCII string equivalent to hexadecimal notation and 128-bit fixed length.
CameraOwnerName		records the owner of a camera used in photography as an ASCII string.
BodySerialNumber	6033674	the serial number of the camera body as an ASCII string.
LensSpecification	"80/1, 400/1, 45/10, 56/10"	a four-element array containing minimum focal length, maximum focal length, minimum F number in the minimum focal length and minimum F number in the maximum focal length.
LensMinFocalLength	80	minimum focal length element of the LensSpecification array.
LensMaxFocalLength	400	maximum focal length element of the LensSpecification array.
LensMinFocalLengthFN	4.5	minimum F number in the minimum focal length element of the LensSpecification array.
LensMaxFocalLengthFN	5.6	minimum F number in the maximum focal length element of the LensSpecification array.
LensMake	Canon	the lens manufacturer as an ASCII string.
LensModel	80.0-400.0 mm f/4.5-5.6	the lens's model name and model number as an ASCII string.
LensSerialNumber		the serial number of the interchangeable lens as an ASCII string.

Go to Top

Field-level enhanced EXIF GPS values

There are three basic forms of writing geographic coordinates; they are explained in a Wikipedia article, Geographic coordinate conversion. The Exif Standard version 2.3 (PDF) and Exif Standard version 2.3 (PDF) documents explain the structure and defines the rules for 32 GPS elements.

The native format of this data is somewhat complicated, so MLA converts the most common elements into a variety of convenient formats. You can use the enhanced values as-is or use them in a Content Template to compose the format(s) you need. You can access the native values with the names defined in the EXIF specification, e.g., "GPSLatitude". The enhanced values are provided in th "GPS" array and accessed with compound names, e.g., "GPS.Latitude". The MLA enhanced values are:

Field	Example	Content
Version	2.2.0.0	The version of the GPS Information specification
LatitudeRef	N or S	Indicates whether the latitude is north or south latitude
LatitudeRefS	empty or "-"	Blank for north, "-" for south
Latitude	44d 7' 34.0167" N	Latitude expressed as degrees, minutes and seconds
LatitudeD	44	Degree portion of Latitude
LatitudeM	7	Minute portion of Latitude
LatitudeS	34.0167	Second portion of Latitude
LatitudeSDM	44 7.5669	Latitude expressed as degrees and decimal minutes (MinDec), with a leading "-" for Southern values
LatitudeSDD	44.126116	Latitude expressed as decimal degrees, with a leading "-" for Southern values
LatitudeDM	44 7.5669N	Latitude expressed as degrees and decimal minutes (MinDec)
LatitudeDD	44.126116N	Latitude expressed as decimal degrees
LatitudeMinDec	7.5669	Decimal Minutes portion of Latitude
LatitudeDegDec	.126116	Decimal Degrees portion of Latitude
LongitudeRef	E or W	Indicates whether the Longitude is east or west longitude
LongitudeRefS	empty or "-"	Blank for east, "-" for west
Longitude	145d 5' 9.2055" E	Longitude expressed as degrees, minutes and seconds
LongitudeD	145	Degree portion of Longitude
LongitudeM	5	Minute portion of Longitude
LongitudeS	9.2055	Second portion of Longitude
LongitudeSDM	145 5.1534	Longitude expressed as degrees and decimal minutes (MinDec), with a leading "-" for Western values
LongitudeSDD	145.085890	Longitude expressed as decimal degrees, with a leading "-" for Western values
LongitudeDM	145 5.1534E	Longitude expressed as degrees and decimal minutes (MinDec)
LongitudeDD	145.085890E	Longitude expressed as decimal degrees
LongitudeMinDec	5.1534	Decimal Minutes portion of Longitude
LongitudeDegDec	.085890	Decimal Degrees portion of Longitude
AltitudeRef	0 or 1	0 = above sea level, 1 = below sea level
AltitudeRefS	blank or "-"	Blank above sea level, "-" below sea level
Altitude	247.0825	Altitude in meters
AltitudeFeet	810.64	Altitude in feet
TimeStamp	01:00:34	The time as UTC (Coordinated Universal Time)
TimeStampH	01	The hours portion of TimeStamp
TimeStampM	00	The minutes portion of TimeStamp
TimeStampS	34	The seconds portion of TimeStamp
DateStamp	2013:08:09	The date as UTC (Coordinated Universal Time)
DateStampY	2013	The year portion of DateStamp
DateStampM	08	The month portion of DateStamp
DateStampD	09	The day portion of DateStamp
MapDatum	WGS-84	The geodetic survey data used by the GPS receiver

Go to Top

Field-level metadata in PDF documents

Metadata in PDF documents comes from two sources. Early versions of the PDF specification defined a Document Information Dictionary (D.I.D.) containing up to nine (optional) fields:

Title	The document's title
Author	The name of the person who created the document
Subject	The subject of the document
Keywords	Keywords associated with the document
Creator	If the document was converted to PDF from another format, the name of the application (for example, Adobe FrameMaker®) that created the original document from which it was converted
Producer	If the document was converted to PDF from another format, the name of the application (for example, Acrobat Distiller) that converted it to PDF
CreationDate	The date and time the document was created, in human-readable form
ModDate	The date and time the document was most recently modified, in human-readable form
Trapped	A keyword (True, False, Unknown) indicating whether the document has been modified to include trapping information

More recent versions of the specification add a second source of metadata, Metadata Streams, holding data defined by the Extensible Metadata Platform (XMP) framework. XMP metadata varies from document to document but is often extensive. MLA provides access to this data in four ways:

If a D.I.D. field is not stored in the document, MLA will copy appropriate values from the XMP data into the empty field to populate it as often as possible. For example, the "creator" value(s) in the "dc" namespace ("dc.creator") might be copied to an empty "Author" field, or the "dc.subject" value(s) might be copied to an empty Keywords field.
Additional values in the "xmp", "xmpMM", "xmpRights", "xap", "xapMM", "dc", "pdf" and "pdfx" namespaces are copied up to the root level for easier access. For example, the "pdfx.SourceModified" value can be accessed as "SourceModified", without the "pdfx." portion of the compound name.
Other namespaces in the document are copied to arrays at the root level. For example, some documents contain information in the "photoshop" namespace, such as "photoshop.CaptionWriter" and "photoshop.AuthorsPosition". The native values of some fields, e.g., "dc.creator", can be an array.
For consistency with other file types, all XMP data found in a PDF document is also available with the "xmp:" prefix.

MLA adds five fields of its own to the metadata information:

PDF_Version	the version of the PDF specification to which the file conforms. For a file conforming to PDF 1.7, this would be PDF−1.7
PDF_VersionNumber	the numeric portion of the PDF_Version. For a file conforming to PDF 1.7, this would be 1.7
xmptk	the XMP software used to create the metadata
xmlns	an array of the namespaces found in the document, such as `'dc' => 'http://purl.org/dc/elements/1.1/'`
ALL_PDF	a special "pseudo value" that returns a string representation of all the metadata. You can use this pseudo-value to examine the metadata in a document, find field names and see what values are present.

Go to Top

Field-level substitution parameter filters (Hooks)

Field-level substitution parameters can be extended to include any data values your application requires. They are supported by a set of filters that enables PHP code in your theme or in another plugin to create data values and make them available to MLA. An example of using the hooks from a simple, stand-alone plugin can be found in the Documentation/Example Plugins submenu. You can find the example plugin here: MLA Substitution Parameter Hooks Example. To run the example:

Click on the link above or go to top of the Documentation tab and click on the "Example Plugins" button.
Hover over "MLA Substitution Parameter Hooks Example" in the Name column, then click the "Install" rollover action.
Go to the Plugins/Installed Plugins screen and activate the "MLA Substitution Parameter Hooks Example" plugin.
Create a new `[mla_gallery]` shortcode, markup template or mapping rule that uses terms from an item's parent post/page.
Run the shortcode or mapping rule to see the plugin's data put to use.

The following hooks are defined in /wp-admin/includes/class-mla-data.php:

mla_expand_custom_data_source	for shortcode and Content Template processing, called when a parameter has no prefix value and the data-source name is not recognized by MLA, giving you an opportunity to generate your custom data value. Use a distinctive data-source name to minimize the risk that your name will conflict with other plugins or future MLA versions.
mla_expand_custom_prefix	called when a parameter's prefix value is not recognized by MLA, giving you an opportunity to generate your custom data value. Using a custom prefix lowers the risk that your data-source name will conflict with other plugins or future MLA versions.
mla_apply_custom_format	called when a parameter's option/format value is not recognized by MLA, giving you an opportunity to apply your custom option/format to the data value. This filter is called after either of the two "expand_custom" filters above. It will also be called if you use a custom option/format with any other field-level substitution parameter.

The following hook is defined in /wp-admin/includes/class-mla-data-source.php:

mla_evaluate_custom_data_source

for metadata mapping rules, called when a parameter has no prefix value and the data-source name is not recognized by MLA, giving you an opportunity to generate your custom data value. Use a distinctive data-source name to minimize the risk that your name will conflict with other plugins or future MLA versions.

Note the distinction between mla_expand_custom_data_source and mla_evaluate_custom_data_source; they are called in different contexts with slightly different parameters.

Content Templates

Content Templates (templates) are one of the Field-level Markup Substitution Parameters, indicated by a prefix value ( [+template: ... +] ). Within a template you can have any combination of four elements:

String	text and/or field-level substitution parameters, e.g., `[+template: Base File - [+base_file+] +]`
Conditional	text and/or field-level substitution parameters that will be tested for missing values. Any field-level substitution parameter that is not valid, is empty or contains only whitespace will cause the entire conditional to be eliminated. Conditional elements are enclosed in parentheses. For example, `[+template: (IPTC Title: [+iptc:object-name+] ) +]`. If the IPTC field is missing or blank both it and the preceding "IPTC Title: " literal are eliminated.
Choice	two or more alternatives from which the first valid, non-empty value will be taken. Choice elements are separated by vertical bars ("\|"), e.g., `[+template: Summary: ([+caption+]\|[+description+]\|[+title+]) +]`
Template	another template. There is no particular advantage to nesting templates, but it works.

The conditional and choice elements are the key to templates' power, particularly with custom fields and metadata such as IPTC and EXIF. With the conditional element you can combine literal text with a substitution value and eliminate the text if the value is missing. With the choice element you can specify multiple sources for a value and decide the order in which they are tested. In the choice example above the text "Description: " will always be used, followed by the attachment's caption (if present) or the description value or the literal "none" if both of the other values are missing. In other words, each alternative of the choice element is evaluated as a conditional element; no need for more parentheses.

Conditional, choice and template elements can be nested as needed. For example, a conditional element can have a choice element within it or a choice alternative could include a conditional. Here's an example:

[+template: Terms: (([+terms:category+], [+terms:post_tag+])|[+ terms: category +]|[+terms:post_tag +]|none)+]

This template has a String, "Terms: " and a Conditional, "(([+terms: ... none)". This Conditional separates the "Terms: " literal from the first alternative in the Choice. Within the Conditional is a Choice having four alternatives. The first alternative is a Conditional, which will be empty unless both categories and tags are present. The second and third alternatives handle the cases where one of the two taxonomies has terms, and the final alternative is used when neither categories nor tags are present.

In the Media/Assistant submenu table Bulk Edit area and the IPTC/EXIF Standard Field mapping fields you can use the special template:[+empty+] value to support deleting the content of the Title, Caption, Description and ALT Text fields.

Special characters inside templates

The conditional and choice elements require delimiters, "(", ")" and "|". If you want to put any of these three characters in your template, preface them with a backslash character, e.g., "\(". If you need a backslash in your template, code it as two backslash characters, i.e., "\\".

In a shortcode parameter: If your template is coded in a shortcode parameter, preface the template delimiters with two backslash characters, e.g., "\\(". If you need a backslash in your template, code it as four backslash characters, i.e., "\\\\". The doubling of backslash characters is required because of the way WordPress processes shortcode parameters.

Go to Top

Regular Expression Features

Regular Expressions is a formal name for a powerful pattern-matching tool you can use to extract parts of, for example, a file name and use the parts to compose or update a caption, title or other item element. Although they can get complicated pretty quickly regular expressions are well defined and even simple examples can be quite powerful. They are definitely a power tool! You can find a wealth of information on the web, such as these resources:

The MLA regular expression features are simply a way to access a few of PHP's PCRE functions, so the last link above is particularly useful. The

Patterns and subpatterns

Each regular expression defines a "pattern" that is applied to the subject, or data source. If the pattern is matched, that part of the data source is returned from the option/format value. Subpatterns allow you to take a portion of the overall pattern and return it separately. For example, you might construct a pattern that matches a date and include within the pattern subpatterns that return the year, month and day portions of the date. The pattern and subpattern matches are stored by MLA and become data sources you can access with the matches: field-level prefix. By default, the pattern match and any subpattern match(es) are assigned index numbers. The pattern is number zero and the subpatterns are numbered from one to the total number of subpatterns.

For example, consider the post_date data source, the "Uploaded on" date and time for a Media Library item. This date is stored as a string with a specific format: "YYYY-MM-DD HH:MM:SS", e.g., "2013-10-03 02:47:13". You can match this value in many ways:

/\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/ - matches the entire date and time, e.g., "2013-10-03 02:47:13"
/(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2})/ - matches the entire date and time (index 0) and matches two subpatterns, for the date portion (index 1) and the time portion (index 2)
/\d{4}-\d{2}-\d{2}/ - matches the date portion, e.g., "2013-10-03"
/\d{2}:\d{2}:\d{2}/ - matches the time portion, e.g., "02:47:13"
/(\d{4})-(\d{2})-(\d{2})/ - matches the date portion (index 0) and matches three subpatterns for the year (index 1), month (index 2) and day (index 3) portions.
/(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/ - matches the date portion (index 0) and matches three subpatterns for the year (index 1, name "year"), month (index 2, name "month") and day (index 3, name "day") portions.

The last example is particularly useful, because named subpatterns let you give unique names to each piece of your data for later use with the matches: prefix. With only one pattern the index values are fine, but if you have more than one pattern the index numbers are reused so later patterns overwrite matches from earlier patterns.

The patterns above contain backslash ('\') characters. When entering backslashes in an argument of the three option/format values below you must code two backslashes because the backslash is used in function arguments to escape special characters such as quotes (" ' "). The examples below show how this is done.

The `,match(p)` option/format value

The ,match(p) option/format value can be applied to any data source, including those specified by any of the field-level prefix values. The "p" argument is a regular expression pattern that is applied to the data source. If a match is found the portion of the data source that matches the pattern is returned. If no match is found and empty value is returned. Any pattern and subpattern matches are stored and made available as data sources accessed with the matches: field-level prefix.

The `,extract(p,v)` option/format value

The ,extract(p) option/format value can be applied to any data source, including those specified by any of the field-level prefix values. The "p" argument is a regular expression pattern that is applied to the data source. By default, the ,extract(p) option/format value returns an empty value; it's purpose is to collect pattern/subpattern matches for later use as data sources accessed with the matches: field-level prefix. You can change the returned value by adding the optional second "v" argument to specify any of the matched pattern or subpattern keys. For example, add zero ("0") to return the entire pattern, the index number of a subpattern or the name of a named subpattern.

The `,replace(p,r,v)` option/format value

The ,replace(p,r) option/format value matches a pattern (like ,match(p)) but returns a modified version of the original data source value. The "p" argument is a regular expression pattern that is applied to the data source. The "r" argument is a replacement pattern. If a match is found the data source modified by the replacement pattern is returned. If the match is not found, the original data source value is returned unaltered. For example, if a post_date data source contains "2013-10-03 02:47:13", then [+post_date,replace( '/(\\d{4})-(\\d{2})-(\\d{2})/', 'year: $1, month: $2, day: $3' )+] would return "year: 2013, month: 10, day: 03 02:47:13". Note the double backslashes in the pattern argument! To specify an array argument enclose the argument in braces ( "{" and "}" ) and separate elements with spaces. For a simple example, ,replace( {'/,/' '/-/'}, {' ' '_'} ) will change commas to spaces and dashes to underscores, while ,replace( {'/,/' '/-/'}, ' ' ) will change both commas and dashes to spaces.

You can alter the value returned by adding the optional third "v" parameter set to "true". If you add this parameter the returned value will be just the matched portion of the original with the replacement modifications applied. For example, if a post_date data source contains "2013-10-03 02:47:13", then [+post_date,replace( '/(\\d{4})-(\\d{2})-(\\d{2})/', 'year: $1, month: $2, day: $3', true )+] would return "year: 2013, month: 10, day: 03". Note the double backslashes in the pattern argument!

Note that, unlike match and extract, the replace format/option value does not store its pattern or subpattern(s) for later use with the matches: prefix.

The `matches:` field-level prefix

The matches: field-level prefix lets you access the patterns and subpatterns matched by all of the match and extract format/option values that precede it in a shortcode, template or rule. For example, if you code [+post_date,extract( '/(?<year>\\d{4})-(?<month>\\d{2})-(?<day>\\d{2})/' )+] you can then code [+matches:year+] or [+matches:1+] (index 1) to access the year subpattern from the extract format/option.

Application Examples

Imagine that you have a photo archive where all the files are named with the date on which the image was taken, for example "2010.06.14 Death Valley Landscape.jpg". You would like to extract the date from the file name and use it to update the post_date (Uploaded on) date in the database. You'd also like to preserve the time portion of the current post_date so the items will sort in the order they were uploaded. You can define an IPTC/EXIF mapping rule to do this or use the Media/Assistant Bulk Edit area. In either place you can compose a Content Template to do the job:

template:[+name_only,extract( '/(?<year>\\d{4}).(?<month>\\d{2}).(?<day>\\d{2})/' )+]([+matches:year+]-[+matches:month+]-[+matches:day+] [+post_date,date( 'H:i:s' )+])

That looks complicated, so let’s consider each part. The first part, [+name_only,extract( ..., extracts the three subparts of the date from the file name and stores them for later use. This part of the template returns an empty value, so it does not contribute to the new post_date value. The second part uses three [+matches: ... data sources to build a valid date separated by dashes. The third part returns just the time portion of the original post_date. The second and third part are surrounded by parentheses, so an empty value is returned when the date values are not found in the file name. That will leave the original post_date value intact for any items whose file names lack a date portion.

Here is a somewhat shorter alternative:

template:[+name_only,extract( '/(?<filedate>\\d{4}.\\d{2}.\\d{2})/' )+]([+matches:filedate,str_replace( '.', '-' )+] [+post_date,date( 'H:i:s' )+])

In this alternative the first part extracts the complete date with its period separators. The second part reformats the date, replacing the periods with dashes. The third part is the same as in the first alternative.

One subtle point. The period characters (".") separating the year, month and day portions of the pattern are actually one of the regular expression metacharacters; they will match any character in the subject. For example, they will match "2010/06/14" or "2010X06X14". Either of those values will cause the str_replace() function to fail. If you want to explicitly match a period, preface it with a backslash, e.g.:

template:[+name_only,extract( '/(?<filedate>\\d{4}\.\\d{2}\.\\d{2})/' )+]([+matches:filedate,str_replace( '.', '-' )+] [+post_date,date( 'H:i:s' )+])

Finally, here’s a version that uses the replace value in a different way:

template:([+name_only,replace( '/(\\d{4})\.(\\d{2})\.(\\d{2})/','$1-$2-$3',true)+] [+post_date,date( 'H:i:s' )+])

In this version the first part matches the date at the beginning of the file name and replaces its period separators with dashes. It uses the thrid `true` argument to return just the matches/modified portion of the file name. The second part is the same as in the first alternative.

As you can see, regular expressions require close attention to detail and they reward careful study of the documentation and examples in the PHP documentation and elsewhere. They are a power tool with sharp edges.

The MLA Text Widget

The MLA Text Widget lets you add content such as [mla_gallery] and [mla_tag_cloud] displays to your site's sidebars. It is an easy way to add slide shows and navigation features to all your pages. The MLA Text Widget is based on the WordPress Text widget, but adds the ability to include any shortcode to widget content. To use the MLA Text Widget:

Go to the Appearance/Widgets Administration screen
Open the sidebar, footer, or Theme section to which you wish to add the Text Widget
Find the Text Widget in the list of Widgets
Click and drag the Widget to the spot you wish it to appear

To open and edit the MLA Text Widget:

Click the down arrow to the right of the MLA Text Widget title
Set the MLA Text Widget Title (optional)
Add the text or HTML code to the box or edit what is currently there
If desired, choose the option to Automatically add paragraphs to wrap each block of text in an HTML paragraph tag
Click Save to save the Widget
Click Close to close the Widget
Switch tabs in your browser and review the results; make changes if necessary

To add an [mla_gallery] or [mla_tag_cloud] shortcode to your widget, simply enter the shortcode name and parameters just as you would in the body of a post or page. Aside from the usually more limited area devoted to displaying the widget content, there are no differences in the way shortcodes are processed in the MLA Widget. Also, there is nothing special about the two MLA shortcodes; any shortcode can be added to the MLA Widget.

Go to Top

Terms Search - filtering on taxonomy term names

The "Terms Search" features let you filter the Media/Assistant submenu table and the Media Manager Modal Window by matching one or more phrases in the Name field of taxonomy terms. There are two ways to access this feature:

Check the "Terms" box under the "Search Media" button on the Media/Assistant submenu table or the Media Manager toolbar. The phrase(s) you enter in the search box will match taxonomy term names as well as any other search fields you have checked.
Click the "Terms Search" button beside the terms filter dropdown. This will bring up the "Search Terms" popup window with several additional controls to refine your search. They are described below.

Entering words and phrases

You can enter one or more words/phrases in the Search Media or Search Terms text box, separated by spaces. A multi-word phrase is created by surrounding two or more words with double quotes ( " ). For example:

' man bites dog ' is three separate one-word phrases
' man "bites dog" ' is a one-word phrase (man) and a two-word phrase (bites dog)
' "man bites dog" ' is one three-word phrase

The first example would match each word separately. The second would match "man" and "bites dog" separately, with exactly one space between "bites" and "dog".

Quote marks have another effect on the search; they restrict the match to a word boundary. For example, if you enter 'man' without enclosing quotes it will match "man" or "woman", because "man" appears as a part of "woman". If you add quotes, i.e., ' "man" ', it will match "man" or "big man" but it will not match the "man" portion of "woman".

In the unlikely event you need to match single or double quotes inside a phrase you can enter them as an escape sequence. Use \47 for a single quote\42 for a double quote.

Connecting multiple phrases

The search is further defined by the connector used between multiple phrases:

'and'/'All phrases' - all of the phrases must appear in the search field/term name.
'or'/'Any phrase' - any one (or more) of the phrases must appear in the search field/term name.

For example, if you choose the default 'and'/'All phrases' connector and enter 'man "bites dog"' in the text box:

'man that bites dog' will match, but 'man that dog bites' will not match.
'dog bites man' will not match.
'man bites man with dog' will not match.

If, however you remove the quotes and enter 'man bites dog' all of the above examples will match, because all three of the phrases appear somewhere in the text. On the other hand 'man bites man' would not match because "dog" does not appear in the text.

If you choose the 'or'/'Any phrase' connector and enter 'man "bites dog"' in the text box:

'man that bites dog' will match.
'man that dog bites' will match because "man" is present.
'dog bites man' will match because "man" is present.
'dog bites another dog' will not match.

Exact phrase matching

The Search Terms popup window has an additional capability, "Exact match" and a checkbox to activate it. When you check the "Exact" box, each phrase must match the entire text of a term name. For example, if you check "Exact", the phrase "man" will match a term of the same name but not a term named "big man". If you check "Exact" and enter "big man" you will match terms named "big" or "man" but not "big man". If you want an exact match on a multi-word term such as "big man", put quotes around the name, i.e., ' "big man" '.

Whole word matching

The Search Terms popup window has an additional capability, "Whole word match" and a checkbox to activate it. When you check the "Whole Word" box, each word in the phrase must match a whole word of a term name. For example, if you check "Whole Word", the phrase "man" will match a term that contains "man" but not the word "woman". If you check "Whole Word" and enter "big man" it is as if you put quotes around each of the words, i.e., ` "big" "man" `. If you want an exact match on a multi-word term such as "big man", put quotes around the name, i.e., ' "big man" '.

Excluding phrases

If you want to exclude terms that match a phrase, enclose the phrase in slash ("/") delimiters. For example, enter "/dog/" to exclude terms containing the word dog. To exclude a multi word phrase, enter something like "/bites dog/" to exclude both words or ' /"bites dog"/ ' to exclude the exact phrase. You can combine include and exclude phrases, e.g., something like "man /that/ dog" to select terms containing "man" and "dog" but not containing "that".

You can also exclude terms by prepending a word or quoted phrase with a hyphen, e.g., 'pillow -sofa' will select terms containing 'pillow' but not 'sofa'.

When you add exclude phrases to your search, the phrases you enter are divided into two sub-values, "positive" and "negative", with everything enclosed by the exclude delmiters going to the negative sub-value and everything else to the positive. Two queries are performed. First, the negative sub-value is used and a list of the item IDs that pass the query is compiled. Second, the positive sub-value is used and items with the "negative" IDs are excluded.

Entering multiple terms

The Search Terms popup window has an additional capability and another control to refine it. The additional capability lets you search for multiple terms and the control sets the connector between terms. For example, consider two taxonomies, each with several terms:

Att. Categories, containing "big animal", "small animal" and "other being"
Att. Tags, containing "male", "female", "cat" and "dog"

If you choose 'All phrases' and 'Any term' (the defaults) and enter 'big dog' there are no matches because none of the terms contain both 'big' and 'dog'. If you choose 'Any phrase' and 'Any term' you will get items assigned to the 'big animal' Att. Category or the 'dog' Att. Tag. If you choose 'Any phrase' and 'All terms' you will get only the items assigned to both the 'big animal' Att. Category and the 'dog' Att. Tag.

If you enter 'big,dog', separating the two phrases with a comma, the search results will change. Terms will be matched against "big" and "dog" separately. The 'All phrases'/Any phrase' choice will not matter because both of the phrases contain just one word. Choose 'All terms' and you will get any items assigned to 'big animal' and to 'dog'. Choose 'Any term' and you will get all of the 'big animal' matches and all of the 'dog' matches; that includes small dogs and big cats.

Selecting taxonomies

By default, the Att. Categories and Att. Tags taxonomies are included in the terms search. In the Taxonomy Support section of the Settings/Media Library Assistant General tab you can use the checkboxes in the Terms Search column to add or remove any of the supported taxonomies from the search process.

In the Search Terms popup window you will find a list of all supported taxonomies, with checkboxes reflecting their participation in the search process. You can add or remove taxonomies from the process on a search-by-search basis.

Debugging output

If you are having problems with search results or are simply curious you can activate some debug logging by adding a special value to the beginning of the phrases text box. Adding }|{ activates the display of information about the query parameters and SQL statements used to retrieve items. You will see a lot of information added to the post or page containing the gallery or to the Media/Assistant admin screen. Of course, this value should ONLY be used in a development/debugging environment; it's quite ugly.

If you add {|} all of the information will be written to the error log, a more practical choice. You can use the MLA Debug Tab to view and download the information in the error log.

Go to Top

Select Parent Popup Window

The "Select Parent" popup window lets you find the parent post/page/custom post type for one or more attachments. You can access the popup window in four ways:

Click the "Set Parent" link in the "Attached to" column of the Media/Assistant submenu table.
Click the "Select" button in the Media/Assistant submenu table Quick Edit area.
Click the "Select" button in the Media/Assistant submenu table Bulk Edit area.
Click the "Select" button in the Media/Edit Media submenu "Parent Info" meta box.

In all cases the Select Parent popup window will appear and will be filled with up to 50 parent candidates. If the current parent is in the list its radio button will be selected. You can select a new parent, including "(unattached)", by clicking anywhere in the row of the candidate you want.

If you don't see the candidate you want you have three ways of updating the list:

Enter one or more keywords in the text box at the top of the window and click "Search". The word(s) you enter will filter the list by searching the Title and Content fields for matches.
Select a post type from the dropdown list at the top of the window. The list will be filtered to show candidates from the post type you choose.
Click the "next page" (" » ") button in the Media/Assistant submenu table Bulk Edit area. The list will move to the next page of up to 50 additional candidates. You can click the "previous page" (" « ") button to move back towards the top of the list.

Once you have chosen a new parent, click the "Update" button at the lower right of the window to save your choice. You will be returned to your starting point with the new value filled in. Changes made in the "Attached to" column are immediate; changes to the Quick Edit, Bulk Edit and Parent Info meta box are made later, when you click the "Update" button in those areas to save all your changes.

If you change your mind you can close the window without making a change by clicking the "X" in the upper-right corner of the window or the "Cancel" button in the lower-left corner of the window.

Go to Top

Support for the “Admin Columns” Plugin

Reorder columns with a simple drag & drop interface.
Re-size columns to give more or less space to a column.
Remove (not just hide) columns from the submenu table.
Add new columns for custom fields and additional information.
The Admin Columns "Pro" version adds support for inline editing, ACF fields and other capabilities.
The Admin Columns "Pro" version adds support for exporting Media/Assistant table values to CSV-format files.

You can find detailed configuration instructions at the Admin Columns web site Documentation page.

Go to Top

Custom Taxonomy Actions and Filters (Hooks)

The Custom Taxonomy filters and actions give you control over the registration of the Att. Categories and Att. Tags taxonomies from PHP code in your theme or in another plugin. An example of using the hooks from a simple, stand-alone plugin can be found in the Documentation/Example Plugins submenu. You can find the example plugin here: MLA Taxonomy Hooks Example. To run the example:

Click on the link above or go to top of the Documentation tab and click on the "Example Plugins" button.
Hover over "MLA Taxonomy Hooks Example" in the Name column, then click the "Install" rollover action.
Go to the Plugins/Installed Plugins screen and activate the "MLA Taxonomy Hooks Example" plugin.
Go to, for example, the Media/Assistant submenu to exercise the filters and write filter/action information to the site's Error Log.
Examine the Error Log to see the filter/action information.

You can find more information about the types, labels and arguments in the Function Reference/register taxonomy repository page.

The example code documents each hook with comments in the filter/action function that intercepts each hook.

The following hooks are defined in /wp-admin/includes/class-mla-objects.php:

mla_attachment_category_types, mla_attachment_tag_types	Modify the array of post types for which the taxonomy is registered. The default is "attachment".
mla_attachment_category_labels, mla_attachment_tag_labels	Modify the array of labels used in the User Interface for submenu and metabox names, etc.
mla_attachment_category_arguments, mla_attachment_tag_arguments	Modify the array of arguments with which the taxonomy is registered. For example, you can change the URL rewrite slug from the default `attachment_category/attachment_tag` values for SEO purposes. Note: You may need to flush the rewrite rules after changing the slug. You can do it manually by going to the Permalink Settings page and re-saving the rules -- you don't need to change them.

Go to Top

Media/Assistant Submenu Actions and Filters (Hooks)

The Media/Assistant submenu supports a comprehensive set of filters and actions that give you control over table columns, inline actions and bulk actions from PHP code in your theme or in another plugin. An example of using the hooks from a simple, stand-alone plugin can be found in the Documentation/Example Plugins submenu. You can find the example plugin here: MLA List Table Hooks Example. To run the example:

Click on the link above or go to top of the Documentation tab and click on the "Example Plugins" button.
Hover over "MLA List Table Hooks Example" in the Name column, then click the "Install" rollover action.
Go to the Plugins/Installed Plugins screen and activate the "MLA List Table Hooks Example" plugin.
Go to the Media/Assistant submenu to exercise the filters and write filter/action information to the site's Error Log.
Examine the Error Log to see the filter/action information.

The example code documents each hook with comments in the filter/action function that intercepts each hook. There are hooks that let you add, modify or delete table columns.

In addition, there are hooks that run when the Media Library items are selected from the database and hooks for adding and processing custom quick actions and bulk actions.

The following hooks are defined in /wp-admin/includes/class-wp-list-table.php:

views_media_page_mla_menu	Filter the list of available list table views.
bulk_actions-media_page_mla-menu	Filter the list table Bulk Actions drop-down. This WordPress filter can currently only be used to remove bulk actions.
months_dropdown_results	Filter the 'Months' drop-down results.
mla_entries_per_page	Filter the number of items to be displayed on each page of the list table.
manage_media_page_mla-menu_sortable_columns	Filter the list table sortable columns for a specific screen.

The following hooks are defined in /media-library-assistant/includes/class-mla-objects.php:

mla_taxonomy_get_columns	Gives you an opportunity to change the columns defined for the Edit Taxonomy submenu table(s).
mla_taxonomy_column	Gives you an opportunity to replace column content in the Edit Taxonomy submenu table(s) before MLA computes the count.
mla_taxonomy_column_final	Gives you an opportunity to replace column content in the Edit Taxonomy submenu table(s) after MLA computes the count.

The following hooks are defined in /media-library-assistant/includes/class-mla-data.php:

mla_list_table_query_final_terms	Gives you an opportunity to change the terms of the prepare_items query after they are processed by the "Prepare List Table Query" handler.
mla_list_table_query_custom_items	Gives you an opportunity to substitute the results of the prepare_items query with alternative results of your own.
mla_list_table_search_filter_fields	Gives you an opportunity to add or remove any of the MLA standard fields for Search Media.
mla_list_table_search_filter_inner_clause	Gives you an opportunity to modify or add to the inner WHERE clause for Search Media.
mla_fetch_attachment_references	Gives you an opportunity to modify or add to the "where-used" reference reporting information.
mla_update_single_item	Gives you an opportunity to modify, delete or add to updates before they are applied.
mla_updated_single_item	Gives you an opportunity to work with the item after updates have been applied.

The following hooks are defined in /media-library-assistant/includes/class-mla-main.php:

mla_list_table_inline_fields	Gives you an opportunity to name the fields passed to the JavaScript functions for Quick editing.
mla_list_table_inline_action	Gives you an opportunity to pre-process an MLA_List_Table "Quick Edit" action before the MLA handler.
mla_list_table_bulk_action_initial_request	Gives you an opportunity to pre-process the request parameters for a bulk action before the action begins. DO NOT assume parameters come from the $_REQUEST super array!
mla_list_table_begin_bulk_action	Gives you an opportunity to pre-process an MLA_List_Table bulk action, standard or custom, before the MLA handler. The filter is called once before any of the items in $_REQUEST['cb_attachment'] are processed.
mla_list_table_bulk_action_item_request	Gives you an opportunity to pre-process the request parameters for each item during a bulk action. DO NOT assume parameters come from the $_REQUEST super array!
mla_list_table_bulk_action	Gives you an opportunity to pre-process an MLA_List_Table bulk action, standard or custom, before the MLA handler. The filter is called once for each of the items in $_REQUEST['cb_attachment'].
mla_list_table_custom_bulk_action	Gives you an opportunity to process an MLA_List_Table bulk action that MLA does not recognize. The filter is called once for each of the items in $_REQUEST['cb_attachment'].
mla_list_table_end_bulk_action	Gives you an opportunity to post-process an MLA_List_Table bulk action, standard or custom. The filter is called once after all of the items in $_REQUEST['cb_attachment'] are processed.
mla_list_table_admin_action	Gives you an opportunity to pre-process an MLA_List_Table item-level action, standard or custom, before the MLA handler. This filter is called before anything is output for the Media/Assistant submenu, so you can redirect to another admin screen if desired.
mla_list_table_custom_admin_action	Gives you an opportunity to process an MLA_List_Table item-level action that MLA does not recognize. This filter is called before anything is output for the Media/Assistant submenu, so you can redirect to another admin screen if desired.
mla_list_table_single_action	Gives you an opportunity to pre-process an MLA_List_Table item-level action, standard or custom, before the MLA handler. This filter is called after the Media/Assistant submenu screen header is output but before the messages and submenu table are displayed.
mla_list_table_custom_single_action	Gives you an opportunity to process an MLA_List_Table page-level or single-item action that MLA does not recognize. This filter is called after the Media/Assistant submenu screen header is output but before the messages and submenu table are displayed.
mla_list_table_clear_filter_by	Gives you an opportunity to clear any custom submenu "Filter-by" parameters.
mla_list_table_new_instance	Gives you an opportunity to extend the MLA_List_Table class.
mla_list_table_inline_values	Gives you a chance to modify and extend the substitution values for the Quick and Bulk Edit forms.
mla_list_table_inline_template	Gives you a chance to modify and extend the template used for the Quick and Bulk Edit forms.
mla_list_table_inline_parse	Gives you a final chance to modify and extend the HTML markup used for the Quick and Bulk Edit forms.

The following hooks are defined in /media-library-assistant/includes/class-mla-list-table.php:

mla_list_table_get_columns	Gives you an opportunity to filter the list table columns.
mla_list_table_get_hidden_columns	Gives you an opportunity to filter the hidden list table columns.
mla_list_table_get_sortable_columns	Gives you an opportunity to filter the sortable list table columns; a good alternative to the 'manage_media_page_mla_menu_sortable_columns' filter.
mla_list_table_get_bulk_actions	Gives you an opportunity to filter the list of bulk actions; a good alternative to the 'bulk_actions-media_page_mla-menu' filter.
mla_list_table_extranav_actions	Gives you an opportunity to add, remove and/or re-order the controls added to the top & bottom table navigation areas.
mla_list_table_extranav_custom_action	Called when the MLA_List_Table can't find a value for an extranav action.
mla_list_table_column_default	Called when the MLA_List_Table can't find a value for a given column.
mla_list_table_submenu_arguments	Gives you an opportunity to filter the URL parameters that will be retained when the submenu page refreshes.
mla_list_table_prepare_items_pagination	Gives you an opportunity to filter the per_page and current_page parameters used for the prepare_items database query.
mla_list_table_prepare_items_total_items	Gives you an opportunity to substitute your own $total_items parameter used for the prepare_items database query.
mla_list_table_prepare_items_the_items	Gives you an opportunity to substitute your own items array in place of the default prepare_items database query.
mla_list_table_prepare_items	Gives you an opportunity to record or modify the results of the prepare_items database query.
mla_list_table_build_rollover_actions	Gives you an opportunity to filter the list of "Rollover" actions giving item-level links such as "Quick Edit", "Move to Trash".
mla_list_table_build_inline_data	Gives you an opportunity to filter the data passed to the JavaScript functions for Quick and Bulk editing.
views_upload	Views for the "upload" page when WPML is active. This filter is hooked by WPML Media in wpml-media.class.php, and is only applied when WPML is active.

The following hooks are defined in /media-library-assistant/includes/class-mla-edit-media.php:

mla_upload_bulk_edit_form_values	Gives you a chance to modify and extend the substitution values for the Bulk Edit on Upload form.
mla_upload_bulk_edit_form_template	Gives you a chance to modify and extend the template used for the Bulk Edit on Upload form.
mla_upload_bulk_edit_form_parse	Gives you a final chance to modify and extend the HTML markup used for the Bulk Edit on Upload form.

Go to Top

Media Manager Enhancement filters (Hooks)

Media Library Assistant adds several controls to the toolbar in the Media Manager Modal Window; more MIME type filters, year/month filter, taxonomy term filter and an enhanced Search media box. These features are supported by a comprehensive set of filters and actions that give you control over MMMW content from PHP code in your theme or in another plugin. An example of using the hooks from a simple, stand-alone plugin can be found in the Documentation/Example Plugins submenu. You can find the example plugin here: MLA Media Modal Hooks Example. To run the example:

Click on the link above or go to top of the Documentation tab and click on the "Example Plugins" button.
Hover over "MLA Media Modal Hooks Example" in the Name column, then click the "Install" rollover action.
Go to the Plugins/Installed Plugins screen and activate the "MLA Media Modal Hooks Example" plugin.
Make any changes or additions you want to in the example plugin source code. For example, you can uncomment the $initial_values assignments and setting a new initial value for one or more controls.
Click the "Add Media" button for a post or page to see the effect of your changes.

The following hooks are defined in /wp-admin/includes/class-mla-media-modal.php:

mla_media_modal_form_fields	Change the content of the Media Manager Modal Window ATTACHMENT DETAILS fields
mla_media_modal_months_dropdown	Change the content of the Media Manager Modal Window Month & Year Dropdown control
mla_media_modal_terms_options	Change the content of the Media Manager Modal Window Terms Dropdown control
mla_media_modal_initial_filters	Change the initial values of the Media Manager Modal Window toolbar controls
mla_media_modal_settings	Change the content of the Media Manager Modal Window toolbar controls
mla_media_modal_strings	Change the content of the string values passed Media Manager Modal Window toolbar controls
mla_media_modal_template_path	Change the path to the JavaScript template file or substitute your own template(s)
mla_media_modal_begin_fill_compat_fields	Replace the content of the Media Manager Modal Window ATTACHMENT DETAILS taxonomy meta boxes before the MLA results have been added
mla_media_modal_end_fill_compat_fields	Change the content of the Media Manager Modal Window ATTACHMENT DETAILS taxonomy meta boxes after MLA results have been added.
mla_media_modal_begin_update_compat_fields	Pre-process the $_REQUEST elements for the Media Manager Modal Window ATTACHMENT DETAILS taxonomy meta boxes updates
mla_media_modal_update_compat_fields_terms	Change the terms assigned to one Media Manager Modal Window ATTACHMENT DETAILS taxonomy
mla_media_modal_end_update_compat_fields	Change the content of one (or more) Media Manager Modal Window ATTACHMENT DETAILS taxonomy meta boxes with updated checkbox or tag/term lists
mla_media_modal_query_initial_terms	Change the terms of the Media Manager Modal Window "Query Attachments" query before they are pre-processed by the MLA handler
mla_media_modal_query_filtered_terms	Change the terms of the Media Manager Modal Window "Query Attachments" query after they are pre-processed by the AJAX handler

The following hooks are defined in /wp-admin/includes/class-mla-data-query.php:

mla_media_modal_query_final_terms	Change the terms of the Media Manager Modal Window "Query Attachments" query after they are processed by the "Prepare List Table Query" handler
mla_media_modal_query_custom_items	Substitute the results of the Media Manager Modal Window "Query Attachments" query with alternative results of your own

Go to Top

Edit Media additional meta boxes (and Hooks)

Media Library Assistant adds support for the "Custom Fields" meta box to the Media/Edit Media screen. MLA also adds several meta boxes to this screen with more information about the item and where it is used on your site. You can enable/disable the additional meta boxes with an option on the Settings/Media Library Assistant General tab.

You can also make individual changes in which meta boxes are displayed and in their content by using one or more of the filters MLA provides. An example of using the hooks from a simple, stand-alone plugin can be found in the Documentation/Example Plugins submenu. You can find the example plugin here: MLA Meta Box Hooks Example. To run the example:

Click on the link above or go to top of the Documentation tab and click on the "Example Plugins" button.
Hover over "MLA Meta Box Hooks Example" in the Name column, then click the "Install" rollover action.
Go to the Plugins/Installed Plugins screen and activate the "MLA Meta Box Hooks Example" plugin.
Make any changes or additions you want to in the example plugin source code. For example, you can modify the mla_inserted_in_metabox example to display a simplified version of the "Inserted in" information.
View the Media/Edit Media screen for an item to see the effect of your changes.

The example code documents each hook with comments in the filter function that intercepts the hook. Generally, each meta box filter lets you change the size of the text box (if appropriate) and the content that appears in the box. There is also a second filter for each meta box that lets you replace all of the HTML content for most boxes; use these with caution. The current hooks are:

mla_edit_media_support	suppress the addition of Custom Fields to the Edit Media screen. To suppress Custom Fields, return an empty array, i.e., `return array();`
mla_edit_media_meta_boxes	record the original list of meta box slugs. You can also remove elements from the array to suppress one or more meta boxes. To suppress a box, remove it from the array, e.g., `unset( $active_boxes['mla-menu-order'] );`
mla_parent_info_meta_box	modify the text portion of the "Parent Info" meta box.
mla_menu_order_meta_box	modify the "Menu Order" meta box.
mla_image_metadata_meta_box mla_image_metadata_meta_box_html	modify the rows, columns and content of the "Attachment Metadata" meta box.
mla_featured_in_meta_box mla_featured_in_meta_box_html	modify the rows, columns and content of the "Featured in" meta box.
mla_inserted_in_meta_box mla_inserted_in_meta_box_html	modify the rows, columns and content of the "Inserted in" meta box.
mla_gallery_in_meta_box mla_gallery_in_meta_box_html	modify the rows, columns and content of the "Gallery in" meta box.
mla_mla_gallery_in_meta_box mla_mla_gallery_in_meta_box_html	modify the rows, columns and content of the "MLA Gallery in" meta box.

Go to Top

Library Views/Post MIME Type Processing

WordPress uses Post MIME Types (a terrible name; they have nothing to do with Posts or Pages), to define the views for the Media/Library screen and the Media Manager/Add Media "media items" drop down list. MLA's Media/Assistant screen uses an enhanced version of the list, Table Views, to support views with multiple MIME Types (e.g., "audio,video") and wildcard specifications (e.g. "*/*ms*").

The first time it is invoked, MLA will retrieve the current list of Post MIME Types and use it to initialize the list. MLA will add any custom items it finds added to the list by other plugins and code. Once the list is initialized, MLA's list will be used and other plugins and code will have no effect. You can disable MLA handling of the list by clearing the Enable View and Post MIME Type Support checkbox at the bottom of the screen and clicking "Save Changes".

Post MIME Type

The Post MIME Type list uses the Slug, Singular Label and Plural Label values. The Slug is most important; it uniquely identifies the list entry. The Slug value must be all lowercase and contain only letters, numbers, periods (.), slashes (/) and hyphens (-). For “Post MIME Type” items, the slug is also the MIME type specification and must be a single, valid MIME specification, e.g., “image” or “image/jpeg”. The labels are displayed in various admin screens.

Use Within WordPress

Within WordPress, the Post MIME Types list is returned from /wp-includes/post.php, function get_post_mime_types(). That function is called from:

/wp-admin/includes/media.php function get_media_item(), to validate the type of an attachment when it is edited,
/wp-admin/includes/post.php, function wp_edit_attachments_query() to count the number of attachments of each type, and
/wp-includes/media.php function wp_enqueue_media(), to populate the the Media Manager/Add Media "media items" drop down list.

Table View

The Table View list adds several enhancements to the Post MIME Type list. In the Specification field you can select several MIME types with a comma-separated list, e.g., "audio,video". Wildcard specifications are also supported. For example, "*/mpeg" to select audio and video mpeg formats or "application/*ms*" to select all Microsoft application formats (Word, Excel, etc.). In the Menu Order field you can enter numeric values to re-arrange the order in which the list entries are displayed in, for example, the Media/Assistant screen.

The Table View list also supports custom field queries. A custom field query has four parts:

A prefix, "custom:"
A comma-separated list of one or more custom field names
An equals sign ("="), to divide the field names from the values
A comma-separated list of one or more values

To return all items that match one or more values, enter the prefix "custom:" followed by the custom field name(s) and then "=" followed by a list of values. For example, custom:Color=red or custom:Color=red,green,blue. To search multiple fields, enter something like custom:Artist,Patron=smith,jones. To search all custom fields, enter an asterisk ("*"), e.g., custom:*=smith,jones. Wildcard specifications are also supported; for example, "*post" to match anything ending in "post" or "th*da*" to match values like "the date" and "this day". As explained below, a value of "*" will match any non-NULL value for a custom field.

There are two special forms of the custom field specification used to test for the presence (non-NULL) or absence (NULL) of any values:

To return all items that have a non-NULL value in the field, enter the custom field name and then "=*", e.g., custom:My Featured Items=*. You can also enter the prefix "custom:" followed by just the custom field name(s). For example, custom:My Featured Items.
To return all items that have a NULL value in the field, enter the prefix "custom:" followed by the custom field name(s) and then "=", e.g., custom:My Featured Items,My Inserted Items=. You can also enter a single custom field name and then ",null". For example, custom:My Featured Items,null.

If you have enabled the Media Manager Enhanced MIME Type filter, the Table View list will also be available in the Media Manager/Add Media "media items" drop down list.

Go to Top

File Extension and MIME Type Processing

The file extension/MIME Type associations are used by WordPress to decide what kind of files can be uploaded to the Media Library and to fill in the post_mime_type value for files added to the Media Library. To upload a file, the file extension must be in this list and be active.

The first time it is invoked, MLA will retrieve the current list of extensions and MIME Types and use it to initialize the list. MLA will add any custom items it finds added to the list by other plugins and code. Once the list is initialized, MLA's list will be used and other plugins and code will have no effect. You can disable MLA handling of the list by clearing the Enable Upload MIME Type Support checkbox at the bottom of the screen and clicking "Save Changes".

WordPress examines the content of a file during upload to more carefully validate the file's MIME type. Sometimes this extra validation prevents valid files from being added to the Media Library. For example, a CSV or plain text file that contains some HTML tags will be classified as "text/html" instead of text/csv or text/plain. This causes the upload to fail for "security reasons".

You can check the Always Use MLA MIME Type option to bypass this extra security and use the MIME Type defined here in all uploads. Consider using this option carefully, only when you are having trouble uploading a file or files you know to be valid.

Extension and MIME Type

The Extension is the file extension for this type, and unique key for the item. It must be all lowercase and contain only letters, numbers and hyphens (-). The MIME Type value must be all lowercase and contain only letters, numbers, periods (.), slashes (/) and hyphens (-). The MIME type specification must be a single, valid MIME specification, e.g., "image" or "image/jpeg". These two values are used to compose the list of valid extension/type associations for use within WordPress.

When a file is uploaded to your Media Library the MIME type associated with that file extension is saved in the WordPress database record for the item. Later, you can use the post_mime_type to, for example, include or exclude the item from an [mla_gallery] display. You can think of the MIME Type as another way to categorize items in the Media Library. Once assigned, the MIME Type is not changed if you later alter the association between file extension and MIME Type. Think twice, therefore, when adding a new association to the list or changing the MIME type associated with an existing extension on the list.

Icons and Icon Types

WordPress maintains a list of "file types" which associate file extensions with type names used to select an icon image. For example, an "audio" file type is associated with an image of musical notes. There are nine of these types: archive, audio, code, default, document, interactive, spreadsheet, text and video. MLA has a much longer list; 112 icon types/images in all. If the "Enable MLA File Type Icons Support" checkbox at the bottom of the Settings screen, Uploads tab is checked, the enhanced icon images will be used in place of the WordPress images.

The MLA icon images are slightly larger than the default images and square; 64x64 pixels. The images are drawn (with permission) from the Crystal Project Icons, created by Everaldo Coelho, founder of Yellowicon. You can find the images in the /plugins/media-library-assistant/images/crystal directory.

You can change the icon image associated with any file extension by selecting a new value from the dropdown list on the Edit Upload MIME Type screen or in the Quick Edit area. You can change the icon image for several extensions at once using the Bulk Edit action.

If you have some other plugin or mechanism for handling the Upload MIME Type items, you can disable MLA support entirely. Clear the checkbox at the bottom-left corner of the screen and click "Save Changes".

Source and Status

The "Source" of an Upload MIME Type reveals where the extension/MIME Type association comes from:

core: WordPress defines a core set of extensions and associated MIME types, and this list changes with new WordPress releases. These are the "official" items. You can't delete them, but you can inactivate them so they are not used to validate file uploads.
mla: Media Library Assistant adds several more extension/type items, drawing from the most popular items found in other plugins and web sites. They are initialized as "inactive" items, so you must explicitly decide to activate them for use in file upload validation.
custom: Defined by some other plugin or code, or by manual action. When MLA first builds its list it will automatically add anything it finds in your current list as a new, active custom item. After that, you can use MLA to manage them.

The "Status" of an item determines whether it is used by WordPress to validate file uploads and assign MIME types to attachments in your Media Library. Only "active" items are used in this way; making an item "inactive" will prevent further uploads with that extension but will NOT affect any attachments already in your Media Library.

Use Within WordPress

Within WordPress, the Uploads list is returned from two different functions. In the current MLA release, the same list is returned from both functions. It appears that wp_get_mime_types() is designed to be more liberal than get_allowed_mime_types(). If you have a reason to return different results from one or the other function, let me know and I will consider enhancing the plugin.

The first function is /wp-includes/functions.php, function wp_get_mime_types(). That function is called from:

/wp-includes/class-wp-image-editor.php function get_mime_type(), to validate the type of an attachment when it is edited,
/wp-includes/class-wp-image-editor.php function get_extension(), to validate the type of an attachment when it is edited,
/wp-includes/functions.php, function do_enclose() to "check content for video and audio links to add as enclosures", and
/wp-includes/functions.php, function get_allowed_mime_types(), to populate the the Media Manager/Add Media "media items" drop down list.

The second function is /wp-includes/functions.php, function get_allowed_mime_types(). That function is called from:

/wp-includes/formatting.php function sanitize_file_name(), to validate the name of a file, and
/wp-includes/functions.php, function wp_check_filetype(), to validate the type of a file before it is uploaded

The list is also used in /wp-includes/ms-functions.php, function check_upload_mimes(), which "is used to filter that list against the filetype whitelist provided by Multisite Super Admins at /wp-admin/network/settings.php." Multisite installs must respect this restriction, so any list we produce will be passed thru that function if it exists.

The Icon Type information is used primarily in a function that matches a file extension to an icon image:

/wp-includes/post.php, function wp_mime_type_icon()

The icon images can be returned in a

[gallery]

or an [mla_gallery] shortcode when size=icon is specified. The icons also appear on the Media/Library and Media/Assistant submenu tables.

Go to Top

Searching for Upload MIME Types

The association between file extensions and MIME Types is an inexact science, as you might imagine. Over the years many companies, standards bodies and other organizations have laid claim to file extensions for different purposes and defined MIME Types to suit their needs. As this is written there are hundreds of web sites with lists of extensions and corresponding MIME Types; most of them give no explanation or justification for their choices.

If you come across a new file extension, or if the existing extension/MIME type association does not suit you, you can search the MLA list of over 1,500 alternatives. The list was compiled from several Internet sources and a vigorous attempt was made to get a Description for each choice. If you find a mistake or an entry missing from the list, let me know!

The Known File Extension/MIME Type Associations list will often list several MIME Types for a given file extension. Think carefully before choosing one that differs from the WordPress and MLA Types, if they exist. Once you choose an association and upload files of that type, think very carefully before changing it, because changes will not be applied to existing Media Library items.

For your own research, I suggest starting with these resources:

Put on your boots and have a paddle handy - it's a swamp! Good luck.

Go to Top

Custom Field and Attachment Metadata Processing Options

In the Custom Fields tab of the Settings screen you can define the rules for mapping several types of file and image metadata to WordPress custom fields. You can also use this screen to define rules for adding or updating elements within the WordPress-supplied "Attachment Metadata", stored in the "_wp_attachment_metadata" custom field. See the Adding or changing Attachment Metadata section below for details.

In this tab there are three ways to execute one or more custom field mapping rules for ALL of your Media Library items:

Execute All Rules button - just below the "Enable" checkbox controls in the upper-left portion of the tab. Click this button to immediately run ALL of the active rules. Rules marked as inactive will not be executed.
Bulk Actions "Execute" - Runs the rules you select by checking the box to the left of one or more rule names. Pull down the "Bulk Actions" control and select "Execute", then click the "Apply" button. Inactive rules will be executed; do not select them unless you want to execute them!
"Execute" rollover action - Runs the single rule you select by clicking the rule's "Execute" rollover action. Inactive rules will be executed.

These commands process your items in "chunks" to prevent timeout errors. You can pause/resume or cancel the operation between chunks. Note that rules with a Data Source of "none" are ignored because they can't change the custom field value.

There are two other ways you can perform custom field mapping for one or more existing attachments:

Edit Media screen - You can click the "Map Custom Field metadata" link in the "Image Metadata" postbox to apply the existing mapping rules to a single attachment.
Bulk Action edit area - To perform mapping for a group of attachments you can use the Bulk Action facility on the Media/Assistant screen. Check the attachments you want to map, select "Edit" from the Bulk Actions dropdown list and click "Apply". The bulk edit area will open with a list of the checked attachments in the left-hand column. You can click the "Map Custom Field metadata" button in the lower left corner of the area to apply the existing mapping rules to the attachments in the list.

Custom field mapping is a powerful tool, but it comes at the price of additional database storage space and processing time to maintain and retrieve the data. Think carefully about your needs before you use this tool. You can disable or delete any rules you create, so you might want to set up some rules for a special project or analysis of your library and then discard them when you're done. That said, the advantages of mapping metadata to custom fields are:

You can add the data to an [mla_gallery] with a field-level markup substitution parameter. For example, add the image dimensions or a list of all the intermediate sizes available for the image.
You can add the data as a sortable, searchable column to the Media/Assistant submenu table. For example, you can find all the "orphans" in your library by adding "reference_issues" and then sorting by that column. You can also click on any value in the column to filter the display on a single custom field value.

If you just want to add a custom field to the Media/Assistant submenu, the quick edit area and/or the bulk edit area you can bypass the mapping logic by leaving the Data Source value as "-- None (select a value) --".

Three checkbox options control the custom field mapping when new items are added to the Media Library:

Enable custom field mapping - Check this option to enable the mapping rules and display the "Map" buttons on the Media/Edit Media and Media/Assistant Bulk Edit screens.
Enable custom field mapping when adding new media - Check this option to enable mapping when uploading new items (attachments) to the Media Library.
Enable custom field mapping when updating media metadata - Check this option to enable mapping when item (attachment) metadata is regenerated, e.g., when the Media/Edit Media "Edit Image" functions are used.

The "when adding" and "when updating" options do NOT affect the operation of the "Map" buttons on the bulk edit or single edit screens, nor do they affect any of the "Execute" mapping functions On this Settings screen.

Check one or more options to enable these features, then click the "Save Changes" button to record your new setting(s).

Some plugins support file uploads from the WordPress "front end", usually by using the WordPress "AJAX" support. To enable mapping when these plugins are used you must add an entry to your wp-config.php file so MLA will load the mapping code:

define( 'MLA_AJAX_EXCEPTIONS', 'wfu_ajax_action,upload_ugc' );

The above example adds the "action" values for two popular file upload plugins, WordPress File Upload and Frontend Uploader respectively. Once the entry is added MLA will run the mapping rules when it detects file upload operations from the other plugin(s).

If you cannot identify the proper "action" value or if your uploader uses another method to do its work you can try adding define( 'MLA_AJAX_EXCEPTIONS', 'always' ); to your wp-config.php file. This value will unconditionally load full MLA support for AJAX operations and may give you better results. You can also use the

Go to Top

Custom field mapping example

Here is a simple example of mapping the items' file size to a custom field, so you can display it in the Media/Assistant submenu table and use it in and [mla_gallery] shortcode. You can go to the Settings/Media Library Assistant Custom Fields tab and define a rule that maps file size to a WordPress custom field. The steps required are:

Navigate to the Settings/Media Library Assistant "Custom Fields" tab.
Make sure the "Enable custom field mapping when adding new media" box is checked. If not, check the box, scroll down and click "Save Changes".
Scroll down to the "Add New Rule" area on the left part of the screen.
Click the "Enter new field" link to change the drop down list of existing fields to a text box.
In the text box, give your field a name, e.g., "File Size".
From the Data Source dropdown list, select "file_size".
Leave the "Meta/Template" text box empty; it's not needed for this example.
Click the "MLA Column" check box to make the field available in the Media/Assistant submenu table. You can also click the "Quick Edit" and "Bulk Edit" check boxes to make the field available in the Media/Assistant submenu table Quick Edit and Bulk Edit areas if that's useful for you.
In the "Existing Text" dropdown list, select "Replace".
In the "Format" dropdown list, select "Commas". This will format the values in a more attractive way.
In the "Option:" dropdown list, select "Text".
Click the "Delete NULL Values" checkbox.
Click the "Add Rule" button to save your work and create the rule.

To create the "File Size" value for the items already in your Media Library, find your new rule in the table on the right part of the screen. Hover below the "File Size" rule name and click the "Execute" rollover action.

On the Media/Assistant screen you can now display a File Size column. If you don't see the column, pull down the Screen Options (upper-right corner) and check the box next to File Size. Each of the terms in the column is a link; click on a value to get a list filtered by that value. You can also sort the table on File Size by clicking on the column header.

You can use the meta_key, orderby and order parameters to sort an [mla_gallery] by your custom field. For example:

[mla_gallery post_parent=all meta_key="File Size" orderby=meta_value order=DESC]

The three parameters in the above example will select all of the images in your media library and sort your gallery so the largest files appear first. You can replace post_parent=all with any other data selection parameters to get the items you want. For example, you can use a "meta_query" to select only those items (of any MIME Type) whose File Size is less than 82,168 bytes (and display the size in the gallery item caption):

[mla_gallery post_mime_type=all meta_query="array( array( 'key' => 'File Size', 'value' => array( ' ', ' 82,168' ), 'compare' => 'BETWEEN' ) )" meta_key="File Size" orderby="meta_value" order="DESC" mla_caption="{+caption+} {+custom:File Size+}"]

Note the format of the value and compare parameters within the meta_query. Because the File Size custom field uses the "Commas" format, the values are stored as 15-character strings with leading spaces; this makes the values display and sort sensibly. You must use 'compare' => 'BETWEEN' and give the lowest and highest values as an array in the 'value' => array( ' ', ' 82,168' ) parameter, padding each value out to exactly 15 characters wide.

Go to Top

The custom field rule elements

Rule Name

Contains the name of the custom field or metadata element to which the rule applies. Attachment metadata elements are displayed as a "meta:" prefix followed by the element name; see the Adding or changing Attachment Metadata section for more details.

Data Source dropdown

Contains a list of data elements you can map to the custom field. You can also select "Metadata" or "Template" and use the text box below the dropdown to specify attachment metadata or a content template for the source.

-- None (select a value) --	nothing, i.e., no change to existing value (if any). Use this source if you just want to add a custom field to the Media/Assistant submenu and/or the inline edit areas.
-- Metadata (see below) --	WordPress attachment metadata, from the _wp_attachment_metadata array. Enter the field you want in the text box below the dropdown list. More coding guidelines are given in the "Adding or changing Attachment Metadata" section below.
-- Template (see below) --	A Content Template; enter the template text (without the "template:" prefix) in the text box below the dropdown list. More coding guidelines are given in the "Custom field mapping with Content Templates" section above.
(other data source)	See the Data sources for custom field mapping section for definitions of the other data elements you can select from.

Most of the data elements are static, i.e., they do not change after the attachment is added to the Media Library. The parent/reference information (parent_type, parent_title, parent_issues, reference_issues) and the "where-used" information (featured in, inserted in, gallery in and MLA gallery in) is dynamic; it will change as you define galleries, insert images in posts, define featured images, etc. Because of the database processing required to update this information, parent, where-used and reference data are NOT automatically refreshed. If you use these elements, you must manually refresh them with the "map data" buttons on the Settings screen, the bulk edit area or the Edit Media screen.

Several of the data elements are sourced from the WordPress "image_meta" array. The credit, caption, copyright and title elements are taken from the IPTC/EXIF metadata (if any), but they go through a number of filtering rules that are not easy to replicate with the MLA IPTC/EXIF processing rules. You may find these "image_meta" elements more useful than the raw IPTC/EXIF metadata.

Meta/Template text

If you select "-- Metadata (see below) --" as the data source you must specify the name of the field you want in the text box below the data source dropdown box. Any of the fields in the _wp_attachment_metadata array may be named, including the new audio/video fields available with WordPress 3.6 and later. For example, "length_formatted" will return the length of a video attachment. You can specify elements within an array with a compound name, e.g., "audio.sample_rate" to get the sampling rate field from the "audio" array of a video attachment. If you simply specify "audio", you will get the values of every array element, e.g., "mp4,ISO/IEC 14496 AAC,48000,2,16,false,stereo".

If you select "-- Template (see below) --" as the data source you must enter your template in the text box below the data source dropdown box. See the Custom field mapping with Content Templates section for more details.

MLA Column checkbox

Check this box if you want a custom field to appear as a sortable column in the Media/Assistant submenu table. Attachment metadata elements cannot be used as a table column; this box is ignored if the Field Title contains the "meta:" prefix.

Quick Edit checkbox

Check this box if you want the field to appear in the Media/Assistant submenu Quick Edit area.

Bulk Edit checkbox

Check this box if you want the field to appear in the Media/Assistant submenu Bulk Edit area.

Existing Text dropdown

If the custom field already has values for one or more items, you can use "Keep" to retain them or "Replace" to delete them. For options other than "Multi", "Keep" means that an item with a non-blank value in the field will be unchanged, and new values will be stored only in those items that do not have an existing value. For the "Multi" option, the existing value(s) will be retained and any new values will be added as separate instances.

You can combine "Keep" and "Multi" in useful ways. For example, you might enter some values manually or source them from another plugin or application. Then, map the same field using an MLA data source with the "Keep" and "Multi" parameters. That will add the MLA values to the values you already entered, giving you a single column with both results.

Format dropdown

Sorting by custom fields in the Media/Assistant submenu is by string values. For numeric data this can cause odd-looking results, e.g., dimensions of "1200x768" will sort before "640x480". Numeric data sources are converted to strings and padded on the left with spaces if you use the "commas" format. This padding makes them sort more sensibly. The following example shows the results for the "size_bytes[large]" data source, sorted in ascending order:

Four data sources, "file_size", "pixels", "width" and "height", are padded on the left with spaces even if you use the "native" format.

You can also use the "raw" format to avoid the conversion of empty values, such as a numeric zero, to a single space. The first row in the above table shows this "raw" treatment; it can be useful for fields like "parent".

Option Dropdown

Several data sources can return more than one value. For example, the "Inserted in" source can return a list of posts/pages that contain references to Media Library items. The format option dropdown can further refine your specification where multiple values exist. There are five options:

The "Multi" option takes advantage of WordPress' ability to store multiple values for a given custom field name (key) as distinct instances (database rows). For example, consider an image that has been inserted in two different posts, "First Post" and "Second Post". The "Text" option would store both titles in a single custom field instance; "First Post,Second Post". The "Multi" option would store two instances, "First Post" and "Second Post". If the custom field is added to the Media/Assistant submenu table as a column, you could click on either of the two values to filter the table listing by value. That would show you all the items inserted in First Post or all the items inserted in Second Post.

Delete NULL values checkbox

The "Delete NULL values" checkbox lets you control what happens if the data source you've selected does not have a value for every attachment. If the checkbox is cleared (not checked), a single space character will be stored for each attachment if the data source value is empty. If the checkbox is set (checked), there will be no entry/row at all in the metadata table for empty data source values and the custom field will not appear in the Edit Media screen for those attachments. This saves space but might confuse other applications that expect a value to be present for all attachments.

If you use the "Multi" option you will almost certainly want to use the "Delete NULL values" option as well.

Status dropdown

The "Status" dropdown lets you turn rules on or off for most mapping purposes. If you select "Active" the rule will always be applied during a mapping operation. If you select "Inactive" the rule will NOT be applied except when explicitly included in a Bulk Action "Execute" or "Execute" rollover action.

Go to Top

Adding or changing Attachment Metadata

WordPress stores an array of information for image, audio and video items in the "_wp_attachment_metadata" custom field. Plugins such as "Fullscreen Galleria" also use this field to store information like GPS coordinates. Many of the array elements, such as the "sizes" array for images, are in turn arrays of more detailed values. Compound names are used to access elements within arrays, e.g., "sizes.thumbnail.file" is used to specify the file name for the thumbnail version of an image.

As explained elsewhere, you can access all of this data with the "meta:" Field-level markup substitution parameter. By coding the "meta:" prefix in the Field Title column of a field mapping rule you can add to or update this data as well, from any of the data sources listed below. You can use a Content Template to compose a value from multiple substitution parameters and test for empty values, choosing among two or more alternatives or suppressing the mapping altogether for a given item.

Let's say, for example, that you want to add GPS coordinates to the "image_meta" element of the Attachment Metadata.

Open the Settings/Media Library Assistant submenu and select the Custom Fields tab. Scroll down to the "Add a new Field and Mapping Rule" section.
In the Field Title text box, enter "meta:image_meta.latitude". The rule will store its results in the "latitude" element of the "image_meta" array within the Attachment Metadata field.
In the Data Source dropdown, select "-- Template (see below) --". In the text box below the dropdown, enter "([+exif:GPS.LatitudeSDD+])". This is a Content Template that extracts the "GPS.LatitudeSDD" value from the EXIF data embedded in an image file. The parentheses test the result to eliminate empty values; only non-empty values will be mapped into the image_meta array.
Set the other parts of the rule as needed. You can select "Keep" if some of your items already have this information or "Replace" to update all items. "Native" and "Text" are appropriate for this example. You can check "Delete NULL values" to remove any existing, empty values for this element. The "MLA Column", "Quick Edit" and "Bulk Edit" checkboxes have no meaning for Attachment Metadata elements and can be left blank; they will be ignored if checked.

If you are creating an IPTC/EXIF mapping rule the details are a bit different.

Open the Settings/Media Library Assistant submenu and select the IPTC/EXIF tab. Scroll down to the "Add a new Field and Mapping Rule" section.
In the Field Title text box, enter "meta:image_meta.latitude". The rule will store its results in the "latitude" element of the "image_meta" array within the Attachment Metadata field.
In the "EXIF/Template" text box, enter "template:([+exif:GPS.LatitudeSDD+])". This is a Content Template that extracts the "GPS.LatitudeSDD" value from the EXIF data embedded in an image file. The parentheses test the result to eliminate empty values; only non-empty values will be mapped into the image_meta array.
Set the other parts of the rule as needed. You can select "EXIF" unless you also select an IPTC value and want it to have priority. You can select "Keep" if some of your items already have this information or "Replace" to update all items.

Go to Top

Custom field mapping with Content Templates

If you select "-- Template (see below) --" as the data source you must enter your template in the text box below the data source dropdown box. Do not code the "template:" prefix, just enter the template text.

Within a template, all of the data sources listed above are available. For example, you can code [+pixels+] or [+size_keys,single+].

You can use a template to compose a custom field from multiple data sources, e.g., "Taken with [+meta:camera+] at [+dimensions+] using ISO [+exif:ISOSpeedRatings,single+] and [+exif:ExposureTime+] exposure time".

You can use a template to compose a custom field from alternative data sources, depending on which fields are populated for a given attachment. For example, "[+pdf:Keywords+]|[+iptc:2#025+]|none" will use the PDF Keywords field, if populated, then the IPTC keywords field, if populated, or the literal "none" if neither field contains a value. With this template you can get keywords from both PDF documents and images in a single field.

Using a template with the Option Dropdown "Text" or "Single" values will yield a text result. For example, multiple IPTC keywords would be converted into a comma-delimited list as a string. If you combine a template with the "Export", "Array" or "Multi" values the template will deliver an array result if the fields inside the template have multiple values. For example, with "Multi" you can code "([+iptc:2#020,array+])([+iptc:2#025,array+])" to store each of the IPTC supplemental-category and keywords values (there is no "|" in the template) in a separate custom field value. Note the use of the ,array formatting option in each field; this is required to get an array result for the field. Also, note that each of the fields is enclosed in parentheses, so the field is suppressed if it contains no values.

CAUTION: If you use the [+custom:ALL_CUSTOM+] pseudo value in a mapping rule, and you apply the rule more than once, you will see copies of the field you are mapping to in the result. To "clear out" a field you are mapping ALL_CUSTOM into, clear out the text box containing the template, select "Replace" and check the "Delete NULL values" box. Then, click "Map All Attachments"; that will delete the old values and give you a clean start. You'll also see that the template you deleted will be restored after the mapping is complete.

Go to Top

IPTC & EXIF Processing Options

Some image file formats such as JPEG DCT or TIFF Rev 6.0 support the addition of data about the image, or metadata, in the image file. In addition, many JPEG, TIFF and PDF files use the Extensible Metadata Platform (XMP) framework. XMP metadata varies from file to file but is often extensive. Many popular image processing programs such as Adobe PhotoShop allow you to populate metadata fields with information such as a copyright notice, caption, the image author and keywords that categorize the image in a larger collection. WordPress uses some of this information to populate the Title, Slug and Description fields when you add an image to the Media Library.

The Media Library Assistant has powerful tools for copying metadata to:

the WordPress standard fields, e.g., the Caption
taxonomy terms, e.g., in categories, tags or custom taxonomies like Att. Categories and Att. Tags
WordPress Custom Fields

You can define the rules for mapping metadata on the "IPTC/EXIF" tab of the Settings page. You can choose to automatically apply the rules when new media are added to the Library (or not). You can click the "Map IPTC/EXIF metadata" button on the Edit Media/Edit Single Item screen or in the bulk edit area to selectively apply the rules to one or more items. You can use the "Execute" functions in the tab to apply the rules to one, some or ALL of the items in your library at one time.

If you use any of the "Execute" functions, the selected rule(s) will be immediately applied to all of the attachments in your Media Library. THERE IS NO UNDO FOR THESE ACTIONS!

If you just want to add a custom field to the Media/Assistant submenu, the quick edit area and/or the bulk edit area go to the "Custom Fields" tab and follow the instructions there.

In this tab there are three ways to execute one or more IPTC/EXIF mapping rules for ALL of your Media Library items:

Execute All Rules button - just below the "Enable" checkbox controls in the upper-left portion of the tab. Click this button to immediately run ALL of the active rules. Rules marked as inactive will not be executed.
Bulk Actions "Execute" - Runs the rules you select by checking the box to the left of one or more rule names. Pull down the "Bulk Actions" control and select "Execute", then click the "Apply" button. Inactive rules will be executed; do not select them unless you want to execute them!
"Execute" rollover action - Runs the single rule you select by clicking the rule's "Execute" rollover action. Inactive rules will be executed.

These commands process your items in "chunks" to prevent timeout errors. You can pause/resume or cancel the operation between chunks.

There are two other ways you can perform IPTC/EXIF mapping for one or more existing attachments:

Edit Media screen - You can click the "Map IPTC/EXIF metadata" link in the "Image Metadata" postbox to apply the existing mapping rules to a single attachment.
Bulk Action edit area - To perform mapping for a group of attachments you can use the Bulk Action facility on the Media/Assistant screen. Check the attachments you want to map, select "Edit" from the Bulk Actions dropdown list and click "Apply". The bulk edit area will open with a list of the checked attachments in the left-hand column. You can click the "Map IPTC/EXIF metadata" button in the lower left corner of the area to apply the standing mapping rules to the attachments in the list.

Three checkbox options control the IPTC/EXIF mapping when new items are added to the Media Library:

Enable IPTC/EXIF Mapping - Check this option to enable the mapping rules and display the "Map" buttons on the Media/Edit Media and Media/Assistant Bulk Edit screens.
Enable IPTC/EXIF Mapping when adding new media - Check this option to enable mapping when uploading new items (attachments) to the Media Library.
Enable IPTC/EXIF Mapping when updating media metadata - Check this option to enable mapping when item (attachment) metadata is regenerated, e.g., when the Media/Edit Media "Edit Image" functions are used.

Check one or more options to enable these features, then click the "Save Changes" button to record your new setting(s).

define( 'MLA_AJAX_EXCEPTIONS', 'wfu_ajax_action,upload_ugc' );

Go to Top

IPTC/EXIF mapping example

Here is a simple example of mapping an image's creation date to a custom field, so you can use it to display a gallery of images sorted by the date on which they were taken. There are three common EXIF fields that are populated in most images. For example:

DateTimeDigitized 2012:11:28 15:53:23
DateTimeOriginal 2012:11:28 15:53:23
DateTime 2012:12:01 17:37:05

You can go to the Settings/Media Library Assistant IPTC/EXIF tab and define a rule that maps any of these fields to a WordPress custom field. The steps required are:

Navigate to the Settings/Media Library Assistant IPTC/EXIF tab.
Make sure the "Enable IPTC/EXIF Mapping when adding new media" box is checked. If not, check the box, scroll down and click "Save Changes".
Scroll down to the "Add New Custom Field Rule" section.
If you have already defined "Date Time Created" as a custom field, select the field name in the first dropdown. If the field does not yet exist, click the "Enter new field" link to change the drop down list of existing fields to a text box and enter, for example, "Date Time Created" in the text box.
Leave the "IPTC Value" dropdown list set to the default "None (select a value)" setting.
Enter "DateTimeOriginal" in the EXIF/Template Value field.
Set the Priority dropdown to "EXIF".
Set the Existing Text dropdown to "Keep", unless you want to wipe out any values you've assigned earlier.
In the "Format" dropdown list, select "Native".
In the "Option:" dropdown list, select "Text".
Click the "Delete NULL Values" checkbox. This prevents storing an empty value in the database for items that do not have a "DateTimeOriginal" value.
Click "Add Rule" to save your rule.

If you want to test your work, you can go to the Media/Assistant submenu table and click the "Edit" rollover action for an image you know has a "DateTimeOriginal" value. Click the "Map IPTC/EXIF Metadata" link in the upper right "Save" area of the screen, then look down at the Custom Fields meta box and see if your "Date Time Created" value is present and correct. Once you've got your rule working you can update individual images, use the Bulk Edit area to update groups of images or use the "Execute" rollover action for your rule to process all of your images.

You can use the meta_key, orderby and order parameters to sort an [mla_gallery] by your custom field. For example:

[mla_gallery post_parent=all meta_key="Date Time Created" orderby=meta_value order=DESC]

The three parameters in the above example will select all of the images in your media library and sort your gallery so the newest/most recent images appear first. You can replace post_parent=all with any other data selection parameters to get the images you want. For example, you can use a "meta_query" to select only those images created after 2012-01-01 (and display the date in the gallery item caption):

[mla_gallery meta_query="array( array( 'key' => 'Date Time Created', 'value' => '2012-01-01', 'compare' => '<' ) )" meta_key="Date Time Created" orderby="meta_value DESC" mla_caption="{+custom:Date Time Created+}" ]

Go to Top

The IPTC/EXIF rule elements

All types of IPTC/EXIF mapping rules have the following common elements:

Field Title

The standard field title, taxonomy name or Custom Field name. In the Add New Custom Field Rule area you can define a new field by clicking the "Enter new field" link and entering its name in the text box; the value will be saved when you click "Add Rule" at the bottom of the area.

You can also use the Add New Custom Field Rule area to define rules for adding or updating elements within the WordPress-supplied "Attachment Metadata", stored in the "_wp_attachment_metadata" custom field. Code the "meta:" prefix in the Field Title textbox to make the destination of the rule an element of the Attachment Metadata; see the Adding or changing Attachment Metadata section for more details.

IPTC Value

The IPTC (International Press Telecommunications Council) metadata, if any, embedded in the image file. For this category, you can select any of the IPTC DataSet tag and field identifiers, e.g., "2#025" for the Keywords field. The dropdown list has the identifier and the "friendly name" MLA defines for most of the IPTC fields; see the table of identifiers and friendly names in the table below. You can find more information in the IPTC-NAA Information Interchange Model Version No. 4.1 specification.

EXIF/Template Value

The EXIF (EXchangeable Image File) metadata, if any, embedded in a JPEG DCT or TIFF Rev 6.0 image file. Though the specification is not currently maintained by any industry or standards organization, almost all camera manufacturers use it. For this category, you can code any of the field names embedded in the image by the camera or editing software. There is no official list of standard field names, so you just have to know the names your camera and software use; field names are case-sensitive. You can find more information in the Exchangeable image file format article on Wikipedia. You can find External Links to EXIF standards and tag listings at the end of the Wikipedia article.

MLA provides enhanced access to GPS values within the EXIF metadata; more details are given in the Enhanced GPS values section below.

You can also enter a Content Template here by coding the "template:" prefix at the beginning of the value. Do not add the "[+" and "+]" delimiters; the prefix is all you need. You can use a Content Template to access XMP metadata as an alternative to EXIF metadata. More information about using templates here is given below.

Two special exif "pseudo-values" are available; ALL_IPTC and ALL_EXIF. These return a string representation (in "export" format) of all IPTC or EXIF data respectively. You can use these pseudo-values to examine the metadata in an image, find field names and see what values are embedded in the image.

Priority

If both the IPTC Value and the EXIF Value are non-blank for a particular image, you can select which of the values will be used for the mapping.

Existing Text

Images already in the Media Library will have non-blank values in many fields and may have existing terms in a taxonomy. You can select "Keep" to retain these values or "Replace" to always map a metadata value into the field. For a taxonomy, "Keep" will retain any terms already assigned to the item and "Replace" will delete any existing terms before assigning metadata values as terms.

Status

The Taxonomy mapping rules have two additional elements:

Delimiter(s): In some cases multiple terms will be contained in a single IPTC or EXIF value. For example, Microsoft Windows stores its "Tags" in a single EXIF value (called Keywords) as a semicolon-delimited list, e.g., "tag1; tag2". You can separate terms encoded in this way by entering one or more delimiter characters in this column.
Parent: For hierarchical taxonomies such as Categories you can select one of the existing terms in the taxonomy as the parent term for any terms you are mapping from metadata values. For example, you could define "IPTC Keywords" as a parent and then assign all of the 2#025 values under that parent term.

The Custom Field mapping rules have three additional elements (see The custom field rule elements for more information on these elements):

Format: The Format element has a "commas" value that can improve the results of sorting on numeric values and a "raw" value that changes the handling of "empty" values such as zero.
Option: Some metadata fields can contain more than one value. For example, the "Keywords" field can contain a list of terms that describe the item. The format option dropdown can further refine your specification where multiple values exist.
Delete NULL Values: The "Delete NULL values" checkbox lets you control what happens if the data source you've selected does not have a value for every attachment.

Go to Top

EXIF/Template mapping with Content Templates

If you code the "template:" prefix at the beginning of the EXIF/Template value you have all the power of Content Templates at your disposal. Do not add the "[+" and "+]" delimiters; the prefix is all you need.

A template can be used to access any IPTC, EXIF or XMP metadata your items contain, as well as any of the field-level data sources. For example:

template:([+xmp:Title+])
template:([+xmp:Regions.RegionList.*.*.Name,array+])

Note the use of parentheses around the XMP parameters, which replace missing values with an empty value to enable proper rule processing.

Within a template, all of the Data sources for custom field mapping are available. For example, you can code [+pixels+] or [+size_keys,single+].

You can use a template to compose a value from multiple data sources, e.g., "Taken with [+meta:camera+] at [+dimensions+] using ISO [+exif:ISOSpeedRatings,single+] and [+exif:ExposureTime+] exposure time".

You can use a template to compose a value from alternative data sources, depending on which fields are populated for a given attachment. For example, "[+iptc:2#020+]|[+iptc:2#025+]|none" will use the IPTC supplemental-category field, if populated, then the IPTC keywords field, if populated, or the literal "none" if neither IPTC field contains a value.

Using a template in the "Standard field mapping" or "Custom field mapping" tables will yield a text result. For example, multiple IPTC keywords would be converted into a comma-delimited list as a string. In the "Taxonomy term mapping" table the template will deliver an array result if the fields inside the template have multiple values. For example, you can code "template:([+iptc:2#020+])([+iptc:2#025+])" to store each of the IPTC supplemental-category and keywords values (there is no "|" in the template) as a separate taxonomy term. Note that each of the fields is enclosed in parentheses, so the field is suppressed if it contains no values.

In the "Standard field mapping" table a special template:[+empty+] value supports deleting the content of the Title, Caption, Description and ALT Text fields. This value is also available in the Media/Assistant submenu table Bulk Edit area.

Note that the ,array formatting option is not required to get an array result for the field in a Taxonomy term mapping template; it is assumed. If you want a text, single or export result you can add one of those formatting options to your field specification.

Go to Top

IPTC/EXIF Mapping and Bulk Editing for the "Uploaded on" Standard Field

The "Uploaded on" Standard Field is set by WordPress to the date and time the item is uploaded to the Media Library. You can use a mapping rule to replace this with a different value, such as the date and time the item was created. Many EXIF date and time values such as DateTimeOriginal and DateTimeDigitized are stored as strings with a format of "YYYY:MM:DD HH:MM:SS". You can parse this format and just about any English textual datetime description into a Unix timestamp, then convert the result to the appropriate format ('Y-m-d H:i:s', e.g., "2014-12-31 23:59:00", or just before midnight on new year's eve). The mapping rule first uses the PHP strtotime() function, then the date() function, to compose a valid date and time. The "Supported Date and Time Formats" that can be passed in to the rule are described at: http://php.net/manual/en/datetime.formats.php.

You can use a Content Template to compose the starting value in many ways. For example:

template:([+exif:DateTimeOriginal+]|[+meta:image_meta.created_timestamp,timestamp('Y-m-d H:i:s')+])

This example first uses the EXIF DateTimeOriginal value, if present. If that value is missing the alternative is the created_timestamp that WordPress calculates and adds to the image_meta array in the attachment metadata. Since the created_timestamp is a Unix timestamp it is first converted to a text format that can be processed by strtotime(). If neither value is available the original WordPress-supplied default will be retained.

You can also replace the Uploaded on values for one or more items in the Bulk Edit Area of the Media/Assistant submenu table. Again, the Content Template feature adds power to this feature. For example, you can replace the date portion of the value while retaining the time portion to preserve the sort order of your items:

template: 20180102 [+post_date,date( 'H:i:s' )+] template: today [+post_date,date( 'H:i:s' )+]

The first example above sets the date to a fixed value. The second example uses "today", one of the

Go to Top

IPTC/EXIF Mapping for PDF Documents

PDF documents contain a Document Information Dictionary (D.I.D.) and many also contain XMP metadata. For the pdf: prefix, you can code any of the nine D.I.D. entries:

Title - The document's title
Author - The name of the person who created the document
Subject - The subject of the document
Keywords - Keywords associated with the document
Creator - the name of the conforming product that created the original document
Producer - the name of the conforming product that converted it to PDF
CreationDate - The date and time the document was created
ModDate - The date and time the document was most recently modified
Trapped - indicates whether the document has been modified to include trapping information

MLA contains logic that attempts to fill in the entries from the dictionary or from any XMP metadata the document contains. This gives you a simple way to access the information regardless of where in the metadata it appears.

You can use Content Templates in the EXIF/Template Value text box to extract metadata from your PDF documents and add it to the Standard Fields and Taxonomy Terms of your Media Library items. The templates can be coded to select the appropriate source whether the item is a PDF document or an image. Here are three rules for metadata contained in PDF documents:

Field	EXIF/Template Value	Priority	Existing Text	Delimiter(s)
Title:	template:([+pdf:Title+])	EXIF	Replace
Caption:	template:([+pdf:Subject+])	EXIF	Replace
Att. Categories:	template:([+pdf:Keywords,array+])	EXIF	Replace	;,

The three rules have a similar structure:

"template:" (goes in the text box below "EXIF/Template Value") is used to access the pdf: values instead of the EXIF values.
The values are surrounded by parentheses "(" and ")" so they will return an empty string for documents without meta data in the field and for other items such as images.
I have selected "Replace" to overwrite the existing text, because a default Title was assigned to the items when they were uploaded. You can change this to "Keep" if you already have values in one or more of the fields that you want to retain.

The taxonomy rule also has the ",array" option to return multiple keywords as individual array elements that can be converted to taxonomy terms. For this rule, the "Delimiter(s)" text box contains a comma and a semicolon, which should cover most of the documents you will encounter.

If your Media Library contains a mix of images and PDF documents you will want a more flexible rule to map metadata from different sources in each MIME type. You can extend the rules as follows:

Field	EXIF/Template Value	Priority	Existing Text	Delimiter(s)
Title:	template:([+pdf:Title+]\|[+exif:Title+])	EXIF	Replace
Caption:	template:([+pdf:Subject+]\|[+exif:ImageDescription+])	EXIF	Replace
Att. Categories:	template:([+pdf:Keywords,array+]\|[+iptc:2#025+])	EXIF	Replace	;,

The three rules have similar changes:

A vertical bar ("|") separates the two data source specifications. This is the Content Template "Choice" operator, which takes the first non-blank alternative from among the choices.
A second data source for images. The PDF documents will not have "exif:"/"iptc:" data sources, and images will not have "pdf:" data sources, so only one (at most) of the two alternatives will be non-blank.

In fact, WordPress contains its own rules for composing a Title from IPTC/Exif metadata (see

Go to Top

WordPress default title, slug and description mapping

When WordPress uploads a new image file that contains IPTC and EXIF metadata it automatically maps metadata values to the title (post_title), name/slug (post_name) and description (post_content) fields. This happens before the MLA mapping rules are applied, so if you want to override the default mapping you must select "Replace" in the "Existing Text" column.

The WordPress rules are somewhat complex; consult the source code if you need exact details. Roughly speaking, the priority order for mapping the post_title and post_name values from non-blank IPTC/EXIF metadata is:

EXIF "Title"
EXIF "ImageDescription" (if less than 80 characters)
IPTC 2#105 "headline"
IPTC 2#005 "object-name"
IPTC 2#120 "caption-or-abstract" (if less than 80 characters)

The priority order for mapping the post_content value from non-blank IPTC/EXIF metadata is:

EXIF "ImageDescription" (if different from post_title)
IPTC 2#120 "caption-or-abstract" (if different from post_title)

Go to Top

MLA Custom Field and IPTC/EXIF Mapping Actions and Filters (Hooks)

The Custom Field and IPTC/EXIF Mapping tools support a comprehensive set of filters and actions that give you complete control over rule execution and value creation from PHP code in your theme or in another plugin. An example of using the hooks from a simple, stand-alone plugin can be found in the Documentation/Example Plugins submenu. You can find the example plugin here: MLA Mapping Hooks Example. To run the example:

Click on the link above or go to top of the Documentation tab and click on the "Example Plugins" button.
Hover over "MLA Mapping Hooks Example" in the Name column, then click the "Install" rollover action.
Go to the Plugins/Installed Plugins screen and activate the "MLA Mapping Hooks Example" plugin.
Upload a new attachment and/or run the mapping rules to exercise the filters and write mapping information to the site's Error Log.
Examine the Error Log to see the mapping information.

The example code documents each hook with comments in the filter/action function that intercepts each hook. There are hooks that run at the beginning and end of the overall mapping operation as well as hooks for each mapping rule.

In addition, there are hooks that run when attachments are uploaded to the Media Library and when the "attachment metadata" is altered, e.g., when the Media/Edit Media "Edit Image" function is used. Plugins and other image editing code can destroy the attachment metadata or the IPTC/EXIF metadata embedded in an image file. These hooks may give you an opportunity to preserve and repair the metadata you need in spite of such damage.

The current mapping hooks are:

mla_begin_mapping	called once, before mapping rules for any/all attachment(s) are executed.
mla_mapping_settings	called once for each attachment, before any mapping rules are executed. You can add, change or delete rules from the settings/rules array.
mla_mapping_rule	called once for each mapping rule, before the rule is evaluated. You can change the rule parameters, or prevent rule evaluation.
mla_mapping_custom_value	called once for each custom field mapping rule, after the rule is evaluated. You can change the new value produced by the rule.
mla_mapping_old_custom_value	called once for each Custom Field mapping rule, after the "old text" portion of the rule is evaluated. You can change the old value produced by the rule.
mla_mapping_iptc_value	called once for each IPTC/EXIF mapping rule, after the IPTC portion of the rule is evaluated. You can change the new value produced by the rule.
mla_mapping_exif_value	called once for each IPTC/EXIF mapping rule, after the EXIF portion of the rule is evaluated. You can change the new value produced by the rule.
mla_mapping_new_text	called once for each IPTC/EXIF mapping rule, after the selection between the IPTC and EXIF values has been made. You can change the new value produced by the rule.
mla_mapping_updates	called AFTER all mapping rules are applied. You can add, change or remove updates for the attachment's standard fields, taxonomies and/or custom fields.
mla_end_mapping	called once, after mapping rules for any/all attachment(s) are executed. This is a good place to close files, perform cleanup, etc.
mla_purge_custom_field_values	called once for each custom field mapping rule, when the "Purge Values" rollover or Bulk action is executed. This is a good place to apply your own purge logic or prevent the purge from taking place.

A second example plugin, MLA Metadata Mapping Hooks Example, illustrates the metadata hooks. The current insert attachment/update attachment metadata hooks are:

mla_upload_prefilter	gives you an opportunity to record the original IPTC, EXIF and WordPress image_metadata before the file is stored in the Media Library. You can also modify the file name that will be used in the Media Library. Many plugins and image editing functions alter or destroy this information, so this may be your last change to preserve it.
mla_upload_filter	gives you an opportunity to record some additional metadata for audio and video media after the file is stored in the Media Library.
mla_add_attachment	called at the end of the wp_insert_attachment() function, after the file is in place and the post object has been created in the database. By this time, other plugins have probably run their own 'add_attachment' filters and done their work/damage to metadata, etc.
mla_update_attachment _metadata_options	lets you inspect or change the processing options that will control the MLA mapping rules in the update_attachment_metadata filter.
mla_update_attachment _metadata_prefilter	called at the end of the wp_update_attachment_metadata() function, before any MLA mapping rules are applied. The prefilter gives you an opportunity to record or update the metadata before the mapping. The wp_update_attachment_metadata() function is called at the end of the file upload process and at several later points, such as when an image attachment is edited or by plugins that alter the attachment file.
mla_update_attachment _metadata_postfilter	This filter is called after MLA mapping rules are applied during wp_update_attachment_metadata() processing. The postfilter gives you an opportunity to record or update the metadata after the mapping.

The current Settings/Media Library Assistant tab list hook is:

mla_get_options_tablist

gives you an opportunity to remove one or more tabs from the list that appears on the Settings/Media Library Assistant screen.

Go to Top

MLA Debug Tab

If you are having trouble with some part of Media Library Assistant it may be helpful to look at the PHP error log. MLA writes messages to the log for a variety of reasons, and the information they contain can be very helpful in finding the cause of a problem and resolving it.

The existence and location of the error log can vary depending on your server configuration. WordPress includes some wp-config.php entries that can help. If you activate the Debug tab but can't access the error log you can try adding or updating these statements in your wp-config.php file:

define( 'WP_DEBUG', 1 ); When WP_DEBUG is true, all PHP notices are reported. WordPress will also display notices, including one when a deprecated WordPress function, function argument, or file is used. Deprecated code may be removed from a later version.
define( 'WP_DEBUG_LOG', 1 ); When WP_DEBUG_LOG is true, errors will be logged to wp-content/debug.log. WP_DEBUG_LOG defaults to false.
define( 'WP_DEBUG_DISPLAY', 1 ); When WP_DEBUG_DISPLAY is true, WordPress will force errors to be displayed. WP_DEBUG_DISPLAY defaults to true. Defining it as null prevents WordPress from changing the global configuration setting. Defining WP_DEBUG_DISPLAY as false will force errors to be hidden.

The full path and file name of the error log is displayed just above the text area that contains the log content. If the content doesn't display and/or you can't download the log file, you can try finding the log file at the location shown. If you can't access the PHP error log for any reason, you can write the MLA-specific messages to a separate file in your /wp-content/ directory using the "Debug File" option explained below.

The MLA Debug Tab appears at the right of the tab list in the Settings/Media Library Assistant submenu. If you want to restrict access to the logging options and error log file you can suppress the tab by adding an entry to your wp-config.php file:

define( 'MLA_DEBUG_LEVEL', 0 );

The MLA_DEBUG_LEVEL is also used to turn categories of debug messages on and off. Each bit of the value has a separate meaning; the current definitions are:

1, or 0x0001	activates the Debug tab. PHP messages and some MLA error messages (such as the `[mla_gallery mla_debug=log]` messages) will be written to the file.
2, or 0x0002	writes MLA-specific messages to the log for some of the "AJAX" functions such as bulk edit updates and mapping rule execution.
4, or 0x0004	writes MLA-specific messages to the log for calls to the WPML/Polylang support functions.
8, or 0x0008	writes MLA-specific messages to the log for thumbnail generation functions supporting the `[mla_gallery mla_viewer=...]` parameter.
16, or 0x0010	writes MLA-specific messages to the log for IPTC, EXIF, XMP and PDF metadata generation.
32, or 0x0020	writes MLA-specific messages to the log for WP REST API calls identified by `/wp-json/` in the SERVER_URI.
64, or 0x0040	writes MLA-specific messages to the log for "where-used" reference collection.
128, or 0x0080	writes MLA-specific messages to the log for MIME Type processing.
256, or 0x0100	writes MLA-specific messages to the log for Media Manager Modal Window actions, e.g., "query_attachments".

You can pick the logging categories you want by adding the above values together. For example, to log only PHP messages you can use define( 'MLA_DEBUG_LEVEL', 1 ); or define( 'MLA_DEBUG_LEVEL', 0x0001 );. To add the "AJAX" messages you can use define( 'MLA_DEBUG_LEVEL', 3 ); or define( 'MLA_DEBUG_LEVEL', 0x0003 );. The hexadecimal notation ( 0x0003 ) can be easier to understand when several options are involved.

Although you can add logging categories to the MLA_DEBUG_LEVEL constant you will find it more convenient to add them in the "MLA Reporting" option on the Debug tab. There you can make changes without editing and uploading the `wp-config.php` file as your needs change. It is best to define( 'MLA_DEBUG_LEVEL', 1 ); and make any other changes in the "MLA Reporting" option. You can also set the "MLA Reporting" option to zero (0) to turn all logging off but leave the Debug tab active for future use.

The Debug Options screen begins with the "Debug Options" section, containing:

Display Limit	lets you limit the amount of log information copied to the text area for display. Setting a limit to, for example, 262144 will display the last 256 Kb of the file; this can be useful if the log file gets very large.
Debug File	lets you specify a text file other than the PHP error log to receive the MLA-specific messages. The absolute path to the `/wp-content/` directory will be prepended to the value you enter. If the file does not exist an attempt will be made to create it. You can enter values such as "my-log.txt" or "/mylogs/my-log.txt". In the latter case, the "/mylogs/" directory must already exist; MLA will not create it.
Replace PHP error_log file	lets you change the PHP error_log destination. You can use this to add PHP Notice, Warning and Error messages to the MLA Debug File. It's best to leave this box unchecked unless you are actively monitoring the MLA Debug file so PHP messages go to the default location.
PHP Reporting	Sets which PHP errors are reported, overriding the value set in the `php.ini` file and the `wp-config.php` file. Setting a limit to, for example, 0x7FFF will display all PHP Notices and "Strict" messages (E_ALL \| E_STRICT). It's best to leave this box blank unless you are actively debugging MLA so the normal PHP error_level is observed.
MLA Reporting	lets you change the MLA_DEBUG_LEVEL without modifying the `wp-config.php` file. You can change any of the additional reporting categories but not the lowest bit which turns the Debug tab on and off. You can set the option to zero (0) to turn all logging off but leave the Debug tab active.

Below the Debug Options section is a list of settings and values that are useful for debugging investigation. If you are posting error information in an MLA Support Forum topic, be sure to add these values to your post to get a quicker resolution to your question or problem.

Below the Debug Settings section is a text area with the current content of the PHP (or MLA-specific) error log file. Below the text box are three action buttons:

Download - click this button to download a copy of the error log to your system.
Reset - click this button to erase the contents of the error log.
Save Changes - click this button to save a new value for the Display Limit option.

If you are having an MLA problem that includes error messages in the log, copying the messages and adding them to your Support Forum topic can be most helpful; thanks!

Go to Top

WPML & Polylang Multilingual Support; the MLA Language Tab

Media Library Assistant provides integrates support for two popular "Multilanguage/ Multilingual/ Internationalization" plugins; WPML and Polylang. These plugins let you write posts and pages in multiple languages and make it easy for a visitor to select the language in which to view your site. MLA works with the plugins to make language-specific Media library items easy to create and manage.

MLA detects the presence of either plugin and automatically adds several features that work with them:

Language-specific filtering of the [mla_gallery] and [mla_tag_cloud] shortcodes.
Media/Assistant submenu table enhancements for displaying and managing item translations.
Term Assignment and Term Synchronization, to match terms to language-specific items and automatically keep all translations for an item in synch.
Term Mapping Replication, to manage the terms created when mapping taxonomy terms from IPTC/EXIF metadata.

Items, Translations and Terms

Each Media Library item can have one or more "translations". The item translations are linked and they use the same file in the Media Library. The linkage lets us know that "¡Hola Mundo!" (Spanish), "Bonjour Monde" (French) and "Hello world!" (English) are all translations of the same post/page. Post/page translation is optional; some posts/pages may not be defined for all languages. The language of the first translation entered for a post/page is noted as the "source language".

Taxonomy terms can also have one or more translations, which are also linked. The linkage lets us know that "Accesorio Categoría" (Spanish), "Catégorie Attachment" (French) and "Attachment Category" (English) are all translations of the same term. Term translation is optional; some terms may not be defined for all languages. The language of the first translation entered for a term is noted as the "source language".

When an item is uploaded to the Media Library it is assigned to the current language (note: avoid uploading items when you are in "All Languages"/"Show all languages" mode; bad things happen). WPML provides an option to duplicate the new item in all active languages; Polylang does not. MLA makes it easy to add translations to additional languages with the Translations column on the Media/Assistant submenu table. For Polylang, MLA provides Quick Translate and Bulk Translate actions as well.

Assigning language-specific terms to items with multiple translations can be complex. MLA's Term Assignment logic assures that every term you assign on any of the editing screens (Media/Add New Bulk Edit, Media/Edit, Media/Assistant Quick Edit and Bulk Edit, Media Manager ATTACHMENT DETAILS pane) will be matched to the language of each item and translation. MLA's Term Synchronization logic ensures that changes made in one translation are replicated to all other translations that have an equivalent language-specific term.

Shortcode Support

The [mla_tag_cloud] shortcode selects terms using the WordPress wpdb class. MLA adds language qualifiers to the database queries that compose the cloud so all terms displayed are appropriate for the current language. No special coding or shortcode modification is required.

Media/Assistant submenu table

Two columns are added to the table when WPML or Polylang is active:

Language - displays the language of the item. This column is only present when "All languages/Show all languages" is selected in the admin toolbar at the top of the screen.
"Translations" - displays the translation status of the item in all active languages. The column header displays the flag icon for the language. The column content will have a check mark icon for the item's language, a pencil icon for an existing translation or a plus icon for a translation that does not exist. You can click any icon to go directly to the Media/Edit Media screen for that translation. If you click a plus icon, a new translation will be created and initialized with content and terms from the current item and you will go to the Media/Edit Media screen for the new translation.

When Polylang is active, several additional features are available:

A Language dropdown control is added to the Quick Edit and Bulk Edit areas. You can change the language of one or more items by selecting a new value in the dropdown and clicking Update. The new language must not have an existing translation; if a translation already exists the change will be ignored.
Translation status links are added to the Quick Edit area, just below the Language dropdown control. If you click one of the pencil/plus translation status links, a new Quick Edit area will open for the translation you selected. A new translation is created if you click a plus status icon.
A Quick Translate rollover action can be added to each item (the default option setting is "unchecked"). If you activate this option, when you click the "Quick Translate" rollover action for an item the Quick Translate area opens, showing the Language dropdown control and the translation status links. From there, click "Set Language" to change the language assigned to the item or click one of the pencil/plus translation status links. A new Quick Edit area will open for the translation you selected. A new translation is created if you click a plus status icon.
A Translate action is added to the Bulk Actions dropdown control. If you click the box next to one or more items, select Translate in the Bulk Actions dropdown and click Apply, the Bulk Translate area will open. The center column contains a checkbox for each active language and an "All Languages" checkbox. Check the box(es) for the languages you want and then click "Bulk Translate". The Media/Assistant submenu table will be refreshed to display only the items you selected in the language(s) you selected. Existing translations will be displayed, and new translations will be created as needed so every item has a translation in every language selected.

Term Management

Taxonomy terms are language-specific, and making sure the right terms are assigned to all items and translations can be a challenge. Terms can change when an item is updated in any of five ways:

Individual edit - this is the full-screen Media/Edit Media submenu provided by WordPress. Taxonomies are displayed and updated in meta boxes along the right side of the screen. When "Update" is clicked whatever terms have been selected/entered are assigned to the item; they replace any old assignments.
Media Manager Modal Window - this is the popup window provided by WordPress' "Add Media" and "Select Featured Image" features. Taxonomies are displayed and updated in the ATTACHMENT DETAILS meta boxes along the right side of the window. Whatever terms are selected/entered here are assigned to the item; they replace any old assignments.
Quick Edit - this is a row-level action on the Media/Assistant screen. When "Update" is clicked whatever terms have been selected/entered are assigned to the item; they replace any old assignments.
Bulk edit - this is a bulk action on the Media/Assistant screen, and is also available on the Media/Upload New Media screen. In the Bulk Edit area, terms can be added or removed or all terms can be replaced. The bulk edit can be applied to multiple item translations in one or more languages.
IPTC/EXIF Metadata Mapping - this is done by defining rules in the "Taxonomy term mapping" section of the IPTC & EXIF Processing Options. The mapping rules can be run when new items are added to the Media Library, from the Settings/Media Library Assistant IPTC/EXIF tab, from the Media/Assistant Bulk Edit area or from the Media/Edit Media submenu screen.

When terms change in any of the above ways there are two tasks that require rules:

How should language-specific terms be assigned to items selected? This is "Term Assignment".
How should terms assigned to one translation of an item be used to update other translations of the same item? This is "Term Synchronization".

When new terms are added during IPTC/EXIF taxonomy term mapping a third task is required; should new terms be added only to the current language or should they be made available in all languages? This is "Term Mapping Replication".

Term Assignment

When a specific language is selected only the item translations for that language are shown, and only the terms for that language are displayed (except for a Polylang bug that shows all languages in the "auto-complete" list for flat taxonomies). When "All Languages"/"Show all languages" is selected the terms for all languages are displayed even if they cannot be assigned to an item. For example, a Spanish term may appear in the list be cannot be assigned to an English item translations.

For individual edit and quick edit updates the rule is simple:

For all terms selected/entered, find the equivalent term in the language of the item translation. Assign the equivalent (language-specific) term if one exists. If no equivalent term exists, ignore the selected/entered term. Assign all equivalent terms to the item translation, replacing any previous terms.

For bulk edit updates the rule depends on which action (add, remove, replace) has been selected. Each of the item translations in the bulk edit list is updated by these rules:

Add: For all terms selected/entered, find the equivalent term in the language of the item translation. Assign the equivalent (language-specific) term if one exists. If the equivalent term exists, add it to the item translation.
Remove: For all terms selected/entered, find the equivalent term in the language of the item translation. Assign the equivalent (language-specific) term if one exists. If the equivalent term exists, remove it from the item translation.
Replace: This is the tricky case. What should happen to terms already assigned to an item translation that have not been selected/entered for the update? In particular, what about terms that do not have translations to all languages? Should a "French-only" term be preserved?

The "Replace" answer is the same as the individual/quick edit answer. If the term is not selected/entered for the update it is discarded along with the other old assignments. After all, in "All Languages"/"Show all languages" mode the "French-only" term would have been in the list and could be selected if desired.

Term Synchronization

If you edit an item translation, for example to add or remove a term assignment, what should happen to the other translations of the same item? Term synchronization will add or remove the equivalent term in the other item translations if the equivalent term exists.

What about "untranslated" terms that do not have translations to all languages? Should an existing "French-only" (untranslated) term be preserved? It is, since there is no way to indicate that it should be removed.

Individual and quick edits are "replace" updates, and "replace" is an option for bulk edits as well. For term synchronization to preserve untranslated terms "replace" updates must be converted to separate "add" and "remove" updates that include only the changes made to the original item translation. For example, if these terms are defined:

English	Spanish
Common-term-1-eng	Common-term-1-esp
Common-term-2-eng	Common-term-2-esp
English-only-term
	Spanish-only-term

And these term assignments exist:

English Translation	Spanish Translation
Common-term-1-eng	Common-term-1-esp
English-only-term
	Spanish-only-term

Then synchronization handles common editing actions as follows:

If you edit the English Translation and add "Common-term-2-eng", synchronization will add "Common-term-2-esp" to the Spanish Translation.
If you edit the English Translation and remove "Common-term-1-eng", synchronization will remove "Common-term-1-esp" from the Spanish Translation.
If you edit the English Translation and remove "English-only-term", nothing will happen to the Spanish Translation.

Term Mapping Replication

When rules are defined in the IPTC/EXIF "Taxonomy term mapping section" they extract values (e.g., "IPTC 2#025 Keywords") from image metadata and use them to assign terms to the Media Library item(s). If the metadata value matches an existing term in the item's language it is assigned to the item. If the term already exists for any other active language it is not assigned to the item. If the term does not exist in any of the active languages, i.e., it is an entirely new term, a decision is required. The "Term Mapping Replication" option controls the decision:

When Replication is active, the term is created in the current language and then copied to every other active language as a translation of the term in the current language.
When Replication is not active, the term is created in the current language only. It is not copied to any other active language and will not be assigned to items in any language other than the current language.

If you use Replication to automatically create terms in non-current languages they will be created with the same text value as the source term in the current language. You can always go to the taxonomy edit page and change the source text to an appropriate value for the other language(s). If you do not use Replication you can always go to the taxonomy edit page and add translations with an appropriate value for the other language(s).

Go to Top

The Example Plugins

The Documentation/Example Plugins submenu lets you browse the list of MLA example plugins, install or update them in the Plugins/Installed Plugins area and see which examples you have already installed. To activate, deactivate or delete the plugins you must go to the Plugins/Installed Plugins admin submenu.

The Example plugins submenu lists all of the MLA example plugins and identifies those already in the Installed Plugins area. In the submenu:

the "Screen Options" dropdown area lets you choose which columns to display and how many items appear on each page
the "Help" dropdown area gives you a brief explanation of the submenu content and functions
the "Search Plugins" text box lets you filter the display to items containing one or more keywords or phrases
bulk and rollover actions are provided to install or update example plugins
the table can be sorted by any of the displayed columns

You can use the "View" rollover action to display the source code for an example plugin. Many of the plugins have documentation and use notes in a comment area at the top of the source file. They also have references to the Support Forum topics that inspired them, which can be an additional source of information.

You can use the "Download" rollover action to download a plugin to your local system. Once you have made your modifications you can copy the plugin to a compressed file (ZIP archive) and then upload it to your server with the Plugins/Add New (Upload Plugin) admin submenu.

If you do make changes to the example plugin code the best practice is to save the modified file(s) under a different name, so your changes won't be lost in a future update. If you want to retain the file name, consider changing the version number, e.g. adding 100 to the MLA value, so you can more easily identify the plugins you have modified.

limit	the maximum number of terms to display in one cloud "page". Think of this as a "terms per page" value.
offset	the number of terms to skip over before starting the current cloud page. This parameter is usually derived automatically from the more useful "mla_cloud_current" parameter.
mla_page_parameter	the name of the parameter containing the current page number; default "mla_cloud_current". You can change the name if you need multiple paginated clouds on one post/page.
mla_cloud_current	the current cloud page number. The name of this parameter can be changed to support multiple paginated clouds on one post/page. This parameter will automatically be added to the URLs generated by pagination output types and managed for you.
term_id	the id of the current term within the cloud. This parameter is used with the "previous_link", "current_link" and "next_link" output types. You must supply a term_id value when using these output types.

[mla_gallery]

Creating Thumbnails (pdfs) w/ MLA

Complete documentation

MLA Gallery Shortcode

Option/Parameter Documentation Sources

Substitution Parameters

Entering Long/Complex Shortcodes

Gallery Display Style

Gallery Display Content

Thumbnail Substitution Support, mla_viewer

Order, Orderby

Size

Link

Transfer by Item Name

Include, Exclude

Post ID, "ids", Post Parent

Author, Author Name

Category Parameters

Tag Parameters

Simple Taxonomy Parameters

Compound Taxonomy Queries, "tax_input"

Taxonomy Queries, the "tax_query"

Taxonomy term keyword(s) search

Post MIME Type

Post Type, Post Status

Pagination Parameters

Simple Date Parameters

Date and Time Queries, the "date query"

Simple Custom Field Parameters

Custom Field Queries, the "meta_query"

Keyword(s) Search

Caching Parameters

Debugging Output

MLA Gallery Filters and Actions (Hooks)

MLA Gallery Examples

Simple Examples

A Paginated Gallery

Tag Cloud and Gallery

Search Form and Gallery

Support for Alternative Gallery Output, e.g., Pagination

The mla_output parameter

Next and previous gallery items; the next_link and previous_link output types

Next and previous gallery pages; the next_page and previous_page output types

An example of the next_page and previous_page output types

Page selection parameters for next_page and previous_page output types

Gallery Display Content parameters for next_page and previous_page output types

Markup Substitution Parameters for next_page and previous_page output types

Generalized paginated link list; the paginate_links output type

Specific parameters for the paginate_links output type

An example of the paginate_links output type

Support for Other Gallery-generating Shortcodes

Support for the “Photonic Gallery for Flickr, Picasa, SmugMug, 500px and Instagram” Plugin

Support for the “Real Media Library” Plugin

Style and Markup Templates

Argument Substitution Parameters

Gallery-specific Substitution Parameters

Substitution parameters for style templates

Substitution parameters for markup templates

Attachment-specific substitution parameters for the markup template Item part

Field-level substitution parameters for the markup template Item part

A Table-based Style and Markup Template Example

Style Template

Markup Template

[mla_tag_cloud]

Complete documentation

MLA Tag Cloud Shortcode

Tag Cloud Output Formats

Tag Cloud Item Parameters

Tag Cloud Item Link

Tag Cloud Display Style (list and grid)

Tag Cloud Display Content

Tag Cloud Data Selection Parameters

Debugging Output

Tag Cloud Substitution Parameters

Tag Cloud Pagination Parameters

Tag Cloud Pagination Example

MLA Tag Cloud Filters (Hooks)

[mla_term_list]

Complete documentation

MLA Term List Shortcode

The `mla_output` parameter

Next and previous gallery items; the `next_link` and `previous_link` output types

Next and previous gallery pages; the `next_page` and `previous_page` output types

An example of the `next_page` and `previous_page` output types

Page selection parameters for `next_page` and `previous_page` output types

Gallery Display Content parameters for `next_page` and `previous_page` output types

Markup Substitution Parameters for `next_page` and `previous_page` output types

Generalized paginated link list; the `paginate_links` output type

Specific parameters for the `paginate_links` output type

An example of the `paginate_links` output type

The `,match(p)` option/format value

The `,extract(p,v)` option/format value

The `,replace(p,r,v)` option/format value

The `matches:` field-level prefix