Portal Tutorial (7.0.0 and later)

Create A Portal

  1. Navigate to the “Portals” tile on the sidebar or the “Portals” button in menu of the developers console

  2. Create a new portal by clicking + Add

  3. Enter the name description for your portal

Create a new portal

Assign roles

Click on the gear next to your new portal and select Edit Roles in order to give permission for our users to access and edit the portal.

This step assumes we have users in our system, if not, please add users in “Users”. Giving the authenticated role access to read will allow these users to sign in and operate a portal. This is the default role when a user signs up on the portal page. By giving administrator roles CRUD access, they will be able to modify the portal that will reflect in the public view.

Give role's access to portal

Access a portal

Now that we have access to open a portal, click the portal’s link and sign in with an administrator’s credentials. Click portal link Login to portal

Welcome to your portal!

Delete a portal

  1. Click on the gear next to your new portal and select Settings
  2. Click Delete Portal

Delete portal

Confirm the deletion when prompted

Datasources

  • Where can datasources be added from?
  1. Left side navigation bar by hovering over the Datasource tab

  2. Scrolling to Datasoure on Quick Add at the top and selecting the type of datasource

  • Complete the information about the datasource in the pop up window.

Above is an example for ClearBlade Messaging. Fields may vary depending on the datasource. The fields below are the standard fields for all datasources.

Settings

Field Description
Name Portal’s label of the datasource
Type Where the data is coming from
Name Name of the datasource where the data is coming from
Refresh Interval(s) How long the datasource should update
Call on load Auto invocation of datasource when starting up the portal
Suppress Errors Do not show network errors, if any
Parse incoming data Parses data for the results to be in a desired format

Data

Manually fetch data from the datasource using Fetch Data.

  • Click “Apply” and the datasource and it’s last update will appear in the side editor. It can also be used in a widget under “Dynamic”.

Widget

Adding widgets

  • Left side navigation bar by hovering over the Widgets tab

    Drag the widget of choice to the portal

  • Scrolling to Widgets on Quick Add at the top and selecting the type of widget

Types of widget

Example Widgets

Widget Link
Color Picker View Video
HTML View Video
Bar Chart View Video
CRUD Grid View IPM

Data Types

All widgets will require you to choose a type of incoming data to render.

Static - data will be loaded as is and is not changed unless code is written for it to listen and force changes.

Calculated - can reference a datasource and the JavaScript in the parser can be customizable.

Dynamic - The datasource is added and data gets updated as changes are made in the datasource. This will appear in ‘Content’ as ‘Datasources’.

Parsers

Editing the Parser

To edit the parser, click on ‘Edit’ next to the data type.

The parser includes:

  • ‘Debug’ button - this is to debug your parser
  • ‘Save’ button - save changes you make to your parser. Do not close the parser without saving your changes.
  • ‘Discard Changes’ button - restores parser to its default state.

Debug Example

An error message should appear at the bottom of the page after clicking the debug button.

Try it out with this example:

buggyCode();
function buggyCode () {
    return thing.doesNotExist;
}

Widget API

  • widgetData

  • overrideSettings: programmatically overrides the setting that is manually set on the widget.

Ex:

return {
    overrideSettings: {
      dropdownOptions: [
        {name: 'manager', value: '1'},
        {name: 'employee', value: '2'},
      ]
    },
    widgetData: 'manager'
  }

To go back to the widget editing page, click on the name of the widget.

To see the types of override settings, click here

Note: This is a list of the most common types. Not all types are listed.

Data Parsers

The parser for the widget can be edited in this section. Datasources can also be added.

Event Parsers

Event parsers trigger an action from a widget, but not all widgets have an event parser. It appears the same as the data parser.

Try it out with this button widget example

alert('clicked button!');

Edit/Delete widget

Hover over the widget and click on the wrench icon to edit. To delete, click on the trash can.

Import widget

There is also an option to import widget configurations. Create and save a widget first.

Try it out with this button widget example

{
  "id":"c346f39d-727b-4857-9829-a2251ce6c30f","type":"BUTTON_WIDGET_COMPONENT","tab":"PANE_GRID","props":{"eventTarget":{"dataType":"CALCULATED_DATA_TYPE","value":"/**\n* The 'parser' variable is the entry point for your parser. Write logic inside of the provided function and return a value\n* Constants and utilility functions can be created outside of the parser\n* The provided ctx parameter is an object that contains data and model information on this item\n* @param {context} ctx \n*/\nparser = (ctx) => {\nalert('clicked button!');\n\n}","outgoing_parser":{"isDebugOn":false,"value":"/**\n* The 'parser' variable is the entry point for your parser. Write logic inside of the provided function and return a value\n* Constants and utilility functions can be created outside of the parser\n* The provided ctx parameter is an object that contains data and model information on this item\n* @param {context} ctx \n*/\nparser = (ctx) => {\n  return ctx.widget;\n}"},"force_data":["CALCULATED_DATA_TYPE","DYNAMIC_DATA_TYPE"]},"backgroundColor":"#2b59bb","backgroundHoverColor":"#c2c2c2","fontColor":"#ffffff","borderColor":"#cccccc","label":"Click me","HAS_UNIQUE_STYLE":false},"externalScripts":[],"name":"BUTTON_WIDGET_COMPONENT_c346f39d-727b-4857-9829-a2251ce6c30f"}

Panes

Panes are used to group widgets in a more logically organized way.

  • Where can panes be added from?
  1. Left side navigation bar by hovering over the Widgets tab

    Scroll down to Containers and drag the pane to the portal

  2. Scrolling to and clicking on Add Pane on Quick Add at the top.

