Nothing But Words

Features

Shashin is a powerful WordPress plugin that enables you display photos and videos from Picasa, YouTube, and Twitpic, anywhere in your WordPress site. It has many features:

• Embed a gallery of your Picasa albums, and all the photos and videos in each album, with customizable pagination of photos.
• Highslide comes included with Shashin, for displaying your images and videos. You can configure Shashin to work with other viewers as well, such as Lightbox, Thickbox, Fancybox, etc.
• Pick individual photos or videos to display, in any size supported by Picasa.
• Pick photos and videos from any combination of albums 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.
• Display any number of random photos and videos, from one or more albums. You can also choose to exclude certain photos or albums from random display.
• Use a widget to display Shashin photos in your sidebar
• Use a jQuery based WYSIWYG media browser for easily adding Picasa photos and albums to your posts.
• Optionally include camera EXIF data in photo captions.
• Dynamically set thumbnail sizes or columns to suit the width of your theme (useful if you change themes in the future).
• Internationalization: Shashin is designed to support translations into other languages (please contribute a translation if you’re bilingual!).
• Customize the Shashin and Highslide stylesheets to suit the theme of your site.
• Schedule daily automatic synchronization of Shashin with your Picasa albums.

Examples

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

Need Help?

Please use the comments section in my most recent plugin support post for questions or bug reports.

Want to Contribute?

The latest revisions are always available at GitHub. Code contributions through GitHub are welcome. Stable releases are available at wordpress.org.

Usage Guide

• Installing/Upgrading
• Keeping Shashin synchronized with Picasa
• Using the Shashin Media Browser
• The Shashin shortcode and attributes
  • type
  • id
  • thumbnail
  • size
  • crop
  • caption
  • columns
  • order
  • reverse
  • limit
  • offset
  • position
  • clear
• Using the Shashin Widget
• Using Shashin with Highslide
• Using Shashin with other image viewers, such as Lightbox
• The Shashin and Highslide stylesheets
• Common problems and solutions
• Highslide’s Settings
• Calling Shashin directly in PHP code
• Planned new features
• What “Shashin” means
• Shashin 2 documentation

---

Usage Guide

Installing/Upgrading

See the instructions in the readme for system requirements, first time installation, and upgrading from Shashin 2.

Note there are some Shashin 2 features that are no longer available in Shashin 3:

• Support for private Picasa albums. There are simply too many variations in web host PHP configurations and security settings for me to continue supporting this feature
• The [salbumlist] tag is deprecated – it will now render as a regular album thumbnail display (I intend to include a proper list layout in a future version)
• The “c” option for captions is deprecated (it is now treated as an “n”)
• The Shashin 2 PHP functions you could call directly have been removed, and replaced with a new one
• The previous widgets have been replaced with a new one

⇑ top

Keeping Shashin synchronized with Picasa

If you add albums to your Picasa account or make changes to them, you need to let Shashin know. On the Shashin Tools Menu, click the icon to sync an album whenever you update it in Picasa. You can also use the “Sync All” option to sync all your albums at once. If you have an extremely large number of albums or photos, see the Known Issues section below concerning the limits of the “Sync All” option.

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

