==== Post Thumbs ====

Tags: thumbnails, post images, resize, highslide
Contributors: Victor, Alakhnor.
Requires at least: 2.0.7
Tested up to: 2.1.1
Stable tag: trunk


Post-thumb revisited automatically detects images, creates and displays thumbnails for posts. Numerous functions and options to modify themes are available.

== Description ==

The plugin:
	· automatically detects if there is an image in a post
	· creates a thumbnail for it and save it in a subfolder. This subfolder must exists and be writable. It is configured in 'Options'.
	· returns '<a href="post url" title="title">'.'<img src="thumbnail url" alt="alt text" /></a>' to be echoed where you want the thumbnail to appear.
	· can return post title, post author and post date below the thumbnail.
	· thumbnails can be linked to cool effects using Highslide library (included). 
	· if highslide is used, thumbnails inside posts can be automatically associated with it.
	· widget ready (see widget directory)

Important: 	Images can be on the same domain than your blog or an external url (might not work for all server though). 
		It can also be relative path until it’s not too complex!



==================
== Installation ==
==================

Unzip the file and upload the post-thumb folder to your Wordpress plugins folder. Activate it from the admin panel. Navigate to the options->post thumb and configure each option before using.

Important: You must configure the domain settings correctly or it will not work.

	· Full domain name: Your domain name including the http://. Example: http://www.google.com. No trailing ‘/’.

	· Base path: 	Enter the base path for your site. This is not your URL. It is the folder path where your blog is actually stored on your server. 
				This one is real important because it’s needed to generate / save images. No trailing ‘/’.

      			Example of Base path:   /username/domain.com 
                              			/home/username/public_html  
				For a local server, it could be: c:\wamp\www

	· Folder name: This one will stored thumb when they are generate by the plugin. It should be the relative path to thumbs. Must exist and be writable. No leading or trailing ‘/’.

	· Use Category names: if checked, PTR will look for a category default image named after: [video image path & name]cat-[category ID].[video image extension]

	· Video regex: this stands for PHP regex ie, REGular EXpression. Input a regular expression which will be used in a preg_match with the content of the post to detect if there is a video in it. Example: for Wordtube video, you should set it to "MEDIA=".

	· Video image: image to be used if a video is detected in the content of a post. No leading or trailing ‘/’.

	· Check stream: check it if you want a specific thumbnail displayed for Dailymotion, Gvideo or Youtube. Otherwise, default image will be displayed.

The rest of the options should be self-explanatory.

When options are validated, it will returns warning messages if some parameters are incorrect.



=============================
== The thumbnail functions ==
=============================

Main function parameters
========================
	· ALTAPPEND: text to append to create thumbnail name. Overide default if exists. 
	· WIDTH: resize width. Overide default if greater than 0. 
	· HEIGHT: resize height. Overide default if greater than 0. 
	· HCROP: horizontal crop. Crop if greater than 0. 
	· VCROP: vertical crop. Crop if greater than 0. 
	· KEEPRATIO: if set to 1, image ratio is kept. Overide default if exists. 
	· BASENAME: force generation of thumbnail and use generic name. Default is 0. 
	· TEXTBOX:  write post title at the bottom of the thumbnail if = 1. Default is 0. 
	· SHOWTITLE: display title, author or date below the thumbnail. Parameters: T, A, D. 
	· MYCLASSHREF: output class name in html <a class="myclasshref" href=...>
	· MYCLASSIMG: output class name in html <img class="myclassimg" href=...>
	· LIMIT: set the number of posts to check to return a random image. Default is 5.
	· USECATNAME: choose if category default image should used or not. Override default if exists.  


Secondary function parameters
============================= 
	· URL: URL to link to thumbnail. It must be a valid URL. 
	· ALTTEXT: text to show on mouseover. 


The html code
=============
The formatted returned html code is:

	<a class="myclasshref" href="URL" title="ALTTEXT"><img class="myclassimg" src="url thumbnail" alt="ALTTEXT"> 
	<a href="URL" style="width:largeur thumbnail"><span>titre, auteur, date</span>
 
The second line is only returned when SHOWTITLE is used.


Function get_thumb ()
=====================
Parameters
	· WIDTH, HEIGHT, HCROP, VCROP, KEEPRATIO, BASENAME, TEXTBOX, SHOWTITLE, MYCLASSHREF, MYCLASSIMG 
Description
	· This function returns the html code to display thumbnails. 
Utilisation
	· <?php get_thumb_array() ?> 


Function get_thumb_array ()
===========================
Parameters
	· WIDTH, HEIGHT, HCROP, VCROP, KEEPRATIO, BASENAME, TEXTBOX, SHOWTITLE, MYCLASSHREF, MYCLASSIMG 
Description
	· Return an array with thumbnail data. 
Utilisation
	· $thumb_array = get_thumb_array()
 
The returned array is: 
	
	o $thumb_array['post_url']       = post url (permalink)
	o $thumb_array['server_image']   = absolute path to thumbnail
	o $thumb_array['image_location'] = thumbnail url
	o $thumb_array['alt_text']       = post title
	o $thumb_array['post_ID']        = post ID
	o $thumb_array['the_image']      = image url
	o $thumb_array['show_title']     = SHOWTITLE result (html code string)


Function get_recent_thumbs ()
=============================
Parameters
	· WIDTH, HEIGHT, HCROP, VCROP, KEEPRATIO, TEXTBOX, SHOWTITLE, MYCLASSHREF, MYCLASSIMG, LIMIT, CATEGORY 
Description
	· This function returns the html code to display the last posts as thumbnails. 
o		CATEGORY: you may specify a category to get posts from
Utilisation
	· <?php get_recent_thumb() ?> 


Function get_random_thumb ()
============================
Parameters
	· WIDTH, HEIGHT, HCROP, VCROP, KEEPRATIO, TEXTBOX, SHOWTITLE, MYCLASSHREF, MYCLASSIMG, LIMIT 
Description
	· This function returns the html code to display a random thumbnail. 
Utilisation
	· <?php get_random_thumb() ?> 


Function tb_post_thumb_test ()
==============================
Parameters
	· true/false: if 'true', tests only image. If ‘false', tests images, videos and video streams. Default is false. 
Description
	· This function tests if an image is in post content. Tests are: 
	o Images are found with the tag <img src=..../> 
	o Video are found with Regex parameter in options. 
	o Video stream are found with link templates for Youtube, Dailymotion and gvideo. 
Utilisation
	· if (tb_post_thumb_test()) 


This functions use post data, so they should be used inside the Loop.



== Simple examples ==

To display the last 8 posts:

	$posts = get_posts('numberposts=8&offset=0');
	foreach ($posts as $post) :
		setup_postdata($post);
		$post_link = get_thumb(‘KEEPRATIO=0&VCROP=10&HCROP=10&MYCLASSHREF=thumb-class’);
		if ( !empty($post_link) ) { echo $post_link; }
	endforeach;


To display a random thumbnail:

	get_random_post(‘LIMIT=5&KEEPRATIO=1&WIDTH=240&HEIGHT=5000’);

L'utilisation d'une hauteur de 5000 permettra de conserver la largeur ŕ 240.


To display posts with their title and date below:

	$posts = get_posts('numberposts=8&offset=0');
	foreach ($posts as $post) :
		setup_postdata($post);
		$post_link = get_thumb(‘SHOWTITLE=TD’);
		if ( !empty($post_link) ) { echo $post_link; }
	endforeach;


== Advanced examples ==

To display a thumbnail for posts containing an image and an excerpt after:

	<?php
      post_content;
	$post_link = get_thumb ('keepratio=0');
	if (tb_post_thumb_test())
	{
		if ( !empty($post_link) ) { echo $post_link; }
		echo '<div class="post-meta">';
	}
	else echo '<div class="post-meta2">';
	$post->post_content = exclude_regex($post->post_content);
	the_excerpt();
	echo '</div>'; 
      ?>



=====================
== Post formatting ==
=====================

If you insert an image with a thumbnail in your post, with Image Manager for example, the image will be displayed using highslide.




================================
== Highslide effect functions ==
================================

Possible effects are ($hs_function):
	· hs_newwindow: open an iframe with a new web page. Size is given by width and height parameters.
	· hs_overlay: display an image. Size is image size.
	· hs_html: display an html content. Width is given by width parameter, height adjusts to content.

Frames can be bordered by 4 different aspects ($hs_style):
	· rounded-white: white border with rounded corner.
	· drop-shadow: white border with shadow effect.
	· beveled: grey smooth border.
	· outer-glow: white border glowing outside.


Function LB_effect ()
=====================
Parameters
	· $hs_function='hs_html' 
	· $style='rounded-white' 
	· $width='700' 
	· $height='500' 
	· $arg_array 
	· $html_content='' 
	· $tag='' 
Description
	· This function displays a content from post-thumb using highslide: 
	· $arg_array is an array which is returned by get_thumb_array or pt_thumb_array functions.
	· $html_content is used to display html content with 'hs_html' effect.
	· $tag is used to named "id" tags inside highslide display 
Utilisation
	· <?php echo LB_effect ('hs_overlay', 'drop-shadow', 700, 500, $post_array); ?> 


Function pt_get_effect ()
=========================
Parameters
	· $hs_function 
	· $hs_style 
	· $hs_url 
	· $hs_width 
	· $hs_height 
	· $hs_ID
	· $hs_text 
	· $hs_image='' 
	· $hs_img_url='' 
	· $hs_slasha='' 
	· $hs_content=''
Description
	· This function displays a content using highslide: 
		o $hs_url is url to link to
		o $hs_ID is used to named "id" tags inside highslide display
		o $hs_text is used for title
		o $hs_img_url is image url (if hs_overlay is used)
		o $slasha is a string appended to main html code. It's usually used to display additional informations (title, author, date).
		o $hs_content is used to display html content with 'hs_html' effect. 
Utilisation
	· <php echo LB_effect ('hs_overlay', 'drop-shadow', 700, 500, $post_array); ?> 


Function pt_thumbed_link ()
===========================
Parameters
	· $hs_style 
	· $hs_url 
	· $hs_width 
	· $hs_height 
	· $hs_ID 
	· $hs_text
	· $hs_image='' 
	· $hr_text=' 
	· $hr_title='' 
Description
	· This function displays an icon with highslide effect then a direct link. 
		o $hs_url is url to link to
		o $hs_ID is used to named "id" tags inside highslide display
		o $hs_text is used for title on icon
		o $hs_image is icon url. Default is post-thumb-path/images/pong.gif
		o $hr_text is displayed text on direct link. Default is $hs_text.
		o $hs_title is used for title on direct link. Default is $hs_text.
		o $html_content is used to display html content with 'hs_html' effect. 
Utilisation
	· <?php echo LB_effect ('hs_overlay', 'drop-shadow', 700, 500, $post_array); ?> 


Constant POSTHUMB_INFRAME
=========================
Parameters
	· None. 
Description
	· This constant is defined in header. 
	· It can be tested inside theme template to adapt display. 
	· It is true if display is in a frame. 
Utilisation
	· <?php if (POSTHUMB_INFRAME==0) { ?>


Function pt_list_categories ()
==============================
Parameters
	· Same as wp_list_categories. 
Description
	· This function works just like wp_list_categories except that it adds an highslide effect to each category link. 
Utilisation
	· <?php pt_list_categories(); ?> 


Function pt_list_bookmarks ()
=============================
Parameters
	· Same as wp_list_bookmarks. 
Description
	· This function works just like wp_list_bookmarks except that it will open links in a pop-up frame. 
Utilisation
	· <?php pt_list_bookmarks(); ?> 


Function pt_next_post_link ()
=============================
Parameters
	· Same as next_post_link. 
Description
	· This function works just like next_post_link except that it will follow links inside a pop-up frame. 
Utilisation
	· <?php pt_next_post_link(); ?> 


Function pt_previous_post_link ()
=================================
Parameters
	· Same as previous_post_link. 
Description
	· This function works just like previous_post_link except that it will follow links inside a pop-up frame. 
Utilisation
	· <?php previous_post_link(); ?>