Update: 11 Apr 2008

  • Fixed fatal error when used with Wordpress 2.5.

My main objective with having a website has always been to post photos. My first real attempt at this was with my previous site. It was a static site that had to be recompiled to include new photos. It was ok, but it required adding code for new photos by hand and all the versions of the image (thumbnails, etc.) also had to be hand generated. I played with writing a java application to do some of this for me (java and cpp are what I’m most familiar with) but ultimately felt that the design of my site was also hindering me.

My next step was to look at tools that could do it for me. I looked at various photo gallery applications and started to look at weblogs. I started to realize that what I wanted was to do both. I didn’t want a separate application for each because I felt that a bunch of photos together tell a story. Sometimes that story can be told with just photos, but sometimes the story needs accompanying text. Sometimes I may only want a couple of photos and more text. With these thoughts I decided that I wanted a weblog.

I started looking at photo plugins for Wordpress and even some for other weblogs. Ultimately I concluded that none of them really gave me what I wanted. The closest I found was Exhibit by Owen Winkler. A nice little plugin, however it lacked a few things that I wanted, in particular, I wanted better control over how thumbnails were handled inside a post.

Thus, I decided to write the Copperleaf Photo Log plugin for Wordpress, CPL for short (not to be confused with the Customizable Post Listings plugin.)

Description

Copperleaf Photolog for Wordpress(CPL for short, not to be confused with Customizable Post Listings) is a photo management tool for Wordpress. It allows for easily adding thumbnails and inline images to posts and pages.

cpl_example_options.jpg cpl_example_post.jpg cpl_example_add.jpg cpl_example_edit.jpg cpl_example_croptool.jpg

Requirements/Restrictions

  • Works with Wordpress 2.x.
  • Requires Javascript to be enabled and to be a recent browser for the admin pages.
  • The only format currently supported in JPEG.
  • Requires either GD2 to be compiled into php or imagemagick (convert) to be installed as a command line utility.
  • For EXIF support, requires that EXIF be compiled into php.
Files

Installation

Download the zip file above and expand (keeping the directories) into your wp-content/plugins directory and activate it. The database tables wp_cpl and wp_cpl_post will be created.

Configuration

After the plugin is activated, you can configure it by selecting the CPL tab on the Options page. Here is a list of the options:

Default Description – When a photo is added, this is the default description that will be associated with the photo.

Default Photographer – When a photo is added, this is the default photographer that will be associated with the photo.

Default Server Directory – Photos can be ftp’d to a server directory then added which is useful
for large additions. This is the directory on the server where the photos will be retrieved. Make sure it is an absolute path and that you have permissions for the server to delete the files when done.

Storage Directory – This is the relative directory under wp-content where the images will be stored.

JPEG Quality Level – For generated images, thumbnails, etc. this is the JPEG quality to use.

Max Cache Size – Used to improve query performance. The max number of images “per page” to cache. If the number of images on a page exceeds this value, no caching is done. Default is 250. Set to 0 to disable.

Auto Purge – When a photo is no longer associated with a post or page (because the page or post has been deleted), this will delete the abandoned images.

Minimum Admin Level – This is the mimimum user level required to get to the admin page. (I haven’t switched to the user level strings used by Wordpress 2.x yet.)

Convert Path – This is a path to the convert utility which does a better job than gd for resizing images. Leave blank to use gd.

Exif Strip Size – If both sides of an image are smaller than this number, the exif info will be stripped. This only applies when convert is being used as gd already strips the exif info. This can save alot of download space when using alot of thumbnails.

Max Original Size – If an uploaded original has both sides larger than this value, it will be resized to fit.

“Photo of the Day” Category – If you want to have a photo of the day in you sidebar, set a category name here. If a post is in that category, it will be hidden from the main page, but can still be displayed in the sidebar. Leave it blank to disable it. See the CopperleafPlus theme for an example of how to do this with your sidebar.

