(add stub) |
(Undo revision 169987 by Annpaul244 (talk)) |
||
(109 intermediate revisions by 25 users not shown) | |||
Line 1: | Line 1: | ||
+ | {{Languages| |
||
− | {{Draft}} |
||
+ | {{en|Post Thumbnails}} |
||
+ | {{it|Immagini in evidenza}} |
||
+ | {{ja|Post Thumbnails}} |
||
+ | }} |
||
− | + | '''Post Thumbnails''' is a [[Theme Features|theme feature]] introduced with [[Version 2.9]]. It was quickly changed to '''Featured Images''' with [[Version 3.0]]. Post Thumbnail, now Featured Image, is an image that is chosen as the representative image for Posts, Pages or Custom Post Types. The display of this image is up to the theme. This is especially useful for "magazine-style" themes where each post has an image. |
|
== Enabling Support for Post Thumbnails == |
== Enabling Support for Post Thumbnails == |
||
− | Themes have to declare their support for post |
+ | Themes have to declare their support for post thumbnails before the interface for assigning these images will appear on the Edit Post and Edit Page screens. They do this by putting the following in their [[Theme_Development#Functions_File|functions.php]] file: |
− | <pre>add_theme_support( 'post-thumbnails' );</pre> |
+ | <pre>add_theme_support( 'post-thumbnails' ); </pre> |
+ | '''Note:''' To enable Post Thumbnails only for specific post types see [[Function Reference/add_theme_support|add_theme_support()]] |
||
− | == Template Functions == |
||
+ | == Setting a Post Thumbnail == |
||
− | DOCUMENTATION PENDING |
||
+ | If your theme was successful in adding support for Post Thumbnails the "Featured Image" metabox will be visible on the on the Edit Post and Edit Page screens. If it isn't, make sure "Featured Image" is enabled in the [[Administration Screens#Screen_Options|screen options]] on the top right. |
||
− | == Outside Resources == |
||
+ | <div style="border:1px solid #DADADA; width: 297px; padding: 5px">[[Image:featured_image_metabox.jpeg|297px|Featured Image Metabox]]</div> |
||
− | http://markjaquith.wordpress.com/2009/12/23/new-in-wordpress-2-9-post-thumbnail-images/ |
||
+ | <small>Featured Image metabox</small> |
||
+ | After clicking the "Set featured image" link follow the same steps as [[Inserting_Images_into_Posts_and_Pages|inserting images]] in Posts and Pages. Once you have selected the featured image and determined the image settings, click on the blue "Set featured image" button, to set it as the featured image for your page or post. |
||
− | To-do: incorporate that information into the Codex |
||
+ | |||
+ | <div style="border:1px solid #DADADA; width: 160px; padding: 5px">[[Image:set_featured_image.png|160px|none|"Set featured image" button]]</div> |
||
+ | <small>"Set featured image" button</small> |
||
+ | |||
+ | == Function Reference == |
||
+ | |||
+ | {| cellspacing="10" width="100%" |
||
+ | |- valign="top" |
||
+ | | width="50%" | |
||
+ | |||
+ | {| class="widefat" |
||
+ | |- style="background:#464646; color:#d7d7d7;" |
||
+ | ! '''Template Tags''' |
||
+ | |- |
||
+ | | |
||
+ | * <tt>[[Function Reference/has_post_thumbnail | has_post_thumbnail()]]</tt> |
||
+ | * <tt>[[Function Reference/the_post_thumbnail | the_post_thumbnail()]]</tt> |
||
+ | * <tt>[[Function Reference/the_post_thumbnail_url | the_post_thumbnail_url()]]</tt> |
||
+ | * <tt>[[Function Reference/get_the_post_thumbnail | get_the_post_thumbnail()]]</tt> |
||
+ | |} |
||
+ | |||
+ | | width="50%" | |
||
+ | |||
+ | {| class="widefat" |
||
+ | |- style="background:#464646; color:#d7d7d7;" |
||
+ | ! '''Other Functions''' |
||
+ | |- |
||
+ | | |
||
+ | * <tt>[[Function Reference/add_image_size | add_image_size()]]</tt> |
||
+ | * <tt>[[Function Reference/set_post_thumbnail_size | set_post_thumbnail_size()]]</tt> |
||
+ | * <tt>[[Function Reference/get_post_thumbnail_id | get_post_thumbnail_id()]]</tt> |
||
+ | |} |
||
+ | |} |
||
+ | |||
+ | == Examples == |
||
+ | |||
+ | === Default Usage === |
||
+ | |||
+ | <pre> |
||
+ | // check if the post has a Post Thumbnail assigned to it. |
||
+ | if ( has_post_thumbnail() ) { |
||
+ | the_post_thumbnail(); |
||
+ | } |
||
+ | the_content(); |
||
+ | </pre> |
||
+ | |||
+ | '''Note:''' To return the Post Thumbnail for use in your PHP code instead of displaying it, use: [[Function Reference/get_the_post_thumbnail|get_the_post_thumbnail()]] |
||
+ | |||
+ | === Linking to Post or Larger Image === |
||
+ | |||
+ | To link the Post Thumbnail to the Post permalink or a larger image see the examples in [[Function Reference/the_post_thumbnail#Examples |the_post_thumbnail()]] |
||
+ | |||
+ | === Thumbnail Sizes === |
||
+ | |||
+ | The default image sizes of WordPress are "thumbnail" (and its "thumb" alias), "medium", "medium_large", "large" and "full" (the image you uploaded). These image sizes can be configured in the WordPress Administration [[Settings Media Screen|Media Screen]] under Settings > Media. If your theme enables Post Thumbnails then "post-thumbnail" is also available and this is the default when using Post Thumbnails. This is how you use these default sizes with [[Function Reference/the_post_thumbnail | the_post_thumbnail()]]: |
||
+ | |||
+ | // without parameter -> Post Thumbnail (as set by theme using set_post_thumbnail_size()) |
||
+ | the_post_thumbnail(); |
||
+ | |||
+ | the_post_thumbnail('thumbnail'); // Thumbnail (default 150px x 150px max) |
||
+ | the_post_thumbnail('medium'); // Medium resolution (default 300px x 300px max) |
||
+ | the_post_thumbnail('medium_large'); // Medium Large resolution (default 768px x 0px max) |
||
+ | the_post_thumbnail('large'); // Large resolution (default 1024px x 1024px max) |
||
+ | the_post_thumbnail('full'); // Original image resolution (unmodified) |
||
+ | |||
+ | the_post_thumbnail( array(100,100) ); // Other resolutions |
||
+ | |||
+ | === Set the Post Thumbnail Size === |
||
+ | |||
+ | To be used in the current Theme's <tt>[[Theme_Development#Functions_File|functions.php]]</tt> file. |
||
+ | |||
+ | Set the default Post Thumbnail size by resizing the image proportionally (that is, without distorting it): |
||
+ | <pre>set_post_thumbnail_size( 50, 50 ); // 50 pixels wide by 50 pixels tall, resize mode</pre> |
||
+ | |||
+ | Set the default Post Thumbnail size by cropping the image (either from the sides, or from the top and bottom): |
||
+ | <pre>set_post_thumbnail_size( 50, 50, true ); // 50 pixels wide by 50 pixels tall, crop mode |
||
+ | set_post_thumbnail_size( 50, 50, array( 'top', 'left') ); // 50 pixels wide by 50 pixels tall, crop from the top left corner |
||
+ | set_post_thumbnail_size( 50, 50, array( 'center', 'center') ); // 50 pixels wide by 50 pixels tall, crop from the center</pre> |
||
+ | |||
+ | === Add New Post Thumbnail Sizes === |
||
+ | Example of a new Post Thumbnail size named "category-thumb". |
||
+ | |||
+ | To be used in the current Theme's <tt>[[Theme_Development#Functions_File|functions.php]]</tt> file. |
||
+ | <pre>add_image_size( 'category-thumb', 300, 9999 ); //300 pixels wide (and unlimited height)</pre> |
||
+ | |||
+ | Here is an example of how to use this new Post Thumbnail size in theme template files. |
||
+ | <pre><?php the_post_thumbnail( 'category-thumb' ); ?></pre> |
||
+ | |||
+ | === Example of functions.php === |
||
+ | |||
+ | <pre>if ( function_exists( 'add_theme_support' ) ) { |
||
+ | add_theme_support( 'post-thumbnails' ); |
||
+ | set_post_thumbnail_size( 150, 150, true ); // default Post Thumbnail dimensions (cropped) |
||
+ | |||
+ | // additional image sizes |
||
+ | // delete the next line if you do not need additional image sizes |
||
+ | add_image_size( 'category-thumb', 300, 9999 ); //300 pixels wide (and unlimited height) |
||
+ | }</pre> |
||
+ | |||
+ | === Styling Post Thumbnails === |
||
+ | |||
+ | Post Thumbnails are given a class "wp-post-image". They also get a class depending on the size of the thumbnail being displayed. For example |
||
+ | |||
+ | <pre>the_post_thumbnail(); |
||
+ | the_post_thumbnail('medium'); |
||
+ | the_post_thumbnail( array(100,100) ); |
||
+ | the_post_thumbnail( 'category-thumb' ); // See above example</pre> |
||
+ | |||
+ | These lines will generate following HTML: |
||
+ | |||
+ | <pre><img src=... class="attachment-post-thumbnail wp-post-image" ...> |
||
+ | <img src=... class="attachment-medium wp-post-image" ...> |
||
+ | <img src=... class="attachment-100x100 wp-post-image" ...> |
||
+ | <img src=... class="attachment-category-thumb wp-post-image" ...></pre> |
||
+ | |||
+ | You can style the output with these [[Glossary#CSS|CSS selectors]]: |
||
+ | |||
+ | <pre>img.wp-post-image |
||
+ | |||
+ | img.attachment-post-thumbnail |
||
+ | img.attachment-thumbnail |
||
+ | img.attachment-medium |
||
+ | img.attachment-large |
||
+ | img.attachment-full</pre> |
||
+ | |||
+ | You can also give Post Thumbnails their own class instead of a class depending on the thumbnail size. Next example display the Post Thumbnail with a class "alignleft": |
||
+ | |||
+ | <pre><?php the_post_thumbnail('medium', array('class' => 'alignleft')); ?></pre> |
||
+ | |||
+ | It will generate the following HTML: |
||
+ | |||
+ | <pre><img src="..." class="alignleft wp-post-image" ...></pre> |
||
+ | |||
+ | == Source File == |
||
+ | |||
+ | * {{Trac|wp-includes/post-thumbnail-template.php}} |
||
+ | |||
+ | == External Resources == |
||
+ | * [http://justintadlock.com/archives/2009/11/16/everything-you-need-to-know-about-wordpress-2-9s-post-image-feature Everything you need to know about WordPress 2.9’s post image feature], by JustinTadlock.com |
||
+ | * [http://wpengineer.com/the-ultimative-guide-for-the_post_thumbnail-in-wordpress-2-9/ The Ultimative Guide For the_post_thumbnail In WordPress 2.9], by wpEngineer.com |
||
+ | * [http://markjaquith.wordpress.com/2009/12/23/new-in-wordpress-2-9-post-thumbnail-images/ New in WordPress 2.9: Post Thumbnail Images], by Mark Jaquith |
||
+ | * [https://gist.github.com/hqhow/36beb6aad5d150006171732b9bd93504 Simple WordPress thumbnail function], by HQHOW.COM |
||
+ | * [http://generatewp.com/theme-support/ WordPress Theme Support Generator] |
||
+ | |||
+ | == Related == |
||
+ | {{Post Thumbnail Tags}} |
||
+ | |||
+ | {{Theme Support}} |
||
+ | |||
+ | [[Category:Advanced Topics]] |
Languages: English • Italiano • Thumbnails 日本語 (Add your language)
Post Thumbnails is a theme feature introduced with Version 2.9. It was quickly changed to Featured Images with Version 3.0. Post Thumbnail, now Featured Image, is an image that is chosen as the representative image for Posts, Pages or Custom Post Types. The display of this image is up to the theme. This is especially useful for "magazine-style" themes where each post has an image.
Themes have to declare their support for post thumbnails before the interface for assigning these images will appear on the Edit Post and Edit Page screens. They do this by putting the following in their functions.php file:
add_theme_support( 'post-thumbnails' );
Note: To enable Post Thumbnails only for specific post types see add_theme_support()
If your theme was successful in adding support for Post Thumbnails the "Featured Image" metabox will be visible on the on the Edit Post and Edit Page screens. If it isn't, make sure "Featured Image" is enabled in the screen options on the top right.
Featured Image metabox
After clicking the "Set featured image" link follow the same steps as inserting images in Posts and Pages. Once you have selected the featured image and determined the image settings, click on the blue "Set featured image" button, to set it as the featured image for your page or post.
"Set featured image" button
|
|
// check if the post has a Post Thumbnail assigned to it. if ( has_post_thumbnail() ) { the_post_thumbnail(); } the_content();
Note: To return the Post Thumbnail for use in your PHP code instead of displaying it, use: get_the_post_thumbnail()
To link the Post Thumbnail to the Post permalink or a larger image see the examples in the_post_thumbnail()
The default image sizes of WordPress are "thumbnail" (and its "thumb" alias), "medium", "medium_large", "large" and "full" (the image you uploaded). These image sizes can be configured in the WordPress Administration Media Screen under Settings > Media. If your theme enables Post Thumbnails then "post-thumbnail" is also available and this is the default when using Post Thumbnails. This is how you use these default sizes with the_post_thumbnail():
// without parameter -> Post Thumbnail (as set by theme using set_post_thumbnail_size()) the_post_thumbnail(); the_post_thumbnail('thumbnail'); // Thumbnail (default 150px x 150px max) the_post_thumbnail('medium'); // Medium resolution (default 300px x 300px max) the_post_thumbnail('medium_large'); // Medium Large resolution (default 768px x 0px max) the_post_thumbnail('large'); // Large resolution (default 1024px x 1024px max) the_post_thumbnail('full'); // Original image resolution (unmodified) the_post_thumbnail( array(100,100) ); // Other resolutions
To be used in the current Theme's functions.php file.
Set the default Post Thumbnail size by resizing the image proportionally (that is, without distorting it):
set_post_thumbnail_size( 50, 50 ); // 50 pixels wide by 50 pixels tall, resize mode
Set the default Post Thumbnail size by cropping the image (either from the sides, or from the top and bottom):
set_post_thumbnail_size( 50, 50, true ); // 50 pixels wide by 50 pixels tall, crop mode set_post_thumbnail_size( 50, 50, array( 'top', 'left') ); // 50 pixels wide by 50 pixels tall, crop from the top left corner set_post_thumbnail_size( 50, 50, array( 'center', 'center') ); // 50 pixels wide by 50 pixels tall, crop from the center
Example of a new Post Thumbnail size named "category-thumb".
To be used in the current Theme's functions.php file.
add_image_size( 'category-thumb', 300, 9999 ); //300 pixels wide (and unlimited height)
Here is an example of how to use this new Post Thumbnail size in theme template files.
<?php the_post_thumbnail( 'category-thumb' ); ?>
if ( function_exists( 'add_theme_support' ) ) { add_theme_support( 'post-thumbnails' ); set_post_thumbnail_size( 150, 150, true ); // default Post Thumbnail dimensions (cropped) // additional image sizes // delete the next line if you do not need additional image sizes add_image_size( 'category-thumb', 300, 9999 ); //300 pixels wide (and unlimited height) }
Post Thumbnails are given a class "wp-post-image". They also get a class depending on the size of the thumbnail being displayed. For example
the_post_thumbnail(); the_post_thumbnail('medium'); the_post_thumbnail( array(100,100) ); the_post_thumbnail( 'category-thumb' ); // See above example
These lines will generate following HTML:
<img src=... class="attachment-post-thumbnail wp-post-image" ...> <img src=... class="attachment-medium wp-post-image" ...> <img src=... class="attachment-100x100 wp-post-image" ...> <img src=... class="attachment-category-thumb wp-post-image" ...>
You can style the output with these CSS selectors:
img.wp-post-image img.attachment-post-thumbnail img.attachment-thumbnail img.attachment-medium img.attachment-large img.attachment-full
You can also give Post Thumbnails their own class instead of a class depending on the thumbnail size. Next example display the Post Thumbnail with a class "alignleft":
<?php the_post_thumbnail('medium', array('class' => 'alignleft')); ?>
It will generate the following HTML:
<img src="..." class="alignleft wp-post-image" ...>
Post Thumbnails:
Theme Support:
add_theme_support(),
remove_theme_support(),
current_theme_supports()
Theme Features:
sidebar,
menus,
post-formats,
title-tag,
custom-background,
custom-header,
custom-logo,
post-thumbnails,
automatic-feed-links,
html5,
editor-style,
content_width