Configuring a Dashboard

Setting Up a User Dashboard 

Setting up a dashboard starts with users choosing from a list of pre-configured widgets to configure their dashboards in a Perspective Session based on their individual needs.

To edit the dashboard in a Perspective Session, the user can put the dashboard into Edit mode by clicking the Edit icon at the bottom of the dashboard and deciding what widgets they want, where they want them, and how they want them configured. They can add, remove, resize and configure widgets, including the ability to interact with widgets such entering text in a text field or displaying/hiding components in a widget. You can also remove this control entirely and implement your own by configuring the 'editingToggle' property on the component. Refer to the Dashboard component properties for more details.

The following sections on this page describe how to setup your own dashboard. 

Adding a Widget

There are two ways a user can add a widget in a Perspective Session: by clicking on a single grid cell, or by dragging a grid cell over multiple grid cells that opens an add widget overlay as shown in the image below. Both ways result in displaying the add widget modal which provides a searchable list of all of the available widgets a user may add to their dashboard.

Dragging a grid cell creates an add widget overlay that specifies the desired dimensions of the widget to add. If the desired widget position overlaps other widgets, the overlapped widgets will be moved to any available space on the dashboard. Widgets do not overlap when being added, resized, and moved unless there happens to be no space for a widget so that it is placed within the grid.

On mobile devices, activating a grid cell requires a long-press of about a second. Once a grid cell is activated, you can then drag to create the add widget overlay. The image below shows Widget 1 dropped over the multiple selected grid cells in the dashboard. You'll notice the active widget has a dashed blue border.

Removing a Widget

Click the Edit icon, select the widget, and you'll notice the widget has a dashed blue border indicating the widget is active, then click the Delete 'X'icon in the top right corner to remove the widget from the dashboard. You will then be prompted with a confirmation modal to delete the widget. Click Remove.

Moving a Widget

Put the dashboard in Edit mode, select the widget so that it becomes active (dashed blue border). Drag the widget to the desired position. As you move the widget, any overlapped widgets will be repositioned into the first available space.

Resizing a Widget

To resize a widget, put the dashboard in Edit mode, then simply select the widget you’d like to resize and drag one of the resize handles. If, while resizing, the widget overlaps other widgets, the overlapped widgets will be repositioned into the first available space.

Configuring a Widget

The dashboard allows your users to configure a widget in a Perspective Session. To do this, you need make a few changes to your view and Dashboard component configuration. 

Setting a Widget as Configurable in the Designer

To make a view allow configuration, you need to set the isConfigurable property for each widget that needs to be configured. This will set a param value on your view (in the runtime) that you can use to create a configuration display in your view. The purpose of this parameter is to avoid having to make a separate widgets for each possible variation of the same view.

1. Select the Dashboard component.

2. Expand the availableWidgets parameter, and expand the array object for the widget that you want to make configurable. 

3. Set the isConfigurable property to 'true' for this widget. 

Creating a Configurable View in the Designer

To make a view configurable, you need to do a bit of work to alter what is in the view. This is possible because the Dashboard component was created to use a parameter named configuring that is set to 'true' when the widget is in put into configuration mode. The idea here is to have a second 'mode' or 'display' version of the view that has controls on it to effect the primary display. The best way to do this is to create two containers in your view; one for configuration, and one for display. You can then bind the visibility on each container so only one is shown at a time.

To learn more about using parameters to pass properties, refer to the Perspective Component Properties page. You will not need to pass any value into the param though, it is done automatically for you if you get the param name correct.

1. Create a new Coordinate view. For the example, we named our Configurable_View.

   If you use a Flex container,  some of the settings will be different further down in the example. 

2. In the Property Editor, add a view param. Name the param 'configuring' and set the value to 'true'. Note the spelling and (lack of) capitalization.
   
   
   
   

3. Drag a Coordinate Container component inside your view. Give the container a good name like 'Runtime.' 

4. Add any display components you want.
   

   If you started from an existing view, move all existing components into the new container then make the container fill your entire view.

   1. Deep Select the Configure container.
   2. Drag a Cylindrical Tank component into it.
   3. Bind the value property to a Tag.
   4. Drag a Temperature Gauge component into it.
   5. Bind the value property to a Tag.

5. We need to create a second new container in the view for your configuration. Duplicate the Runtime container. Give the container a good name like 'Configure.' This container will be a sibling to the Runtime container, not inside the Runtime container.
   
   
   
   

6. Add a Checkbox to toggle the temperature component visibility. 
   
   

   If you started with an existing view, this step is completely up to you. You will decide what should be configurable and create controls for that in your configuration container. For example, you could create a list of Tags for the user to select between and display only the selected Tags on a chart.

   1. Deep Select the Configure container.
      
   2. Drag a Checkbox component into it.
   3. Set the Name and Text to "Show Temp".
      
      

7. Now we need to alter the Runtime container components to listen to our new controls.
   

   1. Deep Select the Runtime Container.
   2. Select the Temperature Gauge component.
      
   3. In the Property Editor under META, bind the Visible property to the Selected value of the Show Temp Checkbox component.
      
      
      
      

8. Now we just need to show one container at at time.
   
   

   If you used a Flex container at the start of this example, then use the 'display' property instead of the 'visible' property in the following steps.

   1. Bind the 'visible' property for the Runtime container using an expression. It should be true when the configuring param is false.
      
      
      
      

   2. Bind the 'visible' property for the Configure container using an expression. It should be true when the configuring param is true.
      
      
      
      

9. Save your project and then put the Designer into Preview mode.  When you click on the Temp Show button, you'll see the Temperature component appear or disappear.
   
   
   
   
10. Now you can use this view in your dashboard.

Configuring in the Dashboard Component in the Runtime (Perspective Session)

This section is for the people using the Dashboard in a Perspective Session.

1. To use a configurable widget in the runtime, put the dashboard in Edit mode and select the widget you’d like to configure. 
2. Click the edit icon (pencil) in the top right corner of the widget. The widget's border will change colors from blue to orange (shown in the image below).
3. The view changes to show the ‘configuring’ mode you set up previously for the view, allowing users to configure the widget.
   

Saving Perspective Session Edits and Populating Widgets

Edits that an end user makes in their dashboard in a Perspective Session are not automatically saved and do not persist when the end user's session restarts. A session can be refreshed within the same session. One possible solution for populating widgets for the next editing session is to add a property change script on the 'widgets' prop to listen for changes and then write that value back to a database along with any user information derived from the active session. The value of the 'widgets' prop will be an array of QualifiedValues, which you’ll need to handle accordingly.In similar fashion, consider adding an 'onStartup' event action that will query the database and then populate the 'widgets' prop with the users last saved configuration and optionally populate the 'availableWidgets' prop (possibly for varying user roles).