Updating the documentation for the plugin.

git-svn-id: http://svn.locallylost.com/plugins/get-the-image/trunk@447 dba0f204-706d-4bc1-bc29-8b92e0485636

readme.html

@@ -24,6 +24,7 @@ <h2>What this plugin does</h2>
 	<li>If no image is added by custom field, check for a <a href="http://justintadlock.com/archives/2009/11/16/everything-you-need-to-know-about-wordpress-2-9s-post-image-feature" title="WordPress 2.9's post image feature">post image</a> (WordPresss 2.9+ feature).</li>
 	<li>If no image is found, it grabs an image attached to your post.</li>
 	<li>If no image is attached, it can extract an image from your post content (off by default).</li>
+	<li>If no image is found, checks for a custom callback function that developers may optionally set.</li>
 	<li>If no image is found at this point, it will default to an image you set (not set by default).</li>
 </ol>
 
@@ -36,50 +37,55 @@ <h2>How to install the plugin</h2>
 	<li>Activate <em>Get The Image</em>.</li>
 </ol>
 
-<p class="alert">If you are upgrading from a version prior to 0.3 just overwrite your old files.  You'll need to change the calls to the plugin in your template files because how the plugin works has changed.  Follow the instructions below to see how the image script should be called.</p>
-
 <h2>How to use the plugin</h2>
 
 <p>To call the image script, you'll need to use what's called <a href="http://codex.wordpress.org/Template_Tags/How_to_Pass_Tag_Parameters#Tags_with_PHP_function-style_parameters" title="PHP function-style parameters">function-style parameters</a>.</p>
 
 <p><strong>Example with function-style parameters</strong></p>
 
-<pre><code>&lt;?php get_the_image( array( 'custom_key' => array( 'Thumbnail', 'thumbnail' ), 'size' => 'thumbnail' ) ); ?></code></pre>
+<pre><code>&lt;?php get_the_image( array( 'meta_key' => array( 'Thumbnail', 'thumbnail' ), 'size' => 'thumbnail' ) ); ?></code></pre>
 
 <h2>The image script parameters</h2>
 
 <p>By simply making a function call to <code>&lt;?php get_the_image(); ?></code> within a template file, the script will default to this:</p>
 
 <pre><code>$defaults = array(
-	'custom_key' => array( 'Thumbnail', 'thumbnail' ),
+	'meta_key' => array( 'Thumbnail', 'thumbnail' ),
+	'post_id' => $post->ID,
 	'attachment' => true,
-	'size' => 'thumbnail',
 	'the_post_thumbnail' => true,
+	'size' => 'thumbnail',
 	'default_image' => false,
 	'order_of_image' => 1,
 	'link_to_post' => true,
 	'image_class' => false,
 	'image_scan' => false,
 	'width' => false,
 	'height' => false,
+	'format' => 'img',
+	'meta_key_save' => false,
+	'callback' => null,
+	'cache' => true,
 	'echo' => true
 );</code></pre>
 
 <dl>
-	<dt>custom_key</dt>
-	<dd>This parameter refers to a custom field key (or keys) that you use.  Remember, custom field keys are case-sensitive (defaults are <code>Thumbnail</code> and <code>thumbnail</code>).</dd>
+	<dt>meta_key</dt>
+	<dd>This parameter refers to post meta keys (custom fields) that you use.  Remember, meta keys are case-sensitive (defaults are <code>Thumbnail</code> and <code>thumbnail</code>).</dd>
+	<dt>post_id</dt>
+	<dd>The ID of the post to get the image for.  This defaults to the current post in the loop.</dd>
 	<dt>attachment</dt>
 	<dd>The script will look for images attached to the post (set to <code>true</code> by default).</dd>
-	<dt>size</dt>
-	<dd>This refers to the size of an attached image.  You can choose between <code>thumbnail</code>, <code>medium</code>, <code>large</code>, <code>full</code>, or any custom image size you have available (the default is <code>thumbnail</code>).</dd>
 	<dt>the_post_thumbnail</dt>
 	<dd>This refers to the WordPress 2.9's new <code>the_post_thumbnail()</code> feature. By having this set to <code>true</code>, you may select an image from the post image meta box while in the post editor.</dd>