Note that “Sync All” 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 media icon, which is above the post editor’s button bar, to launch the WordPress media menu. In the media menu you will see a Shashin Albums tab and a Shashin Photos tab, 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 typical examples of how to use it. 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
• 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 identified in the ID attribute. This is most useful for videos where Picasa generates a solid black thumbnail (so you can substitute a different photo for the 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 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 find the next smallest size supported.

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.

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 yet 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

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 to understand the options. Note the only type supported currently is “photo”. I will add support for albums and album photos after adding support for Highslide thumbstrips in an upcoming version (as it’s not practical to show all the photos for an album in the siebdar, which is very narrow in most themes).

⇑ top

Using Shashin with Highslide

Shashin comes bundled with a specially configured version of Highslide, so you don’t need to download Highslide separately. After installing Shashin, you’ll want to specify your desired settings for Highslide in the Shashin Settings menu. You also have the option of linking your photos directly to Picasa and not using Highslide, or using a different image viewer.

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.

⇑ top

Using Shashin with other image viewers, such as Lightbox

Shashin provides settings that allow you to configure it for use with image viewers other than Highslide. If you want to use another viewer, there are several things to consider:

• If you choose to use an image viewer other than Highslide, you are responsible for installing it, configuring it, and understanding it yourself. I am happy to consider making adjustments to Shashin for supporting other viewers, but I can not help you with setting up Lightbox, Fancybox, Thickbox, etc.
• The Shashin Settings menu lets you control 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.

⇑ top

The Shashin and Highslide 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.

Important Note: if you change the padding for “shashinThumbnailImage” you will need to go to the “Settings” page for Shashin and adjust the “Thumbnail div padding” accordingly.

There’s also a stylesheet for Highslide, at shashin/Public/Display/highslide/highslide.css. Like shashin.css, you can put a customized version of it in your active theme directory. You can find documentation on the Highslide CSS rules here.

⇑ 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 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.
   2. A data load problem: if 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.

   3. 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 your hosting provider if they can enable at least one of them for you, so you can use Shashin.
   4. Not a public album: Shashin does not currently support “limited” visibility Picasa albums (I am planning to add support for “limited, anyone with a link” visibility, but not the full “limited” visibility).
2. Highslide not working: There are several WordPress plugins for Google Analytics, some or all of which conflict with Shashin. They overwrite Shashin’s javascript “onclick” code in the Highslide links with their own Analytics tracking code, causing the Highslide links 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 “ggpht.com” (that’s the Picasa domain where the images are served).
3. 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. There are an infinite variety of possible conflicts, and I no longer have the availability to troubleshoot these problems on an individual basis. 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.
4. Inline videos interfering with Highslide: If you have a Flash video embedded in a page, and you are using Highslide with Shashin on the same page, the embedded video may stay on top of the Highslide viewer. This can be fixed by adjusting the code you use to embed the video. See this post in the Highslide forum.
5. Videos in timed slideshows: If you start a Highslide slideshow and set it to run automatically, and there are videos in the slideshow, the videos will not play to the end. If each pictures is displayed for, say, 5 seconds, then you will get only 5 seconds of a video before it moves on to the next picture or video. Currently Highsldie has no means for handling this situation.

⇑ top

Highslide’s Settings

Highslide settings are managed in an “hs” JavaScript object. Its API is extensively documented at highslide.com. With Shashin, the place to make adjustments to the Highslide settings is in the file shashin/Public/Display/highslideSettings.js, in your plugins folder.

⇑ top

Calling Shashin directly in PHP code

Calling Shahsin 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

These are not in a particular order. If there’s a feature you’d like to see, let me know.

• Twitpic support – DONE
• YouTube support – DONE
• Lazy loading of images
• Support Highslide thumbstrips
• Make image displays compliant with responsive design recommendations
• Support for “limited” access Picasa albums (I do not plan to add private album support)
• Flickr support
• Ajax based syncing (to prevent synchronization timeouts for large album sets)
• WordPress multi-site support
• Option to use HTML lists instead of tables for layout
• Option to automatically add new albums for user accounts
• Add option to prefer mp4 version of a video to flash, if available
• “Share” button
• Automatic paging of album thumbnails
• Make use of Picasa tags (to show photos by tag, and/or have a tag cloud)
• More position options for the Highslide controller
• Show photos or albums by date range

⇑ top

What “Shashin” means

I released the first version of Shashin while living in Tokyo in 2007. Shashin is the Japanese word for photograph, so it seemed fitting.

⇑ top

Shashin 2 documentation

If for any reason you are still using Shashin 2, the documentation for it is still available.

⇑ top