Hide “Photo of the Day” Posts – By default, posts that are in the photo of the day category above are filtered from the main page. If you would like to display them on the main page too, disable this field.

Usage

Once activated, a section is added to the post and page edit views. For posts, this is in the advanced section. This will appear just below the editor. From this view, you can add photos and insert them into the post or page.NOTE: The current implementation requires that a post/page have an id, thus, a page must be saved one time before photos can be added. There is a messsage that will indicate this.

To add photos, click the “Add Photo(s)” button. A dialog will appear that will let you either 1) upload a photo via the browser, 2) add photos that have already been ftp’d to the server, 3) Add photos that are already part of another post.

Once some photos have been added, they will appear in a table in the center of the view. On the left of the table are buttons that will let you edit the data, delete them, or change their order.

To insert photos into the post or page, you can click the “insert matrix” button which will insert the tag ‘<!--cplmatrix-->‘ into the editor. When displayed, this tag will expand to show a matrix of thumbnails in the post. Additionally, there is a button to the left of each image that will let you insert just that image into the post. When you click it, it will insert a ‘<!--cplinline id="4"-->‘ into the editor (where 4 is the id assigned by cpl for that image).

There is an option that you can manually add the will limit the number of thumbnails that will appear on the index page. Modify the tag to look something like ‘<!--cplmatrix mpmax="8"-->‘. This example will only display 8 thumbnails on the index page.

There is another option that will let you group photos when displaying a matrix. If you specify something like ‘<!--cplmatrix group="1"-->‘, then only photos that match group number 1 in the post will be displayed. By default, photos are added to group 0 which is the default group.

If you want to change the order of images in the post (for the cplmatrix tag), you can move them up and down with the arrows to the left of each image, or you can click the “rearrange photos” button. Clicking this button will bring up a dialog where you can click an image, then click where you want it to go, and it will be moved there. (This is much more efficient than the arrows approach).

For developing different layouts, take a look at the files cpltemplate.js, cpltemplate.php, cpltemplate.css and cplphoto.php in the cpl directory. These pages are used to generate the layout of cplmatrix and cplinline. Basically there are three functions: getCplHead, getCplMatrix and getCplInline. They each return a string of html that is inserted into the header, matrix and inline tagss. They use the CplApi class defined in cplview.php. Another example is in the CopperleafPlus theme which has it’s own slightly modified versions of these files and also supports
a “photo of the day” in the sidebar.

One specific API note that pertains to displaying the “photo of the day”. If you want to use the photo of the day functionality, add CplApi::photoOfTheDay(); to your themes sidebar.php. Without any arguments, it will display the first image of newest post in the photo of the day category. There are two arguments that can be passed. The first is the mode: newest | random | roundrobin | newestrandom | newestroundrobin. The newest is the same as no arguments as stated above. Random mode will grab a photo from any post in the photo of the day category. Roundrobin will iterate through all posts in the photo of the day category. For random and roundrobin modes, this will only change once per day. For random and roundrobin modes, this will only change once per day. The modes newestrandom and newestroundrobin will behave like the newest mode if a new “photo of the day” image has been posted in the last 24 hours, otherwise it behaves like random or roundrobin modes. The second argument is a boolean (true | false) that will display the title of the post containing the photo. True means that the title will be displayed.

Notes

With the progress dialog when adding photos from a server directory, some server configurations may prevent the progress from showing. One situation is if mod_gzip is installed on the server (Apache). If this is the case, the following section should be added to your http.conf or .htaccess:
mod_gzip_item_exclude file cpladmloadstat\.php$

Another is a bug that was introduced in php 4.1 that prevented ob_flush() from truely flushing until an 8k buffer has been filled. This has been fixed in php but there may still be installs with the bug.

Execution time limits can also cause problems with large uploads consider adding/modifying the following lines to to your php.ini:

max_execution_time = 300;
max_input_time = 300;
memory_limit = 16M;

Additionally, you may want to look at the timeout for the webserver. For Apache, look at the following in your http.conf:

Timeout 300