Shashin – a WordPress plugin for displaying photos and videos from Picasa, YouTube, and Twitpic

I am currently no longer developing or supporting my WordPress plugins. I may resume development and support in the future, but I’m not sure when.

Shashin has many features for displaying photos and videos from Picasa, Youtube, and Twitpic in your WordPress posts and pages:

  • Show a gallery of all your albums, photos, and videos, with multiple options for organizing them
  • Use the Media Manager to easily create and add galleries to your posts
  • Show your photos and vidoes with your favorite image viewer. PrettyPhoto is included with Shashin, or you can use a different viewer of your choice (Fancybox 1.3.4 is also included, but I will probably remove it soon since the newer version of Fancybox does not have a license that is compatible with WordPress )
  • Pick individual photos or videos to display, in any size, including captions and EXIF data
  • Pick photos and videos from any combination of Picasa, Youtube, and Twitpic to display in groups of thumbnails
  • Show thumbnails of your newest photos and videos, 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 (for Picasa albums with location data)
  • Display any number of random photos and videos. You can also choose to exclude certain photos or albums from random display
  • Use a widget to display Shashin photos in your sidebar
  • Customize the Shashin stylesheet to suit the theme of your site.
  • Internationalization: Shashin supports translations into other languages (please contribute a translation if you’re bilingual!)
  • Schedule daily automatic synchronization of Shashin with your feeds from Picasa, Twitpic, and Youtube.

It is multi-site compatible.

Get Help

Enter a post in the wordpress.org support forum for Shashin, and I’ll respond there.

Give Help

Examples

See the Shashin 3 examples page to see for working examples that illustrate the many options available with Shashin shortcodes.

Usage Guide

Important note: This guide assumes you have already read the instructions in the readme for how to install Shashin and get started with adding photos and videos. That information is not repeated here.


Usage Guide

Terminology: albums, photos, and videos

In Shashin, an “album” contains photos and videos. This is the same terminology as Picasa. For consistency, Twitpic and YouTube feeds are referred to as albums in Shashin. For example, my personal Twitpic feed will show up in my Shashin Tools menu as an album titled “Twitpic: Michael Toppa.”

Synchronizing your photos and videos with Shashin

On the Shashin tools menu, you can manually synchronize with an album at any time. On the Shashin Settings Menu, you can select the option to have Shashin automatically synchronize with all your feeds once per day. What it will do is synchronize 1/24th of your albums per hour, to minimize any performance impact on your site. Note that it is using the WordPress scheduling features, which do not provide precise timing.

For Picasa, note that synchronizing will not automatically pull in new albums to Shashin. It only synchronizes albums you’ve already added to Shashin. For new albums, you need to use the “Add Albums” form on the Shashin Tools Menu. This allows you to selectively control which of your Picasa albums are added to Shashin.

⇑ top

Using the Shashin Media Browser

If you want to add photos or album thumbnails to a page or post, then click the “Add Media” button, which is above the post editor’s button bar, to launch the WordPress media menu. In the media menu sidebar, you’ll see links for “Shashin Albums” and “Shashin Photos,” which you can use to easily add albums and photos to your post. This great feature was contributed by Sune Pedersen for Shashin 2, and I’ve upgraded it for use with Shashin 3.

Here are a couple usage tips:

  • If you mouse over a thumbnail on the left hand side, then the right hand side will show you a larger version of it, and vice versa. This makes good use of the available screen real estate.
  • To select a photo, just click it once. Don’t drag it. After you click it, you’ll see it appear under the “Selected Photos” heading. If you change your mind and need to remove a photo that you selected, just click it in the “Selected” area, and it will be removed.

⇑ top

The Shashin shortcode and attributes

Shashin places photos and albums in your posts by use of a shortcode. Please review the examples page to see how the shortcode works. Below is documentation for all the options available for each shortcode attribute.

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, resulting in invalid HTML (although in most cases browsers will still display it correctly).

Shashin’s most basic usage is:

[shashin]

You can add the following attributes to the shortcode to control what is shown, the size, and the layout.

⇑ top

type

Purpose: whether to show album thumbnails or photos

Supported values:

  • photo: shows photos or videos you specify, from any albums
  • album: shows album thumbnails, and then shows the photos in an album when clicked
  • albumphotos: shows all the photos in an album (without having to click the album thumbnail first)

Default value: photo

Examples:

  • Shows photos with Shashin IDs 3, 7, and 9. You can get the ID numbers by viewing an album’s photos in the Shashin Tools menu. Or if you use the Shashin media browser to create the shortcode, you don’t need to know the ID numbers at all.
    [shashin type="photo" id="3,7,9"]
  • Shows a random selection of 4 photos in a 2×2 layout.
    [shashin type="photo" limit="4" order="random" columns="2"]

