Portals

Introduction

A Portal is a single instance of a web application with preconfigured integrations with the ClearBlade System to which it belongs. It is fully responsive, mobile-friendly, and customizable.

Click here to learn how to get started with portals.

Purpose

  • Very powerful visual and interactive widgets to view and manipulate data
  • Role-based authorization
  • Out-of-box integrations with your ClearBlade System (ex. fetching code services, maintain tokens)
  • User-facing frontend for your ClearBlade Platform System
  • Mobile-friendly
  • Real-time data streaming
  • User management
  • Highly customizable and extensible

Components

Version 7.0.0 and later:

Datasource

Datasources are integrated with assets within your System. These assets can consume or generate data, such as:

Datasources can be globally accessed by using the datasources object.

Page

A User can view one page at a time. Every user starts on the ‘Home’ page by default.

The page can change programmatically by running CB_PORTAL.selectPage from within a widget’s parser. See Changing Pages.

A Page can have:

Pane

A Pane is a container that holds one or more widgets. The width and height of the pane can be set according to Bootstrap Grid.

Widget

A widget links to one or more Datasources and renders a visual or a interactive way to manipulate the datasource.
Tutorials for each widget can be found here.

Parser

A Parser offers a mechanism for manipulating a Datasource’s output prior to its ingestion by a widget. Often times, a Datasource’s output may need to be modified into different data structures to be consumed by different widgets.

Flyout Pane

The customizable pane that flies out from the left-hand side of screen.

The page can change programmatically by running CB_PORTAL.toggleFlyout from within a widget’s parser.

Header Pane

The Header Pane is the same across all of a Portal’s Pages. Header Pane can contain:

  • Multiple Widgets

Internal Resource

An Internal Resource is a JavaScript or CSS file containing global functions or styles. This is loaded just once when the page loads. It is recommended to add global/reusable code in this section which the user chooses to be loaded before anything else loads on the page. Users can set the order of loading of internal resources which are used on the portal. Users can also disable any resource, when this happens, they are not loaded. This is usually used while in development.

External Resource

An External Resource represents a web asset (such as js and css). Users can set the order of loading of external resources which are used on the portal and it is able to disable any resource. When this happens, they are not loaded. This is usually used while in development. This allows for a more customizable development of the widget using other resources.

Theme Editor

You can choose or customize the color scheme of the portal

Screen Size Editor

The layout of panes and widgets can be adjusted at different screen sized

An element that sits on top of an application’s main window. It can contain widgets like a pane.

Security

The portal has a dedicated URL that can be shared and/or linked to a domain name.

A User can visit a portal and interact with the data, edges, messaging, and other assets.

A User of a ClearBlade System, such as an Administrator User, can be granted Write access. This will allow a User to customize a portal for another user.

For information on the difference between a Developer and a User, see here

Advanced

Plugins

A plugin is a Javascript file that can be loaded by a portal to extend the default list of widgets and datasources. This can be used when a custom datasource is necessary and custom widget is called for in a separate portal.

CB_PORTAL

This is used for portal management from the parser. To find out what each object is used for click here

Local Storage

Portals allow users to get/set values in the localStorage using standard javascript functions. ClearBlade natively stores few keys by default to avoid re-authentication & re-querying of constants.

Local Storage stores:

  • Authentication information for the portal to avoid re-authentication
  • Platform and message URLs to avoid querying

Users can access it in browsers’ LocalStorage, usually via the ‘Application Section’ in Developer Tools.

These are the pre-existing key-value pairs in LocalStorage:

Key Type Description Example
cb_messagePort number MQTT over websocket port for messaging 8904
cb_messageURL string Messaging Broker platform.clearblade.com
cb_platformURL string The platform that the broker is connecting to. https://platform.clearblade.com
cb_messageTls boolean Websocket port TLS status depends on the port being used. See here. true
cb_portals object Users can set/unset their own custom keys using window.localStorage object in Javascript { "ExamplePortal":{"email":"guest@clearblade.com","authToken":"RXFrJQhrCZfBwJVsCJXFcmBYJFoyWyuOzaCJrxtOuBP4k6e2DOgvuj4cRk9XcSJfqkMO7zapuGD6eMxH9Q=="}}
cb_isEdge boolean Is the portal connected to Edge Platform? false

Best Practices

JQuery

  • Remove any event handlers for the element before adding a new one to avoid creating multiple handlers for one element

FAQ

Settings

  1. How do I change settings programmatically?

  • To ‘get’ the settings programmatically, use datasources.myDatasource.settings();

  • To ‘set’ the settings programmatically , use

	datasources.myDatasource.settings({
    ...datasources.myDatasource.settings(),
    refresh_interval: 50})

This can be done in the widget’s parser.

Make sure to use the spread operator followed by properties/settings which needs to be changed programmatically.

Datasource

What are the different methods available on a datasource inside of a parser?

Users can access the selected datasource by using this.dsModel, when using a dynamic datasource. Then pair it with methods such as sendData to call on them after being accessed.

Ex. this.dsModel.sendData(<DATA_TO_SEND>);

‘datasources’ is used inside of the widget parser and gives the user the freedom to use any of their datasources.

Examples:

  • datasources.myDatasource.sendData(<DATA_TO_SEND>);

  • To retrieve the latest cache for a datasource, use datasources.myDatasource.latestData()

  • To subscribe and unsubscribe to updates on a datasource, retrieve the data first and assign it to a variable -

    	const updateCb = (data) {
	 //do something with data 
	}
	//then use - 
	datasources.myDatasource.latestData.subscribe(updateCb)
	datasources.myDatasource.latestData.unsubscribe(updateCb)

  • if(datasources.myDatasource.lastUpdated){ const data = datasources.myDatasource.latestData(); }

  • To reach out to the server and update cache - datasources.myDatasource.refresh()

How do I change the message topic on a datasource?

Create a new HTML widget and use your message topic as your datasource

Edit the parser to include this code:

datasources.msg.settings({
...datasources.msg.settings(),
   TOPIC_NAME: "newTopic"
})

Make sure to change ‘msg’ to the name of your topic and ‘newTopic’ to the topic name you want to change to

Save changes and see the change appear when you open the message datasource settings

Can I set a datasource value to a falsey value to trigger any subscription callbacks for that datasource?

Yes in ClearBlade Platform versions 7.0.6 and newer.

Widgets

How do I set up permissions for rule builder?

Permissions needs to be added to the system’s:

  • Code Services

  • Triggers

  • Roles

This can be done in the Roles section of the system. It is recommended to add a new role specifically for the rule builder.

To learn more about adding new roles and permissions to a role, click [here(/security/#authorization)

How do I use the list widget to update other widgets?

Here is an example between the text and list widget:

Create a local variable

Add the list widget to the pane using the local variable as the ‘Selected Item’ datasource

Add the text widget using the local variable as the datasource

As you switch items on the list the text will change to the item’s id.

How to render data from a dynamic datasource in the HTML widget?

This is an example for a collection datasource. You can customize the widget to your preferences.

Choose ‘HTML’ from the widget type dropdown. Select ‘Dynamic’ for the data type. Choose the datasource you would like to use. Click ‘Edit Parser’ Add an id attribute to the HTML parser, id="UniqueID". Type the following into the JavaScript parser:

parser = (ctx) => {
    document.getElementById('UniqueID').innerHTML=ctx.datasource; 
	// If typeof ctx.datasource === "object" then user may have to select // the relevant key or stringify it.
}