Skip to main content
System StatusContact Support
VersionOne Community

Contiuum Canvas Widget Tutorial

This feature is available in Ultimate edition only.

editions-u.png

Overview

Step-by-step Canvas Widget tutorial.

This tutorial assumes Canvas is up and running on localhost. Replace localhost with the appropriate hostname in your environment. Please read the introductory documents before starting the Widget tutorial.

Log in to Continuum, and select Canvas - > Canvas Editor from the upper-right menu.

The Canvas Editor

The Canvas editor is a text editor with syntax checking. The screen is divided into two parts: on the left is the resource browser, on the right is the content editor.

For this tutorial, please do not modify any existing items found in the resource editor. You might be messing with someone else's work!

For certain resources, a Test button will be available in the editor to open a test window. The test button will only work if a .widget or .layout resource is selected.

Hello World

At the bottom of the resource browser is a button. Click New Item. A dialog will appear and prompt for Project, Component, and Name.

Enter tutorials as the Project, tutorial1 as the Component, and hello.widget as the Name. Click Save.

The new Project, Component and resource will appear in the resource browser.

Widget resources are definition documents in JSON format. For our first example, let's not worry about the details. Copy and paste the following into the editor and click the Save button in the upper-right corner of the editor.

{
    "type" : "text",
    "code" : "hello world"
}

All Widgets require a type property. See the Widget Reference for a definition of all valid types.

The simplest type of Widget is the 'text' type. A text Widget will return the contents of the 'code' property.

Click the Test button. A new tab/window should appear that says 'hello world'. Congratulations, you made a Widget!

Clicking the Test button will save the contents of the editor.

Variables

While we're here, let's do a quick example of variable replacement.

In Widgets (and Layouts), the following escape syntax indicates a variable - [$variablename$]. When the Canvas API encounters this pattern, it will attempt to replace variablename with a value from:

  • the URL querystring
  • POST data if POST was used
  • Session variables.

Let's pass an argument on the URL querystring. Switch to the 'hello world' test window, and add ?myname=Bob to the URL, then navigate. Hmmmm... nothing changed.

Of course it didn't... we need to modify the Widget code!

In the editor, change the code and save it.

{
    "type" : "text",
    "code" : "hello [$myname$]"
}

In Canvas, project, component and name are reserved variable names.

Refresh the test window and it should say hello Bob.

Getting Data

Continuum Database (MySQL)

Widgets can return plain text if desired, but the real purpose of a Widget is interacting with data. Widgets can retrieve data from various databases, using built-in Datasources.

Create a new Widget in the editor. This time, instead of clicking the New Item button, let's add it directly to our project.

In the resource browser, click the + beside the component we created called tutorial1. A prompt will appear, with the Project and Component already filled it. Enter deployments.widget into the Name and click Save.

The 'raw' type

Enter the following into the editor and click Save.

{
    "type" : "raw",
    "datasource": {
        "name": "_CATO"
    },
    "code" : "select deployment_name, created_dt, runstate from deployment"
}

_CATO is a built-in Datasource that provides read-only access to the Continuum database. More on Datasources below.

Click the Test button. Assuming you have at least one Deployed Application in Deploy, you should see an ugly response.

The response is ugly because we've selected the raw type of Widget, which will return data with no formatting at all.

The 'json' type

In the editor, change the "type" to json and click Test. Well that's handy!

The 'json' type will attempt to format the result set into a JSON document.

Don't like your results in object format? Let's try this - in the editor, add the following on the line above 'code':

"options" : { "record_format" : "list" },

Click Test and you'll see the results are now a more streamlined JSON list format.

Getting JSON format is very useful and actually accounts for a majority of use cases where Canvas Widgets are used for delivering Ajax data to Canvas Layouts, as the HTML/Javascript Canvas Layout easily makes use of the JSON data.

However, what if you need something more specific and tailored?

The 'format' type

The 'format' Widget type allows moderate manipulation of the results data. The result set will be formatted:

  • using a template for each row
  • using a row delimiter
  • can be wrapped with a prefix and suffix

Format is based on the Python format function. Curly braces are use to denote a key name in the result dictionary (or an index if the result_format is 'list').

Let's do simple comma separated values. In the editor, change the definition to the following, then click Test:

{
    "type" : "format",
    "datasource": {
        "name": "_CATO"
    },
    "options": {
        "row_template": "{deployment_name}, {created_dt}, {runstate}",
        "row_separator": "\n"
    },
    "code" : "select deployment_name, created_dt, runstate from deployment"
}

How about something completely custom?

{
    "type" : "format",
    "datasource": {
        "name": "_CATO"
    },
    "options": {
        "prefix": "BEGIN\n",
        "suffix": "\nEND",
        "row_template": "'label' = '{deployment_name}', 'runstate' = '{runstate}'",
        "row_separator": ",\n"
    },
    "code" : "select deployment_name, created_dt, runstate from deployment"
}

The 'processor' type

