Skip to main content
System StatusContact Support
VersionOne Community

Continuum Canvas Widget Reference

Overview

A Widget definition is a JSON document with many different properties. The schema of the definition can vary depending on the choices for the required properties.

type

Widgets require a type property. Valid values are:

text

A text Widget will simply return the contents of the code property.

raw

Will return the data from a query with no formatting.

json

Will attempt to format the data results from a query into JSON format.

format

Applies formatting rules to each row in the result set. The following properties are available:

  • row_template - A string to be output for each row. The string is parsed for {column_name} tokens. If the 'record_format' option is set to 'list', template tokens must be {0} numeric indexes.

 

In a row template, the special {#} token will be replaced with the zero-based row number. If 'format_type' is 'replace', the index token is %#.

 

  • row_separator - string value used between rows when applying row template formatting.

session

If provided, the value will be used as a key for the Session. If omitted, the default is the Widget name. Providing the same session name to multiple Layouts or Widgets creates a global namespace for the sharing of variables.

clear_session

If 'true', the named Session will be cleared every time this Widget is requested. If omitted, the default is 'false'.

options

The options property of a Widget can vary depending on several factors, such as the Widget type, the Datasource type, etc. Any non-relevant options are simply ignored.

anonymous

Widgets are served anonymously by default, so anyone can access them, even if not logged in to Continuum. To secure a Widget, add the anonymous option with a value of false.

allow_origin ("*", domain)

In almost all cases, Widgets are intended to return #data#. In order to effectively use the Canvas API as a flexible data server, at times it may be desired to embed data in another web site. Cross Origin Resource Sharing allows Canvas to serve the data of a particular Widget to a client where the main page has been served from another domain.

Use with caution, as serving script with a Widget could pose a potential security risk.

Use "*" to allow the Widget to be served to any requesting domain, or explicitly specify an allowed domain.

content_type

Widgets are assumed to be a data response, so the default HTTP Content-Type is application/json. Developers can force a specific Content-Type using this property.

record_format (list, dict)

Valid on results from MySql database queries, this option tells the API to retrieve results in list format - values only with no column names. If omitted, results are always returned in a dictionary format that includes column names and values as key/value pairs.

 

At this time, the record_format option only applies to MySql queries.

 

format_type (replace, index)

When a 'format' widget is used, the rules follow that of the Python 'format' function. However, if the 'format_type' option is set to replace, replacement is done using the alternative Python %s replacement.

replace [ [from, to], [from, to] ]

'replace' is a list of two-element pairs, each pair representing a 'find' and 'replace with' directive. Items are processed in order on the Widget data after it has been obtained.

prefix

Regardless of the Widget type, a string value specified in prefix will be placed at the top of the result.

suffix

Regardless of the Widget type, a string value specified in suffix will be placed at the top of the result.

processor

A dictionary defining the defails for a processor type Widget. (See Processor details below.)

variable_name

If provided, will attempt to put the data returned by the widget into a Session variable using the provided value.

variable_type

Optional. If 'variablename' is provided, will attempt to cast the data results into the format specified by 'variabletype'.

Valid values:

  • text - the default value if omitted.
  • dict - attempt to build a dictionary object by parsing the data response as JSON
  • list - attempt to build a list by parsing the data response as JSON
  • xml - attempt to build an XML document from the data response
  • json - attempt to dump the data response as a JSON document

visible

When set to false, this Widget is fully processed but will return no results. Useful if a Widget sets variables in the Session but should't be returned.

MySql Datasource Options

The following options are specific to MySql Datasources.

query_type

Either: exec or select.

If omitted, the default is select, which will execute the query and return the results.

 

Due to the nature of SQL, you can certainly issue an "update" command with query_type set to exec, and it will work, but the result set will be empty. Using exec will return a 'success' message, and possibly the last inserted autoincrement id, if applicable.

 

MongoDB Datasource Options

The following options are specific to MongoDB Datasources.

collection

A MongoDB collection name.

command

A command to execute in the collection: find, find_one, count, update, update_multi, save, insert, remove, remove_all, exec.

  • If omitted, the default is 'find', which will return all results that match the query.
  • for save, the "document" property is required. If a document with the same _id is found, it will be updated.
  • find_one support an extract option, which if provided will attempt to return the value of a single field in the document.

 

'remove_all' is not a native MongoDB command, however we've implemented it as a safety mechanism. Calling remove({}) with an empty query will remove all documents. A mistake in defining the query could wipe out a collection, so we've made this it's own on-purpose command.

exec is not a native MongoDB command, but we've implemented it as a way to access some management functions, such as db.collection_names().

query

A valid MongoDB query. Default is an empty query {} that will match all documents in the collection.

NOTE: when working with the native _id (BSON "ObjectId") in Mongo, a special cast is required. The BSON ObjectId() notation is not valid in a JSON representation of a query. Therefore, in the 'query' option, if use of _id is required, the following behavior applies:

If the provided _id is capable of being cast as an ObjectId, it will be. If not, it will be used as provided.

  • "query": { "_id" : "12345" } - will be used as provided
  • "query": { "_id" : "525da805910cf032b2a43b71" } - will be cast to "query": { "_id" : ObjectId("525da805910cf032b2a43b71") }

The Widget processor will use that hint to create a proper Mongo query using _id.

fields

An optional list of fields to include in the response.

{ field1: true, field2: false }

 

A Mongo query always includes the _id field even if the field is not explicitly stated to return in the projection parameter.

The 'fields' option cannot contain both include and exclude specifications, except for the exclusion of the _id field.

 

If you explicitly include fields, the _id field is the only field that you can explicitly exclude.

sort

An optional sort directive. Default is Mongo 'natural' sort.

The 'sort' option requires a list of pairs, each pair being a field name and a sort direction. For example:

"sort": [
            ["author", 1],
            ["title", 1]
        ]

would sort first by 'author' then by 'title', both ascending.

limit

An optional limit to the number of results. Default is 0 (no limit).

code

Most Widgets make use of the code property, although it's use varies by type. Code may be plain text, a SQL statement, etc.

 

Because the JSON format of the Widget definition doesn't allow line breaks in string values, for readability, the 'code' property can be either a string or a list of strings. Using a list is handy for building a large query. Spacing is not added, so make sure your list items have the appropriate spacing.

"code" : [
    "select *",
    " from table",
    " where 1=1",
    " and 2=2"
]

Datasources

Widget Datasources can be embedded directly in a Widget definition, or saved as their own Canvas resource. In either case the properties are the same.

Required Properties:

  • type - valid values are sql and nosql
  • provider - currently supported - mysql, oracle, mongo
  • server - the hostname or ip address of the data server
  • uid - a User ID to access the database
  • pwd - a Canvas resource name
  • db - the name of the database, schema, etc.

Optional Properties:

  • project - a Canvas resource name
  • component - a Canvas resource name
  • name - a Canvas resource name, or a reserved built-in datasource name. (Built-in datasources include CATO and CATO_DATASTORE.)
  • port - port of the database service. PRovider specific defaults are used if omitted.
  • _CATO_CREDENTIAL - if provided, will attempt to use the uid/pwd from the specified Shared Credential

Processor

A processor type of Widget requires several properties, defined in the 'processor' section of the Widget definition.

Required Properties:

  • project - processor project name
  • component - processor resource name
  • name - processor name

Optional Properties:

  • args - additional arguments passed in to the processor module
  • handler - the name of the initial function in the processor to call. 'main' if omitted.
  • Was this article helpful?