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.
• FancyBox comes included with Shashin, for displaying your images and videos. Highslide is available as a separate add-on, and you can configure Shashin to work with other viewers as well, such as Lightbox, Thickbox, 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 (if you’d like to contribute a translation, please contact me.
• Customize the Shashin and Fancybox stylesheets to suit the theme of your site.
• Schedule daily automatic synchronization of Shashin with your Picasa (GooglePlus) albums, Twitpic photos, and YouTube videos.

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 Post to Post Links II error: Unrecognized type: cat_slug 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 Fancybox
• Using Shashin with other image viewers
• The Shashin and Fancybox stylesheets
• Common problems and solutions
• 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 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
• 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 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 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 sidebar, which is very narrow in most themes).

⇑ top

Using Shashin with Fancybox

Shashin comes bundled with Fancybox 1.3.4, so you don’t need to download Fancybox separately. After installing Shashin, you’ll want to specify your desired settings for Fancybox in the Shashin Settings menu.

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

I cannot include the lastest version of Fancybox with Shashin, as versions of Fancybox after 1.3.4 are not GPL compliant, which means they cannot be included in the wordpress.org plugin repoistory.

⇑ top

Using Shashin with other image viewers

If you wish to use a viewer other than Fancybox, you have a couple of options:

1. Download and activate the Highslide add-on for Shashin.
2. On the Shashin settings menu, select the option to use your own viewer. 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.

⇑ top

The Shashin and Fancybox 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 Fancybox, at shashin/Public/Display/fancybox/jquery.fancybox.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 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 or hours 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 ask your hosting provider if they can enable at least one of them for you, so you can use Shashin.
   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 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.

• Done in 3.0: Twitpic support
• Done in 3.0: YouTube support
• Done in 3.1: WordPress multi-site support
• Done in 3.2: Support for “limited, anyone with a link” access to Picasa albums (I do not plan to add private album support)
• Done in 3.2: Support adding Picasa albums through Google+ URLs
• Done in 3.2: Improved UI for adding albums
• Lazy loading of images Actually just use the Lazy Load plugin.
• Add social media buttons (Facebook “like”, Google +1, etc)
• Support Highslide thumbstrips
• Include Highslide’s mobile stylesheet
• Make image displays compliant with responsive design recommendations
• Flickr support
• Ajax based syncing (to prevent synchronization timeouts for large album sets)
• 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
• Add option for largest size video to show (and automatically pick smaller size for mobile view)
• 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 Post to Post Links II error: Unrecognized type: cat_slug. 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