Getting Started

This guide will help you get familiar with ClearBlade Portal and demonstrate the usefulness of a growing collection of plugins.

Creating A Portal

First, Log-in to the ClearBlade Platform and select ‘portal’ in the system that you wish to link a portal.
CLick portal on desired system

You will be directed to the portal management screen where you will see a table of your portals and plugins. Since we do not have any portals, let’s create a new one by clicking ‘new’ on the left of the top navigation bar.
Click to add new portal

Here, let’s select Portal and give it a name. Leave the template selection as ‘empty’. This is where you could clone existing portals or select from pre-built templates.
Create a new portal

Before we jump into building our portal, we need to give permission for our users to access and edit the portal. Click the wrench next to your new portal and select the security tab.
Open portal security settings

This step assumes we have users in our system, if not, please add users in Auth -> Users.
Giving the authenticated role access to read will allow these users to sign in and operate a portal. 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

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!
Login to portal

Adding Datasources

Before we start adding widget’s to our portal, lets add a few sources to interact with our ClearBlade system. We will provide an overview of how sources work by setting up a Code, Collection, and Message Topic source. Refer to docs for information regarding all sources.

Code Source

For this example, let’s make a code service in the ClearBlade Platform called helloPortal that responds with “Hello :” plus a random number [0,100).
Sample code service

Similar to giving access to our portal, we need to give access to our code service. Open the code settings and under security let’s add Authenticated and Administrator. Note that all users are given the Authenticated, so we could have stopped there and the Administrators would have access, but in a situation where access may be spread amongst many roles, it is important that every role with access to a portal using this service is granted access.
Give role access

Now that our service is set up, let’s navigate back to our portal and click “add” under datasources and select “code”.
Add Source

Here we enter a local name for our datasource and the name of our service in our ClearBlade system. We will set a 10 second interval, and since our service does not require parameters, we will leave our payload as an empty object. Refresh interval and default payload are available if you want your source to update periodically. In some cases you will only want to update your source when triggered by a plugin rather than loop. Create Code DS

You will notice that the “HelloPortalService” updates every 10 seconds. We will use that source in a few minutes, but first let’s set up a message topic and collection datasource.

Collection Source

Let’s start by adding a collection to our ClearBlade Platform system. First create a json file or saveAs json with weeklyStats.json, then import this sample collection into ClearBlade Platform system.
Create Code DS

Again, we will need to add our roles to access the collection. Collection settings -> Security
Give role's access to portal

Now, let’s navigate back to our portal and add the collection source.
Add Collection Source

Again the name is a local name to refer to our source in the portal and the collection name is what name we gave to our ClearBlade system data collection. We will leave columns blank so we can have access to all the data in the collection. Since we are not expecting this collection to update frequently, we are going to set the refresh interval for every minute.
Configure Collection Source

You will notice that the “WeeklyUseCollectionSource” updates every 60 seconds. We will use that source in a few minutes, but first let’s set up our message topic source.

Message Topic Source

Because we can create new topics by publishing, there is no need to already have a topic in our ClearBlade system. Although in most scenarios you will already have a message topic set up. Let’s give our roles permission to publish, read and update topics. In your ClearBlade Platform system, navigate to Auth -> Roles. For our Authenticated and Administrator roles under “Message History”, add publish, read and update.
Give role's access to messaging

Now we can add our message topic datasource. Navigate back to your portal and click “add” under “datasources”. Select “Message Topic”. Again the name will be a local reference within your portal and the topic corresponds to a ClearBlade platform message topic.
Add message data source

Using Plugins / Widgets

You have set up three datasources, now let’s create dynamic widgets that interact with your ClearBlade Platform system.

Using Our Code Source

We’ll start with a basic text widget that display’s the most recent HelloPortalService response. First let’s delete the default pane and add our own.
Create and delete a pane

Now let’s add a widget.
Add widget to pane

Select “Text”. To understand the options of each widget view our resources in docs. We will give the widget a title and select a Dynamic content type. This is where we link our HelloPortalService. Because a code source responds with an object ({ results: "", success: bool}), we need to format the response to the expected format of our widget. Within “incoming parser” replace with return this.datasource.results;. Close the parser and click save. Once your source updates, you should see the response from the code service, and proceeding updates will update the widget’s content.
Text Widget

Before moving on to using our next datasource, let’s explore the use of a parser by using the same response to update a gauge widget. In the same pane, lets add another widget and select Gauge.
Add Widget

Let’s leave all the defaults and just change the gauge value to “dynamic” and select “HelloPortalService”. Since the gauge expects an integer, we need to edit the parser to return the random number after “hello :“. Gauge Widget Options
Gauge incoming parser
After modifying your parser, click close and save. You’ll see your gauge adjust as the source updates. Note: parsers are where you should provide error handling, for instance if the response was null or it’s success attribute was false.

You’ve now used a datasource in two different widget’s by utilizing parsers. As your source updates the status and gauge will update.
Working with data sources

Using Our Collection Source

Since our WeeklyStatsSource is a collection of bandwidth use for the last week, let’s use it to build a bar graph. Start by adding a new pane then add a “Bar Graph” widget to that pane.
Add a bar graph widget

We need to modify the source’s data to the widget’s expected format, so let’s set up our parser. Collection format [{data: {bandwidth: 50, day: "Mon", item_id: "uniqueid"}, destroy: fn, refresh: fn, save: fn}] so let’s parse through the data and format to expected: [{x:"domain", y: 00}]
Setup Graph Parser

Once setup, click close and “save”. You should now see your bar graph populated with the data in WeeklyStatsSource.
Example bar graph

Using Our Messaging Source

Let’s build a simple interface to publish messages to our topic. First, create a new pane and add an “input” widget. By selecting a dynamic value, we are able to trigger the messaging data source when we leave our input. This will cause the value of out input field to be published to examplePortalTopic. Because we just want basic text, we’ll leave the outgoing parser to the default, returning the widget’s value.
Input widget

Before trying out our input widget, let’s setup a text widget to display the most recent message. In the same pane, add a text widget. Since our message source is already returning data as text, we can leave our incoming parser to return the source’s data.
Text widget

Now we can try out our widgets. Type a message into the input field and click off. You will see the text field pupulate with the most recent message.
Using the input widget

If you navigate to messaging in your ClearBlade Platform system, you will see the messages sent by your portal along with the user_id that published the message.
Messaging results in ClearBlade