WordPress.org

Plugin Directory

Media Library Assistant

Enhances the Media Library; powerful [mla_gallery], taxonomy support, IPTC/EXIF/PDF processing, bulk/quick edit actions and where-used reporting.

Other Notes

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 and Il'ya Karastel for testing and advising on the new multilingual support features!

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.

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

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".1. How should terms assigned to one translation of an item be used to update other translations of the same item? This is "Term Synchronization".

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.

Thumbnail Substitution Support, mla_viewer

NOTE: Google has discontinued the File Viewer support for thumbnail images. 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.

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.
  • 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 maxinum 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 maxinum width 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.
  • 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 (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 (PDF for now) 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.

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

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 values

There are ten prefix values for field-level parameters.

  • request - The parameters defined in the $_REQUEST array; the "query strings" sent from the browser.
  • query - The parameters defined in the [mla_gallery] shortcode.
  • 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.
  • terms - WordPress Category, tag or custom taxonomy terms.
  • meta - WordPress attachment metadata, if any, embedded in the image/audio/video file.
  • pdf - The Document Information Dictionary (D.I.D.)and XMP metadata, if any, embedded in a PDF file.
  • iptc - The IPTC (International Press Telecommunications Council) metadata, if any, embedded in the image file.
  • exif - The EXIF (EXchangeable Image File) metadata, if any, embedded in a JPEG DCT or TIFF Rev 6.0 image file.
  • xmp - Data defined by the Extensible Metadata Platform (XMP) framework, if present. XMP metadata varies from image to image but is often extensive.
  • 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.

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.

Two "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..
  • ,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.

Seven "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.
  • ,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.
  • ,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. The "fraction" format converts these to a more useful format.
  • ,timestamp(f) - Many date and time values 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.
  • ,date(f) - 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 format these values by using the ",date" format.

Requires: 3.5.0 or higher
Compatible up to: 4.2.2
Last Updated: 2015-6-17
Active Installs: 20,000+

Ratings

4.7 out of 5 stars

Support

41 of 55 support threads in the last two months have been resolved.

Got something to say? Need help?

Compatibility

+
=
Not enough data

1 person says it works.
1 person says it's broken.

0,1,0 100,1,1
100,1,1 100,4,4 100,2,2 100,1,1 100,1,1
100,3,3
100,2,2 100,1,1 100,1,1 100,2,2 100,1,1
0,1,0 100,3,3
50,2,1
100,2,2 50,2,1
100,2,2 100,1,1
100,1,1
100,1,1
100,1,1 100,3,3
100,2,2 0,1,0
100,2,2 100,2,2
100,1,1 100,1,1
100,1,1 100,3,3
100,1,1
100,1,1
100,1,1
100,1,1 50,2,1