Creating a Basic "Hello World" App

Version 3

    Overview

     

    The main goal of this tutorial is to show you how to use the Jive Apps Command Line Tools (CLT). These tools are all about making app development as easy as possible. After you install the tools, it only takes a single command to:

     

    1. Create a new app - a simple Hello World application.
    2. Set up version control for your code using Git.
    3. Host the app code online at Jive's AppHosting server.
    4. Register the app on the Jive Apps Marketplace as an app "in development".
    5. Install the app on your default app dashboard in the Jive Apps Sandbox.

     

    After you create an app, use this simple workflow to make changes and see them reflected in the sandbox:

    1. Make a change to the code on your local machine.
    2. Commit the changes to your local Git repository.
    3. Push the changes to the remote Jive Apps repository. This automatically updates the hosted copy on the Jive AppHosting server.
    4. Refresh the app dashboard or canvas page on the Jive Apps Sandbox and see your changes.


    Note: At this time, only your app's gadget XML, JavaScript, and CSS files are uploaded to the Jive AppHosting environment. You are responsible for hosting and providing access to the endpoints of the backend service(s) that your application requires.


    Legend

    • This is a step-by-step tutorial. You need to substitute your own values in the various steps below.
    • Text in the comment-style boxes represents commands you will enter.

     

    Installation:


    Follow the installation instructions for your operating system, then return to this tutorial:

     

    If you are behind a firewall, you should also read:


    Now we are ready to start creating apps.


    Step 1: Create your app

     

    1. Choose a short-name for your app.

     

    Think of the app short-name like a domain name. You want it to be easily typed and memorable for a user. When a user is using the canvas view of your app, the short-name will appear in the URL in this format:

     

    http[s]://<jive-instance-hostname>/apps/<app-short-name>

     

     

    • NOTE: This is a one-time decision.  The shortname you choose for your app cannot be changed at a later time.

     

    • If your app has a website with a domain name, you probably want to name your app to match (without the TLD, no periods (.) are allowed). So if you're "netflix.com", you would want your app short-name to be "netflix".

     

    • NOTE: App short-names must adhere to the following conventions:
      • 5-127 characters long
      • all lowercase letters
      • starts with a letter
      • may contain numbers, dashes, or underscores
      • Regex: ^[a-z][a-z0-9-_]{4,126}$

     

    2. Create your app via the command line. For example, if you wanted your app short-name to be "yourapp", you would type:

     

    $ jiveapps create yourapp         # NOTE: Substitute your own app short-name for "yourapp" 

     

    • The first time you run this command, you need to enter your Jive Apps Developer Community credentials.
    • You may also be prompted to accept appshosting.jivesoftware.com as a known host. Type yes and continue.

     

    3. Note your app URLs and OAuth credentials. At the end of the success message, you see the App URL that you'll need to use in Jive to make sure your app shows up:

     

    Congratulations, you have created a new Jive App!
    =================================================
    Git URL:               git@apphosting.jivesoftware.com:yourapp.git
    App URL:               http://apphosting.jivesoftware.com/apps/dev/yourapp/app.xml
    Sandbox Canvas URL:    https://app-sandbox.jivesoftware.com/apps/yourapp

    Sandbox Dashboard URL: https://app-sandbox.jivesoftware.com/apps/dashboards/default-dashboard

    OAuth Consumer Key:    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    OAuth Consumer Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


    4. View the app in the browser. Copy the Sandbox Canvas URL and paste it into your browser. (The following example won't work for you: you should use the URL generated by the command line tool.)

     

    https://app-sandbox.jivesoftware.com/apps/yourapp 

     

    • Log in with the same credentials you used for the Jive Apps Developer Community.
    • The app should now be displayed in the browser.

    Step 2: Make some changes to your app

     

    1. Look at all the parts that an app requires. Back in the console where you first generated your app, run the following commands:

     

    $ cd yourapp
    $ ls           # (or "dir" on Windows)

     

    • You should see app.xml, hello.html, canvas.html, and home.html, as well as directories for images, javascripts, and stylesheets. The app.xml file is the starting point for all the code in your app.

     

    2. Open app.xml in a text editor to see its code:

     

    <?xml version="1.0" encoding="UTF-8"?>
    <Module>

      <ModulePrefs title="your_app_name"

                   description="TODO: Replace with real description of your_app_name inside app.xml: Module/ModulePrefs/description"

                   author="Your Name"

                   author_affiliation="Company Name"

                   author_email="your@email.com"

                   height="300">

     

        <!-- Commonly used features -->

        <Require feature="dynamic-height" />

        <Require feature="jive-core-v3" />

        <Require feature="osapi"/>

        <Require feature="settitle"/>

        <Require feature="views" />

     

        <!-- Additional Options ... -->

      </ModulePrefs>


      <!-- To begin development, remove the hello view and uncomment the embedded and canvas views below -->
      <Content view="embedded,canvas" href="hello.html">
      </Content>

     

      <!--
      <Content view="embedded" href="embedded.html" />
      <Content view="canvas" href="canvas.html" />
      -->


    </Module>

     

    • Here's what the different tags mean:
      • <Module> indicates that this XML file contains an app.
      • <ModulePrefs> contains information about the app and its author.
      • <Require> tags indicate "features" that this app needs in order to work. We include the features you are likely to use in your app by default.
      • <Content view="embedded,canvas" href="hello.html"> indicates a "Proxied Content" page, "hello.html" - an introductory place-holder page which should be displayed for both the "embedded" (!app) and "canvas" views.


    3. Edit app.xml and make a simple change. Delete the placeholder "hello" view and uncomment the seperate "embedded" and "canvas" views. Update the ModulePrefs meta data if you like.

     

    <?xml version="1.0" encoding="UTF-8"?>
    <Module>

      <ModulePrefs title="Your App's Human-Readable Title"

                   description="The real description of your app."

                   author="You or your Company Name"

                   author_affiliation="Company Name"

                   author_email="your_app_support@companyname.com"

                   height="300">

     

        <!-- Commonly used features -->

        <Require feature="dynamic-height" />

        <Require feature="jive-core-v3" />

        <Require feature="osapi"/>

        <Require feature="settitle"/>

        <Require feature="views" />

     

        <!-- Additional options... -->

      </ModulePrefs>

     

      <Content view="embedded" href="embedded.html" />
      <Content view="canvas" href="canvas.html" />


     

    </Module>


    Step 3: Commit your changes and see how it looks

     

    1. Add, commit, and push your changes to the sandbox by running the following commands:

     

    $ git add app.xml
    $ git commit -m 'your commit message here'
    $ git push jiveapps master

    • Note: If you created an SSH key with a passphrase in the prerequisite section, you will need to enter the passphrase when you do the push. If you did not add a passphrase to your SSH key, you will not be prompted.

     

    2. Refresh the page containing your app. You should see your changes. To continue development, open up "embedded.html" and "canvas.html" to customize the layout and content of your embedded and full-screen views.

     

    More Tutorials for the Command Line Tools

    There is additional functionality that you may utilize via the command line tools, such as registering 3rd party OAuth services for your app, adding multiple developers as collaborators, and livedev to speed up development workflow.

     

     

    Having issues? Check the Apps Development FAQ