=== WP ImageTagger ===
Contributors: phd
Donate link: http://www.photos-dauphine.com/wp-imagetagger-plugin
Tags: images, photos, tags, gallery, photoblog, search, engine, classification, library
Requires at least: 2.7
Tested up to: 2.9.1
Stable tag: 2.2


== Description ==

The **WP ImageTagger** plugin provides the needed tools to categorize any image of your WordPress blog by associating these images to any defined tag.

The following functionalities are available for your blog after installing the ImageTagger plugin package :

> - Associate tags to images from the plugin control panel
> - Associate tags to images from any post or page by clicking on your image captions
> - Provide access to deep image search on any image associated to a list of tags, through a *tag cloud*, *tag form* or *combined* search display
> - Select a display mode for your result page : *itemized image list*, *thumbnail gallery*, or *image captions*
> - Any combination of search mode and result display style is possible

Willing to get a visual flavor of what's in the box ? You can see the *ImageTagger* plugin in action [here](http://www.photos-dauphine.com/phototheque "Check out here the WP ImagerTagger plugin in action"), or have a look at screenshots [there](http://wordpress.org/extend/plugins/wp-imagetagger/screenshots/ "WP ImageTagger screenshots").

   
== Installation ==

To install the **WP ImageTagger** plugin just follow these simple steps:

1. Download the plugin and expand it to an empty directory of your local disk drive.
2. Copy the local *wp-imagetagger* 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-imagetagger* directory.
3. Login into the WordPress administration area and go to the Plugins page.
4. Locate the ImageTagger plugin and click on the *Activate* link.
5. Make sure your blog already holds posts or pages with images.
6. Make sure you already created a list of tags for your blog.
7. Start associating your blog images with any tag of your blog. Two methods for this purpose :

	> - From your WordPress administration panel, go to *Manage > ImageTagger* and start associating the first image found to any tag ;
	> - Alternatively and assuming your site display captions below each image : from any post or page holding images, click on image captions (being administrator) and make the association with any tag.
	
8. Display a search form to allow searching by tags in your image database :

	> - Create a new page (or use existing one if you want).
	> - Make sure you can run PHP code from your page text (using plugins like runPHP).
	> - From your WordPress editor, enter the single line code : `<?php wpit_multisort_insert(); ?>`
	> - Check the result on the page containing this call.
	> - Start playing with the options offered in the ImageTagger admin panel.

