Shashin - A Wordpress Plugin for Displaying Picasa Photos
Shashin is a powerful WordPress plugin that enables you display Picasa images anywhere in your WordPress site. It has many features:
- Embed a gallery of your Picasa albums, and all the photos in each album.
- Show your photos with Highslide.
- Pick individual photos to display, in any size supported by Picasa.
- Pick photos from any combination of albums to display in groups of thumbnails.
- Show thumbnails of your newest photos, from one or more albums.
- Display album thumbnails for albums you choose, or all your albums, sorted however you like. Includes links to Google Maps.
- Display any number of random photos, from one or more albums. You can also choose to exclude certain photos or albums from random display.
- Use widgets for all of the above!
- Customize the Shashin stylesheet to suit the theme of your site.
Commercial Use of Highslide
Shashin comes bundled with Highslide. Although I do not charge anything for using Shashin on a commercial site, Highslide is free for non-commercial use only. If you are using Shashin for commercial purposes, you must either 1. not activate Shashin’s Highslide option or 2. pay the appropriate fee for Highslide to its creator.
Examples
Check out the site I built for the Boxing Dragons art gallery using Shashin. Each artist has his or her own album, so this is a good example of using Shashin to display album thumbnails that link to the photos for each album. You can see a similar example on my personal Photos page. See my post on the Shinjuku gardens for an example of using Shashin to display individual images and groups of images in a post.
Help!
Please use the comments section in the post announcing Shashin 2.1 for questions. (I’ve turned off comments on this page, as the thread was getting way too long).
Usage Guide
- Installing and configuring Shashin
- Keeping Shashin synchronized with Picasa
- Using Shashin with Highslide
- Using Shashin tags
- Supported image sizes
- Displaying a single image - the [simage] tag and widget
- Displaying album thumbnails and album photos - the easy way, with the [salbumphotos] tag
- Displaying album thumbnails, the configurable but more complicated way, with the [salbum], [salbumthumbs], [salbumlist] tags, and widgets
- Displaying thumbnails for all the photos in an album, the configurable but more complicated way, with the [salbumphotos] tag
- Displaying a table of any thumbnails or images - the [sthumbs] tag and widget
- Displaying random images - the [srandom] tag and widget
- Displaying your most recently uploaded pictures - the [snewest] tag and widget
- The Shashin and Highslide stylesheets
Q&A About Shashin
- Why store all the album and photo metadata locally? Why not just read the Picasa RSS feed on the fly?
- Are there other plugins for integrating Picasa with WordPress?
- I’m a programmer and I want to tweak or re-use your code. Is that ok, and do you have documentation?
- What does “Shashin” mean?
Change Log
Known Issues
Usage Guide
Installing and configuring Shashin
Download the Shashin zip file from wordpress.org, unzip it, and copy the “shashin” folder to your plugins directory. Then activate it from your plugin panel. After successful activation, Shashin will appear under your “Manage” tab and under your “Options” tab.
Go to the “Options” tab first and take a look at the default options. Note that Highslide is not activated by default - you need to activate it here. If your Picasa server is outside the US, then change the server (e.g. to picasaweb.google.co.uk).
Now go to the “Manage” tab and follow the directions to add your first album!
Note that Shashin will add two tables to your WordPress database, named wp_shashin_album and wp_shashin_photo. You should include these tables when making backups of your WordPress tables.
Special Note to Upgraders from versions prior to 2.0: Deactivate your old installation, upload the new version, and then reactivate. This is necessary for required updates to the Shashin tables.
Special Note for WordPress installations that are in a subdirectory: For the most part Shashin is smart about detecting the location of files, but if your WordPress installation is in a subdirectory of your web site, you will need to edit the 5 URL paths listed in shashin/display/highslide.css to correctly reflect the location of your WordPress installation.
Keeping Shashin synchronized with Picasa
In the Shashin admin panel, you’ll want to click the icon to sync an album whenever you update it in Picasa. Or, you can use the “Sync All” option to sync all your albums at once. This will synchronize your Shashin tables with the Picasa RSS feed. Note that if you delete a photo from Picasa, it will get deleted from the Shashin tables as well when you synchronize the album.
Shashin comes bundled with specially configured version of Highslide, so you don’t need to download Highslide separately. To activate Highslide, go to the Shashin options menu and select Highslide for the “Full-size image display” option. You can also specify the maximum size for images displayed with Highslide. For any photos that you display in groups (using Shashin tags snewest, sthumbs, etc.) the Highslide navigation controls will appear on the image display. For images displayed individually (with the simage tag) no navigation controls will appear.
Do not upgrade Highslide independently of Shashin, as that may cause it to stop working with Shashin. Note that Highslide is free for non-commercial use only.
There are a number of options available in Shashin’s tags. The easiest thing to do is to keep two windows or tabs open in your browser - one for writing your post and one for the Shashin admin page. The admin pages have markup for Shashin tags that you can copy and paste into your post. After pasting them you can then edit the options as needed.
An important thing to note is that Shashin assigns its own numbers to Picasa albums and photo. In the documentation below these are referred to as album keys and photo keys. This is mainly to avoid the impracticality of you having to type the extremely long Picasa ID numbers when you use Shashin tags.
A Shashin tag will be translated into an xhtml “div” container. Always use a Shashin tag on a line by itself in your post or page. This is important because of how WordPress auto-formats your posts. If you put a Shashin tag on the same line as other text, then it will get wrapped in the paragraph tag that WordPress adds to the line. That is not valid xhtml (although in most cases browsers will still display it correctly).
All the Shashin tags have options that let you set a css float value and a css clear value. Both are optional. If you set a float value, there’s usually no need to set a clear value (e.g. floating left or right and then clearing margins typically defeats the point of the float). Remember that the purpose of a float is to let the floated container flow around other containers. If you float an image near the end of your post, it may flow down below the post. To avoid this, put a <br clear=”all” /> tag at the very end of your post.
Picasa supports only a specific set of image sizes. If you try to use a size not listed, your image will not display at all. The sizes are:
32, 48, 64, 72, 144, 160, 200, 288, 320, 400, 512, 576, 640, 720, 800
Note that these sizes represent a “maximum dimension.” This means if you pick 640, and your picture has a landscape orientation, then it will be 640 pixels wide. If it has a portrait orientation, then it will be 640 tall. Shashin automatically calculates the correct size for the other dimension.
Note that 32, 48, 64, and 160 are special sizes. Picasa will crop them to a square shape. This makes them good sizes for displaying tables of thumbnails.
Displaying a single image - the [simage] tag and widget
In a post or page, use the simage tag:
[simage=photo_key,max_size,caption_yn,float,clear]
Example: [simage=268,200,n,left]
For your sidebar, you can pick the Single Image widget on your widget admin page, or use this code and substitute the desired values:
<?php echo Shashin::getSingle(photo_key,max_size,'caption_yn','float','clear'); ?>- photo_key: (required) the Photo Key listed for the image in its Shashin admin page
- max_size: (required) the size you want, chosen from the list above
- caption_yn: (optional, defaults to ‘n’) use ‘y’ or ‘n’ to indicate whether you want the caption to appear under the image
- float: (optional) a CSS float value
- clear: (optional) a CSS clear value
Displaying album thumbnails and album photos - the easy way, with the [salbumphotos] tag
If you want a page that displays thumbnails for all your albums, and then have each album thumbnail link to a display of thumbnails for all the phots in the album, then follow these instructions.
- Create a page containing the [salbumphotos] tag. Give it whatever title you like. You can also include other text on the page if you want. This page will automatically display thumbnails for all the albums you have loaded in Shashin, sorted by publication date (if you want to sort them differently, or only display certain albums, then you need to follow the instructions below for the more configurable approach). Then when you click on a thumbnail, it will display thumbnails for all the photos in that album. The album title will appear as the caption for the table displaying the thumbnails.
- The [salbumphotos] tag takes the following options:
[salbumphotos=max_size,max_cols,caption_yn,description_yn,order_by,float,clear]Example:
[salbumphotos=160,3,n,y]- max_size: (required) the image size you want, chosen from the list above
- max_cols: (required) how many columns of thumbnails you want
- caption_yn: (optional, defaults to n) use y or n to indicate whether you want captions to appear under the images
- description_yn: (optional, defaults to n) use y or n to indicate whether you want to append the album description to the caption for the table
- order_by: (optional, defaults to taken_timestamp) a field to order the photos by. Common choices are taken_timestamp, title (which is the filename), and uploaded_timestamp.
- float: (optional) a CSS float value
- clear: (optional) a CSS clear value
- In the Shashin options menu, enter the URL for the page you just created that contains the [salbumphotos] tag.
With album thumbnails, the size is fixed by Picasa at 160×160, so adjusting the size is not an option. Shashin automatically displays the album title below the thumbnail. If you choose to display the location, it will appear under the title, and a linked Google Maps icon will appear next to the title as well.
- Displaying a single album thumbnail:
In a post or page, use the salbum tag:
[salbum=album_key,location_yn,pubdate_yn,float,clear]Example:
[salbum=2,y,n,left]For your sidebar, you can pick the Single Album Thumbnail widget on your widget admin page, or use this code and substitute the desired values:
<?php echo Shashin::getAlbum(album_key,'location_yn','pubdate_yn','float','clear'); ?>- album_key: (required) the Album Key listed for the album on the Shashin admin page
- location_yn: (optional, defaults to n) use y or n to indicate whether you want the location to appear under the title. A Google Maps icon will also be added
- pubdate_yn: (optional, defaults to n) use y or n to indicate whether you want the album’s pubdate to appear under the title
- float: (optional) a CSS float value
- clear: (optional) a CSS clear value
- Displaying multiple album thumbnails:
There are a couple different ways to do this. One is to display thumbnails for all your albums, in an order you specify. The sorting options are ‘pub_date’, ‘title’, or ‘last_updated’. You can then add ‘ desc’ if you want reverse ordering.
[salbumthumbs=order_option,max_cols,location_yn,pubdate_yn,float,clear]Example:
[salbumthumbs=pub_date desc,2,y,n,left]The other option is to list the keys for specific albums, if you don’t want to display everything:
[salbumthumbs=album_key1|album_key2|etc,max_cols,location_yn,pubdate_yn,float,clear]Example:
[salbumthumbs=2|24|33,2,y,n]For either option, you can pick the Album Thumbnails widget on your widget admin page, or use this code and substitute the desired values:
<?php echo Shashin::getAlbumThumbs('to_show',max_cols,'location_yn','pubdate_yn','float','clear'); ?>- to_show: (required) see the two options above (you can provide album keys or a sort order)
- max_cols: (required) how many columns the table should have
- location_yn: (optional, defaults to n) use y or n to indicate whether you want the location to appear under the title. A Google Maps icon will also be added
- pubdate_yn: (optional, defaults to n) use y or n to indicate whether you want the album’s pubdate to appear under the title
- float: (optional) a CSS float value
- clear: (optional) a CSS clear value
- Displaying albums with descriptions:
This is just like the previous option, but also displays the album title and description alongside each thumbnail. With the default CSS, the display is a two column layout, with the titles and descriptions to the right of the thumbnails. You can adjust shashin_album_list* in shashin.css if you want a different layout.
[salbumlist=order_option,max_cols,info_yn]Example:
[salbumlist=pub_date desc,n]As with salbumthumbs, you can list the keys for specific albums, if you don’t want to display everything:
[salbumlist=album_key1|album_key2|etc,info_yn]Example:
[salbumlist=2|24|33,y]For either option, if you want to do this in PHP, you can use this code and substitute the desired values.
<?php echo Shashin::getAlbumList('to_show','info_yn'); ?>There is no widget for salbumlist.
- to_show: (required) see the two options above (you can provide album keys or a sort order)
- info_yn: (optional, defaults to n) if y, will display the album photo count, pub date, and location between the title and the description.
If you’re using the [salbum], [salbumthumbs], or [salbumlist] tag to display album thumbnails, and you want to link them to a page on your site displaying all the photos in each album, you can still use the [salbumphotos] tag, but the process has a few more steps than the “easy” setup described above.
- For your desired albums, use the [salbum], [salbumthumbs], or [salbumlist] tag in a page or post.
- Create a page containing the [salbumphotos] tag. This one page will be able to display the photos for any requested album. Feel free to put anything else you like on the page as well - Something useful to include is a link back to the page that displays your album thumbnails. See above for the [salbumphotos] markup and how to activate the page in your Settings menu.
Displaying a table of any thumbnails or images - the [sthumbs] tag and widget
Shashin can generate a table of thumbnails, containing the images you specify. You can also control how many columns the table will have, and whether or not to display captions. Note that this tag is typically used for thumbnails, but since you can specify the image size, you can use it to display larger images as well.
In a post or page, use the sthumbs tag:
[sthumbs=photo_key1|photo_key2|etc,max_size,max_cols,caption_yn,float,clear]
Example: [sthumbs=5|202|115|84|33|189,160,3,n,none,both]
For your sidebar, you can pick the Thumbnails widget on your widget admin page, or use this code and substitute the desired values:
<?php echo Shashin::getThumbs('photo_key1|photo_key2|etc',max_size,max_cols,'caption_yn','float','clear'); ?>- photo_key1|photo_key2|etc: (required) as many photo keys as you want, separated by the | character
- max_size: (required) the image size you want, chosen from the list above
- max_cols: (required) how many columns the table should have
- caption_yn: (optional, defaults to n) use y or n to indicate whether you want captions to appear under the images
- float: (optional) a CSS float value
- clear: (optional) a CSS clear value
Displaying random images - the [srandom] tag and widget
You can display a table of random images. You can specify how many images to include in the table, and how many columns the table will have. You can indicate whether the random images should come from a specific album, or from any album. If you want to display a single random image, simply indicate 1 image and 1 column for the table. Note that, if in the admin pages you change an album’s “Include in Random” flag to “No,” then its photos will not appear in random image displays. The same is true for individual images where you set the flag to “No.”
In a post or page, use the srandom tag:
[srandom=album_key,max_size,max_cols,how_many,caption_yn,float,clear]
Example: [srandom=any,288,2,6,n,none,both]
For your sidebar, you can pick the Random Images widget on your widget admin page, or use this code and substitute the desired values:
<?php echo Shashin::getRandom(album_key,max_size,max_cols,how_many,'caption_yn','float','clear'); ?>- album_key: (required) either the word “any” or the Album Key listed for an album on the Shashin admin page
- max_size: (required) the size you want, chosen from the list above
- max_cols: (required) how many columns the table should have
- how_many: (required) how many random images to display in the table
- caption_yn: (optional, defaults to n) use y or n to indicate whether you want captions to appear under the images
- float: (optional) a CSS float value
- clear: (optional) a CSS clear value
Displaying your most recently uploaded pictures - the [snewest] tag and widget
You can display a table of your most recently uploaded pictures. You can specify how many images to include in the table, and how many columns the table will have. You can indicate whether the images should come from a specific album, or from any album. If you want to display only your newest image, simply indicate 1 image and 1 column for the table.
In a post or page, use the snewest tag:
[snewest=album_key,max_size,max_cols,how_many,caption_yn,float,clear]
Example: [snewest=any,288,2,6,n,none,both]
For your sidebar you can pick the Newest Images widget on your widget admin page, or use this code and substitute the desired values:
<?php echo Shashin::getNewest(album_key,max_size,max_cols,how_many,'caption_yn','float','clear'); ?>- album_key: (required) either the word “any” or the Album Key listed for an album on the Shashin admin page
- max_size: (required) the size you want, chosen from the list above
- max_cols: (required) how many columns the table should have
- how_many: (required) how many random images to display in the table
- caption_yn: (optional, defaults to n) use y or n to indicate whether you want captions to appear under the images
- float: (optional) a CSS float value
- clear: (optional) a CSS clear value
The Shashin and Highslide stylesheets
Under your plugin directory, in shashin/display/shashin.css you can edit the CSS for how Shashin styles its images. The commenting in that file explains which classes are applied where. Important Note: if you change the padding for “.shashin_image img” or “.shashin_thumb img” you will need to go to the Options menu for Shashin and adjust the “Image div padding” and “Thumbnail div padding.”
There’s also a stylesheet for Highslide, at shashin/display/highslide.css. Note that it contains hardcoded paths for some URLs - you will need to adjust these if you have WordPress installed in a subdirectory. You can find documentation on the Highslide CSS rules here.
Q&A About Shashin
Three reasons:
- Flexibility: doing things like showing your newest photos or random photos from across multiple albums wouldn’t be practical if you had to parse through all the album feeds in real time. Also, by storing data locally, Shashin can store additional information about your photos that’s not in Picasa, like whether or not you want to exclude certain photos when making a random photo display.
- Performance: parsing a feed, especially one for a large album, is slower than local database queries.
- Scalability: if you happen to have a very popular site with a lot of images, hitting the Picasa RSS feed dozens or hundreds of times per minute would likely result in Picasa automatically blocking your access to the feed for a period of time (most RSS feeders do this to protect themselves against malicious or misconfigured feed readers).
Are there other plugins for integrating Picasa with WordPress?
Yes, there are other good plugins for Picasa too. IMHO, Shashin is the most flexible and feature rich, but it also requires active management on your part (to sync the albums) and as you can see from this page, there’s a learning curve. If you don’t need all of Shashin’s features, then you may want to consider a more lightweight plugin - browse the Picasa plugins at wordpress.org.
I’m a programmer and I want to tweak or re-use your code. Is that ok, and do you have documentation?
I’ve thoroughly documented the Shashin code in PHPDoc. Shashin is released under GPL, so feel free to extend it. I’d like to hear about any features you add.
Please be aware of the GPL rules, especially these two: 1. you cannot use Shashin, or portions of it, in proprietary software; and 2. if you re-use portions of Shashin code, you must include my copyright statement in your files. I’ve already had a problem with one person who re-used several parts of Shashin, and just replaced my copyright statement with his own. This is not only a violation of the GPL, it’s also not cool.
I started working on this plugin while living in Tokyo. Shashin is the Japanese word for photograph, so it seemed fitting.
Change Log
- 0.6 - Beta version. First public release.
- 1.0
- Added “snewest” tag, which displays a table of thumbnails for a variable number of the latest photos in an album you specify (or from all albums). Thumbnail size, display of captions, and CSS “float” and “clear” for the table also can be specified.
- “sthumbs” now includes option for showing a caption. Note this change is not backwards compatible, as the argument order has been changed slightly. You only need to change existing sthumbs tags if you set values for float or clear.
- Changed “srandom” to display a table of random thumbnails for a variable number of photos in an album you specify (or any album). Note this change is not backwards compatible as the arguments have been changed to support the new features.
- Added options admin menu: can now set options for your Picasa server URL, image div padding, and thumbnail div padding.
- Set default values for options listed above when installing
- Bug fix: now use htmlspecialchars on image alt text (which comes from the Picasa image description)
- Bug fix: now reads the Picasa feed with the correct character set (UTF-8)
- 1.0.1 - bug fix: support arbitrary name for Shashin plugin directory
- 1.0.2 - 1.0.4 - updates to readme.txt and minor code cleanup
- 1.0.5 - bug fix: fixed display of icons on Shashin admin page; added this change log
- 1.0.6 - fixed documentation for sthumbs tag, and help link now points to the Shashin FAQ at wordpress.org
- 1.0.7 - bug fix: ShashinPhoto::getRandomMarkup() was failing when only 1 photo was requested
- 1.1
- Added widgets for all the Shashin functions (single photos, random photos, newest photos, photo thumbnail tables, and album thumbnails)
- Bug fix: ShashinPhoto::getRandomMarkup() was including photos from excluded albums when the album key was set to “any”
- Fixed notification: if an album sync or album add fails, this is now correctly reported as a temporary failure to read the Picasa RSS feed, not as a Shashin database error.
- Added wrapper methods for calling Shashin functions directly. This means, if you want to use Shashin in your sidebar and you’re not using widgets, the code you have to include is now less complicated.
- 1.2
- Wrote a completely knew parser for the Picasa RSS feed. This fixes an incompatibility with Wordpress 2.3.3. Shashin is no longer dependent on the constantly changing Wordpress RSS tools (yay!).
- Can now sync and add all of your albums at once (i.e. per Picasa username).
- Added display of multiple album thumbnails (for selected albums, or all your albums with a sort order you choose) - can be done in posts, pages, or as a widget.
- Bug fix: the sthumbs tag now displays the photos in the order you specified.
- Soft delete of photos: if pictures are removed from a Picasa album, they are now flagged as deleted in Shashin, but are not actually removed from the database.
- Smarter album syncing: if you move photos from one Picasa album to another, you can now do this without the original Shashin photo key being lost.
- 1.2.1
- Bug fix: specifying “any” album when displaying random photos will no longer fail because of the function randomly selecting an album with too few photos.
- Complete rewrite of the algorithm for selecting random photos. If you specify “any” album, it will now return a random set of photos from across all your albums (previously it would select a random album, and then return random photos only from that album).
- Now sets the character set for the Shashin tables to UTF-8, as not all mysql configurations use UTF-8 by default. This may fix reported bugs with multibyte (e.g. Chinese) characters.
- 1.2.2: Bug fix: users upgrading to v1.2 correctly had a new unique index set on their photo table’s photo_ids, but new user’s didn’t, which could cause problems when syncing albums.
- 1.2.3: Bug fix: on the admin page, there was a foreach loop error, trying to display Picasa album usernames even if no albums were loaded yet in Shashin.
- 2.0
- 3 options for image display: link to Picasa (as before), link to Picasa in a new window, or show in Highslide (note videos still display at Picasa).
- Show thumbnails for all photos in an album, linked from the album thumbnail (salbumphotos tag).
- Show album thumbnails side-by-side with the album descriptions (salbumlist tag).
- Option to prefix album titles on photo captions.
- For database table changes, now analyzes tables directly instead of just checking the Shashin version number.
- Bug fix: Album “sync all” feature wasn’t working properly when there was more than one username.
- 2.0.1
- Bug fix: if you select the option to display your photos at Picasa in a new browser window, it actually works now (the formatting of the anchor tag was incorrect).
- Bug fix: now performs a preg_escape on the URL for the page containing your salbumphotos tag. This fixes a warning that was being displayed for some URLs in PHP 5.
- Bug fix: Shashin now correctly detects your WordPress installation directory if you’ve installed it in a subdirectory (except for paths in shashin/display/highslide.css which are hardcoded - you’ll need to edit those by hand).
- Added a full copy of the GPL license.
- 2.0.2: Adjusted for new location of the content_url in the Picasa RSS feed.
- 2.0.3: Adjusted for new location of video data in the Picasa RSS feed.
- 2.0.4: Added “global $wpdb” to the top of Shashin.php - necessary for compatibility with WordPress 2.5 (otherwise the Shashin table names come out wrong). Also added mp4 as a supported video type.
- 2.1
- Simplified methods for displaying album photos. The page containing the [salbumphotos] tag now displays all your album thumbnails by default, instead of breaking if you call it without arguments. It then displays photos for the specified album if you do call it with arguments. Also, no longer tries to manipulate the page title (there is currently no clean way to do this in WordPress).
- Bug fix: thumbnails in the admin panels display correctly again now (this broke after I added Highslide support)
- Bug fix: with certain Highslide settings, captions weren’t always showing on the page when requested.
- Bug fix: fixed minor XHTML validation error in [salbumlist] markup.
Known Issues
- Since the release of WordPress 2.5, I’ve received a few reports from new Shashin users that their Shashin tables were created without the “wp_” prefix. I believe the problem has to do with this, but I have not yet been able to re-create the problem, which means I can’t troubleshoot it. If this happens to you, rename your two shashin tables to “wp_shashin_album” and “wp_shashin_photo”, and please let me know which version of WordPress and which version of PHP you are using.
- Shashin is not compatible with versions of mySQL prior to 4.1. If you are on an older version of mySQL, you will get an error when you try to add an album. To get around this, you can comment out lines 179-181 in ToppaWPFunctions.php (note that doing this means you may run into problems if you move photos from one Picasa album to another - that’s what this code checks for).