⇑ top

id

Purpose: the IDs of the thumbnails to show. If you use “photo” for the type attribute, it will assume photo IDs. If you use “album” or “albumphotos”, it will assume album IDs.

Supported values: any Shashin album or photo ID.

Default value: none

Examples:

  • Shows photos with Shashin IDs 3, 7, and 9.
    [shashin type="photo" id="3,7,9"]
  • Shows albums with IDs 4,8,9,11 in a 2×2 layout.
    [shashin type="album" id="4,8,9,11" columns="2"]

⇑ top

thumbnail

Purpose: the thumbnail specified will be substituted for the photo or video identified in the ID attribute. This is most useful for videos where Picasa fails to generate a thumbnail (for some videos it will show just a solid black image for the thumbnail). This means you can substitute a different photo for the missing video thumbnail, but still show the video when the thumbnail is clicked.

Supported values: same as ID.

Default value: none

Examples:

  • Shows the thumbnail for photo ID 6, but plays the video with ID 7 when the thumbnail is clicked.
    [shashin type="photo" id="7" thumbnail="6"]
  • Same as above, but for the 2nd photo shown, uses the same photo for the thumbnail and the expanded view.
    [shashin type="photo" id="7,11" thumbnail="6,11"]

⇑ top

size

Purpose: determines the size of the thumbnails shown.

Supported values:

  • Any of these size labels: xsmall, small, medium, large, xlarge, or max. If you use “max”, Shashin will pick the largest size supported by your theme (which you can manage on the Shashin Settings menu).
  • A numeric pixel value supported by the photo/video service:
    • Picasa: 32, 48, 64, 72, 94, 104, 110, 128, 144, 150, 160, 200, 220, 288, 320, 400, 512, 576, 640, 720, 800, 912, 1024, 1152, 1280, 1440, 1600
    • Twitpic: 75, 150, 600, 1280
    • Youtube: 120, 480

    If the photo has a landscape orientation, this will be the width; if it has a portrait orientation, it will be the height.

  • Any numeric value: if you enter a number not listed above, Shashin will scale the image accordingly, to provide the size you want. Specifically, Shashin will use the closest, larger standard size available for the image, and then scale it down to the size you’ve specified, so you’re never losing image quality.

Default value: xsmall

Examples:

  • Shows photo with Shashin ID 3 at 640 pixels.
    [shashin type="photo" id="3" size="640"]
  • Shows albums with IDs 4,8,9,11 in a 2×2 layout with the maximum size that will fit in the content area.
    [shashin type="album" id="4,8,9,11" columns="2" size="max"]

⇑ top

crop

Purpose: whether to crop a thumbnail square. Note that thumbnails will be cropped only if the photo service has the requested size available in cropped format. For Picasa these sizes are 32, 48, 64, 72, 104, 144, 150 and 160. For Twitpic they are 75 and 150. Cropped sizes are not available for YouTube.

Supported values: “y” or “n”

Default value: “n”

Example: displays albums in 3 columns, size 144, cropped square

[shashin type="album" columns="3" size="144" crop="y"]

⇑ top

caption

Purpose: determines whether a caption is shown. For photos, it will show the caption under the thumbnail. For albums, it will show the album title under the thumbmnail, a Google Maps icon if location data is available, and the number of photos in the album.

Supported values: “y” or “n”

Default value: “n” if the type is “photo” or “albumphotos”, and “y” if the type is “album”

Example: will show the caption under the photo:

[shashin type="photo" id="3" caption="y"]

⇑ top

columns

Purpose: determines the number of columns to use for displaying the thumbnails

Supported values: any number, or “max”. For “max”, Shashin will determine how many columns will fit in the content area, given the size of the thumbnails.

Default value: 1

Examples:

  • Shows photos with Shashin ID 3,6 in 2 columns.
    [shashin type="photo" id="3,6" columns="2"]
  • Shows albums with IDs 4,8,9,11 at 160 pixels for each album thumbnail, using the maximum number of columns that will fit in the content area.
    [shashin type="album" id="4,8,9,11" size="160" columns="max"]

⇑ top

order

Purpose: determines the order for displaying thumbnails. The supported values vary depending on the type. “user” order means the actual order listed in the id attribute. “source” means the order of the photos at Picasa, YouTube, or Twitpic.

Supported values for type “photo” and “albumphotos”: id, date, filename, random, source, user

