Allowing for WSKey configuration on Installation

In order to allow institutions to share applications, developers should write their gadgets to allow the configuration of API keys (WSKeys) during installation. This is done by using AppData to store and manage institution API keys.

Below is a sample gadget which demonstrates how to configure allow the configuration of API keys on installation.

<?xml version="1.0" encoding="UTF-8"?>
<Module>
  <ModulePrefs title="AppData Gadget">
    <Require feature="opensocial-1.0"/>
	<Require feature="security-token"/>
	<Require feature="osapi"/>
    <Require feature="views" />
    <Require feature="org.jquery.core-1.4.2"/>
</ModulePrefs>
  <Content type="html" view="default,config,main">
	<![CDATA[
	<style>
        html, body, select, input, button, option, textarea {
            font-family: Arial,"Arial Unicode MS",Helvetica,Clean,sans-serif;
        }
        h1 { font-size: 110%; }
	 </style>
	 <script type='text/javascript'>
        var example = {};

        example.getAppdataForInstitution = function(callback) {
            osapi.appdata.get({
                userId: '@me',
                groupId : '@institution',
                appId : '@app'} )
            .execute(function(response) {
                var keys = Object.keys(response);
                if( keys.length > 0 ) {
                    callback.call(null, response[keys[0]]);
                } else {
                    callback.call(null, response);
                }
            });
        }

        example.navigateToConfigView = function() {
            osapi.permissions.hasPermission({
                permission: 'CAN_INSTALL_GADGET'
            }).execute(function(response) {
                gadgets.log('CAN_INSTALL_GADGET: ' + gadgets.json.stringify(response));
                if( response ) {
                    gadgets.views.requestNavigateTo('config');
                } else {
                    gadgets.views.requestNavigateTo('config-no-permissions');
                }
            });


        }

        example.navigateToMainView = function() {
            gadgets.views.requestNavigateTo('main');
        }

	 </script>
	]]>
  </Content>

    <Content view="default" type="html">
    <![CDATA[
    <script type="text/javascript">

        var example = example || {};
        example.onLoad = function() {
            example.getAppdataForInstitution(function(data) {
                if( data.wskey ) {
                    example.navigateToMainView();
                } else {
                    example.navigateToConfigView();
                }

            });
        };

        gadgets.util.registerOnLoadHandler(example.onLoad);
    </script>
    ]]>
    </Content>


     <Content view="main" type="html">
    <![CDATA[
        <h1>Hello to the AppData example!</h1>
        <p>This gadget shows examples of persisting appdata for an institution.</p>
        <div class='label'>Your institution's WSKey: <span id='current-wskey'></span></div>

        <script type='text/javascript'>
        /**
         * Display the latest appdata values next to the form fields.
         */
        example.displayAppDataValues = function() {
            example.getAppdataForInstitution(function(data) {
                var value = data ? data.wskey : "No value set";
                 $('#current-wskey').html(value);
            });
        };
        gadgets.util.registerOnLoadHandler(example.displayAppDataValues);
        </script>
    ]]>
    </Content>


    <Content view="config" type="html">
    <![CDATA[
    <h1>Configure your wskey</h1>
     <div>
        <div class='label'>Enter your institution's WSKey:</div>
        <div><input type='text' id='wskey' name='wskey' /></div>
    </div>
    <button id='save-btn'>Save</button>

    <script type='text/javascript'>
        /**
         * onclick event handler for the save button
         */
        example.saveButtonOnClick = function(event) {
            var wskey = $('#wskey').val();
            osapi.appdata.update({
                userId: '@me',
                groupId : '@institution',
                appId : '@app',
                data : {'wskey' : wskey}} )
            .execute(function(response) {
                example.navigateToMainView();
            });
        };

        gadgets.util.registerOnLoadHandler( function() {
            example.getAppdataForInstitution(function(data) {
                var value = data ? data.wskey : "No value set";
                 $('#wskey').val(value);
            });
        });

       /**
        * Register click event handler on the save button.
        */
        gadgets.util.registerOnLoadHandler(function() {
           $("#save-btn").click(example.saveButtonOnClick);
        });
        $('#wskey').focus();

    </script>
    ]]>
    </Content>

    <Content view="config-no-permissions">
        <![CDATA[
        <h1>Access denied</h1>
        <p>Please contact your institution's administrator to configure your institution's wskey.</p>
        ]]>
    </Content>

</Module>