Lots has changed since the last article I made about WP-prettyPhoto usage, and so it is time to revamp the instructions, explain new features and hopefully be a bit more thorough. First off, let me first mention the following thing:  prettyPhoto is written by Stéphane Caron. Here are some related links to avoid repeating them throughout this article: Stéphane’s blog, prettyPhoto’s project page, prettyPhoto on GitHub, Stéphane on Twitter, WP-prettyPhoto at WordPress Extend, WP-prettyPhoto Support Forum.

Revision History: This article is intended to document the current WP-prettyPhoto (1.5.1) & prettyPhoto (2.5.2) versions.

Now for some organization, here are the topics that will be discussed in this article:

• 1. Technical Information
• 2. Installing WP-prettyPhoto
• 3. Using WP-prettyPhoto
  • 3.1. On Images
  • 3.2. On Videos (MOV) and Flash (SWF)
  • 3.3. On YouTube Videos
  • 3.4. On External Sites (iFrame)
  • 3.5. Shortcode API Calls
• 4. Examples

1. Technical Information

The idea behind WP-prettyPhoto is to avoid having to use Lightbox to display pictures. Lightbox is based on the Prototype JavaScript library, and most WordPress plugins tend to use jQuery. Using WP-prettyPhoto thus allows you to avoid loading multiple libraries to perform a single task. Stephane Caron developed prettyPhoto because the jQuery Lightbox clones, at the time, were close enough to the real Lightbox.

prettyPhoto uses attribute hooks to bind itself on elements to display. In other words, if prettyPhoto finds a rel attribute inside a link pointing to one of its supported format (bmp, gif, jpg, jpeg, png, swf, mov), and that rel attribute matches the one prettyPhoto looks for, it will know that link is meant to be displayed within a prettyPhoto box. Since prettyPhoto 2.4, it also looks for simple text links with the configured rel attribute and the string “iframes=true” within the target URL. Since prettyPhoto 2.5, an API is available.

2. Installing WP-prettyPhoto

The installation of WP-prettyPhoto is pretty straightforward, as with most WordPress plugins. Once you have downloaded the current version of WP-prettyPhoto, you have two options:

1. Use WordPress’ builtin plugin installation system located in your WordPress admin panel, labeled as the “Add New” options in the “Plugins” menu to upload the zip file you downloaded
2. Extract the zip file and upload the resulting “wp-prettyphoto” folder on your server under “wp-content/plugins/”.

All you need to do after that is navigate to your blog’s administration panel, go in the plugins section and enable WP-prettyPhoto.

For more information, see the “Installing Plugins” article from the WordPress Codex.

3. Using WP-prettyPhoto

There are several ways to use WP-prettyPhoto on your blog. All of them can be automatically achieved by enabling the “All Formats” option in the “Automate” section of the WP-prettyPhoto settings, located inside WordPress’ Media settings page. All of the “Automate” options will trigger automatic activation of the specific format. That is how to use WP-prettyPhoto automatically. However, some of prettyPhoto’s formats require specific instructions. For all formats, you will need to do the following: Insert the media you want prettyPhoto to bind itself on in your post or page, surround it by a link and make the HREF attribute point to the original media Then, simply add WP-prettyPhoto’s configurable REL string to the link.

It is important to note that there is also a way to exclude specific elements from being displayed in prettyPhoto. To do so, simply make the link point to a new window using “_blank” as the value of the link’s TARGET attribute.

3.1. On images

Manually using prettyPhoto on images is simple.  If you want to display a title inside the prettyPhoto box, make sure the “Display title” setting is activated. When active, prettyPhoto will use whatever is inside the image’s ALT attribute. To display a description, use the link’s TITLE attribute.

To manually insert a prettyPhoto gallery, the process is similar. All you need to do is make sure all your images have the same REL attribute with a slight modification. The REL attribute should define the gallery’s unique name between [square brackets]. Doing so will allow prettyPhoto to display next/previous links as well as display the current picture count and the total pictures found in the gallery.

3.2. On videos and flash

The process of linking prettyPhoto to your video files is the same as images. Link to the .swf or .mov file, then specify the width and height. In the case your flash needs specifics parameters, add &flashparams to the URL specify the parameters.

3.3. On YouTube Videos

To load a YouTube video, simply link to the YouTube video url. You can also add “&width” and “&height” to specify the sizes, if not provided, default dimensions will be applied.

3.4. On External Sites

To load sites in an iframe inside prettyPhoto, link to the desired website and add the following params. “?iframe=true”, to tell prettyPhoto to open the page in an iframe and “&width=300″ “&height=300″, to specify the iframe dimensions.

3.5. Shortcode API Calls

Since WP-prettyPhoto 1.5 and prettyPhoto 2.5, API calls are supported through WordPress shortcodes. There are two distinct shortcodes available to users, please note that shortcode usage must first be enabled in WP-prettyPhoto settings.

• [ppo img="" title="" desc="" button="false"]Text[/ppo]: Opens a prettyPhoto box using img value for image source, title value for title, desc value for description. If you want to display a button instead of a link, set the button parameter to true.
• [ppg files="" titles="" desc="" button="false"]Text[/ppg]: Opens a prettyPhoto gallery using files values for images, titles value for image titles and desc values for descriptions. All values should be comma-separated and ordered properly. The second desc item corresponds to the description of the second files item. Here again, you can output a button instead of a link using button=”true”.

4. Examples

• Simple image hook with no title and with description.

  <a title="Simple image hook with no title and with description." href="http://blog.fusi0n.org/wp-content/uploads/2009/05/avatar-trans.png">Simple image hook with no title and with description.</a>

• YouTube video

  <a href="http://www.youtube.com/watch?v=oHg5SJYRHA0" rel="wp-prettyPhoto">YouTube video</a>

• Flash Movie

  <a href="http://movies.apple.com/movies/weinstein/nine/nine-tlr1_h.480.mov?width=480&height=204" rel="wp-prettyPhoto">Flash Movie</a>

• External Site

  <a href="http://m.reddit.com/?iframe=true" rel="wp-prettyPhoto">External Site</a>