Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 209 lines (143 sloc) 12.418 kB
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2 <html xmlns="http://www.w3.org/1999/xhtml">
3 <head>
4 <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
5 <title>A guide to the Get the Image plugin</title>
6
7 <link rel="stylesheet" href="readme.css" type="text/css" media="screen" />
8
9 </head>
10 <body>
11
12 <h1>A guide to Get the Image</h1>
13
14 <p class="first"><em>Get the Image</em> is a plugin that grabs images for you. It was designed to make the process of things such as adding thumbnails, feature images, and/or other images to your blog much easier, but it's so much more than that. It is an image-based representation of your WordPress posts.</p>
15
16 <p class="second">To use this plugin, you must be familiar with two very important things in WordPress: the <a href="http://codex.wordpress.org/Template_Hierarchy" title="Template Hierarchy">Template Hierarchy</a> and <a href="http://codex.wordpress.org/The_Loop" title="The Loop">The Loop</a>. If you don't have a working knowledge of those two things, then you should not attempt to use this plugin. More importantly, you should be familiar with how all of this works within your theme because not all themes are the same.</p>
17
18 <h2>What this plugin does</h2>
19
20 <p>This plugin was made to easily find images and add them on pages where the full post isn't shown. This is the order in which the plugin attempts to grab an image.</p>
21
22 <ol>
23 <li>Looks for an image by custom field.</li>
24 <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>
25 <li>If no image is found, it grabs an image attached to your post.</li>
26 <li>If no image is attached, it can extract an image from your post content (off by default).</li>
453f159 Updating the documentation for the plugin.
greenshady authored
27 <li>If no image is found, checks for a custom callback function that developers may optionally set.</li>
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
28 <li>If no image is found at this point, it will default to an image you set (not set by default).</li>
29 </ol>
30
31 <h2>How to install the plugin</h2>
32
33 <ol>
34 <li>Uzip the <code>get-the-image.zip</code> folder.</li>
35 <li>Upload the <code>get-the-image</code> folder to your <code>/wp-content/plugins</code> directory.</li>
36 <li>In your WordPress dashboard, head over to the <em>Plugins</em> section.</li>
37 <li>Activate <em>Get The Image</em>.</li>
38 </ol>
39
40 <h2>How to use the plugin</h2>
41
42 <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>
43
44 <p><strong>Example with function-style parameters</strong></p>
45
453f159 Updating the documentation for the plugin.
greenshady authored
46 <pre><code>&lt;?php get_the_image( array( 'meta_key' => array( 'Thumbnail', 'thumbnail' ), 'size' => 'thumbnail' ) ); ?></code></pre>
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
47
48 <h2>The image script parameters</h2>
49
50 <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>
51
52 <pre><code>$defaults = array(
453f159 Updating the documentation for the plugin.
greenshady authored
53 'meta_key' => array( 'Thumbnail', 'thumbnail' ),
54 'post_id' => $post->ID,
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
55 'attachment' => true,
56 'the_post_thumbnail' => true,
453f159 Updating the documentation for the plugin.
greenshady authored
57 'size' => 'thumbnail',
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
58 'default_image' => false,
59 'order_of_image' => 1,
60 'link_to_post' => true,
61 'image_class' => false,
62 'image_scan' => false,
63 'width' => false,
64 'height' => false,
453f159 Updating the documentation for the plugin.
greenshady authored
65 'format' => 'img',
66 'meta_key_save' => false,
67 'callback' => null,
68 'cache' => true,
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
69 'echo' => true
70 );</code></pre>
71
72 <dl>
453f159 Updating the documentation for the plugin.
greenshady authored
73 <dt>meta_key</dt>
7d49016 Bringing this up to 0.6.1 standards.
greenshady authored
74 <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>). By default, this is an array of meta keys, but it can also be a string for a single meta key.</dd>
453f159 Updating the documentation for the plugin.
greenshady authored
75 <dt>post_id</dt>
76 <dd>The ID of the post to get the image for. This defaults to the current post in the loop.</dd>
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
77 <dt>attachment</dt>
78 <dd>The script will look for images attached to the post (set to <code>true</code> by default).</dd>
79 <dt>the_post_thumbnail</dt>
ca5ff9c Bringing code up to version 0.5.
greenshady authored
80 <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>
453f159 Updating the documentation for the plugin.
greenshady authored
81 <dt>size</dt>
82 <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>
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
83 <dt>default_image</dt>
84 <dd>Will take the input of an image URL and use it if no other images are found (no default set).</dd>
85 <dt>order_of_image</dt>
86 <dd>You can choose for the script to grab something other than the first attached image. This only refers to image attachments.</dd>
87 <dt>link_to_post</dt>
453f159 Updating the documentation for the plugin.
greenshady authored
88 <dd>Whether the image shown should be linked to the post (set to <code>true</code> by default).</dd>
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
89 <dt>image_class</dt>
90 <dd>You can give an additional class to the image for use in your CSS.</dd>
91 <dt>image_scan</dt>
92 <dd>If set to <code>true</code>, the script will search within your post for an image that's been added.</dd>
93 <dt>width</dt>
94 <dd>Set the width of the image on output.</dd>
95 <dt>height</dt>
96 <dd>Set the height of the image on output.</dd>
453f159 Updating the documentation for the plugin.
greenshady authored
97 <dt>format</dt>
98 <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>
99 <dt>meta_key_save</dt>
100 <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>
101 <dt>callback</dt>
102 <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>
103 <dt>cache</dt>
104 <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>
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
105 <dt>echo</dt>
106 <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>
107 </dl>
108
109 <h2>Some examples of how to use this plugin</h2>
110
111 <p><strong>Example 1:</strong> Let's suppose that you want to add thumbnails to your category archive pages. What you'll need to do is open your <code>category.php</code> file and add this code within the Loop:</p>
112
113 <pre><code>&lt;?php get_the_image(); ?></code></pre>
114
115 <p>By default, that will look for an image with the custom field <strong>key</strong> <code>Thumbnail</code> and <code>thumnbail</code>. If that image doesn't exist, it will check if a post image has been set. If that image doesn't exist, it will search for any images attached to your post.</p>
116
117 <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>
118
7d49016 Bringing this up to 0.6.1 standards.
greenshady authored
119 <pre><code>&lt;?php get_the_image( array( 'meta_key' => 'Feature', 'size' => 'full' ) ); ?></code></pre>
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
120
121 <p>If no feature image exists by custom field, it will look for images attached to your post.</p>
122
123 <p><strong>Example 3:</strong> If you want to have a sort of fallback image, then you can set an image for the script to default to if no other images are found.</p>
124
125 <pre><code>&lt;?php get_the_image( array( 'default_image' => 'http://mysite.com/wp-content/uploads/example.jpg' ) ); ?></code></pre>
126
127 <p><strong>Example 4:</strong> You can even make the script scan for images that have been added to your post with this:</p>
128
129 <pre><code>&lt;?php get_the_image( array( 'image_scan' => true ) ); ?></code></pre>
130
131 <p><strong>Example 5:</strong> You might want to make the script grab the second attached image to a post. You can do that with this code:</p>
132
133 <pre><code>&lt;?php get_the_image( array( 'order_of_image' => 2 ) ); ?></code></pre>
134
7d49016 Bringing this up to 0.6.1 standards.
greenshady authored
135 <p><strong>Example 6:</strong> Saving an image to the <code>Thumbnail</code> custom field automatically.</p>
136
137 <pre><code>&lt;?php get_the_image( array( 'meta_key_save' => 'Thumbnail' ) ); ?></code></pre>
138
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
139 <h2>A real-world example</h2>
140
141 <p>This is an example Loop, which may differ slightly from your theme, but the concept is the same. The call to get the image can go anywhere between the opening and closing lines.</p>
142
143 <pre><code>&lt;?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
144
145 &lt;div id="post-&lt;?php the_ID(); ?>" &lt;?php post_class(); ?>>
146
7d49016 Bringing this up to 0.6.1 standards.
greenshady authored
147 &lt;?php get_the_image( array( 'meta_key' => 'feature_img', 'size' => 'medium', 'width' => '200', 'height' => '200', 'image_class' => 'feature' ) ); ?>
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
148
149 &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>
150
151 &lt;div class="entry-summary">
152 &lt;?the_excerpt(); ?>
153 &lt;/div>
154
155 &lt;/div>
156
157 &lt;?php endwhile; endif; ?></code></pre>
158
159 <h2>Protect yourself from errors in the future</h2>
160
161 <p>Sometimes, we stop using plugins, but we forget to remove the function calls to the plugin in our theme files. When deactivated, this causes errors. To protect yourself from these errors, you can call the image script like this:</p>
162
163 <pre><code>&lt;?php if ( function_exists( 'get_the_image' ) ) { get_the_image(); } ?></code></pre>
164
165 <p>Basically, this just checks to see if the plugin is activated and has loaded the appropriate function.</p>
166
167 <h2>Styling your images</h2>
168
169 <p>The plugin will help you style your images by giving you some CSS classes to work with. It will turn your custom field keys and default size into CSS classes. You can also choose to input your own class.</p>
170
171 <p>By default, you can add this to your CSS:</p>
172
173 <pre><code>img.thumbnail { }</code></pre>
174
175 <p>Let's suppose you've used this code:</p>
176
ca5ff9c Bringing code up to version 0.5.
greenshady authored
177 <pre><code>&lt;?php get_the_image( array( 'custom_key' => array( 'Donkey Kong', 'mario' ), 'size' => 'full' ) ); ?></code></pre>
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
178
179 <p>This will give you these CSS classes to work with:</p>
180
181 <pre><code>img.full { }
182 img.donkey-kong { }
183 img.mario { }</code></pre>
184
185 <p>You can also input a custom CSS class like so:</p>
186
187 <pre><code>&lt;?php get_the_image( array( 'image_class' => 'custom-image' ) ); ?></code></pre>
188
ca5ff9c Bringing code up to version 0.5.
greenshady authored
189 <p>You will still have the <code>size</code> and <code>custom_key</code> classes plus your additional class:</p>
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
190
191 <pre><code>img.custom-image { }
192 img.thumbnail { }</code></pre>
193
194 <h2>Plugin support</h2>
195
196 <p>I run a WordPress community called <a href="http://themehybrid.com" title="Theme Hybrid">Theme Hybrid</a>, which is where I fully support all of my WordPress projects, including plugins. You can sign up for an account to get plugin support for a small yearly fee ($25 <acronym title="United States Dollars">USD</acronym> at the time of writing).</p>
197
198 <p>I know. I know. You might not want to pay for support, but just consider it a donation to the project. To continue making cool, GPL-licensed plugins and having the time to support them, I must pay the bills.</p>
199
200 <h2>Copyright &amp; license</h2>
201
202 <p><em>Get the Image</em> is licensed under the <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" title="GNU GPL">GNU General Public License</a>, version 2 (<acronym title="GNU General Public License">GPL</acronym>).</p>
203
204 <p>This plugin is copyrighted to <a href="http://justintadlock.com" title="Justin Tadlock">Justin Tadlock</a>.</p>
205
bd4cc24 Bringing plugin up to version 0.6.2.
greenshady authored
206 <p>2008&thinsp;&ndash;&thinsp;2011 &copy; Justin Tadlock. All rights reserved.</p>
4c2ae75 Importing the files and folders for the Get the Image plugin.
greenshady authored
207
208 </body>
209 </html>
Something went wrong with that request. Please try again.