What if 'format' still isn't enough to get your data formatted properly? One option would be a) develop multiple Widgets to deliver flat content and b) perform formatting in Javascript in the Layout. However, this assumes the end consumer of this Widget is a Layout, which is often not the case.

When complex processing must be performed on the server in a Widget, the processor type can be used.

Defining processor Widgets is beyond the scope of this tutorial, but in summary - Processor Widgets are full Python modules capable of very precise and complex data manipulation.

Continuum Datastore (MongoDB)

In addition to the built-in _CATO Datasource, Canvas can also access the built-in MongoDB which contains Deployment specific documents, as well as user custom data.

In the editor, click the + in the 'tutorial1' component. Enter mongo.widget as the Name and click Save.

Enter the following into the editor and click Test.

{
    "type": "json",
    "datasource": {
        "name": "_CATO_DATASTORE"
    },
    "options": {
        "collection": "deployments",
        "query": {}
    }
}

If there are any Deployed Applications, a list of Deployment datastore documents will be returned in JSON format.

The format type will work with Mongo results, however unlike a relational database, Mongo documents do not follow a strict schema. It's possible certain documents may not contain fields used in a row template.

HTTP Data

Let's try one more thing. Many software systems provide useful data via the HTTP protocol. This is especially helpful when exposing data from a database across network firewalls.

Specifying an http Datasource allows a Widget to query any accessible server using the HTTP protocol. While the HTTP standard is consistent, there's no guarantee what you might get back from a server, so take precautions when using HTTP and only query trusted sources for known data formats.

When using the HTTP Datasource from a Widget, in most cases the Widget 'type' should be set to raw. In this way the Widget simply acts as a proxy between the data source and the Canvas client.

Create a new Widget in the editor.

In the resource browser, click the + beside the component we created called tutorial1. A prompt will appear, with the Project and Component already filled it. Enter http.widget into the Name and click Save.

Enter the following into the editor and click Save.

{
    "type" : "raw",
    "datasource": {
        "type": "http",
        "server" : "https://httpbin.org/get"
    }
}

httpbin.org is a free service useful for testing HTTP. It simply responds with details about the request it received.

Click the Test button, and the test window will be populated with a JSON response from httpbin.org. Congratulations, you've made a Widget get data from an HTTP server on the Internet!

If no options are provided, an HTTP 'GET' is performed. Let's do another request, this time we'll POST data.

Enter the following into the editor and click Save.

{
    "type" : "raw",
    "datasource": {
        "type": "http",
        "server" : "https://httpbin.org/post"
    },
    "options": {"method" : "post", "args" : { "foo" : "bar" } }
}

Click the Test button to see a different response from httpbin.org, including your arguments.

Arguments are defined in the same manner, regardless of the method being get or post.

External Data

A Widget can access any data accessible by a Canvas Datasource.

For complete details about Datasources, click here.

Canvas can access data in many databases, including: MySql, Oracle and MongoDB. External datasources can be defined in several different ways: a) as a Canvas resource file and b) explicitly in a Widget definition.

Explicit Credentials

Explicit Datasource credentials can be provided directly in the Widget.

While explicit Datasources are useful for testing, there is no security to protect ids and passwords saved in a Widget definition.

Let's return to our first Deployments example (deployments.widget), but we'll define explicit credentials instead of using the built-in _CATO name.

{
    "type" : "json",
    "datasource": {
        "type": "sql",
        "provider" : "mysql",
        "server" : "localhost",
        "port" : "3306",
        "uid" : "catoread",
        "pwd" : "catoread",
        "db" : "cato"
     },
    "code" : "select deployment_name, created_dt, runstate from deployment"
}

Datasource Resource

For an additional level of security, Datasources can be defined as a Canvas resource. In the editor, click the + beside "tutorial1" component, and enter cato.datasource as the Name, and click Save.

Paste the following into the editor, and click Save.

{
    "type": "sql",
    "provider" : "mysql",
    "server" : "localhost",
    "port" : "3306",
    "uid" : "catoread",
    "pwd" : "catoread",
    "db" : "cato"
}

Now, in the resource browser, go back to the deployments.widget definition, and change it to the following:

{
    "type" : "json",
    "datasource": {
        "project": "tutorial",
        "component" : "tutorial1",
        "name" : "cato.datasource"
     },
    "code" : "select deployment_name, created_dt, runstate from deployment"
}

Notice instead of full credentials, we can provide a pointer to a Canvas resource. In this way the only people who can see the credentials are those with permission to edit Canvas resources.

Automate

Assets and Shared Credentials are also available to Datasources. See the Datasource documentation for more details.

Wrapping Up

In this tutorial, we've been introduced to the basics of using Widgets to retrieve data. Widgets are far more powerful than defined here - they can just as easily update data.

By designing Widgets for reading and updating data, the Canvas API can very easily be made into a full featured, flexible API on any application with a relational or NoSQL database.

  • Was this article helpful?