Portal Tutorial (7.0.0 and later)
Create A Portal
Navigate to the “Portals” tile on the sidebar or the “Portals” button in menu of the developers console
Create a new portal by clicking + Add
Enter the name description for your 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.
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.
Welcome to your portal!
Delete a portal
- Click on the gear next to your new portal and select Settings
- Click Delete Portal
Confirm the deletion when prompted
Datasources
- Where can datasources be added from?
Left side navigation bar by hovering over the Datasource tab
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?
Left side navigation bar by hovering over the Widgets tab
Scroll down to Containers and drag the pane to the portal
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
- Hover over pane and click on the trashcan.
- 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 ‘+’
Fill in the name of the page and click ‘Apply’
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
Adding children to page
Click on the plus button of the page you wish to add a child page
Add name and parameters
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:
- The current page changes so the portal should display data that is relevant to the URL parameters
- 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
Hover over ‘Modals’ on the side editor and click the ‘+’
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
Select the screen size you’d like to change the layout for by choosing from the dropdown
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
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