Hi Jordan, First thanks you for this interesting faq!
Could you create an issue for this and provides a diff from this: https://svn.apache.org/repos/asf/incubator/shindig/trunk/site/src/site/fml/faq.fml I am willing to apply it. Thanks! Vincent 2009/5/4, Jordan Zimmerman <[email protected]>: > Here is a first pass at a newbie FAQ. There's still lots I'd like to > add, but I thought I'd let the community have a look at this point: > > Shindig Newbie FAQ > v 0.1 > by Jordan Zimmerman > > * Who this FAQ is For > * Someone starting from "square one" with Shindig > * Developers needing to integrate Shinding into their app > * Shindig developers who are at their wits end > > * Shindig is an application not a code library > * Can only be hosted in a Servlet Container that supports WARs > * If you are used to code libraries, take a step back. Shindig is a > > self-contained application. You plug into it to integrate with > your > application. > > * Shindig is, essentially, undocumented > * Shindig does not have a user manual of any kind > * You must search the net for documentation > * Some of the docs are good > * Some are out of date > * See the "Important URLs" section below from some helpful links > > * Important directories: > * <shindig>/java/server/target - maven target for the built Shindig > WAR: > shindig-server-1.1-SNAPSHOT.war > * Main source directories: > <shindig>/java/common/src/main/java > <shindig>/java/gadgets/src/main/java > <shindig>/java/server/src/main/webapp > <shindig>/java/social-api/src/main/java > > * Learn how to use Maven > * Shindig is built via Maven > * In order to integrate with your app, you will need to change > Shindig > files and rebuild Shindig > > * Learn about Guice and dependency injection > * Shindig is built using Google's Guice dependency injection library > * The only way to integrate your own code is via Guice > > * You need to write a Guice module > * In order to integrate with your app, you will need to write a > Guice > Module > * This module needs to be added to Shindig's web.xml list of modules > * Your module _replaces_ SampleModule.java > * Your module will most likely need to copy some of the code in > SampleModule.java > > * You will need to modify web.xml > * Shindig's main web.xml must be modified to add your code > * location: <shindig>/java/server/src/main/webapp/WEB-INF/web.xml > > * Implement PersonService, AppDataService, and ActivityService > * These are the closest things to APIs in Shindig > * These interfaces handle data storage/retrieval for various > OpenSocial > methods > * You need to register your implementations of these interfaces in > your > Guice module > * This doc is not bad: > > http://cwiki.apache.org/SHINDIG/providing-your-own-data-service-implemen > tation.html > > * SecurityToken > * The SecurityToken object is the key to integrating your app with > Shindig > * There are lots of methodologies for doing this > * One option is to register (via your Guice module) an > implementation of > The AuthenticationHandler interface. The important method is > getSecurityTokenFromRequest(). > > * OAuth > * You should read the OAuth spec/docs: http://oauth.net/ > * OAuth is an authentication specification > * For Shindig/OpenSocial, it allows a server to validate OS > makeRequest() calls > * This FAQ does not deal 3-legged OAuth > * To get OAuth working, you only need to implement the OAuthStore > interface and register it via your Guice module > * On your server that handles the makeRequest() method, you can use > the > code from ouath.net to validate the OAuth parameters > * The existing OAuth Shindig docs are confusing. Read them, but > realize > that you need more info than they provide. > > * Container, iframe, Hostnames > * You will read about the "container". Shindig is an OpenSocial > container. However, Shindig has its own concept of a container: a > page > that contains gadgets. Think of an iGoogle page with applets in > it. > The iGoogle page is the container. > * Each gadget is a self-contained <iframe> in the container page. > * For security reasons, the gadget iframe URL should be a hostname > _different_ than the container hostname. This prevents the gadget > from > getting the container's cookies, DOM, etc. > * A lot of Shindig docs assume that your container is written in > pure > Javascript. However this is not a requirement. > > * Container Responsibilities > * TBD > > * Important URLs: > * http://incubator.apache.org/shindig/ > * http://cwiki.apache.org/SHINDIG/index.html > * > http://cwiki.apache.org/SHINDIGxSITE/how-to-support-features-that-depend > -on-gadgetsrpc.html > * http://incubator.apache.org/shindig/mail-lists.html (subscribe to > these listservs) > * http://code.google.com/p/mediated-opensocial/ - this is how this > FAQ > writer integrated Shindig > > > > > Jordan Zimmerman > Principal Software Architect > 831.647.4712 > 831.214.2990 (cell) > [email protected] > > SHOP*COMTM > Shop Smart, Save Big(tm) > www.shop.com > > This message (including any attachments) is intended only for > the use of the individual or entity to which it is addressed and > may contain information that is non-public, proprietary, > privileged, confidential, and exempt from disclosure under > applicable law or may constitute as attorney work product. > If you are not the intended recipient, you are hereby notified > that any use, dissemination, distribution, or copying of this > communication is strictly prohibited. If you have received this > communication in error, notify us immediately by telephone and > (i) destroy this message if a facsimile or (ii) delete this > message > immediately if this is an electronic communication. > > Thank you. >
