=== Media Tags === Contributors: Paul Menard Donate link: http://www.codehooligans.com/donations/ Tags: images, tags, media, shortcode, permalinks Requires at least: 2.7.1 Tested up to: 2.8.4 Stable tag: 2.2 == Description == Adds an input to the media upload and management screens. This input field can be used to "tag" a media file. Works with images, documents or anything. 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. Because the media tags plugin now uses the WordPress Taxonomy system you can now access attachments via the new permalink '/media-tags/'. This is very powerful and one of the most requested features since the plugins initial release. 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. * single_mediatag_title() - Get the Title of the Archive. Speaking of template tags you can now have even more control over the display of media tags archives. Much like the WordPress category template hierarchy you can now define a template file as part of your theme names 'mediatag.php' This is a special archive file tha can be used to display your loop of items. Alternately, you can also used ID specific template files like 'mediatag-25.php'. This is the same basic logic for category specific template file. It lets you use a special template file to display that specific media tag ID group. If the 'mediatag.php' template file is not provided then the default hierarchy or template files will be used starting with archive.php. 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. Just want to display attachments in a post or page? Use the new media tags shortcodes. [Plugin Homepage](http://www.codehooligans.com/2009/07/15/media-tags-20-released/ "Media-Tags Plugin") == Installation == 1. Upload the extracted plugin folder and contained files to your `/wp-content/plugins/` directory 2. Activate the plugin through the 'Plugins' menu in WordPress. 3. If you are upgrading from an earlier version of Media Tags the tags will be converted automatically when the plugin is activated. 4. Navigate to any Post/Page where a media file has been attached. Click on the 'Add Media' option on the post content icon bar. Select a media item from the Gallery. Click the 'Show' link to show the media item details. You will notice the new 'Media Tags' input field just below the WordPress Size option. 4. All used tags will be displayed as checkboxes below the new Media Tag input field. 5. Also all used media tags can be managed via the new Media Tags interface as part of the Media section in wp-admin. Management of Media tag is now part of a familiar interface like Tags and Categories. 6. Tweak out your template to display media tags (optional). == Frequently Asked Questions == = Ok I can now add tags to my images. So what, what can I do with them = Excellent question. By default if you are uploading an image to a post then inserting the media link into your post there is no need for you to use this plugin as it will not provide any benefit for you. But consider this scenario. You have 5 images you want to upload for a post. Two of these images will be inserted into the actual post content but the other three you want to display in the sidebar. How would you do this? Normally, in the past I would make the 3 images used in the sidebar follow a specific filename convention like sidebar1.jpg, sidebar2.jpg and sidebar3.jpg. This get ugly if you are managing lots of images. I would be better ( and one reason I wrote this plugin) to allow the tagging of the 3 images as 'sidebar'. To actually get to the images for display in the sidebar you will need to have a way of filtering the attachments that are associated with a post. Luckily I've also included a simple function: `get_attachments_by_media_tags()` This function works similar to most other WordPress functions. There are a number of arguments that can be passed into the function to filter the media: media_tags: (Required) This is a comma separated list of tags (slug) you want to filter on. media_types: (Optional) This is a comma separated list of media types - gif, pdf, png to return search_by: (Optional) Default is 'slug'. Denotes what is passed in the 'media_tags' parameter. To search by media tag name pass the name into the 'media_tags' parameter and 'name' into the 'search_by' parameter. 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. Actual examples of the function call are: ` $media_items = get_attachments_by_media_tags('media_tags=banner'); This call will filter the tags for the tag 'banner'. $media_items = get_attachments_by_media_tags('media_tags=sidebar,trees&media_types=pdf,xls&tags_compare=AND); This is another example. Filtering media based on the tags sidebar and trees. Also filtering the media type to be pdf or xls only. We are also specifying the 'AND' compare option to only return elements that are part of all media_tags. Note: in the earlier versions of the media tags plugin you had to call the function by way of the object like $mediatags->get_media_by_tag(...); The use of the object as well as the 'get_media_by_tag' function has been deprecated. In the current version you can now access the function directly as in 'get_attachments_by_media_tags(...)'. The legacy $mediatags->get_media_by_tag() function is still supported for now. ` = I want to use the new shortcode feature to display attachments by media tag on a page = Great. 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 media_tags parameter is the mediatag slug. 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="