=== WP ImageTagger === Contributors: phd Donate link: http://www.photos-dauphine.com/wp-imagetagger-plugin Tags: widget, plugin, images, taxonomy, photos, tags, gallery, photoblog, search, engine, classification, library Requires at least: 2.7 Tested up to: 2.9.1 Stable tag: 2.5.4 == 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 or category. It includes a tagcloud widget that will make the process straightforward for everyone. The following functionalities are available for your blog after installing the *ImageTagger* plugin package : > - Associate tags to images from the *Tag Editor* > - List all the images of your site and associated tags in one central place to ease the tagging process with the *Image Explorer* > - 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 > - Seamless integration in your sidebar thanks to the *ImageTagger tagcloud widget*, with direct connection to the image tagging database you just built > - The *ImageTagger* image taxonomy can optionally supersede the default post taxonomy 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 this simple 10-step recipe : 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 click on the *Plugins* left menu. Expand the *Installed* view. 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 *Settings > ImageTagger* and start associating the first image found to any tag in the *Tag Editor* > - Or, still from the *ImageTagger* 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 image : from any post or page holding images, click on the image 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 *ImageTagger shortcode* : `[imagetagger]` - 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 ImageTagger admin panel. 9. By default your **search page** is the same as your result page. You can also choose to activate the ImageTagger widget to integrate an image search tagcloud in your sidebar, or to manage the search page at a different address for a specific use. 10. Go ! 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, if you have any questions, please refer to the [FAQ bottom page](http://wordpress.org/extend/plugins/wp-imagetagger/faq/ "If you need some help"), section - section *Damned, my question is not listed there*. 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 are defined the tags proposed for the image 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 image formats are supported ? = JPEG, GIF and PNG are supported. = Are the WordPress gallery themes supported ? = Yes, the images managed within WordPress galleries will be available for tagging as any other standalone image. = 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 in the *Tag Editor* ; - Or, 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 image : from any post or page holding images, click on the image caption (being administrator) and make the association with any tag from the *Tag Editor* panel. = How do I know if an image 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 images and the associated tags. You are able to get any image tagging status from this page. Additionally, in case your site theme displays image captions : 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. = How do I change the tags already associated to an image ? = 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 images and the associated tags. You are able to get any image tagging status from this page. Additionally, in case your site theme displays image captions : click on the image caption (being administrator) and make the association with any tag from the Tag Editor panel. = 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 the specific *ImageTagger shortcode* `[imagetagger]`. From this point the plugin will manage the calls to the adequate functions. = 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 `[imagetagger]` 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 **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 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 *ImageTagger shortcode* : `[imagetagger]`. > - Check the result on the page containing this call. > - Start playing with the options offered in the *ImageTagger 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/imagelibrary_search*, or use existing one if you want. > - From your WordPress editor, enter *ImageTagger shortcode*, with one option : `[imagetagger result_page_url="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 URL passed inside the *ImageTagger shortcode* let's say *http://www.mysite.com/imagelibrary_result* (or use existing one if you want). > - From your WordPress editor, enter the *ImageTagger shortcode* : `[imagetagger]`. > - 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 : > - In this case, the call to the *ImageTagger* 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 *ImageTagger 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 *ImageTagger 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 ImageTagger 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 `imagetagger` 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 : [imagetagger opt1="val1" opt2="val2" ...]

The 6 options available are : $result_page_url = URI of the result page, for instance 'http://www.mysite.com/imagelibrary_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 : [imagetagger] *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 : [imagetagger 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 : [imagetagger 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. = What is the Image Taxonomy feature all about ? = This option is meaningful when you are managing a large collection of images. The idea is to tag the images with *ImageTagger*, and let then the plugin automatically associate the relevant tags to the post holding these images. - 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 *image 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 an image, the collection of tags associated to the images contained in the post (*image taxonomy*) to which belongs the image you tagged will be associated to the post itself. At the time you tag an image, the tags formerly associated to the post containing the image are replaced by this *image taxonomy*. - The *image taxomonmy* mechanism applies to the *posts* only given that WordPress does not support *page* tagging. Tagging an image contained in a page will not have any other effect than the image tagging by itself. - What is the interest in having the *post taxonomy* driven by the *image taxonomy* ? It will help you keeping with a coherent post tagging scheme by solely focusing on your images tagging. When the *image taxonomy* is activated, the WordPress database is updated to replace the tags manually associated to the posts by the *image taxonomy* (on top of updating the *wp_term_relationships_img* table which is the basic *ImageTagger* mechanism) : - the table *wp_term_relationship* is updated to associate the post to the tags provided by the *image 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, *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*. - If you decide to have the *image 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 *ImageTagger Admin Panel*. - 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 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](http://www.photos-dauphine.com/ecrire "Write me here"), 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 ImageTagger 2.4.1 | 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 images, 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](http://www.photos-dauphine.com/ecrire "Suggestions"). == Screenshots == 1. ImageTagger administration interface 2. ImageTagger image search form implementation == Changelog == = Under development / Ideas for future implementation = - Fix GD problem occuring in some cases - Plugin cleanup to make the HTML generated code strict XHTML compliant - Improved pagination for multipage results, displaying quick access page links - Log visitors search and make it visible to the administrator - 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. - *Any idea to make this plugin even more valuable to you ? Spin your suggestions [this way](http://www.photos-dauphine.com/ecrire "Suggestions").* = Latest stable release : 2.5.4 = - This release is major in the sense it brings the *image taxonomy* feature into real life. I am glad to come to this achievement, I envisionned it as the objective for this plugin : having the tags you associate to the images directly controlling the tags associated to the post containing those images. Very nice for lazy people, as I tend to be sometimes. It should be a nice fit when your site content consists largely in images. Note that this feature will take control over the standard WordPress tables *wp_term_relationship* and *wp_term_taxonomy*. As such, take some time reading the FAQ before deciding to activate this option and, although it has been extensively tested under various situations ... make a backup of your database before trying it out ! = 2.5.3.3 = - When linking the result gallery images to the post containing the image, the permalink is used instead of the http://www.mysite.com/?p=41 notation. - Rich-text-tags now supported. An image used in the standard WordPress tag result header page will be linked back from the ImageTagger result page (if link parametrized as "link to post") on the tag result page. - New option in Admin Panel : the ImageTagger tag cloud can be displayed by ascending alphabetical order (default), descending rank order, or random. - New option in Admin Panel : the credit line displayed at the bottom of the search form in its plain version (not in accordance with the WP Plugins authoring guidelines, I concede) can now be disabled. In this case and assuming you enjoy this plugin, I let to your good willingness the possibility to include anywhere else on your site a credit line linking back to my home site (http://www.photos-dauphine.com). You decide. Be simply aware that this plugin requires that I spend a very significant amount of my spare time to answer the support requests, maintain and manage the evolution with bunch of new features. = 2.5.3.2 = - All the ImageTagger supported formats (gif, jpeg, png) now take benefit of the thumbnail transfer optimization. In the previous version only the jpeg files had their transfer optimized. - Fix : some functions released to be used later (association of image tags to the post containing the images) were causing servers in PHP 4.3 to fail at plugin init. = 2.5.3.1 = - In marginal cases, the server side image resizing introduced in 2.5.3 was found not to provide the expected results. A new option was added in the Admin Panel / Output format / Optimize thumbnail transfer. By default this option is set to "No", which is the setup that will work in any case. To move to the optimized transfer mode, set this to "Yes", save the ImageTagger options and check that your search result displayed as a gallery properly displays the thumbnails. If not, revert this option setting to "No". If the GD graphic library is not available on your server (check it in the page footnote), this option will be set to "No" and will not be selectable. = 2.5.3 = - Dynamically resizes images server side before transferring images for gallery or image list result mode. This provides a much faster gallery display when transferring big number of images. *This improvement is only made available for sites being hosted on servers having the GD library module enabled. This setup is automatically detected by ImageTagger*. To know if you benefit or not of this feature, check the footnote line in your admin panel : if you read *GD Lib not available*, your server does not support it. Otherwise, the GD library version is displayed. - Minor fixes for marginal cases (all images tagged). = 2.5.2 = - The plugin can now be inserted in a page or post using the safer `[imagetagger options...]` shortcode notation. Refer to the [FAQ](http://wordpress.org/extend/plugins/wp-imagetagger/faq/) for any detail. - This improved implementation does not require anymore to have PHP execution enabled in your page. - The direct PHP call to the plugin function `wpit_multisort_insert()` is deprecated and should not be used anymore. It still works with a recommendation message, and will not be supported in future releases. = 2.5.1 = - Minor bug fixes - Added gradient colors to the tag cloud (widget and plain page). The options can be parametrized from the *ImageTagger* admin interface for the plain page version, and from the *ImageTagger* widget control window for the widget implementation. = 2.5 = - The plugin is now delivered with a widget interface. This new feature enables the ImageTagger tagcloud in your site sidebar. - There is currently no error checking on the widget input parameters - Be kind to him ! = 2.4.2 = - Various minor fixes in the Image Explorer (search functionality) = 2.4.1 = - Admin panel : fixed Tag Editor and Image Explorer inconsistencies in specific cases (no image available, all images tagged, all images untagged) = 2.4 = - Admin panel : expanded tagging control panel. Two views are now available : a first view ("Tag Editor", default) to tag the images. This view scans the untagged images and displays those for tagging ; a second view ("Image Explorer") listing all the site images. This list can be filtered to show only the tagged images, untagged images, or all the referenced images. This approach provides a way to rework tagging for sites themes not displaying captions under the images. A search field is available to filter the listed images. - Admin panel : the options setup panel can now be minimized to avoid screens unnecesarily overloaded with data not of immediate use. = 2.3.3 = - various fixes, notably a possible path detection issue for specific twisted server setup cases. **For that reason it is a major upgrade given the possible impact of the issue - get this one ASAP**. In specific cases, the plugin could not detect images due to broken image path reconstruction. = 2.3.2 = - Fix : .png and .gif formats now supported on top of .jpeg. = 2.3.1 = - Fix : various side effects = 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. = 2.2 = - Admin panel : fixed font display problem - Admin panel : options presentation improved (fields now come aligned for better readability) = 2.1 = - Added parametrization of tag cloud, forgotten in 2.0 : min / max font size and number of tags to display. = 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 : `` ; 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. = 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. = 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.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.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.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.0 = - First release. ImageTagger concept implemented with the minimum features set enabling root functions. Plugin available in French. English localization on going. == 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.