WP MediaTagger

FAQ

Installation Instructions

To install the WP MediaTagger plugin just follow this simple 10-step recipe.

CAUTION : if upgrading from WP ImageTagger, backup your database, taking care to include the table wp_term_relationships_img and deactivate the ImageTagger plugin from the extensions administration page before activating WP MediaTagger (CRITICAL !). Refer to instructions at page bottom.

1. Download the plugin and expand it to an empty directory of your local disk drive.
2. Copy the local wp-mediatagger folder created by the unzipper onto your server plugins folder (wp-content/plugins/). Make sure you end up with all the PHP files, readme.txt and screenshots in wp-content/plugins/wp-mediatagger directory.
3. Login into the WordPress administration area and click on the Plugins left menu. Expand the Installed view.
4. Locate the MediaTagger plugin and click on the Activate link.
5. Make sure your blog already holds posts or pages with medias (medias or any other WordPress media).
6. Make sure you already created a list of tags for your blog.

7. Start associating your blog medias with any tag of your blog. Two methods for this purpose :

   • From your WordPress administration panel, go to Settings > MediaTagger and start associating the first media found to any tag in the Tag Editor
   • Or, still from the MediaTagger administration area, switch to the Image Explorer mode, navigate to the file you want to tag and click on the file to select it back to the Tag Editor
   • Or, assuming your site display captions below each media : from any post or page holding medias, click on the media caption (being administrator) and make the association with any tag from the Tag Editor panel.

8. Prepare a result page to present the search results :

   • Create a new page (or use existing one if you want).
   • From your WordPress editor, enter the MediaTagger shortcode : [mediatagger] – There are options you will learn later, but this simple form is perfect for a quick start.
   • Check the result on the page containing this call.
   • Start playing with the options offered in the MediaTagger admin panel.

9. By default your search page is the same as your result page. You can also choose to activate the MediaTagger widget to integrate an media search tagcloud in your sidebar, or to manage the search page at a different address for a specific use.

10. Go ! And if you like it, why not proceeding with a small donation?

If you are interested in seeing the plugin in action, you might wish to go and have a look here.

More information on this plugin utilization can be found there.

Finally, if you have any questions, please refer to the FAQ bottom page, section – section Damned, my question is not listed there.

That’s all for today – Enjoy !

If you are upgrading from WP ImageTagger :

The tagging made on images will be preserved IF you follow these simple instructions:

1. BACKUP YOUR DATABASE, TAKING CARE TO INCLUDE THE wp_term_relationships_img TABLE – in case something turns wrong during the upgrade.

2. Deactivate ImageTagger plugin from the extensions administration page – OTHERWISE YOU RISK TO LOOSE THE TAGGING ALREADY DONE.

3. Install and activate MediaTagger plugin

4. On your result page : replace the shortcode [imagetagger] by [mediatagger], keeping the same options if you use some

5. If you were using the ImageTagger widget : go to Appearance > Widgets ; reposition the MediaTagger widget in the sidebar, all the settings formerly made for the ImageTagger plugin will be automatically restored.

6. You can de-install the WP ImageTagger plugin from the Extensions interface.

What are the prerequisites to run this plugin ?

• At least one media should be present in your blog. Otherwise the MediaTagger admin panel will inform you that you need to start working on your blog !
• Same comment for the tags declared in your blog.

How are defined the tags proposed for the media classification ?

By default the plugin will use the WordPress tags. Anyhow you can decide to use WordPress categories instead, or to combine tags and categories.

Can I create groups of tags ?

The tags can be gathered by groups. This grouping does not affect the search, it has only an effect on the tags presentation in the classification panel and in the search form. Grouping the tags by themes provides a more consistent presentation, and makes the appropriate selection faster.

Which media formats are supported ?

The formats below can be tagged with WP MediaTagger :

• Images : GIF (image/gif), JPEG (image/jpeg), PNG (image/png)
• Audio / video : MP3 (audio/mpeg)
• Documents : TXT (text/plain), RTF (application/rtf), PDF (application/pdf)

Are the WordPress gallery themes supported ?

Yes, the medias managed within WordPress galleries will be available for tagging as any other standalone media.

How do I tag the medias of my blog ?

Having installed the plugin according to the instructions provided on the installation page, two alternatives are offered to tag your medias :