Supported values for type “album”: id, date, title, location, count, sync, random, source, user

Default values for type “photo” and “albumphotos”: “user” if an id was provided, and “source” otherwise (grouped by albums)

Default values for type “album”: “user” if an id was provided, and “date” otherwise

  • Shows photos from album ID 5, in 3 columns, ordered by date.
    [shashin type="albumphotos" id="5" columns="3" order="date"]
  • Shows 2 random photos.
    [shashin type="photo" limit="2" order="random"]

⇑ top

reverse

Purpose: whether to reverse the specified order

Supported values: “y” or “n”

Default value: “n”

Example: Shows photos from album ID 3, in 3 columns, in reverse order by date.

[shashin type="albumphotos" columns="3" order="date" reverse="y"]

⇑ top

limit

Purpose: to limit the number of thumbnails displayed

Supported values: any number

Default value: can be set on the Shashin settings pages (set at 18 initially)

Examples:

  • Shows the first 9 photos from album ID 5, in 3 columns, ordered by date.
    [shashin type="albumphotos" id="5" columns="3" order="date" limit="9"]
  • Shows 2 random photos.
    [shashin type="photo" limit="2" order="random"]

⇑ top

offset

Purpose: to show a specific subset of thumbnails. Shashin does automatic photo paging but does not provide automatic album paging. This will let you do manual album paging, with one shortcode per page (you’ll need to add your own “previous” and “next” links).

Supported values: any number

Default value: none

Examples (these three together are an example of album paging):

  • Shows the first 18 albums, with the most current first.
    [shashin type="album" order="date" reverse="y" limit="18" size="160" columns="max" position="center" crop="y"]
  • Shows the next 18 albums.
    [shashin type="album" order="date" reverse="y" limit="18" offset="18" size="160" columns="max" position="center" crop="y"]
  • And the next 18.
    [shashin type="album" order="date" reverse="y" limit="18" offset="36" size="160" columns="max" position="center" crop="y"]

⇑ top

position

Purpose: to control the position of thumbnails in your post or page.

Supported values: any CSS float value (left, right, none, inherit), or “center”

Default value: none

  • Shows photo ID 52, large and centered
    [shashin type="photo" id="52" size="large" position="center"]
  • Shows photo IDs 5,9,42, in a single column, floated left.
    [shashin type="photo" id="5,9,42" columns="1" position="left"]

⇑ top

clear

Purpose: specifies which sides to disallow floating elements around Shashin thumbnails

Supported values: any CSS clear value (left, right, both, none, inherit)

Default value: none

Example:

[shashin type="photo" id="52" size="large" clear="left"]

⇑ top

Understanding the “max” value for “size” and “columns”

“max” helps you not have to think too hard with your Shashin shortcodes. If you specify “max” as the size, Shashin will use the size specified in your Shashin settings for “Content width (in pixels) for your theme.” If your theme has a responsive design, pick the largest size you would want to display thumbnails (starting with Shashin 3.4, Shashin will then scale it down as needed for smaller displays). This is also helpful if you ever change themes in the future – you can just update this settings rather than have to edit a bunch of previously created shortcodes.

“max” can also be used with columns. So if you know, for example, you want the thumbnails size to be 150, Shashin will do the math to figure out how many columns to display (by referring to the content width setting).

Note that you cannot specify “max” for the size and the columns in the same shortcode.

⇑ top

Using the Shashin Widget

The input fields in the form for the Shashin widget are the same as the shortcode attributes, so please review that section of the documentation to understand the options. Note the only type supported currently is “photo” (as it’s not practical to show all the photos for an album in the sidebar, which is very narrow in most themes).

Here are some tips:

  • The title will appear above the Shashin images, in an H2 heading tag.
  • For the widget, there is no photo picker to get the photo IDs for you, if there are specific images you want to show. I recommend going to the post editor, and generating a Shashin shortcode in a post, using the Shashin media browser to pick the photos you want. Then copy-and-paste the photo IDs from the shortcode into the widget (you can then go ahead and delete the shortcode from the post).
  • If you want random images, select “Random” for the “Order by,” and leave the photo IDs field blank. Then under “Limit” put in how many random images you want.

⇑ top

Using Shashin with prettyPhoto

Shashin comes bundled with prettyPhoto. After installing Shashin, review the settings for prettyPhoto in the Shashin settings menu, and update them as desired.

If you already have prettyPhoto installed on your site, there is an option in the Shashin settings menu to prevent Shashin from loading its own copy of prettyPhoto. Use this option to prevent possible problems with running multiple instances of prettyPhoto at the same time.