Edit pane

Hover onto the pane and click on the wrench

Field Description
Title Label for the pane
Hide header Hides pane header
Hide borders Hides pane outlines
Tabbed pane Adds tabs to the pane
Theme type Changes the color theme of the pane
Custom Pane ID A unique ID for the pane. Useful when switching tabs programmatically.
Grid container padding Adds padding between pane and widgets

Resize pane

Click the resize handle on the bottom right corner or the pane and drag to desired shape

Delete pane

  1. Hover over pane and click on the trashcan.
  2. Confirm deletion when prompted.

Flyout pane

Click on the hamburger icon on the left-hand side of the header

Note: The menu title defaults to the name of the portal but can be configured like a widget

Widgets can be added to the flyout pane.

Tabbed pane

There can be separate tabs in one pane. To change the label of the tab, double click on the label.

Pages

Create a page

Hover over ‘Pages’ on the side editor and click the ‘+’

Add page

Fill in the name of the page and click ‘Apply’

Create page

Edit/Delete page

Click on the pencil icon of the page you wish to edit

Click on the trash can icon of the page you wish to delete

Edit page

Adding children to page

  1. Click on the plus button of the page you wish to add a child page
    Add child

  2. Add name and parameters
    Save child

  3. Save the child page by clicking Apply

The default value for the parameter will be used when navigating to the page

Programmatic interaction

The portal provides an interface via the CB_PORTAL object for interacting with pages from within a parser, widget, or datasource.

Selecting a page programmatically

CB_PORTAL.selectPage("/states/TX/city/Austin")

Example use case:

User selects a state from a list of states so the portal should navigate to a new page

Retrieving the current path parameters

CB_PORTAL.getPathParams() // will return {"state": "TX", "city": "Austin"} if the current path is "/states/TX/city/Austin"

Example use case:

  1. The current page changes so the portal should display data that is relevant to the URL parameters
  2. The portal needs to load the correct state on initial startup when the URL is /states/TX/city/Austin

Edit/Delete page

Click on the pencil icon of the page you wish to edit

Click on the trash icon of the page you wish to delete Confirm deletion when prompted

Modals

  1. Hover over ‘Modals’ on the side editor and click the ‘+’

  2. Give it a name, size, make it draggable or add click outside to close.

Field Description
Name Portal’s label of the datasource
Size Where the data is coming from
Draggable? Gives the ability to drag the modal around the portal
Close on click outside? Allows modals to close when the user clicks away from them.
Grid container padding Adds padding between pane and widgets

Note: If you make the modal dragrabble, you cannot select ‘close on click’.
There will be tips in the modal as a default. You can hover over these and edit the widget by clicking the wrench.

3. You can also add more widgets by clicking ‘+ Add Widget’ next to the modal
4. To delete or edit the modal hover over the name in the side editor and click on the pencil or trash can respectively.

Internal Resources

Internal resources can be added in the toolbar on the left in the portal.

There are two ways to add an internal resource:

  • In the internal resource parser
  • Importing a file

Parser

Click ‘Add Internal Resource’ and a ‘New File’ modal will appear. Give your file a unique name, choose whether it is a JS or CSS file, and type in the code. There is an option to test before saving the changes.

Import File

Click ‘Import Files’ and choose the file(s) from your computer.

After being created, they should be listed in the ‘Internal Resources’ section. From there, the file(s) can be exported and searched.

Add More Files

To add more files, hover over ‘Internal Resources’ and click on ‘+’.

Export Files

Mark the checkbox of the file(s) you want to export and click ‘Export Files’.

Delete Files

To delete files, hover the file you want to remove and click on the trashcan icon.

External Resources

External resources can be added in the toolbar to the left in the portal.

In the example we will be using a CSS URI example from Font Awesome Icons. The icons can be found here.

Make sure to add the HTML widget to the portal before continuing with the example.

Copy the URL (https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.9.0/css/all.css) and add it to the box that appears after clicking ‘Add Resource +’.

Hit the enter key to add the resource.

The resource should then get added to the list.

Mark the ‘Block’ checkbox if there is an error during import of the external resource.

Go to the HTML widget edit and copy/paste the code below in the HTML parser:

<div class="text-center underline">
  <h2>Address</h2>
  <i class="fas fa-address-book fa-7x"></i>
</div>

This should appear in the widget:

To delete, hover the resource and the click on the trash can icon that appears.

Screen Size Editor

This guide assumes that panes and widgets have already been added to your portal

  1. Select the screen size you’d like to change the layout for by choosing from the dropdown

  2. Adjust the layout by resizing your panes and/or resizing your widgets

Theme Editor

The theme editor can be found in the toolbar on the left of the portal and when you click it you will have options to change the theme on Macro (general) level or on a Micro (Specific) level.

Macro

  • Choose between a standard or night base theme
  • Choose different color themes using a palette
  • Change the colors of the graph elements

Micro

Change the color palette by portal element

Plugins

Create a plugin

Plugins can be created in the portals page Click + Add

Enter the name and URL for your plugin

Create a new portal

The plugin should appear under the ‘Plugins’ tab

Clicking on the plugin will take you to the URL

Settings

Go to the gear next to the Plugin and click ‘Settings’

The name cannot be edited but the URL can be as well as copied.

The plugin can also be deleted from this window.

To save changes, click, ‘Update’.

Export

Plugins can be exported one at a time or all at once

All at once:

One at a time:

Go to the gear next to the plugin and click ‘Export’:

Click ‘Export as JSON’

Then click on ‘Download {Plugin Name}’ and a zip file will be downloaded onto the computer.

Click ‘Done’ when finished