• From your WordPress administration panel, go to Manage > MediaTagger and start associating the first media found to any tag in the Tag Editor ;
• Or, switch to the Media Explorer mode, navigate to the file you want to tag and click on the file to select it back to the Tag Editor ;
• *** NOT SUPPORTED ANYMORE STARTING 3.4 *** Or, assuming your site display captions below each media : from any post or page holding medias, click on the media caption (being administrator) and make the association with any tag from the Tag Editor panel.

How do I know if a media is tagged or not ?

Go the the plugin admin panel and switch the view to Image Explorer mode. This gives you access to a page listing all your site medias and the associated tags. You are able to get any media tagging status from this page.

Additionally, in case your site theme displays media captions : a tooltip appears if you put your mouse pointer over the media caption in the page or post holding this media. This tooltip displays the tags associated to the media.

How do I change the tags already associated to a media ?

Go the the plugin admin panel and switch the view to Media Explorer mode. This gives you access to a page listing all your site medias and the associated tags. You are able to get any media tagging status from this page.

Additionally, in case your site theme displays media captions : click on the media caption (being administrator) and make the association with any tag from the Tag Editor panel.

How do I know the total number of medias my site holds, and that can be tagged ?

This information is the X value displayed in light grey in the upper right part of the MediaTagger admin panel as X/Y/Z.

How do I know the number of medias I already tagged ?

This information is the Y value displayed in light grey in the upper right part of the MediaTagger admin panel as X/Y/Z.

How do I know the number of medias remaining to be tagged ?

This information is the Z value displayed in light grey in the upper right part of the MediaTagger admin panel as X/Y/Z. Consequently Y+Z=X.

How do I insert the MediaTagger search form on a page or post ?

Edit your page or post with the WordPress editor and insert the specific MediaTagger shortcode [mediatagger]. From this point the plugin will manage the calls to the adequate functions.

Can I tag medias without having yet inserted the MediaTagger form on my site ?

Yes, these are two separate processes. On one hand you build your database by tagging the medias, on the other you run queries on this database through to the [MediaTagger] shortcode.

What are the different display modes available to manage the search page ?

The search can be presented to the visitor under two different representations than can be mixed together into a third one :

• a tag cloud display : the tags available for search are presented WordPress fashion ; this representation is compact but suitable for single tag search only
• a form display : the tags are listed in a form ; the search is done by ticking one or more tags. This makes this representation more adapted for advanced, multi-criteria search, although requiring potentially much more room on your page in case of big tag collection.
• a text field : to search on the media names rather on the tags associated to those medias.

All these modes can be freely combined.

Can the visitor switch between the three search display styles ?

This possibility is offered by default in the option panel. You can anyhow preset a default search display style, not switchable by visitors.

What are the different display modes available to manage the result page ?

This can be done using in three different ways :

• itemized media list : the results are presented as a vertical list of medias displayed with a title and the post they refer to (if attached). This mode is suitable for getting the maximum information on the search result, but not adequate when the number of results found is too important.
• thumbnail gallery : the results are presented in a compact display consisting in a gallery of thumbnails. More information can be obtained rolling the mouse over each thumbnail, although it is not the most adequate for having a direct reading of the media related information.
• media captions list : this display mode does not display the media and restrict itself to the text information. It will be preferred by visitors looking for specific text information rather than pictorial impression.

These three modes are paginated. The number of result per page is an option accessible in the admin panel.

Can the visitor switch between the three result display styles ?

This possibility is offered by default in the option panel. You can anyhow preset a default result display style, not switchable by visitors.

Has the search page to be at the same address as the result page address ?

Although this possibility is offered, the search panel can redirected to a different page. See below for the implementation details.

What are the possible implementations of the search and result pages ?

There are three possible implementations :

• Single page implementation :

  • Create a new page (or use existing one if you want).
  • From your WordPress editor, enter the MediaTagger shortcode : [mediatagger].
  • Check the result on the page containing this call.
  • Start playing with the options offered in the MediaTagger admin panel.

• Search page different from the result page :

1. Manage the page embedding the search access :

   • Create a new page, for instance http://www.mysite.com/medialibrary_search, or use existing one if you want.
   • From your WordPress editor, enter MediaTagger shortcode, with one option : [mediatagger result_page_url="http://www.mysite.com/medialibrary_result"], assuming you want your visitor to be directed and have the results displayed on page http://www.mysite.com/medialibrary_result.
   • Set the proper options in the Admin Panel to control the Search Format as you want.
   • Check the result on the page containing this call, without running any search yet.

2. Manage the result page :

   • Create a new page matching the URL passed inside the MediaTagger shortcode let’s say http://www.mysite.com/medialibrary_result (or use existing one if you want).
   • From your WordPress editor, enter the MediaTagger shortcode : [mediatagger].
   • Check the result on the page containing this call
   • Set the proper options in the Admin Panel to control the Result Format as you want.
   • Launch a search from your page http://www.mysite.com/medialibrary_search ; you will be directed to the result page http://www.mysite.com/medialibrary_result
   • Play with the options offered in the MediaTagger admin panel to adjust the search and result format.

• Sidebar tag cloud widget :

  • In this case, the call to the MediaTagger API is directly managed by the widget. Refer to the section below for the activation.

How do I activate the tagcloud widget ?

Before that you need to have defined your MediaTagger result page, as described just above.

Then from your site admin page, go to Appearance > Widget and click on Add to add the widget to your sidebar. Configure then the widget in the right column clicking on the Edit link, followed by Done. Do not forget to Save Changes. Pay specific attention to the Result page address parameter. This parameter must be the address of a page of your site that you defined as your MediaTagger result page according to the section What are the possible implementations of the search and result pages ? above.

If you get the error 404 when clicking on the sidebar tag cloud, you likely misconfigured the Result page field.

What is the syntax for the MediaTagger shortcode ?

In the WordPress glossary, a shortcode is a syntaxic expression that will trigger some functions. In our case, the shortcode is built around the mediatagger keyword. The shortcode relies on a single scalable function, managing the search aspect as well as the result display under various shapes. It can be called with a variable number of arguments. The shortcode needs to be formatted as follows :

[mediatagger opt1="val1" opt2="val2" ...]

The 6 options available are :

$result_page_url = URI of the result page, for instance 'http://www.mysite.com/medialibrary_result'. Can be absolute (preferred) or relative to the site root
$num_tags_displayed = number of displayed tags - If set to 0 (zero), the complete set of tags is displayed
$font_size_min = minimum font size for the tag cloud (pt)
$font_size_min = maximum font size for the tag cloud (pt)
$font_color_min = color that will be used for the least frequently used tags (hex format : 4343f6 for instance)
$font_color_max = color that will be used for the most frequently used tags (hex format : 4343f6 for instance)

The shortcode works with default arguments. Therefore it can be called without explicitly passing the complete list of arguments. When an argument is omitted, the behaviour is the following :

• $result_page_url : when omitted, the result page is the same as the one containing the shortcode
• $num_tags_displayed : when ommitted, the number of tags displayed is the one defined in the options set in the plugin admin panel.
• $font_size_min : when ommitted, the minimum font size for the tag cloud is the one defined in the options set in the plugin admin panel
• $font_size_max : when ommitted, the maximum font size for the tag cloud is the one defined in the options set in the plugin admin panel
• $font_color_min : when ommitted, the color used for the least frequently used tags is the one defined in the options set in the plugin admin panel
• $font_color_max : when ommitted, the color used for the most frequently used tags is the one defined in the options set in the plugin admin panel

Some examples :

• Shortcode with no argument :

  [mediatagger]
  

Result : a search panel (form, tag cloud or combined) is displayed on the page holding this call. The search result is displayed on the same page. The number of tags and font sizes are the ones set in the admin panel.

• Shortcode overriding the number of tags in the tag cloud :

  [mediatagger num_tags_displayed="15"]
  

Result : as well, the search panel and results are displayed on this same page. The number of tags is set to 15, independantly from the setup done in the option panel ; other parameters are the ones set in the options panel.

• Explicit passing of all 6 arguments :

  [mediatagger result_page_url="http://www.mysite.com/search_result/" num_tags_displayed="15" font_size_min="8" font_size_max="25" font_color_min="4545fe" font_color_max="111132" ]
  

Result : the 6 parameters are forced to the values passed in, and the corresponding options set in the admin panel are ignored.

Can a search be triggered directly from the URL, not being through the tag cloud, search form or search field?

