[mla_gallery]
Enhanced version of the WordPress [gallery] shortcode.
[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
<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 themy_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.
Tag Cloud and Gallery
Adding the "taxonomy=term" parameter to your shortcode is all well and good, but letting the viewer choose a term when they view the post/page is often better. One easy way to do this is to add the [mla_tag_cloud]
shortcode. Here is a simple combination of a cloud and a gallery display:
[mla_tag_cloud taxonomy=attachment_category number=0 mla_link_href="{+page_url+}?term_slug={+slug+}"]
[mla_gallery attachment_category="{+template:({+request:term_slug+}|a-bad-term)+}" mla_nolink_text="Click a term to display the gallery."]
The [mla_tag_cloud]
displays Att. Categories terms in the familiar cloud format. The number=0
parameter ensures that all of the terms are displayed. The mla_link_href
parameter links each term back to the current page ({+page_url}
) and passes a variable back with the term selection (?term_slug={+slug+}
). If you put the [mla_tag_cloud]
shortcode on another page or in a widget you will have to hard-code the URL portion of the link.
The [mla_gallery]
displays the images assigned to the selected attachment_category term. The mla_nolink_text
parameter gives the text to display when the gallery is empty, e.g., before you click on a term. In this shortcode:
- The
template:
prefix says that this is a Content Template - The parentheses "()" around the two elements are used to group them into a list of alternatives
- The vertical bar "|" between the two elements means "stop when you get a non-empty alternative"
{+request:term_slug+}
will be empty unless there is a term_slug in the URLa-bad-term
is a literal value (and thus never empty) which does not match any term in the attachment_category taxonomy, so the gallery will be empty if this alternative is used
You can read more about templates in the Content Templates section. You can paginate your gallery by adding a third shortcode to the post/page. Put the new shortcode between the cloud and gallery so the pagination controls will appear above the gallery display:
[mla_tag_cloud taxonomy=attachment_category number=0 mla_link_href="{+page_url+}?term_slug={+slug+}"]
[mla_gallery attachment_category="{+template:({+request:term_slug+}|a-bad-term)+} posts_per_page=12" mla_output="paginate_links,prev_next" mla_link_href="{+page_url+}?term_slug={+request:term_slug+}"]
[mla_gallery attachment_category="{+template:({+request:term_slug+}|a-bad-term)+}" posts_per_page=12 mla_nolink_text="Click a term to display the gallery."]
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 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+}?term_slug={+request:term_slug+}"
parameter is added so the pagination controls pass the term_slug
from page to page.
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.
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.
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.
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.
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.
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 |
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 |
Substitution parameters for markup templates
All of the
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.
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+] |
Row Open | <tr class='gallery-row'> |
Item | <td class='gallery-icon'> |
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.
Tag Cloud Output Formats
The traditional tag cloud output is a "heat map" of term names where larger names are associated with more attachments than smaller names. 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. "flat" is the default output format value. |
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. |
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. |
grid | Modeled on the galleries produced by [mla_gallery] ; a rectangular display with rows and columns. The tag parameters listed above, the "columns" parameter and the Display Style parameters customize the display. |
array | Returns a PHP array of cloud hyperlinks. This output format is not available through the shortcode; it is allowed when the MLAShortcodes::mla_tag_cloud() function is called directly from your theme or plugin PHP code. |
The list and grid formats can be extensively customized by using custom . The [mla_tag_cloud]
shortcode also supports pagination with "previous_link", "current_link", "next_link", "previous_page", "next_page" and "paginate_links" formats. These are essentially the same as those for the [mla_gallery]
shortcode.
Tag Cloud Item Parameters
Each item in the tag cloud comprises a term name of varying size, 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:
smallest | The text size (default 8) of the tag with the smallest count value (units given by unit parameter). |
largest | The text size (default 22) of the tag with the highest count value (units given by the unit parameter). |
unit | Unit of measure as pertains to the smallest and largest values. This can be any CSS length value, e.g. pt (the default), px, em, %. |
separator | The text/space between tags. Default '\n' (whitespace) |
single_text | The text for the "title" attribute (Rollover Text) when the count value is one. The default is "%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. The default is "%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. |
current_item | Identifies the current/selected item in the cloud. 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 cloud. |
current_item_class | The class attribute for the current item in the cloud 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 cloud item. For the list and grid formats you can also use the
Tag Cloud Item Link
The Link parameter specifies the target and type of link from the tag cloud term/item to the item's archive page, edit page or other destination. You can also specify a non-hyperlink treatment for each item.
current | Link back to the current post/page with a query argument, current_item , set to the term_id of the selected term. |
view | Link to the term's "archive page"; this is the default value. 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 pagination 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 tag cloud to select a term and then go to another post/page that uses that selection as part of an [mla_gallery]
shortcode. The pagination example later in this section uses this technique.
Tag Cloud Display Style (list and grid)
Two parameters provide a way to apply custom style and markup templates to your [mla_tag_cloud]
display. These parameters replace the default style and/or markup templates with templates you define on the "MLA Gallery" tab of the Settings page. Templates are supported for the "list" and "grid" cloud formats.
mla_style | replaces the default style template for an [mla_tag_cloud] shortcode. You can code "none" to suppress the addition of CSS inline styles entirely. |
mla_markup | replaces the default markup template for an [mla_tag_cloud] shortcode |
Three parameters provide control over the placement, size and spacing of terms in the "grid" format without requiring the use of custom Style templates.
mla_float | specifies the CSS float attribute of the ".tag-cloud-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 ".tag-cloud-item" style. The default value is "1.5%", a percent of the total grid 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 ".tag-cloud-item" style. You can specify a percent of the total grid 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 margin 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%. |
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 also code mla_style=none
to suppress inline styles entirely and use a separate stylesheet to control the format of the grid.
Three parameters provide control over the XHTML tags used to enclose each part of the tag cloud items. These parameters are only used in the "list" and "grid" output formats.
itemtag | for "list" format, the name of the XHTML tag used to begin the list; the default is "ul". When an explicit "captiontag" parameter is added to "list" format, the default is "dl". For "grid" format, the name of the XHTML tag used to enclose each item in the cloud; the default is "dl". |
termtag | the name of the XHTML tag used to enclose each term in the cloud. For "list" format, the default is "li"; for "grid" format or when an explicit "captiontag" parameter is added to "list" format, the default is "dt". |
captiontag | the name of the XHTML tag used to enclose each caption. For "grid" format, the default is "dd". To add a caption in "list" format you must enter an explicit "captiontag=dd" parameter to the shortcode. |
These parameters give you some control over the markup used for the cloud and its elements. For more complex applications you can use style and markup templates to gain complete control over the cloud display.
Tag Cloud Display Content
Nine parameters provide an easy way to control the contents of tag cloud 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_style | replaces the CSS styles for the hyperlink. The default style is font-size: [+font_size+][+unit+] . |
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 cloud items or no pagination link |
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 "grid" 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 |
All but the "mla_target" parameter support the Markup, Item-specific, Field-level and Content Template substitution parameters defined for Markup Templates. For example, if you code "mla_rollover_text='{+slug+} : {+rollover_text+}'
, the rollover text will contain the term slug, a colon, and the appropriate "single text" or "multiple text". 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 cloud 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 "viewlink" and "editlink" are not modified.
The "mla_link_attributes" parameter accepts any value and adds it to the "<a>" or "<span>" tags for the item. For example, you can add a unique identifier to each item by adding mla_link_attributes='id="{+selector}-{+index+}"'
to your shortcode (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. 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_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.
Tag Cloud Data Selection Parameters
The data selection parameters specify which taxonomy (or taxonomies) the terms are taken from, which terms are returned for the cloud 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_tag_cloud() 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 cloud. 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 |
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 final sort order of the retrieved terms. Can be one or more of "count", "id" (term_id), "name" (the default), "none", "random", or "slug". Coding "none" is equivalent to "orderby=count order=DESC" (the initial sort to qualify the most popular terms for the cloud).
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 . |
no_orderby | The default, "false", applies the orderby and order parameters to the final term list. If you have a large number of terms and/or attachments, this can take a long time. You can code "true" to omit both the initial sort (most popular terms) and the final sorting process. If you do that, the sort order of the cloud will be indeterminite. |
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. |
limit | The number of terms to return. This parameter is used for pagination; it is applied after and separate from the "number" parameter above. |
offset | The number of terms to skip before returning the results. This parameter is used for pagination. |
You can sort on more than one value, e.g., orderby="count DESC, name"
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="count DESC, name" order=ASC
is the same as orderby="count DESC, name ASC"
.
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.
Tag Cloud 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_link_href="{+page_url+}?current_id={+term_id+}&mla_cloud_current={+request:mla_cloud_current+}"
, the hyperlinks behind each cloud term will contain the page URL and the taxonomy term ID. There are many parameter names like `page_url` and `term_id` divided in several categories:
Cloud-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 cloud-specific CSS inline styles are composed just before cloud output begins |
Markup | values that are known at the beginning of cloud output processing and remain the same for the entire cloud |
Item-specific | values that change for each term/item in the cloud, 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 cloud. The other prefixes are attachment-specific and have no meaning in a cloud |
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.
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 "\\}".
Cloud-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 cloud based on information about the post/page on which the cloud appears. The cloud-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_tag_cloud-{$instance}", e.g., mla_tag_cloud-1 |
page_ID, id |
the ID value of the post/page in which the cloud appears |
page_author | the post_author value of the post/page in which the cloud appears |
page_date | the post_date value of the post/page in which the cloud appears |
page_content | the post_content value of the post/page in which the cloud appears |
page_title | the post_title value of the post/page in which the cloud appears |
page_excerpt | the post_excerpt value of the post/page in which the cloud appears |
page_status | the post_status value of the post/page in which the cloud appears |
page_name | the post_name value of the post/page in which the cloud appears |
page_modified | the post_modified value of the post/page in which the cloud appears |
page_guid | the post_guid value of the post/page in which the cloud appears |
page_type | the post_type value of the post/page in which the cloud appears |
page_url | absolute URL to the page or post on which the cloud appears, if any, with trailing slash |
Style and Markup templates give you great flexibility for the content and format of each [mla_tag_cloud] when you use the "list" and "grid" output formats. You can define as many templates as you need.
Style templates provide 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 cloud, 2) the beginning of each row ("grid" format), 3) each cloud item, 4) the end of each row ("grid" format) and 5) the end of the cloud. 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.
For the "grid" output format, all of the Markup template sections are used. For the "list" output format, only the "Open", "Item" and "Close" sections are used. There are two default templates for the "list" format; "tag-cloud-ul" and "tag-cloud-dl". As the names imply, the "tag-cloud-dl" default is used 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_tag_cloud] shortcode. For example, if your shortcode is [mla_tag_cloud 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. |
Tag cloud substitution parameters for the Style template are:
mla_output | shortcode parameter, default = 'flat' |
mla_style | shortcode parameter, default = 'tag-cloud' |
mla_markup | shortcode parameter, default = 'tag-cloud-ul', or 'tag-cloud-dl' if the "captiontag" parameter is present. |
taxonomy | the slug of the taxonomy on which the cloud is based. Multiple taxonomy slugs are joined with a dash to form a single value. |
current_item | the current/selected item in the cloud, as entered in the shortcode parameters. |
itemtag | shortcode parameter, default = 'ul', 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. |
columns | shortcode parameter, default = '3'; only meaningful for the "grid" output format. |
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 |
found_rows | the number of terms retrieved for the cloud |
min_count | the smallest number of attachments associated with any term |
max_count | the largest number of attachments associated with any term |
min_scaled_count | the smallest scaled count associated with any term |
max_scaled_count | the largest scaled count associated with any term |
spread | max_scaled_count - min_scaled_count |
smallest | the text size of the tag with the smallest count value |
largest | the text size of the tag with the largest count value |
unit | Unit of measure as pertains to the smallest and largest values |
font_spread | largest - smallest |
font_step | font_spread / spread |
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' |
Tag cloud substitution parameters for the Markup template are available in all of the template sections. All of the cloud-specific substitution parameters and the substitution parameters for Style templates are available for use in markup templates. There are no additional substitution parameters defined at the start of markup processing, but there are
Tag cloud item-specific substitution parameters for the Markup template are available in the "Item" section of the template. They include all of the parameters defined above (for the Style and Markup templates) Additional item-specific parameters are:
index | starts at '1', incremented for each item in the cloud |
last_in_row | for the "grid" output format, set to "last_in_row" for the last item in each full cloud row, and to an empty string for all other items in the row. If the cloud ends with a partial row, the last_in_row parameter is not set. |
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 |
scaled_count | scaled count value, for determining font size. The default formula for scaling the count is round(log10($tag->count + 1) * 100) |
font_size | the numeric portion of the CSS "font-size" attribute |
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 |
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 |
current_item_class | set to "mla_current_item" for the current item in the cloud as determined by the "current_item" parameter, and to an empty string for all other items in the cloud. |
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 |
Tag Cloud Pagination Parameters
If you have a large number of terms in your cloud taxonomy you may want to paginate the cloud display, i.e., divide the cloud into two or more pages of a reasonable size. Pagination support for [mla_tag_cloud]
is modeled on similar functions for[mla_gallery]
, and you can find more explanation of the ideas behind pagination in the section. Five parameters are supplied for this purpose:
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. |
The [mla_tag_cloud]
shortcode can be used to provide "Previous" and "Next" links that support moving among the individual items in a cloud or among cloud "pages". For example, if you have many terms in your Att. Category or Att. Tag taxonomies you can build a term-specific [mla_gallery]
page with links to the previous/next term in the taxonomy (a complete pagination example is included below). You can also build a page that shows a large taxonomy in groups, or "cloud pages", of ten terms with links to the previous/next ten terms or links to all of the cloud pages of terms in the taxonomy.
The "mla_output" parameter determines the type of output the shortcode will return. For pagination output, you can choose from six values:
next_link | returns a link to the next cloud item, based on the "term_id" parameter value. The optional ",wrap" qualifier determines what happens at the end of the cloud. If you omit the qualifier, an empty string is returned for the "next_link" from the last item. If you code the ",wrap" qualifier, the "next_link" from the last item will be to the first item. |
current_link | returns a link to the current cloud item, based on the "term_id" parameter value. This gives you an easy way to provide a visual indication of where you are within the taxonomy. The "span" and "none" link formats are often used with this mla_output type. |
previous_link | returns a link to the previous cloud item, based on the "term_id" parameter value. The optional ",wrap" qualifier determines what happens at the beginning of the cloud. If you omit the qualifier, an empty string is returned for the "previous_link" from the first item. If you code the ",wrap" qualifier, "previous_link" from the gallery item will be to the last item. |
next_page | returns a link to the next "page" of cloud items, based on the "mla_cloud_current" parameter value. The optional ",wrap" or ",last" qualifiers determine what happens at the end of the taxonomy. If you omit the qualifier, an empty string is returned for the "next_page" if there are no more items in the taxonomy. If you code the ",wrap" qualifier, the "next_page" from the last page of items will be to the first page. If you code the ",last" qualifier, the "next_page" link will return to/remain on the last page. |
previous_page | returns a link to the previous "page" of cloud items, based on the "mla_cloud_current" parameter value. The optional ",wrap" or ",first" qualifiers determine what happens at the beginning of the taxonomy. If you omit the qualifier, an empty string is returned for the "previous_link" from the first page. If you code the ",wrap" qualifier, "previous_page" from the first page will be to the last page. If you code the ",first" qualifier, the "previous_link" link will return to/remain on the first page. |
paginate_links | returns a link to cloud items at the start and end of the list and to pages around the current "cloud page" ( e.g.: « Previous 1 ... 3 4 5 6 7 ... 9 Next » ), based on the "mla_cloud_current" parameter value. The optional ",show_all" qualifier will show all of the cloud 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. |
The best way to understand cloud pagination is by example, as in the next section below.
Tag Cloud Pagination Example
This section takes you through several of the [mla_tag_cloud]
features, step by step. Let's start with a very simple cloud showing all of the terms in the "Att. Category" taxonomy:
[mla_tag_cloud taxonomy=attachment_category number=0]
The "number=0" parameter overrides the default maximum of 45 terms, showing all of the terms in the taxonomy. Let's paginate the cloud and limit the terms display to ten terms per "page":
[mla_tag_cloud taxonomy=attachment_category number=0 limit=10]
[mla_tag_cloud taxonomy=attachment_category number=0 limit=10 mla_output="paginate_links,prev_next"]
The "limit=10" parameter (on both shortcodes) limits the term display to ten terms. The second [mla_tag_cloud]
shortcode, adding the 'mla_output="paginate_links,prev_next"' parameter, displays a line of pagination links below the cloud page. Coordination between the two shortcodes is automatic, using the "mla_cloud_current" parameter added to the URLs by the shortcode.
Now we'll make the cloud a convenient way to control a term-specific [mla_gallery]
. The next step uses the "mla_link_href" parameter to change the link destination of each cloud term, returning to the current page with the term id of the selected term. We also add the "mla_cloud_current" parameter to each of these new links, so the tag cloud page is retained when a term is selected:
[mla_tag_cloud taxonomy=attachment_category number=0 limit=10 mla_link_href="{+page_url+}?current_id={+term_id+}&mla_cloud_current={+request:mla_cloud_current+}"]
[mla_tag_cloud taxonomy=attachment_category number=0 limit=10 mla_output="paginate_links,prev_next"]
The "&" before the "mla_cloud_current" parameter is required to get by the WordPress Visual Editor. The "{+request:mla_cloud_current+}" value copies the current page number from the URL ($_REQUEST array) and adds it to each term's link. Now, let's use the "current_id={+term_id+}" information in the link to compose a term-specific [mla_gallery]
:
[mla_tag_cloud taxonomy=attachment_category number=0 limit=10 mla_link_href="{+page_url+}?current_id={+term_id+}&mla_cloud_current={+request:mla_cloud_current+}"]
[mla_tag_cloud taxonomy=attachment_category number=0 limit=10 mla_output="paginate_links,prev_next"]
[mla_gallery post_mime_type=all tax_query="array ( 0 => array ( 'taxonomy' => 'attachment_category', 'field' => 'id', 'terms' => array( {+request:current_id+} ), 'include_children' => false ) )" mla_caption="{+title+}" columns=5 size=icon link=file]
The most complicated part of the new shortcode is the "tax_query" parameter, which we're using to ensure that the gallery items displayed match the count displayed for each term in the tag cloud. The tag cloud count does not contain items associated with any "child terms", or sub-categories, of the cloud item. To match this count we must use the "include_children=false" and "field=id" parameters of the "tax_query".
We can easily paginate the term-specific gallery by adding a second [mla_gallery]
shortcode and a "posts_per_page" parameter to both shortcodes:
[mla_tag_cloud taxonomy=attachment_category number=0 limit=10 mla_link_href="{+page_url+}?current_id={+term_id+}&mla_cloud_current={+request:mla_cloud_current+}"]
[mla_tag_cloud taxonomy=attachment_category number=0 limit=10 mla_output="paginate_links,prev_next"]
[mla_gallery post_mime_type=all tax_query="array ( 0 => array ( 'taxonomy' => 'attachment_category', 'field' => 'id', 'terms' => array( {+request:current_id+} ), 'include_children' => false ) )" mla_caption="{+title+}" columns=5 posts_per_page=5 size=icon link=file]
[mla_gallery post_mime_type=all tax_query="array ( 0 => array ( 'taxonomy' => 'attachment_category', 'field' => 'id', 'terms' => array( {+request:current_id+} ), 'include_children' => false ) )" columns=5 posts_per_page=5 mla_output="paginate_links,prev_next"]
The pagination controls for the tag cloud and the gallery operate independently because by default they use different names for their respective "_current" page parameters. Our page now has a lot of functionality without requiring any WordPress templates or PHP code.
For extra credit, let's add some more navigation options to the page. We'll build previous, current and next term links at the bottom of the page. These are enclosed in an HTML table so they all appear on one line of the page. Here is just the additional content; the table of three link navigation controls:
<table width=99%><tr>
<td width=33% style="text-align: left">[mla_tag_cloud taxonomy=attachment_category number=0 term_id="{+request:current_id+}" mla_output="previous_link" smallest=12 largest=12 mla_link_href="{+page_url+}?current_id={+term_id+}" mla_link_text="Previous: {+name+}"]</td>
<td width=33% style="text-align: center; font-weight: bold:">[mla_tag_cloud taxonomy=attachment_category number=0 term_id="{+request:current_id+}" mla_output=current_link smallest=12 largest=12 mla_link_text="Current: {+name+}" link=span]</td>
<td width=33% style="text-align: right">[mla_tag_cloud taxonomy=attachment_category number=0 term_id="{+request:current_id+}" mla_output="next_link" smallest=12 largest=12 mla_link_href="{+page_url+}?current_id={+term_id+}" mla_link_text="Next: {+name+}"]</td>
</tr></table>
The "smallest=12" and "largest=12" parameters make "font-size" the same for all of the term names regardless of how many items are associated with the term. The "mla_link_text" parameters add labels to each of the three navigation links. Finally, the "link=span" parameter in the middle ("mla_output=current_link") shortcode removes the hyperlink behind the term name, since it would just take you back to the page you're already on.
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 themy_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.
- CDN-tag
- cheat-sheets-tag
- CODING-tag
- Design-tag
- do-it-yourself-tag
- essential-grid-ptag
- FONTS-tag
- MAC
- Overviews-tag
- postie
- SEO-tag
- site-controls
- svg-tag
- Tools-tag
- Virtualbox
- WEBSITES-tag
- WORDPRESS-tag
- wpcli-tag
- ZSH-tag
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 |
All but the "mla_target" parameter support the Markup, Item-specific, Field-level and Content Template substitution parameters defined for Markup Templates. For example, if you code "mla_rollover_text='{+slug+} : {+rollover_text+}'
, the rollover text will contain the term slug, a colon, and the appropriate "single text" or "multiple text". 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 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.
The "mla_link_attributes" parameter accepts any value and adds it to the "<a>" or "<span>" tags for the item. For example, you can add a unique identifier to each item by adding mla_link_attributes='id="{+selector}-{+index+}"'
to your shortcode (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. 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_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.
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.
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.
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 |
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. |
You can sort on more than one value, e.g., orderby="count DESC, name"
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="count DESC, name" order=ASC
is the same as orderby="count DESC, name ASC"
.
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+}¤t_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.
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 "\\}".
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 themy_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.
![Mla Shortcode Options](https://mlxzzgdzt2jx.i.optimole.com/cb:yX5x.1db17/w:auto/h:auto/q:mauto/f:best/ig:avif/https://clickety-clack.click/img/mla-shortcode-options-800x588.png)
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
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.
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”:[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')"]
-
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:
[mla_gallery post_mime_type=application/pdf post_parent=all link=file mla_viewer=true columns=1 orderby=date order=desc]
-
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 theids=
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:
[mla_gallery attachment_category=vegetable tax_operator="NOT IN" mla_alt_shortcode=gallery type="rectangular"]
Most lightbox plugins use HTML
class=
and/orrel=
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:[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"']
-
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., 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 ( 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, 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. |
||||||
meta | WordPress attachment metadata, if any, embedded in the image/audio/video file. For this category, you can code any of the field names embedded in the _wp_attachment_metadata array. The "Attachment Metadata" display in the Media/Edit Media screen will show you the names and values of these fields. Note that the fields available differ among image, audio and video attachments.
The "image_meta" portion of the attachment metadata is of particular interest. This array contains some "extended image metadata" drawn from IPTC and EXIF fields by WordPress and improved a bit. You can find more information in the Codex Function Reference/wp read image metadata. For example, to get the ISO speed rating for an image, code |
||||||
The Document Information Dictionary (D.I.D.)and XMP metadata, if any, embedded in a PDF file. For this category, you can code any of the nine D.I.D. entries (Title, Author, Subject, Keywords, Creator, Producer, CreationDate, ModDate, Trapped). For many documents there is also a rich collection of additional metadata stored in XMP Metadata Streams; see the Metadata in PDF documents section below for details on accessing PDF metadata.
You can find more PDF information at the Adobe PDF Technology Center. |
|||||||
iptc | The IPTC (International Press Telecommunications Council) metadata, if any, embedded in the image file. For this category, you can code any of the IPTC DataSet tag and field identifiers, e.g., "2#025" for the Keywords field. You can also use the "friendly name" MLA defines for most of the IPTC fields; see the table of identifiers and friendly names below.
You can find more IPTC information in the IPTC-NAA Information Interchange Model Version No. 4.1 specification (PDF document). A special iptc "pseudo-value" is available; ALL_IPTC ( The ALL_IPTC value is altered in two ways. First, values of more than 256 characters are truncated to 256 characters. This prevents large fields such as keyword arrays from dominating the display. Second, array values are shown once, at their expanded level. |
||||||
exif | 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. It is also supported by many image editing programs such as Adobe PhotoShop. 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 uses a standard PHP function, exif_read_data, to extract EXIF data from images. The function returns three arrays in addition to the raw EXIF data; COMPUTED, THUMBNAIL and COMMENT. You can access the array elements by prefacing the element you want with the array name. For example, the user comment text is available as "COMPUTED.UserComment" and "COMPUTED.UserCommentEncoding". You can also get "COMPUTED.Copyright" and its two parts (if present), "COMPUTED.Copyright.Photographer" and "COMPUTED.Copyright.Editor". The THUMBNAIL and COMMENT arrays work in a similar fashion. A special exif "pseudo-value" is available; ALL_EXIF ( The ALL_EXIF value is altered in two ways. First, values of more than 256 characters are truncated to 256 characters. This prevents large fields such as image thumbnails from dominating the display. Second, array values are replaced by an "(ARRAY)" placeholder, e.g., |
||||||
xmp | Data defined by the Extensible Metadata Platform (XMP) framework, if present. XMP metadata varies from image to image but is often extensive. MLA provides access to this data in three ways:
MLA adds three fields of its own to the XMP metadata information:
The ALL_XMP value is altered in two ways. First, values of more than 256 characters are truncated to 256 characters. This prevents large fields such as image thumbnails from dominating the display. Second, array values are replaced by an "(ARRAY)" placeholder, e.g., |
||||||
mso | For Microsoft Office documents, data defined by the Office Open XML file formats, if present. The formats (e.g., docx, xlsx, pptx) were developed by Microsoft and first appeared in Microsoft Office 2007. MLA provides access to the "Document Properties" data in three ways:
MLA adds two fields of its own to the MS Office metadata information:
The ALL_MSO 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 replaced by an "(ARRAY)" placeholder, e.g., |
||||||
id3 | Wikipedia says "ID3 is a metadata container most often used in conjunction with the MP3 audio file format. It allows information such as the title, artist, album, track number and other information about the file to be stored in the file itself." WordPress includes a subset of the getID3() PHP Media File Parser with support for audio and video file formats. A few values are available for other file types but they are not very useful.
You can also use [+id3:ALL_ID3+], 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 file, find field names and see what values are present. The ALL_ID3 value is altered to limit the amount of information displayed. Values of more than 256 characters are truncated to 256 characters. This prevents large fields such as image thumbnails from dominating the display. Array values are replaced by an "(ARRAY)" placeholder, e.g., |
||||||
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 templates. | ||||||
matches | The matches prefix is part of MLA’s Regular Expression Features. It allows you to access data sources created by applying the ,match(p) and ,extract(p) format/option values. |
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, |
,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, |
,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 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., |
,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 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., |
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. |
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 |
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 |
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. |
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 |
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. |
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.
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:
- Regular expression - Wikipedia
- Regular-Expressions.info
- Regular Expressions (Perl-Compatible) in PHP
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.
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.
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.
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.
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. |
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. |
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 |
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. |
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.
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.
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:
- Internet Assigned Number Authority MIME Media Types
- Wikipedia: Internet Media Type
- Wikipedia: Mailcap
- FILExt: A free online resource by Uniblue
Put on your boots and have a paddle handy - it's a swamp! Good luck.
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
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.
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. 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) --".
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:
Native Commas Raw 0 374871 4,096 374871 4096 8,192 4096 440242 374,871 440242 8192 440,242 8192 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:
Text (the default) stores a list of the data source values, separated by commas Single stores the first value and discards any additional values, e.g., "mp4" for the "audio" example below Export for single values, same as Text. For multiple values, stores all the field names and values (including nested arrays). For example, the below audio data would be returned in Export format as "array ('dataformat' => 'mp4', 'codec' => 'ISO/IEC 14496-3 AAC', 'sample_rate' => 48000, 'channels' => 2, 'bits_per_sample' => 16, 'lossless' => false, 'channelmode' => 'stereo')". Array stores an array of values in a single instance (database row) of the custom field. Multi stores each unique value in a separate instance (database row) of the custom field. This is the most flexible format, as explained below. 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.
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.
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.
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.
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
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+}" ]
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 uses a standard PHP function, exif_read_data, to extract EXIF data from images. The function returns three arrays in addition to the raw EXIF data; COMPUTED, THUMBNAIL and COMMENT. You can access the array elements by prefacing the element you want with the array name. For example, the user comment text is available as "COMPUTED.UserComment" and "COMPUTED.UserCommentEncoding". You can also get "COMPUTED.Copyright" and its two parts (if present), "COMPUTED.Copyright.Photographer" and "COMPUTED.Copyright.Editor". The THUMBNAIL and COMMENT arrays work in a similar fashion.
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 "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.
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.
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.
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
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
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)
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. |
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!
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_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 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).
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
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.
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.