Creating Gadgets

Overview

Out of the box, there are fifteen gadgets built into the system. Developers can make use of the OU Campus web Application Programming Interface (API) to write institution-specific gadgets that make use of functionality provided by the API. Gadgets typically utilize XML, HTML, CSS, and JavaScript.

Gadgets Chart

There are really only two requirements for a gadget. One is that it must have a web page/address that can be reached at a real URL — one that starts with http:// (or https://) and ends with a slash. It doesn't necessarily have to be a static HTML file, as it can be a generated web page such as when using PHP. This web address for the gadget must be accessible to the OU Campus users for whom the gadget is intended.

The second requirement is that it has to have a configuration file named config.xml, which must be in the root directory of the gadget. The config.xml file contains key/value pairs for various attributes that describe the gadget to OU Campus and, optionally, create persistent variables for the gadget's own use. For example:

<entry key="title">My First Gadget</entry>

In this case, the value of "title" is "My First Gadget" and this is what the user will see in the gadget's title bar.

Existing client-side gadgets make use of JavaScript, various JavaScript libraries, JSON for data exchange, and Bootstrap for styling. OmniUpdate provides a JavaScript library that can be uses to make writing client-side API calls to OU Campus easier, and to easily obtain the gadget's properties that are stored in the OU Campus database.

The foundation of a gadget is in its index.html file (or the server-side script that acts as this file). A CSS stylesheet can be linked to, or styling can be added with a <style> tag in the head. Same with the scripts, as a JavaScript file can be called with the <script> tag. For example:

<script type="text/javascript" src="../lib/gadgetlib.js"></script>

Or the JavaScript can be added to the page within a <script> tag.

After the developer has written the gadget, the gadget files are added to the system by an administrator from Setup > Gadgets > New.

For complete instructions to add a gadget to the system, visit the New Gadget page.

Basic Steps for Creating a Gadget

  1. In a folder in your site, start off with two files: config.xml and index.html.
  2. Check out config.xml and edit the source code.
  3. Start with the following code:
    <config>
           <entry key=”types” private=”true”>dashboard</entry>
           <entry key=”title”>My First Gadget</entry>
           <entry key=”icon” private=”true”> http://support.omniupdate.com/oucampus10/images/icons/cog2.png </entry>
    </config>
  4. Save the file.
  5. Open index.html for editing. Make sure to enter content inside the <div id=”main”> element.
  6. Save and Publish the File.

For more detailed instructions, here is a recorded Training Tuesday session about creating custom gadgets:

http://ousupport.s3.amazonaws.com/training-tuesdays/2014/2014-09-30-building-custom-gadgets.mp4

Registering a Gadget for Files Upload

To register for file upload notifications within your gadget, you must add the following entry to the gadget's config.xml:

<entry key="notifications" private="true">upload</entry>

Next, you must implement the event handler within your gadget code:

$(gadget).on({
    // ...
    'upload': function(evt, notification) {
        console.log('Upload results',notification);
    }
});

The resulting notification will contain a data object which contains the key that represents which upload request the notification is for, and detailed results of the operation. If the operation resulted in an exception, the data object contains a code property and an error string that will describe the error. If the code property is not present, then data will contain one or more properties (successwarning, and error), each containing arrays of strings detailing the result for each file in the upload request.

Note: Once you register your gadget to receive upload notifications, it will receive notifications for all uploads -- whether initiated from the gadget or not. To ensure that you are processing the correct notification, you must compare the key value in the notification with the key that was returned in your original upload request.

Final Notes

An error message displays for non-HTTPS gadgets if the user navigates into any HTTPS view in OU Campus.