Contents:
About wp-popeye
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 [1].
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.
It is based on Christoph Schuessler’s jQuery.popeye which was designed as an alternative to the often-seen JavaScript image lightbox (see Lightbox 2, Fancybox or Colorbox, just to name a few). In contrast to them it does not employ a modal window to display the large images, thus disrupting the workflow of the user interacting with a webpage, but takes a different approach: not only allows it for browsing all thumbnails as well as the large images in a single image space, it also repects the page flow and stays anchored and rooted in the webpage at all times, thus giving a less disruptive user experience than modal windows.
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.
License
wp-popeye is licensed under the GPL v3 [2]. 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 [0]) especially. If you share it you are only allowed to do so under the same license.
Installation
- Get wp-popeye from the Wordpress Plugin Directory [3]
- 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. [4]
- Reporting bugs via the bugtracker [5]
- 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 [4] 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
- exclude: allows you to specifiy a list of image ids to be excluded from the gallery
- include: ids of images to be included into the gallery additionally
- 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
- viewsize: thumbnail/medium/large; selects the size of the popeye when not enlarged
- enlarged_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 [7] and its demo page [6] 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
/wp-content/plugins/wp-popeye/styles
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. [7]
Your design and the popeye style catalog
A great way of sharing your style with the world is to send me [0] a link to where you host it. Please include a link to a demo (e.g. your own blog) or at least a screenshot. I would like to collect them here, so please send them to me. The most beautiful ones I can include in the next releases of wp-popeye.
Links
[0] The author: http://chrp.es/
[1] jquery.popeye Homepage: http://dev.herr-schuessler.de/jquery/popeye/
[2] GPL v3: http://www.gnu.org/licenses/gpl-3.0-standalone.html
[3] Wordpress Plugin Directory: http://wordpress.org/extend/plugins/popeye
[4] UserVoice feedback page: http://wppopeye.uservoice.com/
[5] Bugtracker: http://bugz.hrnstrm.de
[6] jquery.popeye documentation: http://dev.herr-schuessler.de/jquery/popeye/doc.html
[7] jquery.popeye demo: http://dev.herr-schuessler.de/jquery/popeye/demo.html
Hi,
I’ve just installed your plugin!!! I was waiting for this……..and it’s great……
I just can’t order images…….How can I order all images? I tried to order in the gallery order, but is not working……
Thanks very much!!!!!
Thanks for the compliments
Yet there is no way to order the images when including them automatically. If you add them by shortcode you can define the order using the ids=”…” attribute.
I added your feedback to the uservoice suggestions.
I received this fatal error when I tries to activate the Popeye plugin:
Parse error: parse error, unexpected ‘&’, expecting T_VARIABLE or ‘$’ in /var/www/vhosts/tilehaus.com/httpdocs/blog/wp-content/plugins/wp-popeye/popeye.php on line 126
WordPress 2.9.2
I have deactivated NextGen
Thanks for your help.
Keith
@Keith: Whats your PHP version?
I’ve got the same problem as Keith. Can’t activate the plugin (even when I deactivate all my other plugins). Using Wordpress 2.9.2. Getting this error Parse error: parse error, unexpected ‘&’, expecting T_VARIABLE or ‘$’ in /var/www/vhosts/arnohoogwerf.nl/httpdocs/blog/wp-content/plugins/popeye/popeye.php on line 126
My php-version is 4.3.9
Hi Arno, yeah, seems to be an issue with PHP4. I’ll include this in my next release. Stay tuned
A Flickr-integration would be cool. Instead of an ID you enter the photoset or photoid from Flickr.
But still my favourite image-plugin at the moment
Great idea!
Your plug-in is beautiful…
Combine this with NextGen Gallery !
(excuse my english ^^)
I use Wordpress 2.9.2.
I select “Original” with plug-in Enlarged Size Option, but the setting is set to Large.
Why ?
Because it’s a bug. Thanks for telling. I fixed this issue with the current version 0.2.1
Hi Chris, really like the effort you’ve put in! I’ve also got a fail on install. Initially the same error as above on line 126.I removed a lost &, and now it’s saying:
Parse error: syntax error, unexpected T_ARRAY, expecting ‘)’ in /homepages/25/d184093902/htdocs/matthewhare/wordpress/wp-content/plugins/popeye/popeye.php on line 180
I would love to have this working as it’s ideal for my site
Any ideas?
Seems like a PHP4 thing… doesn’t like typed params in line 180. Sadly I’m not a PHP Dev! But I’ll see if I can fix it. I don’t think it would take long with some knowledge!
It is a PHP thing indeed. Never designed it to work with PHP4, but if you would make the script backward compatible I’d be happy to integrate it!
Hi Chris, I discovered that actually my host has PHP5, but it requires files to be named ‘*.php’
The best way around this was to add the following line to the .htaccess file at the WordPress root directory :
AddType x-mapp-php5 .php
I host with 1and1, and I’m there’s a lot of people that will come up with the same problem, so I hope this helps them
I’ve also blogged the fix:
here
*correction to the above post… my host requires the file to be named ‘*.php5′
Thanks for sharing your solution. I added PHP4 support finally with the current version 0.2.1
Great Plugin – if it works…
I have the following error:
Warning: file_get_contents() [function.file-get-contents]: Unable to access wp-content/plugins/popeye/styles/example-blue/structure.template in /home/httpd/vhosts/xxxxxx.xx/httpdocs/WordPress/wp-content/plugins/popeye/popeye.php on line 243
Great work.
But some problem.
I want to use popeye via shortcode. It works well. But if the imgages should be open to full size they will be cut during the with of my wordpress theme. This problems appears to landscape format. My content area is 620 px. And the background and the description is missing.
Do you have an idea?
Hi Manu, you might want to check out the z-index option which you can find in the settings.ini of the style you are using. The value must be higher than the z-index of the div layers in your wp layout. HTH, chris
when using popeye, it only shows maximum number of 5 images. but i added more in the post.
i include popeye using the [popeye] tag.
is it a popeye problem or do i have to change something in wp ?
thanks for your help,its a really nice way to show images
ok found a solution:
in function ppy_get_image_attachments_of_post change() add “‘numberposts’ => 100″ to the arguments.
imho this should be in the settings of the plugin
cheers
Thanks Tom! Thanks for the solution. I finally found out that you can retrieve unlimited attachments by setting numberposts to -1. I included your suggestion in the next release.
Great plugin, it cleans up clutter in my posts. By far my favourite image lightbox plugin.
Just a question though, is there any way to have popeye aligned in the center of posts? I’d like to have the view size set to Medium without having text on the left or right. If it is an easy fix I must have looked past it, I’m not really good with coding and such.
Thanks!
Sorry I did not include this yet. It is not really the idea of popeye to be used in that way but anyhow I will consider a center option for the next update…
Hi Chris,
the value z-index of my theme is 0.
The value of popeye is: z-index = integer value = default 10000, optional.
For better understanding: what should I change?
The blue and green style of popeye is working. The plan style is loosing the background color for description if the images are in full preview. That’s the other little problem.
Thanx for your support.
Hi,
First of all I want you to congratulate for this grate plugin !
Secondly, is there an option we could include flickr images ?
Thanks in advance !
Yet not. But maybe you can somehow convince me to make the effort?
Hey, there is a new update to version 0.2.2. Here’s what changed:
* replaced jQuery.popeye with current version 2.0.4
* now uses the description of an image as it’s caption (or the caption as until now when the description is empty)
* solved the “only 5 pics” issue – see here: http://chrp.es/wp-popeye#comment-39
* now orders the images by title descending so you can edit the order by renaming the images (e.g. 10_bla, 11_blup, 12_foo, etc.)
Hi Chris,
Really fantastic plugin. However, I have a problem…in the theme Argentpress that I am using, the popeye images don’t appear. But if I activate the classic and default Wordpress themes, the plugin seems to work fine.
What do you think could be wrong? I really wish to use your plugin for the theme that I have already customized.
Could it be the timthumb script?
Thanks for any help you can give me…
Does your theme make use of jquery? Is there some ppy-related html code in the source?
Hello, the new update solves the only issue “5 pics” I had. This plugin is great and there isn’t better to display images gallery. I made a simple template, I’ll see to share it.
Great! Could you share a link to your installation to have a look on your design?
hi, great plugin!! im using a theme that need to use the kino event calendar plugin, and in home page im using a slider with jflow. so, when i active the popeye the slider stops to work and popeye doesnt works too. how can i fix this? i guess it can be a bug / confllict with jqery versions… other question: it is possible to use popeye with jquerycolorbox?
thanks!
Of course you could use your version of jQuery only. Have a look into the function ppy_init() in popeye.php.
Greetings…
Beautiful plugin…
I have Wordpress 3.0 and it seems i can’t put this to work…is it not compatible yet???
Hello, this is a very good plugin with lots of potential! thanks for the effort on this.
there is a problem that needs urgent attention: the wp excerpt function parses the plain links from the wp_popey into the except text. how would it be possible to avoid this? as a consequence, it can scare search engine robots…
another cool feature would be the keyboard navigation. I have seen that this works well on safari for iphone, that’s cool.
*this works well = wp_popeye gallery in iphone, not the keyboard navigation ;·)
Is there any way to order the images to match the post’s gallery customizable order?
I’m willing to improve this, just need some tips as I’m not a pro php programmer…
Ok, so I found the solution to order the images according to wordpress gallery manager, when using the automatic insertion mode:
On line 288 of popeye.php, simply replace
'orderby' => 'ASC',by
'orderby' => 'menu_order ASC',Thanks for sharing your solution!
Hello, I am trying to use shortcode to insert the popeye slide show.
I’m getting the follwoing error:
jQuery(“.ppy”).popeye is not a function
[Break on this error] easing: ’swing’
Though the html for the slideshow is in the source code it isn’t visible.
Also if I change the setting to include the slideshow automatically it works fine.
I’m using wordpress v3.0
Any idea what’s wrong? ~Thanks!
Great info, thanks for useful article. I’m waiting for more
Another issue: the rss feed is displaying all captions and navigation text before the post content as well as in the excerpt. This is an urgent to-do i.m.o. – Is it possible to be fixed with feedburner?
Your right, this should be changed… it really looks ugly.
Ah, yeah and feedburner can do nothing about it, I guess.
New release, wooh: 0.2.3
* allow custom order of images
* added include & exclude attributes for inclusion or removal of specific image ids
* checked for wp 3.0 compatibility
* added some simple usage help
* thanks to Raoni Del Persio for sponsoring this release!
For everybody out there who keeps me telling, that there are issues with wp3: I cannot reproduce them with my local wp3 installation. It seems like an issue with the jquery-inclusion. What you can do is to change line 315 of popeye.php from
jQuery('< ?php echo $identifier ?>').popeye({to$('< ?php echo $identifier ?>').popeye({. If anybody out there with some more jQuery/wp experience might want to share a solution for this I would really appreciate this.For those of you who still have this z-index issue I will see what I can do. I got the same problem with my installation here (do a mouseover on the shrinkend popeye of my hello popeye article and you’ll see it)
A yes and finally: The developement of the current release was generously sponsored by Raoni Del Persio from agencia ad in Brazil. Thanks Raoni!
Hey Chris, thanks for the new release and a big hooray to Raoni Del Persio for sponsoring the release!
The jquery-inclusion was not the issue in my situation, I never did have trouble bringing in
jQuery('.ppy').popeye({For now I’ve hard coded an image gallery for my client and expect to go live within 2 weeks. I currently have the site set up on a testing server and I’d be happy to hand over the keys for you to play with once I have my clients site live. —let me know if you’re interested.
Cheers!
Jules
really cool!
Hi Chris,
The updates are really good!
Thanks very much for writing the credits to me!!!
I just can’t get the Shortcodes to work. Like, if I put:
[popeye viewsize="thumbnail" enlarged_size="large"]
Nothing happens…….the output is the normal configuration in the admin panel and not the size of the shortcode……
Can you have a look after, please!?!
Thanks again!
Hello, after the update I have an error on line 181 of popeye.php. I replaced
foreach($ids as &$id)byforeach($ids as &$id)and now, it’s fine.You replaced it with the same code?
@rémy: Sure, I can have a look (after my holidays..)
As I will go traveling for the next month there will be no updates from my side. I hope that the plugin does a good job for the most of you. For those for whom it doesn’t: Please keep me updated with the latest bugs. Also sending an email with some details or an installation on some server which I can access might help to ‘em.
Enjoy the summer! (for those in the northern hemisphere)