Today I would like to finally release to the wild the totally rewritten Media-Tags plugin version 2.0. The Media-Tags plugin 2.0 has been completely rewritten to use to WordPress Taxonomy system for storing related media-tag information. As a benefit to this rewrite the user now has a new Media Tags management interface located under the Media section. Via this Media Tags management interface users can better manage the media tags used on the site. Deleting, renaming and adding new media tags is now quite simple. The Media Tags for the attachment are still display both under Media and the media popup on the editor screen as before.
Some highlighted features in the new Media-Tags 2.0 release:
Media tags storage now using WordPress Taxonomy
In previous versions of the Media-Tags plugin the tag information was stored into the postmeta table. While this worked well it meant the tag information was only accessible in relationship to the post parent. The Media-Tags 2.0 version now uses the built-in WordPress Taxonomy system. Using this system greatly increases the flexibility of the media tag data. Using the standard WordPress functions get_terms() for example to directly query media tag information.
Permalinks Support
Because the media tags plugin now uses the WordPress Taxonomy system you can now access attachments archives via the new permalink tag ‘/media-tags/’. This is very powerful and one of the most requested features since the plugins initial release. An example of a media tag archive is something similar to
http://www.yoursite.com/media-tags/<media tag name>
where ‘<media tag name>’ is one media tag name from your site.
Media Tags Archive
Along the same lines as the new permalink structure you can now also use archive template files specific for media tags. By default WordPress will use the template file ‘archive.php’ if part of your theme. While this works fine you may also want to have a template file specific for displaying media tags archive. Introducing the ‘mediatags.php’ template file. The mediatags.php template is looks and functions much like a normal archive.php file complete with the header, footer, sidebar options as well as the standard WordPress loop. Actually my recommendation is to copy the existing archive.php to mediatags.php to start. Then add needed code to finish out the template file. Also you may define tag specific template files. Lets assume you have many media tags in your system. But one media tag, ‘bulk’, for example you want displayed a certain way. You can define a tag specific template file like ‘mediatags-23.php’ where ’23 is the ID of that media tag. Please not the template file when used will display attachments not the parent post. In WordPress all uploaded media is part of a parent/child association. Unlike the normal post related template the media tag template display the actual media files.
Media-Tags Management interface
In version 2.0 of the Media-Tags plugin I’ve included a new management screen. When the plugin is activated you will see a new menu options ‘Media-Tags’ located under the top-level Media section. This management screen lets you add, delete, update media tags in your system. The interface should seem very familiar to user who use the WordPress Categories and Tags management screens.
Template functions
Also included as part of the plugin rewrite are some handy template tags to use via your theme. Below are a list of the template functions available. These are located in the plugin file mediatags_template_functions.php. All these functions should seem very familiar since they were modeled after the built-in WordPress tags template functions.
- is_mediatag() – Tests is we are displaying a media-tags archive. Much like is_category() function
- in_mediatag() – Tests is an attachment post marked in a certain mediatag_id.
- get_mediatags()
- list_mediatags() – Very handy for listing your media tags like list_tags() in the sidebar.php
- get_mediatag_link() – Given a mediatag_id this functon will return a link href value.
- the_mediatags() – Very much like the post-level the_tags() to display a comma separated list of tags for a given post item. Used then displaying media tags archives.
The original plugin function mediatags->get_media_by_tag(…) has now been replaced with a more simple non-object based template function get_attachments_by_media_tags(…). The original function has been deprecated and will be removed in future releases.
More options for Media-Tag Queries
The new Media Tags access function, get_attachments_by_media_tags(…), now supports many more parameters to let you filter the returned information better.
- media_tags: (Required) This is a comma separated list of tags you want to filter on.
- media_types: (Optional) This is a comma separated list of media types – gif, pdf, png to return
- post_parent: (Optional) This is the post ID of the related media items. This item is no longer required. This allows you to query media_tag items across all posts
- numberposts: (Optional) Default is all. Allows control over the number of items returned.
- orderby: (Optional) Default menu_order. See get_posts() for full list of options
- order: (Optional) Default ‘DESC’. Controls the order of items. Other option is ‘ASC’.
- offset: (Offset) Default is 0. Allows control over the subset of items returned.
- return_type: (Optional) Defaults to Array. Other option is ‘li’. In the case of shortcodes the return type is ‘li’ by default. When using the ‘li’ return type each element is given a class of ‘media_tag_list’ and an id of ‘media-tag-item-xxxx’ where ‘xxx’ is the attachment id.
- tags_compare: (Optional) Defaults to ‘OR’. When requesting multiple media_tags elements allow a compare between the lists of items returned. When using the ‘OR’ option returned item will be in one or more of the requested media_tags values. Other value is ‘AND’. When using ‘AND’ you are requesting only attachments which are in all requested media_tags.
Shorcode support
The media tags plugin now support the use of shortcodes. In its simplest form the media tag shortcode appears like
[media-tags media_tags=”alt-views,page-full,thumb”]
Note you need to include quotes around the element value to ensure proper handling. The shortcode parameters available are pretty close to the direct function call. The exception is you need to specify the parameter name and value pairs.
[media-tags media_tags=”alt-views,page-full,thumb” tags_compare=”AND” orderby=”menu_order”]
When using the shortcode option the return type is automatically set the ‘li’ which means list elements will be returned. When using shortcodes you can specific two parameters ‘before_list=’ and ‘after_list=’ to control the wrapper elements. Also, you can specify a new parameter ‘display_item_callback=’. This parameter will be a user defined function which allows you to control the output. The callback function will be called for each found element. Check the plugin file ‘mediatags_shortcodes.php’. There is a function used ‘default_item_callback()’ which is the default callback actually used by the plugin. Remember when using shortcodes in WordPress you MUST return every output. Do not echo information.
Lastly, when using the shortcode feature you may have a time when you need to specify the post_parent for the media_tags queried. Now you could add the post_parent ID directly to the shortcode settings. But then you would be hard-coding the ID for the given post. A better way is to just set the post_parent value to ‘this’. This will allow dynamic control over the shortcode processing.
[media-tags media_tags=”alt-views,page-full,thumb” post_parent=”this” before_list=”<ul class=’frank’>” after_list=”</ul>”]
