# OpenSocial Container Sample - Getting started

- Purpose
- Theory
- Tips

## Purpose

This sample serves two primary purposes:

1. To demonstrate how a container can be implemented using a simple example.
2. To create an environment for easy gadget testing. OpenSocial is all about social APIs, which means that gadget testing usually involves multiple user accounts. This container makes testing easy by letting gadgets specify arbitrary state for any number of users.

## How it works? (Theory)

As the gadget developer you need to specify two pieces of information:

1. URL to the gadget definition; and
2. initial state of the container in the form of a URL to a state file.

You can find the DTD for the state definition in the docs/state.dtd folder. The state definition file allows you to specify the viewer of the gadget, the owner, the friends and the activities of those users. Once the gadget and its state are loaded you can use the gadget in the same way as any other container. At any point you can also dump a snap shot of the state of the environment to an XML file (with the same format as the state definition file).

## Tips/caveats

- Due to browser security restrictions, your gadget definition file and system state file must be on the same server as the container if you specify a url. The above step by step procedure runs the test container from the local file system. You can also copy the files to a web server and run off it instead.
- The gadget definition URL is stored in a cookie. You can set the values to empty or clear your cookies to clear existing values for those fields.
- For easier debugging of your gadget script in Firebug, include the gadget script using a script tag in the gadget definition file, instead of inlining the script. Sometimes Firebug still cannot display the gadget javascript if it is on the local file system. To avoid this, you can untar the package to a web server and access it through an `http` URL to that server.
- You always need to specify a state file for the container. At a minimum it must include the viewer name. All other fields are optional.