What is Shindig?

Shindig is a new project in the Apache Software Foundation incubator and is an open source implementation of the OpenSocial specification and gadgets specification.

The architectural components of Shindig can be broken down as follows:

• Gadget Container JavaScript -- core JavaScript foundation for general gadget functionality. This JavaScript manages security, communication, UI layout, and feature extensions, such as the OpenSocial API.
• Gadget Server -- used to render the gadget XML into JavaScript and HTML for the container to expose via the container JavaScript.
• OpenSocial Container JavaScript -- JavaScript environment that sits on top of the Gadget Container JavaScript and provides OpenSocial specific functionality (profiles, friends, activities, datastore).
• OpenSocial Data Server -- an implementation of the server interface to container-specific information, including the OpenSocial REST APIs, with clear extension points so others can connect it to their own backends.

Downloading periodic builds of Shindig

We currently do not have an automated builds infrastructure set up to offer periodic builds yet, but hope to have it available soon. Check back here in the near future for downloadable builds of Shindig.

In the meantime, please visit the Building Shindig tab for instructions on using the code in the repository.

Building and running Shindig

There are both Java and PHP versions available, the following steps provide useful information on how to build and run Shindig.

Java

• Building and running Shindig (Java)
• Prequisites
• Get the code
• Build and run the code (with Maven)
• Setting up an Eclipse project
• Running with Caja

PHP

• Building and running Shindig (PHP)
• Prequisites
• Get the code
• Running Shindig
• Additonal reading

Building and running Shindig (Java)

Prequisites before building Shindig

In order to build Shindig, you must have the following:

• Java (JDK/JRE) 1.5 or later installed on your system and the JAVA_HOME environment variable set.
  • See: http://java.sun.com/ for installation instructions.
• A Subversion client installed in order to checkout the code.
  • Instructions for downloading and installing Subversion can be found here: http://subversion.tigris.org/
• Apache Maven installed to perform the build.
  • Instructions for downloading and installing Maven can be found here: http://maven.apache.org/download.html

Getting the code

Create a subdirectory and checkout the Shindig code from its Subversion repository

