This documentation and the Cisco Observability Platform functionalities it describes are subject to change. Data saved on the platform may disappear and APIs may change without notice.
UI Enhancements
This page will teach you how to configure DashUI to create UI components and map them to entities for the Space Fleet solution. We will focus on configuring DashUI to render a spacecraft speed widget on the details of an entity page. We will only focus on key points in this walkthrough, but you can download the Space Fleet solution to see the source code.
We'll walk you through the following sections:
- Dependencies
- Location of DashUI Files
- DashUI Types and Objects
- Entity Pages
- DashUI Templates
- Entity Configurations
- Declaration of DashUI Objects in the Manifest
- DashUI Rendering in the Solution
- Next Steps
1. Dependencies
DashUI provides the ability to configure layouts and content in the UI.
The Space Fleet's manifest.json file specifies the dashui dependency that is needed to use DashUI.
{
"manifestVersion": "1.0.0",
"name": "Space Fleet",
"solutionVersion": "<solution-version>",
"dependencies": [
"...",
"dashui"
],
"..."
}
2. Location of DashUI Files
You are not required to store DashUI files in any specific location, but the Space Fleet solution organizes the DashUI knowledge object files in the /objects/dashui directory. The knowledge object files are JSON configuration based on the DashUI knowledge types that we'll discuss in the next section.
In /objects/dashui/ directory, we'll be looking at the DashUI knowledge types templates and entity pages:
/objects/dashui/entityPages/objects/dashui/templates
We'll also take a closer look at the the following knowledge object files of those knowledge types:
/objects/dashui/entityPages/spacecraft.json- This object file will define two types of entity pages, the list and the detail pages./objects/dashui/templates/spacecraft/ecpDetails.json- Because the speed widget is on the detail page, we're going to focus on the template for the details page:ecpDetails.json.
See Solution Structure for more information about the manifest.json file and the solution directory structure.
3. DashUI Types and Objects
The Cisco Observability Platform is codeless and instead uses configuration in the form of JSON. The use of JSON enables the code to be portable, easily stored in the Knowledge Store for retrieving and saving, and ensures that the platform is more secure.
DashUI provides you with predefined types that you create object files from. The types are like classes or templates to create objects or instances for your solution.
We will look at the following two types and these objects based on those types:
- entityPage -
/objects/dashui/entityPages/spacecraft.json - template -
/objects/dashui/templates/spacecraft/ecpDetails.json
4. Entity Pages
The user interface of Cisco Observability Platform solutions, such as Space Fleet, is based on rendering entity pages in the UI. The entity pages have different views depending on the scope. The entity page can have three scopes offering unique views: detail, list, and group.
As we introduced briefly, the entity page for the spacecrafts is configured with the object /objects/dashui/entityPages/spacecraft.json.
We can see that the entityPage for spacefleet:spacecraft defines templates for two scopesType values, detail and list, as shown in the following example:
[
{
"kind": "entityPage",
"scopeType": "detail",
"entityType": "spacefleet:spacecraft",
"template": "spacefleet:spacecraftEcpDetails"
},
{
"kind": "entityPage",
"scopeType": "list",
"entityType": "spacefleet:spacecraft",
"template": "spacefleet:spacecraftEcpList"
}
]
The list scope shows a list of spacecraft entities in a table on an entity page. In the Cisco Cloud Observability application, the entity page with the scope list is called the List View.
The detail scope for the spacecraft entity shows many facets displaying details about one spacecraft entity, such as the Spacecraft Speed, that we're going to look at more closely. In the Cisco Cloud Observability application, the entity page with the scope detail is called the Detail View.
See also Entity Centric Pages.
5. DashUI Templates
The DashUI templates arrange, configure, and bind data to a UI component. Your template can be predefined or combine components and add styling.
The template that we will be looking at in this walkthrough is the one for the spacecraft ECP details page as we're going to focus on the speed widget:
/objects/dashui/templates/spacecraft/ecpDetails.json
Two important keys of the template file are the kind and the target. The key kind refers to the document type of the template (as required by the Knowledge Store), and the target specifies that it applies to entities of the type.
In ecpDetails.json, the kind specifies that the type is template, and the target uses the * to denote that the template to all of the entities of the type.
[
{
"kind": "template",
"name": "spacefleet:spacecraftEcpDetails",
"view": "default",
"target": "*",
"..."
},
"..."
]
The element key represents the actual content of the template. Template elements are always configurations of building blocks. Building blocks can either be atomic or other templates. You specify the type of building block with the key instanceOf.
The element for the spacecraft ECP details page is html as shown in the following example, by the first reference to instanceOf.
[
"...",
{
"...",
"element": {
"instanceOf": "html",
"style": {
"display": "flex",
"flexDirection": "column",
"gap": 12
},
"elements": [
"..."
]
}
}
]
The ECP details page has many child elements composing the page. We will look at the child element for the Spacecraft Speed widget. The Spacecraft Speed widget uses the building block cartesian with a simple key for the height, denoted by props and children for the widget label (name: "Spacecraft Speed") as well as some data specified by the metric key, and the key type for "LINE", which indicates that the metrics should be rendered as a line graph.
{
"...": "...",
"elements": [
"...",
{
"instanceOf": "card",
"props": {
"title": "Spacecraft Speed"
},
"elements": [
{
"instanceOf": "cartesian",
"props": {
"style": {
"height": 250
}
},
"children": [
{
"props": {
"name": "Spacecraft Speed"
},
"metric": {
"name": "spacefleet:speed",
"source": "RS-datagen",
"y": {
"field": "value"
}
},
"type": "LINE"
}
]
},
"...": "..."
]
},
{
"...": "..."
}
]
}
See also Templates and dashui-template.
6. Entity Configurations
We saw a lot of different properties (key-value pairs) for the ECP details page in the last step but could have gone into more detail about their usage and functionality. In this section, we'll look at a few essential keys used to configure the UI of ECP pages in more depth and point you to more comprehensive documentation afterward.
One of the most important keys found in ecpDetails.json is the html key that denotes a div HTML element. We saw that the body of the ECP details page is added to the page as a div element, a parent container, because of html being the value for instanceOf:
[
"...",
{
"...",
"element": {
"instanceOf": "html",
"style": {
"display": "flex",
"flexDirection": "column",
"gap": 12
},
"..."
},
"..."
}
]
Now within the parent div element, you have elements that are displayed as flex elements in flex-direction of column, which displays the elements in a vertical column with a specified gap between elements of 12 pixels:
"element": {
"instanceOf": "html",
"style": {
"display": "flex",
"flexDirection": "column",
"gap": 12
},
"..."
}
The Spacecraft Speed widget is displayed with the wrapper element card. The card wrapper lets you embed a table of building block elements of different instance types. The first element of card is a cartesian instance type that renders a chart. The props key enables you to style the chart. The children elements consist of a name for the card name, a metric element that uses RS-datagen (a data generator) of type LINE that specifies the type of chart to render (line chart).
{
"...": "...",
"elements": [
"...",
{
"instanceOf": "card",
"props": {
"title": "Spacecraft Speed"
},
"elements": [
{
"instanceOf": "cartesian",
"props": {
"style": {
"height": 250
}
},
"children": [
{
"props": {
"name": "Spacecraft Speed"
},
"metric": {
"name": "spacefleet:speed",
"source": "RS-datagen",
"y": {
"field": "value"
}
},
"type": "LINE"
}
]
}
]
},
"...": "..."
]
}
We've touched on some of the entity configurations in this section: html, card, element, instanceOf, props, and cartesian. See Create an Entity Centric Page for a more comprehensive discussion about the configurations for creating an entity page.
7. Declaration of DashUI Objects in the Manifest
The solution needs to know the location and type of your object files. The manifest.json maps out the object files for data models, access management, workflows, data collection, and UI enhancements.
We're going to focus on the DashUI object files that we have looked at throughout this walkthrough. You declare the directories where your DashUI objects are located and specify the DashUI type. The type dashui:template and directory for our Spacecraft object templates are declared in the first object, and the directory and type dashui:entityPage are declared in the second object.
{
"...",
"objects": [
"...",
{
"type": "dashui:template",
"objectsDir": "objects/dashui/templates/spacecraft"
},
{
"type": "dashui:entityPage",
"objectsDir": "objects/dashui/entityPages"
},
"..."
]
}
8. DashUI Rendering in the Solution
Congratulations! We've learned how to include DashUI in our solutions, the relationship between DashUI types and object files, the template for the ECP Detail View, and how to configure an entity with building blocks and wrappers to include content on the ECP page.
Let's look at how that gets rendered into an actual UI. The screenshot of the Detail View of the Spacecraft ECP page calls out that the entire page is composed of an object file (ecpDetails.json) based on the type spacefleet:spacecraft. Within that template ecpDetails.json, we can see that the Spacecraft Speed widget is an element in the page using the building block card.
9. Next Steps
As this is a walkthrough, we only covered a few of the essential concepts and features of DashUI. We hope this gets you started and whets your appetite to begin creating solutions with DashUI and build upon what we covered.
What should you do next? We recommend you start learning more about entity pages, the Authoring Tool that helps you build UI components, and look at the other DashUI types:
- DashUI Basics
- DashUI Tools
- DashUI Types: