By continuing to use this site, you agree to the storing of first- and third-party cookies on your device to enhance site navigation; analyze site, product, and service usage; and assist in our marketing and promotional efforts. Cookie Policy

 
Skip to Content

Custom Gadgets

In addition to the gadgets provided by OmniUpdate, you can create and add custom gadgets to your account. A gadget is any standard web application loaded into the OU Campus interface as an <iframe>. Through the use of our JavaScript library and the OU Campus API, gadgets can interact with and extend the functionality of the OU Campus. Gadgets typically utilize HTML, CSS, and JavaScript, and access functionality provided by the OU Campus API. Once created, gadgets are added to the account from Setup > Gadgets.

Gadget files can be edited and deployed anywhere, including from within OU Campus, as long as they exist on a published web server. A gadget has three requirements:

  • An https URL accessible to any user who uses the gadget.
  • A configuration file named config.xml which must be in the root folder of the gadget.
  • An HTML web page with source code and styling for the gadget.

Basic Steps for Creating a Gadget In OU CampusLink to this section

You can download both a sample gadget and a starter gadget to jumpstart your own gadget development. OmniUpdate also provides a JavaScript library (gadgetlib.js) that can be used 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.

  1. Download our starter gadget and use zip import to upload it into OU Campus.
  2. In a folder in your site, create two files: config.xml and index.html.
  3. Check out config.xml and edit the source code.
  4. 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>
  5. Save and close the file.
  6. Open index.html and edit it, entering your gadget content inside the <div id="main"> element.
  7. Save and publish the file.

Working with the OU Campus APILink to this section

OU Campus offers a REST API that accepts an HTTP request and returns JSON data. All API requests are made to protocol://<server host>/<api endpoint> (e.g., https://a.cms.omniupdate.com/users/list). Comprehensive API documentation is available at developers.omniupdate.com.

Calls to the OU Campus API must be authenticated using a gadget token. Gadget developers can use gadgetlib.js to obtain the token when the gadget first loads.

gadget.ready().then(function () {
var APITOKEN = gadget.get('token');

// Code that uses the token goes here
});

This API token represents the user's authenticated session, and therefore provides access only to OU Campus functionality that the user has permission to access.

When calling the OU Campus API, this token should be passed as a query string parameter called authorization_token. Note that both GET and POST API requests expect the authorization token as a query string parameter.

gadget.ready().then(function () {
var API_TOKEN = gadget.get('token'); // the authorization token
var API_HOST = gadget.get('apihost'); // the API server host

// Example GET request to /files/list 
$.ajax(API_HOST + '/files/list?authorization_token=' + API_TOKEN + '&site=' + gadget.get('site'));

// Example POST request to /files/new_folder
$.ajax(API_HOST + '/files/new_folder?authorization_token=' + API_TOKEN,
{
method: 'POST',
data: {
name: 'foo',
site: gadget.get('site'),
path: '/'
}
});
});

Registering a Gadget to Receive EventsLink to this section

Gadgets can register to receive push events when certain operations are triggered outside of the gadget window.

Event NameTrigger
expandedThe gadget is expanded in the sidebar.
collapsedThe gadget is collapsed in the sidebar.
configurationThe user navigates to a different view.
view_changedThe user navigates to a different view.
notification

One of the below notification types are triggered. Note that the config.xml must have the appropriate notifications entry in order to receive these notifications.

Event NameTrigger
activityPage actions (publish, copy, move, revert), user created, group created
copyPage copied
generalPage recycled
linkcheckLink check finished
messageInbox message received, workflow message received
movePage moved
params-savePage parameters saved
publishAfter a page is published or a published page is renamed or moved
renamePage renamed
revertAfter site revert
scanAfter site or folder scan has completed
uploadedFile uploaded
workflowWorkflow request received
wysiwyg-selectionContent selection occurs in the WYSIWYG (Classic WYSIWYG/JustEdit)
zipimportZip file uploaded

Example: Upload Notifications

To register your gadget to receive file upload notifications, add the following to the gadget's config.xml:

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

Next, implement the event handler within your gadget code:

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

The resulting notification contains a data object which in turn 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 describes the error. If the code property is not present, then data contains one or more properties (success, warning, 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 receives 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.

Additional ResourcesLink to this section