1. mkdir ~/src/shindig (or wherever you'd like to put it)
2. cd ~/src/shindig
3. svn co http://svn.apache.org/repos/asf/incubator/shindig/trunk/ .

Building and running the code (with Maven)

To build a Web Archive (WAR) file for the Gadget server and run tests, perform the following:

1. Make sure you have the prerequisites installed first.
2. cd ~/src/shindig/
3. mvn
4. Once the build successfully completes, you can install the built WAR files located in the /target subdirectory onto your JEE server.

To run the code and start a Jetty server that will run on at localhost:8080:

• mvn -Prun

To run the Jetty server on a different port, use:

• cd java/server
• mvn clean install jetty:run -DrunType=<full|gadgets|social> -Djetty.port=<port>

Once you've either installed the WAR file on your JEE server, or are running locally using the Jetty server, you can test the Gadget server using:

• http://localhost:<port>/gadgets/ifr?url=http://www.labpixies.com/campaigns/todo/todo.xml

Setting up an Eclipse project to build Shindig

These steps, after completing the previous section, will allow you to build from within Eclipse using the Maven2 plugin. You should first install the Maven plugin, then create the new Java project.

• Create ~/.m2/settings.xml consisting solely of

<settings>
</settings>

• Install the Maven2 plugin
  1. Help -> Software Updates -> Find and Install
  2. Search for new features to install
  3. Create a new remote update site for the Maven 2 plugin
     • Name: Maven2 - Sonatype
     • URL: http://m2eclipse.sonatype.org/update/
  4. Select the site and click "Finish"
  5. There are optional dependencies on mylyn and subclipse. If you don't have these plugins, you can get them here. Otherwise, select only the Maven Integration plug-in.
  6. Complete the installation

• Setup new workspace and project
  Creating a new workspace eliminates the performance cost from existing projects and makes it easier to manage the code.
  1. File -> Switch Workspace -> Other...
  2. Select directory to store workspace
     • Do not select a parent directory of the shindig source (e.g. ~/src/shindig) as Eclipse won't allow you to create the Java project.
     • Something like ~/eclipse/workspaces/shindig would work fine
  3. File -> New -> Java Project
     1. Name the project. The instructions below will assume "SHINDIG".
     2. Select 'Create project from existing source' and navigate to .../src/shindig/java
     3. Click Finish
     4. If you see a dialog for "Open Associated Perspective", click Ok. Don't worry about the errors after loading as they will be fixed in the next step.
  4. Right-click the project, select Maven : Enable Dependency Management
  5. Right-click the project, select Maven : Enable Nested Modules
  6. Right-click the project, select Maven : Update Source Folders
  7. Optionally, if you would like to be able to browse or step into the code of your dependent jars when debugging, you need the source jars. Right-click the project, select Maven : Download Sources and Eclipse will automatically know about these sources when debugging. You can browse them under Maven Dependencies in your project.
  8. If you'll be using AllTests to run tests or generate code coverage stats, adjust the project's output folders.
     1. Project -> Properties -> Java Build Path -> Source
     2. Locate and open SHINDIG/gadgets/src/test/java
     3. Select Output Folder: (Default Output Folder) and click Edit...
     4. Select Specific Output Folder
     5. Enter target/test-classes and click OK.
     6. Repeat for SHINDIG/social-api/src/test/java

Generating Code Coverage in Eclipse

To generate code coverage statistics inside of Eclipse, install the EclEmma plugin. Then

• Open org.apache.shindig.gadgets.AllTests
• Right-click in the class, and select Coverage as -> JUnit Test

Running inside Eclipse

To debug the server in Eclipse, follow the last two steps here (takes a few minutes to set up):

• "Using eclipse external tools"
• "Attaching to the server running in debug mode, using eclipse"

Note: You must have set up Eclipse to build the code or do mvn package yourself after making changes, but you won't need to restart Jetty to see your changes.

Running with Caja

Caja is an important part of OpenSocial that greatly enhances JavaScript security. Caja is managed in a separate open source project hosted by Google code projects. For more information on Caja, see: http://code.google.com/p/google-caja/wiki/CajaEasyIntro

1. Load this page: http://localhost:8080/gadgets/files/samplecontainer/samplecontainer.html
2. Point it to this gadget: http://localhost:8080/gadgets/files/samplecontainer/examples/SocialHelloWorld.xml

To see the cajoled code (Firefox only), right-click inside the iframe and do "This Frame -> View Frame Source"

Additional reading

Read java/README for original instructions on how to start up any of the java shindig servers.

Read javascript/README for instructions for using the Shindig Gadget Container JavaScript to enable your page to render Gadgets.

Building and running Shindig PHP server

Prequisites before building Shindig for PHP

In order to build and run Shindig for PHP, you must have the following:

• A Subversion client installed in order to checkout the code.
• Instructions for downloading and installing Subversion can be found here: http://subversion.tigris.org/
• Apache with mod_rewrite enabled.
• PHP 5.2.x with the json, simplexml, mcrypt and curl extentions enabled.

Getting the code

Create a subdirectory in your web document root, e.g. /var/www/html and checkout the Shindig code from its Subversion repository

1. mkdir /var/www/html/shindig
2. cd /var/www/html/shindig
3. svn co http://svn.apache.org/repos/asf/incubator/shindig/trunk/ .

Running Shindig

With PHP There is no need to build anything - the source code is already built.

To run the code, you have several options:

a. Create a new virtual host

Point your apache to the php dir with a virtual host like:

		<VirtualHost your_ip:your_port>
	
		       ServerName your.host
		       DocumentRoot /var/www/html/shindig/php
		       ... other normal settings in vhosts...
		</VirtualHost>
	  

Restart apache, and point your browser to:

http://your.host/gadgets/ifr?url=http://www.labpixies.com/campaigns/todo/todo.xml

you should see something like this.

b. Run with an existing host

If you cannot/don't want to create a virtual host, you can edit the file php/config.php and change the web_prefix setting to '/shindig/php'.

Then you can run the gadget by pointing your browser to:

http://your.host/shindig/php/gadgets/ifr?url=http://www.labpixies.com/campaigns/todo/todo.xml

Additional reading

Read php/README for original instructions on how to start up the php shindig server.

Read javascript/README for instructions for using the Shindig Gadget Container JavaScript to enable your page to render Gadgets.

How to contribute to Shindig

Shindig is strengthened by accepting quality contributions from a wide variety of sources. These steps serve as an in-progress guide to contributing code into the source code repository for Shindig.

• Code submissions
  • Creating patches
  • Submitting Patches

Code Submissions

Creating Patches

For new people to the project, creating patches is the way to get started and build your reputation.

1. Start editing the code, since Subversion is being used no checkout is needed
2. Move to top level folder, e.g. cd ~/src/shindig
3. Generate diffs using svn di > fix-xxx-bug.patch
4. If needed, remove from the patch file any changes you do not want to submit until later
5. If you're new, create an account on https://issues.apache.org/jira/browse/SHINDIG
6. Create a new issue with the patch:
   1. Follow the "New" link: https://issues.apache.org/jira/secure/CreateIssue!default.jspa
   2. For the "Issue Type", select "Bug", "Improvement" or "New Feature"
   3. Click "Next>>"
   4. Enter summary / description and select the component
      
   5. Click "Create"
   6. Click "Attach file" and select the mychanges.patch file
   7. Check the "Grant license to ASF for inclusion in ASF works" option
   8. Click on "Watching" and then click on "Start" watching to get updates

The newly created issue will automatically be sent to shindig-dev@incubator.apache.org. You should also subscribe using shindig-dev-subscribe@incubator.apache.org to see all the feedback, in which case you'll get the updates on the issue without needing to "Watch" them individually.

Submitting Patches

If you have commit permission, then you can submit directly from subversion and should also look at patches provided by others.

1. Move to top level folder, e.g. cd ~/src/shindig (you might find it helpful to create a separate tree from your working tree)
2. Apply patch: patch p0 < mychanges.patch
3. svn commit
4. For the log message put Applied patch for JIRA issue SHINDIG-XXX, where XXX is the JIRA issue number you are applying the patch for. This will automatically update the JIRA issue with a link to the subversion commit. You don't need additional comments as the JIRA issue should contain enough information already.

Example

• JIRA Issue with patch: http://issues.apache.org/jira/browse/SHINDIG-13
• Code Change: http://svn.apache.org/viewvc?view=rev&revision=612299

Mailing List

• To subscribe to the Shindig mailing list, send a blank email to shindig-dev-subscribe@incubator.apache.org
• The email archives are located at:
  • http://mail-archives.apache.org/mod_mbox/incubator-shindig-dev/
  • http://shindig-dev.markmail.org/

Issue Tracker (using JIRA)

To file bugs or feature requests, please use Shindig's issue tracker (JIRA):

1. Login to the issue tracker (top right corner) or follow the instructions to make a new account (anyone can make an account).
2. Once logged in you should be able to see all of Shindig's open issues.
3. If the issue has not been filed, use the "Create a new issue" link (this will not be shown if you are not logged in).