TypePad Widget API

• Overview
• How a User Adds a Widget to their Blog
• Building Widgets for TypePad
• Example Web Form
• About the Published Widget
• Widget Design Best Practices
• Frequently Asked Questions

Overview

TypePad provides a simple form-based API that allows third parties to create a Widget on the sidebar of a user’s weblog. A Widget is a block of HTML and/or JavaScript that can add content or functionality to a user’s weblog, and be managed by the user through TypePad’s drag-and-drop weblog design functionality.

The process for adding a new Widget to a weblog is very simple:

1. Your application embeds an HTML form on their website that contains information within a few hidden form fields that will provide TypePad with everything necessary to embed a Widget within a user’s weblog, including the HTML that will be inserted into the weblog.
2. A user visits your application and clicks a button that submits the form to TypePad.
3. The user is taken to TypePad and is prompted to login with their username and password.
4. The user previews the content Widget provided by your application posting, and is asked to select the weblog or weblogs that they would like to add the widget to.
5. The user is given the option to preview what the Widget will look like on their weblog, and then confirm their selection.
6. The user is then able to return to your application, or continue on in TypePad to reposition the widget on their weblog.

That’s it. The user’s weblog now has a new widget installed in their weblog.

How a User Adds a Widget to Their Blog

Step 1: User clicks a button to submit the widget form, and begins the Widget Installation Wizard.

From anywhere on your website a user can submit the form discussed above to begin the wizard installation process.

If a user has already installed your widget, then the widget installation wizard will allow them to update the widget’s HTML with any new HTML you wish to provide.

Note to implementers: The button text can say anything you want. Just change the value of the “value” attribute in the button element.

Step 2: User logs into TypePad.

If the user does not have an active TypePad session, they will be prompted to login. Once they successfully login to the application they will immediately be taken to the first step in the widget installation wizard.

Step 3: User selects the weblog or weblogs that they wish to add the widget to.

At this step the user can select as many weblogs as they wish to install the widget onto, and they can preview the widget on their live weblog before committing the change by clicking the “Preview” link.

Users are also allowed to change the name of the widget if they prefer another name.

Note to implementers: The values associated with the ‘service_name’ and ‘service_url’ form elements are used to display the text and link “Provided by: Service Name Here.”

Step 4: User completes the process.

From here the user is free to place the widget in a specific location in their sidebar by clicking “Change Content Ordering” which will take them to an easy to use drag-and-drop interface. Users can also view the finished product by clicking the “View Weblog” link.

Note to implementers: The values associated with the ‘service_name’ and ‘return_url’ form elements are used to display the button labeled “Return to Service Name Here.” Clicking this button will then send the user to a landing page of your choosing.

Restrictions

• This mechanism cannot be used to install widgets in weblogs that utilize Advanced Templates or Mixed Media Layouts.

Building Widgets for TypePad

The widget installation process is driven by a single HTML form that is published on a third party’s website. This form contains all the information necessary for TypePad to install a widget on someone’s weblog.

Listed below are the form fields that must be included in this form. See Section N, Widget Design Best Practices below for more information about these fields.

Example Web Form

The following is an example web form utilizing the fields discussed above:

<form action="https://www.typepad.com/t/app/weblog/design/widgets" method="post">
  <input type="hidden" name="service_key" value="YOUR API KEY HERE" />
  <input type="hidden" name="service_name" value="Six Apart" />
  <input type="hidden" name="service_url" value="http://www.sixapart.com/" />
  <input type="hidden" name="long_name" value="I love Six Apart" />
  <input type="hidden" name="short_name" value="i_heart_6a" />
  <input type="hidden" name="content" value=" <img alt=&quot;I Love 6A&quot; 
           src=&quot;http://www.sixapart.com/pronet/i/I-heart-6a-horizontal.gif&quot; 
           width=&quot;150&quot; height=&quot;63&quot; />" />
  <input type="hidden" name="return_url" value="http://www.sixapart.com/" />
  <input type="submit" name="submit" value="Install Widget on TypePad" />
</form>

The HTML form above produces a single button that reads, “Install Widget on TypePad.” At the end of the process, the user will have added the following widget to their TypePad weblog.

