Media Library AssistantbyDavid Lingren

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.

Acknowledgements

Media Library Assistant includes many images drawn (with permission) from the Crystal Project Icons, created by Everaldo Coelho, founder of Yellowicon.

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

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.

Argument Substitution Parameters for custom markup templates

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.

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 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.

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.

[mla_gallery] Post Type, Post Status support

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 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]

Note that you must also change the post_status and post_mime_type 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 Type Parameters and Status Parameters sections.

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 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:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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:

1. How should language-specific terms be assigned to items selected? This is “Term Assignment”.
2. 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:

1. 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:

1. 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.
2. 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.
3. 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 synchroniztion 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

• Common-term-1-eng
• Common-term-2-eng
• English-only-term

Spanish

• Common-term-1-esp
• Common-term-2-esp
• Spanish-only-term

And these term assignments exist:

English Translation

• Common-term-1-eng
• English-only-term

Spanish Translation

• Common-term-1-esp
• Spanish-only-term

Then synchronization handles common editing actions as follows:

1. If you edit the English Translation and add “Common-term-2-eng”, synchronization will add “Common-term-2-esp” to the Spanish Translation.
2. If you edit the English Translation and remove “Common-term-1-eng”, synchronization will remove “Common-term-1-esp” from the Spanish Translation.
3. 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).