API Reference

• APIs for the Javascript tab
  • Endpoints
  • $scope.portalHelpers object
  • favourites Service
  • calendar Service
• APIs for the Server Script tab
  • console.log()
  • privateDataService
  • db object
  • proxy object
  • user object
  • args object

Other Documents

• Portal SDK Document
• HTML Directives
• Portal App Development
• Server API List

APIs for the Javascript tab

You can use the following APIs to develop the controller of your widget. Refer to the documentation of AngularJS for more information on controllers.

Endpoints

You can use endpoints to access external data sources and student information.

Note: For sensitive transactions, use the proxy object in Server Scripts instead.

/Develop/PostProxy

Sends a POST request to an endpoint and returns a string response from the endpoint.

• values - an optional { key : value, … } object that serves as POST parameters.
• url - URL endpoint.
• config - an optional { headers: { key:value, ... } } object that contains the headers of the request.

Note: Ensure the domain is whitelisted by Portal staff before using this function. To see available domains press "External Sources" on the top menu of the SDK.

Example:

$http.post( "/Develop/PostProxy", { values : postParams, url : "https://yourURL.com"}).success(function(response) {
     // Code to run on success 
});

Use the config parameter to update the header of the request. Example:

var requestConfig = { 
    headers: [
        { header1:value1 },
        { header2:value2 }
    ]
};
$http.post( "/Develop/PostProxy", { values : postParams, url : "https://yourURL.com"}, config : requestConfig).success(function(response) {
     // Code to run on success 
});

/Develop/GetProxy

Sends a GET request to an endpoint and returns a string response from the endpoint.

Note: Ensure the domain is whitelisted by Portal staff before using this function. To see available domains press "External Sources" on the top menu of the SDK.

Example:

$http.get('/Develop/GetProxy?url=yourUrl).success(function(data){
    // Code to run on success 
});

Use the config parameter to update the header of the request. Example:

var requestConfig = { 
    headers: [
        { header1:value1 },
        { header2:value2 }
    ]
};
var configString = encodeURIComponent(JSON.stringify(requestConfig ));
$http.get('/Develop/GetProxy?url=yourUrl&config=' + configString ).success(function(data){
    // Code to run on success 
});

$scope.portalHelpers object

Use this object to perform common tasks within Portal.

$scope.portalHelpers.invokeServerFunction

Invokes a function on the server that was defined previously inside the Server Script window.

$scope.portalHelpers.invokeServerFunction(functionName, args);

• functionName - name of the function to be invoked in the server script
• args - arguments to pass to the function. These can be accessed using args.Get("ArgName") within the Server Script. See the Server Script section for more details.
• Returns - angular promise object (see angularJS documentation for $q)

$scope.portalHelpers.invokeServerFunction('getDataFromDB', {id : 2, member : 32 }).then(function(data){
     // Code to run after execution completes 
});

$scope.portalHelpers.toggleLoading

Shows loading animation in the upper section of a widget. Use this to indicate that widget is busy processing information.

$scope.portalHelpers.toggleLoading(Boolean show);

• show - a boolean value to indicate whether to show the animation.

$scope.portalHelpers.showView

Shows a view inside a column.

$scope.portalHelpers.showView(string viewName, integer column, Boolean appendHistory);

• viewName - the name of the view to show (specified in the "id" parameter of the template script tag inside the HTML view)
• column - an integer value from 1 to 3 corresponding to the column in which to show the view
• appendHistory - whether to append this state change to browser history (default is true)

In HTML:

<script type= "text/ng-template" id= "details.html" > … </script>

In JavaScript:

$scope.portalHelpers.showView("details.html", 2);

$scope.portalHelpers.closeLastView

Closes last opened view.

$scope.portalHelpers.closeLastView();

$scope.portalHelpers.importJsLib

Imports JS libraries into your widget.