If you are interested in seeing the plugin in action, you might wish to go and have a look [here](http://www.photos-dauphine.com/phototheque "Check out here the WP ImagerTagger plugin in action").  

More information on this plugin utilization can be found [there](http://www.photos-dauphine.com/wp-imagetagger-plugin "WP ImageTagger Home").

Finally, you can direct your questions to [this page](http://www.photos-dauphine.com/ecrire "Write me here"), I will do my best to timely answer.

That's all for today - Enjoy !


== Frequently Asked Questions ==

= What are the prerequisites to run this plugin ? =

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

= How do I tag the images of my blog ? =

Having installed the plugin according to the instructions provided on the [installation page](http://wordpress.org/extend/plugins/wp-imagetagger/installation/ "How to install the WP ImageTagger plugin for your site ?"), two alternatives are offered to tag your images :

- From your WordPress administration panel, go to *Manage > ImageTagger* and start associating the first image found to any tag ;
- Alternatively and assuming your site displays captions below each image : from any post or page holding images, click on image captions (being administrator) and make the association with any tag.

= How do I know if an image is tagged or not ? =

A tooltip appears if you put your mouse pointer over the image caption in the page or post holding this image. This tooltip displays the tags associated to the image.

*In case your site theme does not use captions, this possibility will be offered soon (V2.3). This functionality will come through an admin page listing all your site images and the associated tags. You will be able to an image tagging status from this page.*

= How do I change the tags already associated to an image ? =

Go to the post or page containing this image. Being logged as administrator, click on the caption to be directed to the ImageTagger tagging panel.

*In case your site theme does not use captions, this possibility will be offered soon (V2.3). This re-tagging functionality will come through an admin page listing all your site images and the associated tags. You will be able to re-associate from this page.*

= How do I know the total number of images 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 ImageTagger admin panel as X/Y/Z. 

= How do I know the number of images I already tagged ? =
This information is the Y value displayed in light grey in the upper right part of the ImageTagger admin panel as X/Y/Z. 

= How do I know the number of images remaining to be tagged ? =
This information is the Z value displayed in light grey in the upper right part of the ImageTagger admin panel as X/Y/Z. Consequently Y+Z=X.

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

Edit your page or post with the WordPress editor and insert `<?php wpit_multisort_insert(); ?>`. Then ensure this page is allowed to run PHP code (refer for instance to the runPHP plugin for this purpose).

= Can I tag images without having yet inserted the ImageTagger form on my site ? =

Yes, these are two separate processes. On one hand you build your database by tagging the images, on the other you run queries on this database through to the `<?php wpit_multisort_insert(); ?>` call.

= 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 *combined display* : ultimately the 2 display styles can be merged in one ; the tag cloud is displayed above the search form, to bring at the same time the lightness and efficiency of the tag cloud method while proposing the search form for more advanced filtering.

= 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 image list* : the results are presented as a vertical list of images displayed with a title and the post they refer to. 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 thumbnail images. More information can be obtained rolling the mouse over each image, although it is not the most adequate for having a direct reading of the image related information.
- *image captions list* : this display mode does not display the image 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 redirect to a different page. See below for the implementation details.

= How do I manage the calls to wpit_multisort_insert() ? =

There are three possible implementations  

- Single page implementation :  

	> - Create a new page (or use existing one if you want).
	> - Make sure you can run PHP code from your page text (using plugins like runPHP).
	> - From your WordPress editor, enter the single line code : `<?php wpit_multisort_insert(); ?>`
	> - Check the result on the page containing this call.
	> - Play with the options offered in the ImageTagger admin panel to adjust the search and result format.

- 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/imagelibrary_search*, or use existing one if you want.
	> - Make sure you can run PHP code from your page text.
	> - From your WordPress editor, enter the single line code : `<?php wpit_multisort_insert("http://www.mysite.com/imagelibrary_result"); ?>`, assuming you want your visitor to be directed and have the results displayed on page *http://www.mysite.com/imagelibrary_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 argument passed to *wpit_multisort_insert()*, let's say *http://www.mysite.com/imagelibrary_result* (or use existing one if you want).
	> - Make sure you can run PHP code from your page text.
	> - From your WordPress editor, enter the single line code : `<?php wpit_multisort_insert(); ?>`.
	> - 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/imagelibrary_search* ; you will be directed to the result page *http://www.mysite.com/imagelibrary_result*
	> - Play with the options offered in the ImageTagger admin panel to adjust the search and result format.

- Sidebar tag cloud widget : (> V2.x)

	> - Under development.
	
= How is my WordPress database affected by this plugin ? =

- ImageTagger 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 images are stored in a new table *wp_term_relationships_img*.
- ImageTagger 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 image 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 image 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*,  
... 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](http://wordpress.org/extend/plugins/wp-imagetagger/changelog/ "WP ImageTagger Changelog"), *in project* section.  

= Damned, my question is not listed there !!! =
Did you make sure you read carefully enough the FAQ ? Although this is not my primary job, you might direct your questions to [this page](http://www.photos-dauphine.com/ecrire "Write me here"), I will do my best to timely answer.


== Screenshots ==

1. ImageTagger administration interface
2. ImageTagger image search form implementation


== Changelog ==

= 1.0 =
- First release. ImageTagger concept implemented with the minimum features set enabling root functions. Plugin available in French. English localization on going.

= 1.1 =
- Admin panel offers now a bunch of settings, like capability to display the list of images matching the searched tags in a gallery or itemized list mode.
- Result page is paginated. Number  of images shown is a parameter.
- Most of the messages are translated to English.

= 1.2 =
- Administration panel : input parameters are now validated against expected valid parameter ranges to make sure the plugin will not be shot by funky option settings. In case of improper entry, an explicit message is displayed while highlighting the faulty option entry line.

= 1.3 =
- PHP version is checked to ensure the server complies with the minimum required (PHP 5).
- Language localization now provided relying on I18n : english (default), french

= 1.4 =
- PHP support extended down to PHP4. Any dependency on PHP 5 was removed. Now the requirements are the same as for WordPress (PHP 4.3 or greater, MySQL 4.1.2 or greater), therefore I don't expect anymore issue.

= 1.5 =
- Irrelevant tags can be excluded from the tagging panel. The same possibility is offered to filter the list of tags displayed on the search page. This is parametrized through two separate CSV tag lists available in the Admin Panel.

= 2.0 =
- Tag cloud search representation added to the initial form, with capability to be combined with this form
- Search result : image title list mode added
- Possibility to have the search page address different from the result page address with explicit argument : `<?php wpit_multisort_insert("http://www.mysite.com/imagelibrary_result") ?>` ; without argument the results are displayed at the same address as the search page address
- All these new possibilities are parametrized through new admin panel options, plus additional parameters.

= 2.1 =
- Added parametrization of tag cloud, forgotten in 2.0 : min / max font size and number of tags to display.

= 2.2 =
- Admin panel : fixed font display problem
- Admin panel : options presentation improved (fields now come aligned for better readability)

= 2.3 =
- Images can now be associated not only to tags but as well as to categories defined in your blog. The admin panel allows to define the source for your keywords list : tags, categories, or tags and categories merged together.
- Tags can be gathered by groups through the admin panel. This group display is used for both the admin panel and the search page tags form.

= Under development =
- various bug fixed (notably path detection routine)
- Added to the admin page the possibility to list all the site images with their associated tags on one line, to provide a top level view of the tagging, and provide a way to change tagging for sites themes not displaying captions under the images. Images can be filtered as 'all images', 'tagged images' or 'untagged images'

- Improved pagination for multipage results, displaying quick access page links
- Tag cloud widget for the sidebar  
- Group wpit options in one string to streamline options table usage (no usability impact)
- Plugin internationalization : the `imagetagger.pot` file, required to translate the package to any other language, is provided for volunteers with the plugin files. If you are interested in internationalizing this plugin, I would certainly welcome your help. Simply [let me know](http://www.photos-dauphine.com/ecrire "Any volunteer to push the WP ImageTagger internationalization ?") so that I can push your translation to the repository. If needed I can provide you the methodology, many tools are available to ease this task.


== Upgrade Notice ==

= All versions =
This plugin is upward and backward compatible :

- The structure of the *wp_term_relationships_img* table, as defined for the release 1.0 did not evolve.
- If an option is required and not found in the *wp_options*, it will be initialized to a preset value, avoiding the plugin to be jeopardized the division by zero error styles.