Custom Gadgets

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

Gadget files can be edited and deployed anywhere, including from within Modern Campus CMS, 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 Modern Campus CMSLink to this section

You can download both a sample gadget and a starter gadget to jump-start your own gadget development. Modern Campus also provides a JavaScript library (gadgetlib.js) that can be used to make writing client-side API calls to Modern Campus CMS easier, and to easily obtain the gadget's properties that are stored in the Modern Campus CMS database.

1. Download our starter gadget and use zip import to upload it into Modern Campus CMS.
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.moderncampus.com/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 Modern Campus CMS APILink to this section

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

Calls to the Modern Campus CMS 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 Modern Campus CMS functionality that the user has permission to access.

When calling the Modern Campus CMS 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.

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

• How to Build Gadgets (PDF)
• Modern Campus CMS API Documentation
• Starter Gadget