| <!-- |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| --> |
| <html> |
| <head> |
| <title>OpenSocial Container Sample</title> |
| </head> |
| |
| <body> |
| <h1>OpenSocial Container Sample - Getting started</h1> |
| |
| <ul> |
| <li><a href="#Purpose">Purpose</a> |
| <li><a href="#Theory">Theory</a> |
| <li><a href="#Tips">Tips</a> |
| </ul> |
| |
| <h2 id="Purpose">Purpose</h2> |
| This sample serves two primary purposes: |
| <ol> |
| <li>To demonstrate how a container can be implemented using a simple |
| example. |
| <li>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. |
| </ol> |
| |
| <h2 id="Theory">How it works? (Theory)</h2> |
| As the gadget developer you need to specify two pieces of information: |
| <ol type="a"> |
| <li>URL to the gadget definition; and</li> |
| <li>initial state of the container in the form of a URL to a state file.</li> |
| </ol> |
| |
| 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). |
| |
| <h2 id="Tips">Tips/caveats</h2> |
| <ul> |
| <li>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. |
| <li>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. |
| <li>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 <code>http</code> URL |
| to that server. |
| <li>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. |
| </ul> |
| |
| </body> |
| </html> |