Yes, this is possible. A search can now be done directly on the media database without going through the search form or tag cloud. All you have to do is to form URLs like http://wwww.mysite.com/media_library?tags=car+plane+airport, forming your tag list using tag slugs. In that example, the page media_library is the one set with the search form and/or tag cloud, that will be displayed with the tag cloud and/or search form, clean of any search result if requesting http://wwww.mysite.com/media_library. A tag slug is the tag name with no accent and spaces replaced by hyphens. For instance, the tag «l’automne en forêt» becomes «l-automne-en-foret».

By default the result page produced by explicit search URL will not hold any tag cloud or search form. Anyhow you can request to have this capability on top of the search results by forming URL like : http://wwww.mysite.com/media_library?tags=car+plane+airport&display=cloud+form. Possible values for the display argument are : cloud, form, field, which can be combined together.

What is the Media Taxonomy feature all about ?

This option is meaningful when you are managing a large collection of medias. The idea is to tag the medias with MediaTagger, and let then the plugin automatically associate the relevant tags to the post holding these medias.

• This feature is optional ; by default it is not activated.
• Having this feature disabled, the tags associated to your posts are the ones manually set when editing your post and setting appropriate tags in the dedicated field. The standard WordPress mechanism applies.
• Before enabling the media taxonomy, backup your WordPress database. Nothing special to be scarred about, but it is a general good practice when you know your database will be affected by a mechanism you did not experience yet.
• How does it work once activated ? When you enable this feature, every time you tag a media, the collection of tags associated to the medias contained in the post (media taxonomy) to which belongs the media you tagged will be associated to the post itself. At the time you tag an media, the tags formerly associated to the post containing the media are replaced by this media taxonomy.
• The media taxomonmy mechanism applies to the posts only given that WordPress does not support page tagging. Tagging a media contained in a page will not have any other effect than the media tagging by itself.
• What is the interest in having the post taxonomy driven by the media taxonomy ? It will help you keeping with a coherent post tagging scheme by solely focusing on your media tagging. This is particularly relevant when your site is media-centric.

When the media taxonomy is activated, the WordPress database is updated to replace the tags manually associated to the posts by the media taxonomy (on top of updating the wp_term_relationships_img table which is the basic MediaTagger mechanism) :

• the table wp_term_relationship is updated to associate the post to the tags provided by the media taxonomy. Lines will be automatically added or removed, as your post tagging is extended or reduced (the natural trend is normally the extension …)
• the table wp_term_taxonomy count column is updated to keep the tag counters up-to-date.

How is my WordPress database affected by this plugin ?

• By default, MediaTagger does not affect any of the existing WP data tables to avoid any risk of corrupting your database. The association you create between tags and medias are stored in a new table wp_term_relationships_img.
• If you decide to have the media taxonomy overriding the post taxonomy as explained above, the tables wp_term_relationships and wp_term_taxonomy (count) will be modified. For that reason, run a full database backup before activating this taxonomy control in the MediaTagger Admin Panel.
• MediaTagger options set in the admin panel as stored in the wp_options table, in accordance with WordPress plugin development guidelines.

What should I do to ensure I backup the media tagging information when I am run backups of my WordPress database ?

Make sure you include the wp_term_relationships_img table specifically created by this plugin to keep track of the media tagging information you patiently grew over time. This table should be selected for your backup as well as the standard WordPress database tables, such as wp_options, wp_terms, wp_posts, etc.

What are the available languages ?

English, French, Spanish
… and as much as you can contribute if you are fluent with a language not in this list. More details on the changelog page bottom, in project section.

Damned, my question is not listed there !!?

Did you make sure you read carefully enough the FAQ I took time and care to build as complete and explanatory as possible ? I do my best to maintain it with the latest questions I got and answers I made to their author.

Although this is not my primary job, you might direct your questions to this page, I will do my best to timely answer. To help me answering faster, please provide me with the necessary data :

• copy paste the footnote line you see at the bottom of your plugin administration panel.
  Ex : WP MediaTagger 3.0 | PHP 5.2.6-1+lenny4 | MySQL 5.0.32-Debian_7etch8-log | GD Lib 2.0 or higher
• indicate step by steps what you did to get the issue
• describe as specifically as possible the issue you could observe (a screenshot is a plus), with any peripheral aspect
• information related to your site : specific server setup, redirections, number of medias, any special setup …

Although I would if I could … I would not be able to give a hand being only informed that it does not work. Thanks for your cooperation.

Ideas or suggestions …

… are truly welcomed given that it will make this plugin even more valuable to the users community. Spin your suggestions this way.