+	<dt>size</dt>
+	<dd>This refers to the size of an attached image.  You can choose between <code>thumbnail</code>, <code>medium</code>, <code>large</code>, <code>full</code>, or any custom image size you have available (the default is <code>thumbnail</code>).</dd>
 	<dt>default_image</dt>
 	<dd>Will take the input of an image URL and use it if no other images are found (no default set).</dd>
 	<dt>order_of_image</dt>
 	<dd>You can choose for the script to grab something other than the first attached image. This only refers to image attachments.</dd>
 	<dt>link_to_post</dt>
-	<dd>Whether the attachment image should be linked to the post (set to <code>true</code> by default).</dd>
+	<dd>Whether the image shown should be linked to the post (set to <code>true</code> by default).</dd>
 	<dt>image_class</dt>
 	<dd>You can give an additional class to the image for use in your CSS.</dd>
 	<dt>image_scan</dt>
@@ -88,6 +94,14 @@ <h2>The image script parameters</h2>
 	<dd>Set the width of the image on output.</dd>
 	<dt>height</dt>
 	<dd>Set the height of the image on output.</dd>
+	<dt>format</dt>
+	<dd>What format to return the image in.  If set to <code>array</code> the return value of the function will be an array of <code>&lt;img></code> attributes.  All other values will return the <code>&lt;img></code> element.</dd>
+	<dt>meta_key_save</dt>
+	<dd>A meta key to save the image <acronym title="Uniform Resource Locator">URL</acronym> as.  This is useful if you're not using custom fields but want to cut back on database queries by having the script automatically set the custom field for you.  By default, this is set to <code>false</code>.</dd>
+	<dt>callback</dt>
+	<dd>A custom callback function that will be called if set.  It's only called if no images are found by any other options of the plugin.  However, it will be run before the <code>default_image</code> is set.  The <code>$args</code> array is passed to the callback function as the only parameter.</dd>
+	<dt>cache</dt>
+	<dd>Whether to use the WordPress Cache <acronym title="Application Programming Interface">API</acronym> (integrates with caching plugins) to serve the post images.  By default, this is set to <code>true</code>.</dd>
 	<dt>echo</dt>
 	<dd>If set to <code>true</code>, the image is shown on the page.  If set to <code>false</code>, the image will be returned to use in your own function. (Set to <code>true</code> by default.)</dd>
 </dl>
@@ -102,7 +116,7 @@ <h2>Some examples of how to use this plugin</h2>
 
 <p><strong>Example 2:</strong> Let's suppose you want a full-sized image and maybe you want to grab it by a custom field key of <code>Feature</code>.  Depending on your theme, this will need to go within the Loop in whatever file is calling the featured article.</p>
 
-<pre><code>&lt;?php get_the_image( array( 'custom_key' => array( 'Feature' ), 'size' => 'full' ) ); ?></code></pre>
+<pre><code>&lt;?php get_the_image( array( 'meta_key' => array( 'Feature' ), 'size' => 'full' ) ); ?></code></pre>
 
 <p>If no feature image exists by custom field, it will look for images attached to your post.</p>
 
@@ -126,7 +140,7 @@ <h2>A real-world example</h2>
 
 	&lt;div id="post-&lt;?php the_ID(); ?>" &lt;?php post_class(); ?>>
 
-		&lt;?php get_the_image( array( 'custom_key' => array( 'feature_img' ), 'size' => 'medium', 'width' => '200', 'height' => '200', 'image_class' => 'feature' ) ); ?>
+		&lt;?php get_the_image( array( 'meta_key' => array( 'feature_img' ), 'size' => 'medium', 'width' => '200', 'height' => '200', 'image_class' => 'feature' ) ); ?>
 
 		&lt;h2>&lt;a href="&lt;?php the_permalink(); ?>" title="&lt;?php the_title_attribute(); ?>" rel="bookmark">&lt;?php the_title(); ?>&lt;/a>&lt;/h2>
 

readme.txt

@@ -4,7 +4,7 @@ Donate link: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_i
 Tags: image, images, thumbnail
 Requires at least: 2.9
 Tested up to: 3.0
-Stable tag: 0.5
+Stable tag: 0.6
 
 An easy-to-use image script for adding things such as thumbnails and feature images.
 
@@ -56,7 +56,12 @@ You can view this plugin in action on my <a href="http://justintadlock.com" titl
 
 == Changelog ==
 
-Earlier versions were not documented well.
+**Version 0.6**
+
+* Deprecated `custom_key` in favor of `meta_key`.
+* Added the `meta_key_save` argument to allow users to save the image as a meta key/value pair.
+* Added a `callback` argument to allow developers to create a custom callback function.
+* Added a `cache` argument, which allows users to turn off caching.
 
 **Version 0.5**