Understanding how an app works; app.xml, features, and views

Version 2

    Overview

    In this document, we'll explain how a Jive App works. You'll become familiar with how an application is defined via the app.xml file, how capabilities are added to the app, and where you add the HTML, CSS, and JavaScript that you want rendered in Jive. When you created Your First App in 5 Minutes! you either generated or started with a skeleton that serves as the basis for your application. This document will describe how all the pieces come together and explain the relevant parts of the app's definition. After reading this document, you should have a good handle on how to add features to your application and where to plugin your own business logic.

     

    app.xml

    A Jive app is standard based Web component that is defined using an XML file. In Jive, our convention is to name this file app.xml. The app.xml file contains everything necessary for Jive to understand how to render your application within the Jive framework, including its HTML, CSS, and JavaScript. The app definition conforms to the OpenSocial standard, and although we call it an application, it is technically correct to also refer to it as an OpenSocial gadget.

     

    The app.xml file is broken into two different sections; module prefs and content. Module prefs control how your app appears in the market and in Jive, e.g. title, screenshots, icon, as well as the capabilities that Jive will provide to your app. These capabilities are know as features, e.g. dynamic-height. The content section is where you define, ultimately, what HTML will be rendered for you app give a specific view. Here's an example app.xml file.

     

    <?xml version="1.0" encoding="UTF-8"?>
    <Module specificationVersion="1">
      <ModulePrefs title="SugarCRM Sweetness -- An Example App"
                   description="This app shows an exmaple of using What Matters to surface workflow from Sugar CRM"
                   author="Mark Weitzel"
                   author_affiliation="Jive"
                   author_email="mark.weitzel@jivesoftware.com">
        <!-- Commonly used features -->
        <Require feature="dynamic-height" />
        <Require feature="jive-core-v3" />
        <Require feature="osapi"/>
        <Require feature="settitle"/>
        <Require feature="views" />
        <Require feature="opensocial" />
        <Require feature="opensocial-data" />
        <Require feature="setprefs" />
        <Optioanl feature="minimessage" />
        <Optional feature="locked-domain"/>
        <Optional feature="oauthpopup"/>
        <Optional feature="dynamic-width" />
        <Optional feature="embedded-experiences"/>
        <Optional feature="selection"/>
        <Optional feature="open-views"/>
        <Optional feature="firebug-lite"/>
        <Optional feature="actions">
          <Param name="action-contributions">
              <![CDATA[
                 <action id="jiveapps.jw12sweetness" path="jive/actions/content/*" label="Sugar is Sweet" view="embedded" icon="http://apphosting.jivesoftware.com/apps/dev/actest/images/icon16.png" />
                 ]]>
          </Param>
        </Optional>
        <!-- Preloaded Content: http://wiki.opensocial.org/index.php?title=Remote_Data_Requests_%28v0.9%29#Preloading_data -->
        <Preload href = "http://mgmarum.com:8080/osJumpstart/rest/sugar/entries/raw" views="home,canvas"/>
    
        <!-- Icons: 3 sizes, 16x16, 48x48, 128x128 -->
        <Link rel="Icon"       href="images/icon16.png" />
        <Link rel="MediumIcon" href="images/icon48.png" />
        <Link rel="LargeIcon"  href="images/sugarTrophy.png" />
      </ModulePrefs>
      <Content type="html" view="home" href="http://apphosting.jivesoftware.com/apps/dev/jw12sweetness/canvas.html" preferred_height="500" />
      <Content type="html" view="canvas" href="canvas.html" />
      <Content type="html" view="embedded" href="embedded.html" />
    </Module>
    
    
    
    

     

    Understanding Features

    One of the first things to notice is the <Require feature="...."/> and <Optional feature="..."/> tags. These are the capabilities that you are requesting Jive add to your application when it's loaded. These give you the JavaScript APIs that you invoke from your application. Essentially, this is telling Jive to inject the proper JavaScript into your app. Features can be required, meaning your app won't work without them, or optional, meaning you have compensating logic in your app if a feature is not available.

     

    Features come from two different places. This first place they come from is OpenSocial. For example, dynamic-heigh, minimessage, osapi, these are all capabilities that have been standardized in the OpenSocial specification. The second place features come from is Jive. In this case, we've defined several capabilities that complement OpenSocial's features. The most common ones that you will use will be jive-core-v3 and jive-connects-v1.

     

    Understanding Views

    It's possible for one application to have multiple visualizations. For example, you might have a view that is customized for an embedded experience that is used for a specific interaction with your app. For example, the wikipedia app has a view for !App Experiences (it's embedded view) that let's you quickly lookup articles and insert them in Jive content. Views are defined in the <Content ... > tag. At it's most basic, a view has a name and points to a file that simply includes HTML. You can also insert a CDATA tag and embed the content directly in the tag if you like. There are several top level views that are defined by the OpenSocial specification, e.g. canvas, embedded. It's also not uncommon to have child views, e.g. embedded.customerLookup.

     

    A view is called at different times in Jive. Canvas is called when your someone clicks on your app's icon in the quick launcher. The embedded view is called after you insert an app artifact into Jive content. You can also call views programmatically depending on the work flow of your application. As you become more comfortable with views, you'll develop ever more powerful and sophisticated app interactions with your users.

     

     

    How your app is rendered

    When you created your first app, you may have noticed several files, for example, the app.xml, canvas.html, and main.js. We've talked at length about the app.xml. Now, let's understand how it all comes together. When you added your app to Jive, you gave it a URL that pointed to your app's definition that is contained in the app.xml file. Jive does several things with this file. Let's talk through the high level steps that happen when an app is rendered:

    1. First, Jive resolves the app.xml file and starts to process it's contents.
    2. Jive will then look at the set of required and optional features and injects the corresponding JavaScript into the HTML that will be returned.
    3. Jive then retrieves the HTML that is defined in the Content section for the view that is being rendered.
    4. All of this is combined, then returned down to the browser.

    Presto! You have an app that is loaded in the browser!

    apprender.png

    This covers the high level of how and app is built, where you can put your own HTML, and how it ultimately gets rendered on Jive page. There are many interesting and complex things you can do at the time your app is loaded, e.g. dynamically generate HTML, pass in users and friends from Jive, and preload your app with data from external servers. These are covered in other documents in the developer community. Regardless of what you want to do, Jive Apps provides a powerful and flexible framework to get you building successful apps.