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.
The Dashboard component has a built in edit/play toggle icon located at the bottom of the component as shown in the image below. Users can enter into and out of Edit mode by clicking this control. 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.
Widget's Minimum Dimensions
When adding a widget, if the desired dimensions are less than the configured minimum dimensions, the desired dimensions will get overridden by the minimum dimensions. If a single grid cell is clicked, the configured default dimensions will be applied, if and only if, the default meets the required minimum dimensions, otherwise the minimum dimensions are applied. By default, the minimum and default dimensions for a widget are 1x1.
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 '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. Press Remove.
Moving a Widget
Put the dashboard in Edit mode, select the widget so that it becomes active (dashed blue border), and drag the widget to the desired position. As you move the widget, any overlapped widgets will be packed into the first available space.
Resizing a Widget
To resize a widget, make sure the dashboard is 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 packed 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.
Select the Dashboard component.
Expand the availableWidgets parameter, and expand the array object for the widget that you want to make configurable.
Set the isConfigurable property to 'true' for this widget.
Creating a Configurable View in the Designer
To make a view configurable, you need alter what is in the view. First, there is a param passed in named
configuring that is set to 'true' when the widget is in configuration mode.The best way to take advantage of 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.
Add a Param to your view named '
Move any existing display components on your view into a container. Make sure to give the container a good name like 'Runtime.'
Create a new container for your configuration. Make sure to give the container a good name like 'Configure.'
This step is completely up to you. You should decide what should be configurable and create controls for that in your configuration container. For example, you could add a Checkbox that toggles the temperature component on a tank display, or you could create a list of Tags for the user to select between and display only the selected Tags on a chart.
Alter your Runtime container components to listen to those controls.
Bind the visible property for the Runtime container to show when the
configuringparam is 'false'.
Bind the visible property for the Configure container to show when the
configuringparam is 'true'.
Configuring in the Dashboard Component in the Runtime
This section is for the people using the Dashboard in a Perspective Session.
- To use a configurable widget in the runtime, put the dashboard in Edit mode and select the widget you’d like to configure.
- 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).
- 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).