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="firstname.lastname@example.org"> <!-- 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>
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.
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:
- First, Jive resolves the app.xml file and starts to process it's contents.
- Jive then retrieves the HTML that is defined in the Content section for the view that is being rendered.
- All of this is combined, then returned down to the browser.
Presto! You have an app that is loaded in the browser!
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.