features/README

                          Apache Shindig Features

  What is it?
  -----------

  Shindig is a JavaScript container and implementations of the backend APIs
  and proxy required for hosting OpenSocial applications.

  This is the features component of Shindig.

  Documentation
  -------------

  The most up-to-date documentation can be found at http://shindig.apache.org

  Using features
  --------------

  You can automatically include new features into your shindig server by adding
  them to this directory. Features should exist in a self-contained directory
  with the following structure:

  features
    |_your-feature-name
     |_feature.xml
     |_code-to-run-inside-gadget.js
     |_code-to-run-inside-container.js

  The structure of feature.xml is as follows:
  TODO: link to xml schema for feature.xml

  <?xml version="1.0"?>
  <feature>
    <name>your-feature-name (required)</name>
    <dependency>any dependency you have (optional, may have multiple)</dependency>
    <gadget> (optional)
      <script src="code-to-run-inside-gadget.js"/> (optional, may have multiple,
          may use web resources as well but we strongly encourage bundling your
          javascript with the xml)
    </gadget>
    <container> (optional)
      <script src="code-to-run-inside-container.js"> (same as for <gadget>)
    </container>
    <all> (optional, to mean for both gadget and container)
      <script src="code-to-run-inside-either-gadget-or-container.js"> (same as for <gadget> or <container>)
      <api>
          optional, to export API in compiled JS for external usages and incremental-loading,
          via ExportJsProcessor.java and exportJs JS.
        <exports type="js">gadgets.rpc.call</exports>
            optional, the API to export, for two scenarios:
            1. the JS code internally can use obfuscated/property-renamed g.r.c() to reduce
               size, but external clients continue to use unobfuscated (exported-to-window)
               gadgets.rpc.call.
            2. incremental-loading of JS. rpc.js is loaded (gadgets.rpc.* is exported). Then,
               dynamic-height!rpc.js can be loaded without rpc (and its transitive dependencies)
               and it will use unobfuscated (or extern'ed) gadgets.rpc.
      </api>
    </all>
  </feature>

  Please always make sure that all files you provide are encoded as utf8.

  When adding new features, your javascript should conform to shindig javascript
  coding conventions. This means that you should not be producing new globals and
  your feature should be compatible with Caja.

  When committing a new feature, you should update the features.txt file by
  running the following script in a unix-like environment:

  ls -R1a features/**/*.xml > features/features.txt

  TODO: Instructions for regenerating features.txt for other operating system
  environments.

  Licensing
  ---------

  Please see the file called LICENSE.


  Shindig URLS
  ------------

  Home Page:          http://shindig.apache.org/
  Downloads:          http://shindig.apache.org/download/index.html
  Mailing Lists:      http://shindig.apache.org/mail-lists.html
  Source Code:        http://svn.apache.org/repos/asf/shindig
  Issue Tracking:     https://issues.apache.org/jira/browse/SHINDIG
  Wiki:               http://cwiki.apache.org/confluence/display/SHINDIG/