The short version
Popeye presents images from the WordPress media library in a nice and elegant way within your posts and pages. It is based on the famous jQuery.popeye .
The long version
Popeye presents images from the WordPress media library in a nice and elegant way within your posts and pages. Use it to save space when displaying a collection of images and offer your users a simple way to show a big version of your images without leaving the page flow.
The plugin is very easy to set up and integrates automatically into your posts or allows you to use a shortcode. It comes with several styles but can be also easily customized to integrate into your blog’s design.
wp-popeye is licensed under the GPL v3 . You may use it as you like, may redistribute it free of charge, you are allowed to make changes and to publish them but you have to share them with the world openly and with me (the author ) especially. If you share it you are only allowed to do so under the same license.
- Get wp-popeye from the WordPress Plugin Directory 
- Unzip `wp-popeye-X.X.zip` into `/wp-content/plugins/wp-popeye`
- Activate the plugin through the ‘Plugins’ menu in WordPress
- Read the next chapter for an explaination of the different ways to use popeye
- Choose your insertion mode & style in the ‘Settings’ menu under `Popeye´.
How to use popeye
Popeye is beta and what you can do about it
Not every combination of modes & shortcode attributes of popeye is properly tested. Simply because this costs a lot of time. As well I only checked its functionality only with the current WP version. You can help me by:
- Gathering and voting for new features and extensions on the wp-popeye Uservoice page. 
- Solving bugs & implement new features into the plugin
- Creating new styles for everybody to use (see further down below how this works)
- Help me maintainig it by joining the WP developer community which gives you access to the plugin SVN
Using popeye manually aka by shortcode
You can insert a popeye box by inserting [popeye] (or for short [ppy] works as well) into your posts and pages.
Using popeye with image ids
You can control popeye completely yourself. The following code example places a popeye at the exact position of the shortcode and displays the images with the ids 4, 5 and 10. If you don’t know what IDs your images have, look at the URLs in the Media Library overview. In every link there is a parameter `attachment_id`, this is it.
[popeye ids="4,5,10"] Some random text, with which this paragraph could begin...
Using popeye with attached images
Much easier is it to attach images to posts and pages. If you use popeye without the ids-attribute, it will simply take them instead. If there is no image attached to your post it will not show up. You can attach images to posts by uploading them in the Media Library, clicking `Attach` and then selecting the post to attach them to.
This paragraph shows at its end the
mages attached to the post. [popeye]
Using popeye with NextGEN gallery
Yet there is no way to combine wp-popeye with the popular NextGEN gallery. If you want this to change, vote for the idea on the feedback website  or even better: build it and contribute it to the community. Post a comment to this page if you have a solution.
Popeye shortcode attributes
The [popeye] shortcode comes with a lot of attributes. Sometimes they only exist to override the options you have on the popeye settings page. Use them to change the look and behaviour of the popeyes individually. Here they are:
- ids: a comma seperated list of images IDs (attachment ids); lets you specify pictures explicitly to be showed
- style: the directory name of the style to use; lets you choose a different style than the default style from the settings page
- alignment: left/right; aligns the popeye within the text
- view_size: thumbnail/medium/large; selects the size of the popeye when not enlarged
- enlarge_size: medium/large/full; selects the size of the zoomed images
Using popeye automatically in your posts
The popeye settings page gives you the option to let the plugin completely take care of the insertion of popeyes inside your blog. Choose one of the insertion modes 0, 1, 2 or R to insert a popeye at the beginning of
- 0: every post/page.
- 1: the second paragraph of every post/page.
- 2: the third paragraph of every post/page.
- R: a random paragraph withing every post/page.
The automatic display of popeye will only work on a specific post if there are images attached to it and if there is no [popeye] shortcode within the post.
Styling your popeye
You can choose a style to be applied to all you popeyes from the settings page.
Build your own popeye style
You are more than welcome to contribute your own popeye design. A look on the documentation of jQuery.popeye  and its demo page  will help you to understand how it works and what it needs to change it. All the wp-popeye styles are collected within the path
When you open one of the example styles you can find some files. Here is what they do:
- style.css: The stylesheet itself.
- structure.template: A fragment of HTML code which lets you define the structure of popeye
- settings.ini: Lets you define some options and contains the meta info about your style
- And all the graphics files (e.g. buttons). You can reference them from the style.css
Template tags within structure.template
The are several markers in the HTML structure that will be replaced on runtime:
- id: The HTML id of the outer div enclosing the popeye
- ppyClass: The class to assign the outer div
- align: Can be “left”, “right” or “auto”. Used to assign classes corresponding to the alignment setting
- imageList: Contains the image list structure
- stageWidth: Contains the width of the ppy-stage element
- stageHeight: Contains the height of the ppy-stage element
Whats in Settings.ini?
See one of the example style’s settings.ini for some explanation. The options to be defined are explained on the jQuery.popeye documentation. 
Your design and the popeye style catalog
A great way of sharing your style with the world is to send me  a link to where you host it. Please include a link to a demo (e.g. your own blog) or at least a screenshot. The most beautiful and sufficent generic ones I will include in the next mayor release of wp-popeye.
 jquery.popeye documentation: http://dev.herr-schuessler.de/jquery/popeye/doc.html
 jquery.popeye demo: http://dev.herr-schuessler.de/jquery/popeye/demo.html