PhotoShow Authoring Widget

The PhotoShow Authoring Widget allows your users to create PhotoShows.

The authoring widget is typically integrated into the "edit my profile" or "create a new posting" section of your site, on a page that is only accessible to logged-in members. It's also a great idea to make PhotoShow authoring an option on the "upload photos" page, if you have one.

To integrate the Authoring Widget, you'll need to:

1. Add HTML code to the page where you want to embed or launch authoring
2. Implement a postShow callback that adds the HTML for a newly-created show to the user's page

These are described in more detail below.

Adding the Authoring Widget to Your Page

The PhotoShow Authoring Widget goes on the page where you want to let users create new PhotoShows.

There are two methods for integrating authoring:

• launchMakePhotoShow: Lets the user click a button that opens the authoring widget in a new popup window.
• embedMakePhotoShow: Embeds the authoring widget inline, in a <div> you provide.

Launching authoring in a new window is often easier to integrate into an existing site design (you just need a button or link on your page), and allows the user the option of resizing the authoring window to see more of their photos. Embedding authoring into your page can provide a more-integrated experience, but requires a minimum 600x404 area. The choice is up to you.

The authoring code is HTML code that can be dropped on any web page. Here's the code for launchMakePhotoShow. (If you wanted to use embedMakePhotoShow instead the code would be very similar, but you'd also pass a div id.)

<script type="text/javascript" src="http://api.photoshow.com/widgets/make_photoshow.0.1.0.js"/></script>
<script type="text/javascript">
    var psConfig = {
        postShow: 'YOUR_CALLBACK_URL', // e.g. http://www.mydomain.com/callbacks/post_photoshow.php
        userId: yourUserIdVariable, // Optional
        sessionKey: yourSessionKeyVariable, // Optional 
        viewerWidth: WIDTH, // Optional , e.g. 400
        viewerHeight: HEIGHT // Optional , e.g. 325 
    }
</script>
<a href="javascript:PhotoShow.widgets.launchMakePhotoShow('YOUR_DEVELOPER_KEY', psConfig);">Add a PhotoShow</a>

In this code:

• postShow is a callback that receives the newly-created PhotoShow. See the next section for details.
• userId and sessionKey are optional variables passed through to the postShow callback. You can use these to validate the user when a show is posted to you.
• viewerWidth and viewerHeight allow you to set the default width and height of the PhotoShow viewer for the show the user creates (not the width and height of the authoring widget). This is just a default; PhotoShows are infinitely resizable, at any time, and you can always override the viewer size. (See PhotoShow Viewer for viewer configuration options.)

Implementing the postShow Callback

Now that you've integrated the authoring HTML into your page, your users can create new PhotoShows. But how do those shows find their way onto your site? The answer is the postShow callback.

The postShow callback is an absolute URL on your server that PhotoShow will call when a new show has been created and is ready to be added to your site. It's typically very similar to whatever handler you already have to let users add content to their pages. (Your code that handles add-to-my-profile, or add-a-new-forum-post, or Atom POST... that's pretty much the code you're looking for.)

Your postShow URL will be called with form variables containing the HTML embed code needed to include the PhotoShow viewer on a page. You can simply drop this HTML into the user's profile page, forum, or wherever you want the PhotoShow to end up. Other variables provide you with the show's title and other helpful information, which you can use or not as you please. Full details are in the postShow Callback API reference.

It's important to realize that postShow will be called from PhotoShow's servers, not from the end user's browser. This means that cookies or other session information you might rely on are not directly available to you in your postShow function. So that you can authenticate the post, PhotoShow will pass through two variables from the authoring session: a userId and a sessionKey. You can use these variables for anything you want, but the names will probably suggest the most typical case.

When the post succeeds, you return a "success" response (surprise), along with permalink for the page where the show ended up. This permalink is optional, but highly encouraged. It's the return link to your site that PhotoShow will use if a viewer decides to embed the show elsewhere, share it by email, etc. (If you don't tell PhotoShow where on your site to find the newly-created-and-posted show, we'll create a page on PhotoShow.com to handle viral sharing. But we'd much rather send users back to the show author's page on your site!)

If for some reason you can't accept the postShow (e.g., if the userId and sessionKey aren't valid), you can provide a failure response to PhotoShow, along with an explanatory message to display to the user.

Most sites should set up their postShow callback URL as part of their application setup. You can also override it in JavaScript, as in the example above, if (for example) you need to send different users to different posting servers.

Get the Code

Fill in the form and copy the code below to add the PhotoShow Authoring Widget to your site. If you haven't already set up your application, you'll need to do that, too.

For more customization options, see the API reference: launchMakePhotoShow or embedMakePhotoShow.

Additional Customization

The above explanation just covers the basics. You can customize the PhotoShow Authoring Widget for your site:

• If you let users upload photos to your site, you can configure the authoring widget so users can import those photos into their shows. See Importing User Pictures.
• To specify custom playback settings for the PhotoShow viewer, see PhotoShow Viewer.
• To customize the PhotoShow styles offered to authors, see One Click Styles.
• To skip the authoring process altogether and auto-create an instashow based on an RSS feed of photos, see Instashow Widget.