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.


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.


  1. Get wp-popeye from the WordPress Plugin Directory [3]
  2. Unzip `wp-popeye-X.X.zip` into `/wp-content/plugins/wp-popeye`
  3. Activate the plugin through the ‘Plugins’ menu in WordPress
  4. Read the next chapter for an explaination of the different ways to use popeye
  5. 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]
  • 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
  • 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 [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


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. The most beautiful and sufficent generic ones I will include in the next mayor release of wp-popeye.


[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/

[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


  1. Right here is the perfect web site for everyone who would like to
    find out about this topic. You know a whole lot its almost hard to argue with
    you (not that I really would want to…HaHa). You certainly put a brand new spin on a subject which has been written about
    for decades. Great stuff, just great!

    Also visit my web page – ppi claims

  2. There is definately a great deal to learn about this topic.
    I love all of the points you’ve made.

  3. My relatives always say that I am killing my time here at web, however
    I know I am getting familiarity all the time by
    reading thes nice articles.

  4. Way cool! Some extremely valid points! I appreciate you writing this post and also the rest of the site is also really good.

  5. It’s impressive that you are getting ideas from this piece of writing as well as from our argument made at this

  6. I am sure this article has touched all the internet users,
    its really really nice paragraph on building up new webpage.

  7. Hi therе&X44;ear, are you genu&X69;ne&X6c;y visiting this si&X74;e dai&X6c;y, if s&X6F; a&X66;teг
    that y&X6F;u wi&X6c;&X6c; without doubt take good knowledg&X65;.

  8. Excellent, what a website it is! This website gives valuable data
    to us, keep it up.

  9. Hi, Neat post. There’s an issue together with your website in
    web explorer, could test this? IE still is the marketplace leader and a big
    part of other folks will miss your fantastic writing because of
    this problem.

  10. Điều này là thực sự thú vị, Bạn đang một blogger rất có tay nghề.
    Tôi có và mong muốn tìm kiếm thêm bài viết hay của
    bạn. Ngoài ra, tôi đã chia sẻ trang web của bạn trong mạng xã hội của tôi!

  11. Nice post. I learn something new and challenging on websites I
    stumbleupon every day. It will always be helpful to read through content from other authors and use a little
    something from their web sites.

  12. My partner and I stumbled over here different page and thought I might check things
    out. I like what I see so now i’m following you.
    Look forward to looking at your web page again.

  13. Your calorie intake goes hand in hand with your body weight.
    Women should take half a serving, and men should take one serving,
    mixed in the recommended amounts of water.
    Sunlight on un-protected skin produces a highly usable form of Vitamin D that lasts twice as long
    in your bloodstream as when you consume it through food or a supplement, but you still need caution due to the risk of
    skin cancer.

  14. My developer is trying to persuade me to move
    to .net from PHP. I have always disliked the idea because of the costs.

    But he’s tryiong none the less. I’ve been using WordPress
    on various websites for about a year and am anxious about switching to another platform.
    I have heard excellent things about blogengine.net.
    Is there a way I can import all my wordpress posts into
    it? Any help would be greatly appreciated!

  15. It’s very trouble-free to find out any topic on net as compared to books,
    as I found this article at this website.

  16. Encore un post гéellement intéressant

  17. I believe what you said was actually very reasonable.
    However, what about this? what if you added a little information?

    I mean, I don’t wish to tell you how to run your website,
    but suppose you added a title that makes people want more?
    I mean wp-popeye is a little vanilla. You should look at Yahoo’s home page
    and note how they write news titles to grab people
    to click. You might try adding a video or a picture or two to grab readers interested about everything’ve got to say.
    In my opinion, it could bring your posts a little bit more interesting.

  18. Voսss rédigez cߋnstamment Ԁes postes attrɑctifs

  19. Oո vɑ te Ԁire quе ce n’est pas іnexact !

  20. J’ɑi guère fii de regarder par cojtre je reviendrai dans
    la soirée

    • efbbbfI drop a comment each time I acpperiate a article on a site or I have something to contribute to the conversation. Usually it is triggered by the sincerness displayed in the post I browsed. And after this post Bloginfo Shortcode WordPress. I was excited enough to drop a comment I do have some questions for you if you do not mind. Could it be only me or does it give the impression like some of these comments appear like they are written by brain dead people? And, if you are writing on other online sites, I’d like to keep up with anything fresh you have to post. Could you make a list every one of all your shared sites like your linkedin profile, Facebook page or twitter feed?

    • scrive:I wish to show appreciation to you for recuisng me from such a scenario. Because of browsing through the the net and coming across concepts that were not helpful, I believed my entire life was well over. Living without the presence of answers to the difficulties you have solved by means of your main guideline is a crucial case, as well as ones that might have adversely affected my career if I hadn’t discovered the website. Your main capability and kindness in handling all the things was vital. I am not sure what I would’ve done if I hadn’t come upon such a stuff like this. I am able to at this time relish my future. Thanks very much for your reliable and amazing help. I won’t think twice to endorse your site to any individual who wants and needs guidance on this situation.

  21. Thanks for finally writing about > wp-popeye < Loved it!

  22. Whoa! This blog looks exactly like my old one! It’s on a totally different subject but it has pretty much the
    same page layout and design. Excellent choice of colors!

  23. Oո voit de suite que vous maîtrisez bien lle thème

  24. We are a group a group of volunteers and starting
    a brand new scheme in our community. Your web site provided us with helpful helpful and work on .

    You have a formidable job and our all the neighborhood
    will grateful to you .
    Definitely believe that you said . Your favorite
    reason appeared to be on the web simple thing to be aware
    of . I tell you , i definitely get annoyed people
    think worries not realize about . You controlled perfectly
    as defined everything managed to hit the nail on the top without having side effect ,
    other folks could take a signal. Will likely be again to get
    more. Thank you

    My site :: Minion Rush Cheats

  25. Je suiѕ tout à fait en accorɗ aνec toi

  26. Poste vraiment attrayant

  27. What’s up, just wanted too say, I enjoyed this blog post.
    It was inspiring. Keep on posting!

    Heree is my site; Search Engine Optimisation St Albans

  28. Hey there! I could have sworn I’ve been to this site before but after checking through
    some of the post I realized it’s new to me. Anyways, I’m definitely
    happy I found it and I’ll be book-marking and checking back often!

  29. Рoste très attrayant

  30. If provide enhancing your house. Things do happen even provide in Britain. As a final request to her house before getting
    it painted by washing the exterior painting, roofing, to avoid shouldering the burdens and legal regulations.

    Atlanta Home remodeling will give them some advice on product selection and in this
    specialization. If so, it’s essential that your company bankable.

    Maybe the disparity helps in preventing these problems and delays in the direction it faces.

    Here is my site homepage – Shad,

  31. It is important that it readily appeals to you the desired end-result.
    If you are long seo gone. If that looks promising and click to
    another swiftly and easily understandable. When you hire cannot work on all
    platforms and management of their clients, commonly known as the expectations of the requirements of any organization. You will not
    only a professional photographer, spend wealth, and look for a living cheating people.

    My blog post sem search engine marketing

  32. Hello, i believe that i saw you visited my web site so i came
    to go back the choose?.I’m attempting to in finding things to improve my web site!I suppose its adequate to
    use some of your concepts!!

  33. Hello, after reading this amazing piece of writing i am also
    delighted to share my know-how here with colleagues.



  1. [...] the original post: wp-popeye documentation Tags: lightbox, plugin, [...]

Leave a Comment