Tip:
One requirement for the content submitted to TypePad is that it be properly escaped. However, escaping quote marks, ampersands, and other special characters can be cumbersome. One way to work around this is to encapsulate the content, HTML and javascript you want to post to TypePad in an HTML <textarea> element unescaped. When the form is submitted, the user's browser will escape the content within the textarea automatically! Then all you need to do is hide the textarea field in the browser using CSS (specifically, the "display: none" property). That way the content you are submitting to TypePad is hidden from the user, but is still submitted with the form. For example:

<form action="https://www.typepad.com/t/app/weblog/design/widgets" method="post">
  <input type="hidden" name="service_key" value="YOUR API KEY HERE" />
  <input type="hidden" name="service_name" value="Six Apart" />
  <input type="hidden" name="service_url" value="http://www.sixapart.com/" />
  <input type="hidden" name="long_name" value="I love Six Apart" />
  <input type="hidden" name="short_name" value="i_heart_6a" />
  <textarea name="content" style="display: none">
    <img alt="I Love 6A" 
       src="http://www.sixapart.com/pronet/i/I-heart-6a-horizontal.gif" 
       width="150" height="63" />
  </textarea>
  <input type="hidden" name="return_url" value="http://www.sixapart.com/" />
  <input type="submit" name="submit" value="Install Widget on TypePad" />
</form>

About the Published Widget

All widgets created through this interface will be wrapped in an HTML <div> element automatically by TypePad. This is to ensure that all widgets interoperate with as many browsers as possible, and to provide users with a predictable mechanism for styling widgets via TypePad’s Custom CSS feature.

Below is an example of the HTML TypePad uses when publishing widgets:

  <div id="WidgetShortName-WidgetLongName" class="module-widget module">
    <!-- YOUR WIDGET’S HTML HERE -->
  </div>

Widget Design Best Practices

Design your widgets to scale 100%, but to scale gracefully to a minimum width of 160 pixels. This will ensure the broadest support for your widget across all possible TypePad styles, designs and layouts.

There are no height restrictions for the widgets being installed, but Widget providers should be sensitive to the fact that blog owners may be conflicted in installing a widget that is too tall and therefore displaces too much content on their published blog.

The long_name parameter submitted with your form contains the name of the Widget as it will be displayed within TypePad. In order to maintain the integrity of the TypePad interface it is recommended to keep the length of this field within 50 characters.

For optimal interoperability with TypePad, make sure that the long_name and short_name parameters you provide TypePad consist of only alpha numeric characters (a-Z, A-Z, 0-9).

Frequently Asked Questions

What is the “service key” or “API key” used for?

The service key, or “API key” is a unique identifier assigned to you by Six Apart. It is used to track the creation of widgets within the system as well as for security purposes.

Can I obtain usage statistics on my widget?

The program does not currently support the ability for partners to obtain usage statistics for the widgets they create.

Where does the widget get installed? Can I change the location of the widget on a user’s weblog?

By default, all new widgets are installed at the bottom of the user’s sidebar, or if the user has a three column layout, at the bottom of their right sidebar. Users are free to re-arrange the contents of their sidebars at any time and are given the option to do so at the end of the widget installation wizard. Widget providers are not allowed to change this default behavior.

What is a user permitted to do with the widget once it has been created?

Users are allowed to perform the following actions in regards to the widgets installed via the widget installation wizard:

• Position the widget in their weblog
• Delete the widget from their weblog
• Show/hide the widget in their weblog

Users are not allowed to:

• Edit the content of the widget
• Change the name of the widget

What happens if a user tries to install the same widget twice?

A widget is uniquely identified within a user’s account using the service name and short name of the widget. If a user attempts to create a new widget using the exact same service name and short name of a widget that is already installed, then the older widget’s contents will be replaced using the new widget’s content and widget name.

What happens if the user wishing to create the widget does not have a TypePad account?

Users wishing to use your widget in a weblog are free to create a free trial account on TypePad. A link to register for a new account will be available on the same screen that prompts the user to login to an existing account.

Tip: Have you considered signing up for Six Apart’s Affiliate Program which rewards companies and individuals that refer customers to TypePad and then subsequently sign up for a free trial account.

How do I obtain an API key?

Your API key is provided to you by Six Apart upon successfully registering within the Widget API program. If you ever forget or lose this key, contact Six Apart’s Technical Support team, and they can resend them to you.

Is the TypePad Widget API "open?"

The TypePad Widget API is available to anyone and everyone who is interested. However, in order to ensure the highest standard for quality and security, widgets must go through a brief review process prior to being added to the TypePad Widget Directory.

• Pricing
• Features
• News
• Support
• Widgets