Note: To see available JS libraries and to make requests for new ones, press "JS Libraries" button on the top menu of the SDK. Use "Insert" button while in JS editing mode to insert a code snippet.

$scope.portalHelpers.importJsLib(array libNames);

• libNames - an array of library names to import
• Returns - angular promise object (see angularJS documentation for $q)

Example:

$scope.portalHelpers.importJsLib(["Raphael 2.1.3"]).then(function(){ 
    …
});

$scope.portalHelpers.getApiData

Sends a get request to a specified portal server API.

$scope.portalHelpers.getApiData(string url);

• url - the URL of the portal server API.

Example:

Refer to the Server API List for examples.

$scope.portalHelpers.postApiData

Sends a get request to a specified portal server API.

$scope.portalHelpers.postApiData(string url, object payload);

• url - the URL of the portal server API.
• playload - the data payload of the post request.

Example:

Refer to the Server API List for examples.

favourites Service

Use this service to manage favourited items in your widget. You can inject this service to your controller to use it.

.controller('myCtrl', ['$scope', '$filter', '$http', '$q', 'myFactory', 'favouritesService', 'calendarService', 
    function ( $scope, $filter, $http, $q, myFactory, favouritesService, calendarService) {
        ...
    }

Then, you can add the service to the scope.

$scope.favService = favouritesService;

register

Register your widget with the service. This function enables the service to start pulling in favourites for this widget and configures the service to be specific to this widget.

favouritesService.register(uniqueNameId, list, idField);

• uniqueNameId - specify the unique name of the widget. e.g. "athletics".
• list - specify a list of items that you want to add to the service.
• idField - specify the id field of the list. e.g. 'title'.

sync

Synchronize the local favorite settings with the Portal server.

favouritesService.sync();

Example:

favouritesService.sync().then(function() {
    console.log("Data synced:" , $scope.data);
});

toggle

Toggles the favorite status of an item.

favouritesService.toggle(key);

• key - specify the id of the item whose favorite status you want to toggle. Example:

$scope.toggleFav = function(val) {
    // toggle(val) function will save or delete the entry from the database
    $scope.favService.toggle(val);
}

calendar Service

Use this service to interact with Portal calendar. You can inject this service to your controller to use it.

.controller ('myCtrl', ['$scope', '$filter', '$http', '$q', 'myFactory', 'favouritesService', 'calendarService',
    function ($scope, $filter, $http, $q, myFactory, favouritesService, calendarService) {
        ...
    }

register

Register your widget with the service and retrieve calendar events of the widget.

calendarService.register(uniqueNameId);

• uniqueNameId - specify the unique name of the widget. e.g. "todo". You can access the calendar events using calendarService.events[uniqueNameId].

add

Add a new item to the calendar.

calendarService.add(item, noAlert, update);

• item - specify calendar item that you want to add. Example:

var item = { 
        Description : 'description',
        End : new Date(),
        Identifier : 1,
        IgnoreTime : false,
        Location : 'location',
        Start : new Date(),
        Summary : 'summary',
        Transparent : false,
        WidgetProjectUniqueNameId : 'todo',
        Resource : null
    };

• noAlert - specify a boolean value that indicate whether to display an alert after adding the item. the default is false
• update - specify a boolean value that indicate whether you want to replace an existing item with the value of item. The default is false.

remove

Remove an existing item from the calendar.

calendarService.remove(item, noAlert);

• item - specify calendar item that you want to remove. Example:

 var item = {
        Description : 'description',
        End : new Date (),
        Identifier : 1,
        IgnoreTime : false,
        Location : 'location',
        Start : new Date (),
        Summary : 'summary',
        Transparent : false,
        WidgetProjectUniqueNameId : 'todo',
        Resource : null
    };

• noAlert - specify a boolean value that indicate whether to display an alert after removing the item. the default is false

APIs for the Server Script tab

You can use the following APIs on the portal server. For example, you may use them to interact with databases or get student information.

Note: if a function returns complex data, it will be a string. If you would like to access fields in the returned data inside Server Script, you will need to parse the string into JSON using JSON.parse(yourString) to get a JS object.

console.log()

Uses this function to write information to your browser console.

Refer to Server Script Logging for an example of using console.log.

privateDataService

Refer to Accessing Private Data for examples of using the privateDataService.

db object

Use this object to perform database operations

db.Execute

Executes a TSQL statement.

db.Execute(string tsqlStatement);

• tsqlStatement - TSQL Statement
• Returns - JSON formatted string representing the result of execution.

db.Execute( "SELECT * FROM myTable" );

db.Declare

Declares a TSQL variable.

db.Declare(string key, string value, bool unicode);

• key - name of the variable
• value - variable value
• unicode - indicate whether to initialize variable as 1024 bit SqlDbType.NVarChar

db.Declare("myId", "1" , true);
    db.Execute ("SELECT * FROM myTable WHERE id=@myId");

proxy object

Use this object to perform http requests to external sources.

proxy.GetProxy

Submits a GET request to a remote server and returns a string response.

Note: Ensure the domain is whitelisted by Portal staff before using this function. To see available domains press "External Sources" on the top menu of the SDK.

proxy.GetProxy(string url, object config);

• url - url to which to submit the request.
• config - an optional { headers: { key:value, ... } } object that contains the headers of the request.

proxy.PostProxy

Submits a POST request to a remote server and returns a string response.

Note: Ensure the domain is whitelisted by Portal staff before using this function. To see available domains press "External Sources" on the top menu of the SDK.

proxy.PostProxy(array values , string url, object config);

• values - post parameters to submit to the url.
• url - url to which to submit the request.
• config - an optional { headers: { key:value, ... } } object that contains the headers of the request.

var requestConfig = { 
    headers: [
        { header1:value1 },
        { header2:value2 }
    ]
};
proxy.PostProxy([["key", "value"], ["key", "value"]], 'http://posttestserver.com/post.php', requestConfig);

user object

Use this object to access information of a currently logged in user.

user.Username

Gets the name of the current user.

var username = user.Username;

user.Student object

Use this object to access information of a currently logged in student.

These functions return a JSON string, use JSON.parse(yourString) if you want to process it as a JS object on Server Script.

user.IsInRole function

user.IsInRole('SDK User') - returns true or false

Student.Career

Gets the career of the current user. For example:

• UG: Undergraduate
• GRD: Graduate

var career = user.Student.Career;

Student.Faculty

Gets the faculty name of the current user. For example: AHS, MAT, or SCI

var faculty = user.Student.Faculty;

Student.Departments

Gets all department names of the current user. For example: ARTSDEAN, MATHDEAN, or SCIDEAN

var departments = user.Student.Departments;

Student.PlanTitles

Gets all plan titles of the current user. For example: Accounting, Professional, or Science,

var plans = user.Student.PlanTitles;

Student.FormOfStudy

Gets the form of study of the current user. For example:

• ENRL: Enrolled
• COOP: Co-op

var form = user.Student.FormOfStudy;

Student.Level

Gets the level of the current user. For example: 1B, 3B, or M.

var level = user.Student.Level;

Student.StudentNumber

Gets the student number of the current user.

var uid = user.Student.StudentNumber;

args object

Use this object to access arguments that were passed to the Server Script function from Javascript using $scope.portalHelpers.invokeServerFunction (see JS section for more details).

args.Get

Gets the argument by key.

args.Get(string key);

• key - name of the argument that you want to get.

args.Set

Sets a value in the args dictionary.

args.Set(string key, string value);

• key - name of the argument that you want to set.
• value - new value of the the argument.

You can use args.Set to declare SQL variables. For example:

args.Set('test', '2'); 
db.Execute('INSERT INTO bla VALUES (@test)');

args.Clear

Clears the args dictionary.

args.Clear();