Media-Tags 3.0 Released
I’m proud to say I’ve finally released Media-Tags 3.0 to the general public and is available in the WordPress plugin repository http://wordpress.org/extend/plugins/media-tags/. Thanks to all who contributed ideas, bug reports and support in this milestone development. And my apologies for taking so long to get this out.
This plugin contains many new features. Some highlighted items are:
- Bulk Administration of media items This feature on both the Media > Library and Media Upload popup for the Post admin screen allow you to assign/remove Media-Tags to a selected group of media items. In previous versions you would need to edit each media item.
- Roles management Under the Media-Tags Settings panel is a new Roles management panel. This panel allows you to fine tune the access by individual users.
- Internationalization This is a much needed and requested features. Now all text handled by the plugin are using the WordPress i18n hooks to support translation into other languages.
- Removed over 1000 lines of custom code This old code was used to provide basic functionality for the tagging and URL rewrites. Since WordPress core functions have progressed over the last two years this custom code is no longer needed. This means the plugin will run cleaner and is more stable than previous releases.
- Better support for WordPress standard Taxonomy templates In the past the plugin has supported a custom theme template, mediatag.php. The plugin now support the more standard WordPress templates taxonomy-media-tags.php.
- A new Help section This new Help section provides many topics from general use to shortcodes tricks to template files support questions. Check it out.
- Many other features have been added. Too many to mention here.
What does the Media Tags plugin do? And why do I need it?
Simply put the Media-Tags plugin allow you assign tags to your uploaded media (i.e. Image, document, etc.) much like the way you assign tags to post in WordPress. The Media-Tags plugin add new fields to the Media Upload popup on the Pages and Posts editor as well as the edit form on the Media Library editor form.
The Media-Tags plugins works by creating a custom Taxonomy using the built-in WordPress Taxonomy support framework. This Taxonomy framework is the same system used by Categories, Post tags, etc. This means the Media-Tags plugin is not creating new database tables in your system or storing tons of data into your wp_options table.
Using Media-Tags to tag media
I know the previous line may seem like I’m talking in circles. Let me explain.
Once you have media items tagged you can access then with some simple PHP functions via your templates like:
get_attachments_by_media_tags()
This function takes a number of possible arguments:
media_tags (Required) – This is a comma separated list of tag slugs used to filter the possible selections. At least one media tag slug is required.
media_types (Optional) – This is a comma separated list of media types pdf, jpg, gif, etc.
post_parent (Optional) – This will limit the media items selected to the given post/page ID. Only a single ID can currently be used.
search_by (Options) – default ‘slug’. Allows searching by other methods. At this time only ‘slug’ is supported.
numberposts (Optional) – default ‘-1’. Specify the number of items to return. Works much like get_posts();
orderby (Optional) – default ‘menu_order’. Specify display ordering.
order (Optional) – default ‘DESC’. Specify display ordering.
offset (Optional) – default ‘0’. Allow skipping the number of media items returned. Good for handling paging.
return_type (Optional) – default ”. Be default the function returns a raw PHP array. you then need to handle the display of items. Passing ‘li’ will force the function to return the items as an list elements.
tags_compare (Optional) – default ‘OR’. When using multiple elements in the ‘media_tags’ argument this tells the function how they should be compared. For example if you want items that are tagged either ‘vacation’ OR ‘hawaii’. The other possible value here is ‘AND’ to get items that are tagged for both values.
display_item_callback – By default not used. If set this would be a user defined function. A call to this user function will be made for each item found. See the function ‘default_item_callback’ in the plugin file mediatags_shortcodes.php.
call_source – Used internally by the function. Is set when using the shortcode part of the plugin.
An examples of using this function are:
$media_items = get_attachments_by_media_tags('media_tags=vacation,hawaii&numberposts=10&return_type=li');
if ($media_items) {
echo "
- ". $media_items. "
";
}
Media-Tags uses WP Shortcodes.
I’m sure when reading the above many readers growned about needed to code in PHP. Well the good news is Media-Tags also supports the WP shortcode system. The shortcode equivalent for the previous example would be the following.
[media-tags media_tags="vacation,hawaii" numberposts="10"]
When using the shortcode the default output is a ‘li’ for list elements. But you can also use the ‘display_item_callback’ parameter to call a user defined function. Use of the shortcode also provides more parameters that let you control the output.
before_list (Optional) – default is ‘<ul>’. Using this parameter you can pass in your own list wrapper ‘ul’, ‘ol’ and provide needed CSS class and ID settings.
after_list (Optional) – default is ‘</ul>.
post_parent (Optional) – here the value ‘this’ can be used to designate the current global post/page ID.
Pretty cool!
Template function
The Media-Tags plugin also supports a wide range is available template function you can use in your theme templates. For example to list out the Media-Tags tag cloud which is very similar to the Post tags tag cloud you would add the following to your sidebar.php
mediatags_cloud();
This template function is actually just a wrapper around the WordPress built-in wp_tag_cloud function. As part of the wrapper we specify using the Media-Tags Taxonomy instead of the default Post tags. To find out what options are available for the mediatags_cloud function just follow the information for wp_tag_cloud.
Another handy function is ‘get_mediatag_link’. This function takes one required argument. The argument is the ID of the Media-Tag. This is link the Category or Tag ID.
Yet another function is ‘the_mediatags’. This function is patterned after the ‘the_tags’ function provided by WordPress. The ‘the_mediatags’ function will output a comma-seperated setup of values for the current post item.
Look for a complete template functions reference coming soon.
Media-Tags Permalink Base
The Media-Tags plugin allows you to setup archives to display the tagged media items. Think of this similar to Category, Tag or Author archives. By default the Media-Tags plugin assigns a special URL parameter where you pass in the Media-Tag slus like ‘http://www.yoursite.com/media-tags/
Media-Tags Archive Templates
As mentioned the Media-Tags plugin allows for display of tagged media items in an archive much like Categories, Post Tags and Authors. To support this Media-Tags also support the use of specific theme template files for displaying media-tag items. Following the built-in WordPress template hierarchy when you view an archive if the archive.php theme file is present it will be used instead of the index.php. With the Media-Tags plugin if you have a file in your theme folder named ‘mediatag.php’ it will be used before the archive.php or index.php. Also you can define a specific Media-Tag archive to control the display on a specific Media-Tag ID. For example you want your media items from Media-Tag 12 to look different. You can create a theme file ‘mediatag-12.php’ to display those items differently than the normal media items.
Media-Tags Archive RSS Feed
As part of these Media-Tags archives you also have available an RSS feed which will allow users to add to their feed reader to track new information you tag using Media-Tags. Following the previous example on the archive for media items tagged as ‘vacation’. The archive URL will appears be default as http://yoursite.com/media-tags/vacation The RSS2 feed for this Media-Tag item will be http://yoursite.com/media-tags/vacation/feed/
Export and Import
Since Media-Tags works using the built-in Taxonomy system provided by WordPress it also handles the export of your Media-Tag information via the Tools -> Export options under wp-admin. This allows you to transfer you site content via the WordPress Export process to another WordPress instance where you can import the XML file.
Widgets
The Media-Tags plugin does not contain or support widgets itself. But other developers have put together some Widgets you can download and play with. Note these Widgets depend on Media-Tags being installed.
- Media Widget (http://wordpress.org/extend/plugins/media-widget/)
- Tag Gallery (http://wordpress.org/extend/plugins/tag-gallery/)
Download
As is customary the only place you should ever download released plugins is via the WordPress official plugin repository.
Download the new Media-Tags plugin
Support
For support you can contact me via this site. But I would prefer you use the Media-Tags support forums on WordPress.org