Note that Fancybox is also included, but may be removed in future versions of Shashin. It’s an older version of Fancybox, as the newest version does not have a license that is compatible with WordPress. It’s currently included only for legacy support.

⇑ top

Using Shashin with other image viewers

If you wish to use a viewer other than prettyPhoto or Fancybox, go to the Shashin settings menu, and select the option to use your own viewer. This is an “experts only” option. Then fill out the fields to configure the “id”, “class”, and “title” attributes of Shashin’s image tags and anchor tags. You will need to know how to structure the values for these attributes for your viewer.

The ability to click an album thumbnails and view its photos may not work “out of the box” with viewers other than prettyPhoto and Fancybox. If you run into any trouble, post a question in the support forum – we may need to add some custom javascript for the viewer you want to use.

⇑ top

The Shashin and prettyPhoto stylesheets

The CSS for styling Shashin is in your plugin directory at shashin/public/display/shashin.css. If you want to customize it, copy it to your active theme folder, and edit it there. Shashin automatically looks for a copy of shashin.css in your active theme folder first. This way you won’t lose your customizations the next time you upgrade Shashin.

There’s also a stylesheet for prettyPhoto, at shashin/public/display/prettyphoto/prettyPhoto.css. Like shashin.css, you can put a customized version of it in your active theme directory.

⇑ top

Common problems and solutions

  1. Album syncing problems: There are four possible causes of the error “Failed to retrieve album feed at [your album’s json url].”
    1. A server security limitation: Shashin uses WordPress’ HTTP API to retrieve album feeds. The HTTP API will try using PHP’s curl, fopen, and fsockopen functions to retrieve your album feeds before it gives up. If all three are disabled on your server, then you should ask your hosting provider if they can enable at least one of them for you, so you can use Shashin.
    2. A temporary connection problem: a temporary internet connection problem between your site and the feed server is the most common cause (note that just because you can get to the feed url from your browser doesn’t mean your web hosting server can connect). Wait a few minutes and try again to see if the problem goes away.
    3. A data load problem: if you are trying to use “Sync All”, and you have hundreds of albums, or dozens of albums with several hundred photos per album, your web server may timeout re-loading the Shashin Tools page before the syncing can complete. In this case you will need to add or sync albums one at a time. Or, if you are comfortable editing code, you can try adding the following line of code at the beginning of Shashin’s start.php file:
      set_time_limit(120);

      Your server might not honor this setting, but if it does, then it will allow more time for Shashin to process all your albums’ feeds.

    4. A private album: Shashin supports public and “limited” visibility Picasa/Google+ albums. It does not work with private albums.
  2. Undesired styling for Shashin thumbnails: if you are seeing off-center image borders, extra borders, or incorrect thumbnail positioning, it is being caused by a conflict between the Shashin stylesheet and your WordPress theme’s stylesheet. The major browser’s have tools which let you fairly easily analyze these problems (such as Firebug for Firefox). Once you find the conflict you can then alter Shashin’s stylsheet or your theme’s stylesheet to resolve it. For thumbnails not floating to the left or right in the Twenty Ten and Twenty Eleven themes, please see this comment for a solution.
  3. Album links going to Picasa instead of showing photos on your site: there are several WordPress plugins for Google Analytics, some or all of which conflict with Shashin. They add “onClick” code to the album links, causing the Shashin code to not function properly. If you’re using one of these plugins, see if it has an option where you can tell it to ignore links to certain domains. If so, tell it to not track links to “googleusercontent.com” (that’s the Picasa/Google+ domain where the images are served).

⇑ top

Calling Shashin directly in PHP code

Calling Shashin directly in your PHP code is easy. The static method ShashinWp::display() accepts an associative array as an argument, which works exactly like the Shashin shortcode. Here is an example, for showing two random photos in a single column:

<?php
$shortcode = array(
    'type' => 'photo',
    'limit' => 2,
    'order' => 'random',
    'size' => 160,
    'crop' => 'y',
    'caption' => 'y',
    'columns' => 1
);
echo ShashinWp::display($shortcode);
?>

⇑ top

Planned new features

I maintain a list of planned new features at GitHub. If there’s a feature you’d like to see that is not already listed, post a message in the support forum to let me know.

Note that my time for development work on Shashin is very limited (as I don’t get paid anything for it), so please be patient.

⇑ top

What “Shashin” means

I released the first version of Shashin while Post to Post Links II error: Unrecognized type: cat_slug. Shashin is the Japanese word for photograph, so it seemed fitting.

⇑ top