Thanks for a good question. As you’ve seen, many plugins add taxonomy support to media items in different ways.
MLA strives to be as WordPress-like as possible, using the custom taxonomy support it provides and the WP_Query class for searching the Media library. Here are the sections from the MLA Documentation that describe taxonomy support in the [mla_gallery] shortcode.
Simple Taxonomy Parameters, “tax_operator”
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 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 must use the name/slug strings for taxonomy and terms, not the “title” strings. If you are using the “Att. Tag” taxonomy built in to MLA then your shortcode should be something like:
[mla_gallery attachment_tag=artisan post_parent=all]
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. 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.
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 tax_query="array(array('taxonomy' => 'attachment_category','field' => 'id','terms' => array(11, 12)))" post_parent=current post_mime_type='']
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.
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. 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 will clean up most of the damage, but if your query fails use the “mla_debug=true” parameter to see if your query has been corrupted.
IMPORTANT: Beginning with version 4.0, WordPress changed the way it handles shortcode parameters. Using the => characters in the first shortcode on a post/page will return “Invalid mla_gallery tax_query” errors. There are two ways to prevent this: 1) add "<code></code>" tags around your shortcode, or 2) use the “ampersand gt semicolon” escape sequence in your query.
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_phrases – The word(s) or phrase(s) you are searching for.
- 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.
- mla_phrase_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.
mla_term_connector If you enter multiple terms (separated by commas) 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.
I hope that gives you a good idea of the taxonomy support in MLA. I am marking this topic resolved, but please update it if you have further questions regarding the above material. Thanks for your interest in the plugin.
