Skip to main content
System StatusContact Support
VersionOne Community

WHYCanvas Javascript Reference

This feature is available in Ultimate edition only.

editions-u.png

Overview

Lists the set of classes that make common Canvas functions easier.

The 'canvas' Class

The canvas class contains helper functions for a few built-in and common operations.

Alerts

canvas.showAlert(alert, info, options)

Will display a Mac OS 'growl' type of notification to the user, with an 'alert' theme. The alert will stay visible until dismissed.

canvas.showAlert("Oh noes!", "Something happend.");

'options' can be:

  • icon - an alternative icon
  • title -an alternate title
  • sticky - (true/false) the alert will persist
  • duration - duration in milliseconds if sticky is false

canvas.showInfo(msg, info, options)

Will display a Mac OS 'growl' type of notification to the user, with an 'info' theme. The notification will persist for 2 seconds then fade.

canvas.showInfo("I should tell you...");

'options' are the same as canvas.showAlert

canvas.showSuccess(msg, info, notimeout_)

Will display a Mac OS 'growl' type of notification to the user, with a 'success' theme. The notification will persist for 2 seconds then fade unless 'no_timeout' is true.

canvas.showSuccess("We did it!");

canvas.getQuerystringItem(item)

Will return a specific item from the current page's URL.

Authenticated Users

If the Canvas session is authenticated, there are some helpful utilities for accessing user information.

canvas.user

The canvas.user object contains details about the currently authenticated User. The following properties are available:

  • user_id
  • user_name
  • full_name
  • email
  • ip_address
  • role
  • tags

canvas.user.hasTag(tag)

Will return true or false, if the current user matches the provided tag.

canvas.user.hasTag("foo");

Configuration

The Continuum suite has a general configuration dictionary, useful for advanced interaction from a Canvas to other Continuum applications.

canvas.config

The canvas.config dictionary contains urls to access different services, the version number, and other advanced information.

Other

canvas.loadScript(url, callback)

Will dynamically obtain a script resource from a Canvas API url and inject it into a <script> block in the <head> of your page. New <script> blocks are evaluated when added.

Dynamic loading of script resources is an uncommon case. In the majority of cases, it's enough to define script resources in the scripts section of a Layout definition.

This can also be used for including scripts from publicly hosted resource such as Google Hosted Libraries.

 Take caution when including resources from outside sources - only include libraries you trust!

  • url - the url of the resource.
  • callback - a callback function executed when the response is received, not evaluated.

canvas.loadStyle(url)

Will obtain a CSS resource from a Canvas API url and inject it into a <link> reference in the <head> of your page.

canvas.pleaseWait.show($element)

Will show a modal 'Please Wait' indicator. If $element is provided (must be a jQuery element), then the modal will be attached over that element. If omitted, the modal covers the entire body.

canvas.pleaseWait.hide()

Hides the Please Wait indicator previously displayed with canvas.pleaseWait.show().

canvas.session.get(sessionname, path_)

Will obtain a Session collection by name using an Ajax GET and return it.

If path is omitted, the entire Session matching the provided session_name is returned.

canvas.session.set(sessionname, path, value_)

Will set a specified location in a Session collection to the provided value, and returns a success object.

All arguments are required.

Will return a 'success' message, or an 'error' message on fail.

The 'layout' Class

The 'layout' class has helper functions for obtaining a Canvas Layout using Ajax.

This is an advanced use case, but creative developers may wish to dynamically embed the contents of one layout inside another. Layouts are complex constructions of many resources, and in addition to creating a user interface, they can also be utilized to create complex data objects consisting of data from multiple Widgets.

layout.render($target, path, args)

Will obtain a Layout using an Ajax GET, and load the specified $target (jQuery object) with the results of the Layout at the specified path. If provided, the args (in querystring format) will be sent with the request.

layout.render($mydiv, "project/component/name.layout", "name=Bob&age=31");

Equivalent to:

$.get( "project/component/name.layout?name=Bob&age=31", function( data ) {
  $mydiv.html( data );
});

layout.render_post($target, path, args, datatype)

Will obtain data using an Ajax POST, and load the specified $target (jQuery object) with the results of the Layout at the specified path.
If provided, the args (in JSON object format) will be sent with the request.

datatype (xml, json, script, html or text) will change the response data type. If omitted, html is assumed.

layout.render_post($mydiv, "project/component/name.layout", { "name" : "Bob", "age" : 31 });

Equivalent to:

$.ajax({
    async: false,
    type: "POST",
    url: "project/component/name.layout",
    data: JSON.stringify({
        "name": "Bob",
        "age ": 31
    }),
    contentType: "application/json; charset = utf-8",
    dataType: datatype,
    success: function(response) {
        $mydiv.html(response);
    }
});

layout.get(path, args, on_success, datatype)

Will obtain content with an Ajax GET, execute the provided function when the response is received.
If provided, the args (in JSON object format) will be sent with the request.

datatype (xml, json, script, html or text) will change the response data type. If omitted, html is assumed.

var result = layout.get("project/component/name.layout", {
    "name": "Bob",
    "age": 31
}, function(response) {
    // do something with the response
});

Equivalent to:

var result;
$.ajax({
    async: false,
    url: "project/component/name.layout",
    data: JSON.stringify({
        "name": "Bob",
        "age ": 31
    }),
    contentType: "application/json; charset = utf-8",
    dataType: datatype,
    success: function(response) {
        result = response;
    }
});
return result;

layout.exec(path, args, datatype)

This is an extreme edge use case. Using Ajax to POST data to a Layout provides a developer with a very advanced method for performing a series of Widget updates in a single POST. This use case would likely involve a hidden iframe or other uber-nerdy approach. As such, any examples are beyond the scope of this document.

Unlike widget.render_post, this function assumes a default datatype of html. Otherwise they are identical.

layout.exec is syntactically identical to widget.exec.

The 'widget' Class

The 'widget' class has four functions that are functionally equivalent to the 'layout' class, except of course they request and return Widget resources instead of Layouts.

widget.render($target, path, args)

See layout.render.

widget.render_post($target, path, args, datatype)

Unlike layout.render_post, this function assumes a default datatype of json. Otherwise they are identical.

See layout.render_post.

widget.get(path, args, on_success, datatype)

Unlike layout.render_post, this function assumes a default datatype of json. Otherwise they are identical.

See layout.get.

widget.exec(path, args, onsuccess, datatype_)

widget.exec is a core feature, and is the common and standard method for any Layout to make an atomic Ajax update via HTTP POST to a Datasource.

If on_success is provided, the call will be asynchronous. If omitted, the function will return the results of a sychronous Ajax request.

datatype (xml, json, script, html or text) will change the response data type. If omitted, json is assumed.

Synchronous:

var response = widget.exec("project/component/name.layout", {
    "name": "Bob",
    "age": 31
});

Asychronous:

widget.exec("project/component/name.layout", {
    "name": "Bob",
    "age": 31
}, function(response) {
    // do stuff when the response is received
});

Equivalent to:

$.ajax({
    async: false,
    url: "project/component/name.layout",
    data: JSON.stringify({
        "name": "Bob",
        "age ": 31
    }),
    contentType: "application/json; charset = utf-8",
    dataType: datatype,
    success: function(response) {
        // do something with the response
    }
});

The 'velocityui' Class

The 'velocityui' class has helper functions for interacting with the Continuum UI.

While Canvas is a standalone service, many Canvas elements are embedded inside the Continuum UI, in HTML IFrames. As such, any hyperlinks on a Canvas would by default direct to another Canvas.

If it's necessary to have actions in a Canvas affect the parent page in Continuum, the following functions are available.

velocityui.getObject

 velocityui.getObject(object_name, on_delivery, set_variable);

Request an object from the DOM of the host page. Sets a variable in the current scope. Useful for grabbing a javascript object from the parent page.

  • object_name - name of a Javascript object on the parent page.
  • on_delivery - name of a function on the Canvas that will handle the response.
  • set_variable - name of a variable on the current page to receive the value.

getObject is ashcyronous, meaning the variable specified in set_variable won't necessarily be available immediately after making the request. To ensure availablility, use the on_delivery feature.

You cannot pass a function definition to the parent page. This is not allowed with cross window messaging. Therefore, on_delivery must be a named function on your page, not a complete function object.

For example, to get the Continuum UI global configuration object:

$(function(){
    velocityui.getObject("g_config", "handle_response");
});

function handle_response(r) { console.log(r); }

velocityui.redirectToPage

Sends a request to the Continuum UI to redirect to another page.

velocityui.redirectToPage(url)

Different pages in Continuum have different argument requirements - most include one or more UUID identifiers. When using this function, it's helpful to first visit the desired page via normal navigation and inspect the address bar.

Many pages in Continuum have bubble tabs on the left edge. By passing a &tabs= argument, certain pages will automatically select the requested tab. Common tab names are: status, details, actions, log, sequences, monitors, and data.

For example, to go the detail page for a specific Deployed application (where 'xxx' is the ID of the Deployment), and show the Log tab:

velocityui.redirectToPage(/deployment_detail?tab=log&id=xxx);

velocityui.newWindow

Similar to redirectToPage, this sends a request to the Continuum UI to open a new window/tab and navigate to the provided URL.

velocityui.redirectToPage(url, name, specs)

For example, to open a window on a Sequence Instance log:

velocityui.newWindow(/sequence_status?seq_instance=263);

velocityui.refreshPage

Sends a request for Continuum to refresh the current page.

Since the Canvas is embedded in a Continuum page, this will refresh the Canvas to its initial state as well.

velocityui.refreshPage();
  • Was this article helpful?