Set up UI Framework
Learn how to get your developer environment set up to create the front end of your AI application using the C3 AI UI Framework.

Prerequisites

  1. 1.
    Have your C3 AI Suite accessible.
  2. 2.
    Install VSCode.
    • You can use other IDEs, but we recommend using VSCode.
  3. 3.
    • The C3 AI VSCode extension allows developers working within C3 AI Suite to access development features like auto-completion and syntax highlighting. In Developer Portal, go to C3 AI Extensions for VS Code for installation guide.
  4. 4.
    Install Google Chrome. This is the browser that we support.
  5. 5.
    • The Redux DevTools extension is a Google Chrome extension that shows how your application state changes based on your code. Developers who have the Redux DevTool Extensions can troubleshoot their code by seeing the application state change based on their code. Go to Redux DevTools Extension on Google Chrome to install the extension.

Step 1 - Create your directory structure

Once you've set up your development environment, you need to create the framework of your application. The first step is to develop your application package with the correct directory structure.
This section guides you on how to set up your directory and render components, pages, and create routes. For more information on directory structure, go to the Directory and Filename Conventions section under Fundamentals.
UI Framework directory has four main subdirectories: seed, src, config, ui/c3/meta.
1
exampleRepository
2
├── exampleUI
3
| └── seed # route live here
4
| └── config # style, theme template live here
5
| └── src # epics, application state live here
6
│   └── ui/c3/meta #component, page live here
7
│   └── package.json
8
└── repository.json
Copied!

Step 2 - Create components and pages

Components are the reusable building blocks you use to render and fill your webpage with. With UI Framework, you have a wide variety of UI components available. To find the different available components, go to your UI Demo application. To learn more about setup instructions, go to Set up UI Demo.
Pages are layout components that hold other components. The page component is tied to an associated route, making it viewable as a web page. Other layout components are available than the ones shown and used.
To create components and pages, it is mandatory to have the subdirectory /ui/c3/meta/.
The subdirectory /ui/c3/meta/ holds:
  • UI pages files
  • UI components configuration files
It is best practice to separate pages and components files into two separate folders. You have freedom in how you organize your files under ui/c3/meta.

Example - Create a home page using UI Framework

The image shows an example of the UiSdlLayoutNavigation component which holds a Page Title, Navigation Bar, and Layout component.
  1. 1.
    Page Title: UiSdlPageTitle type.
  2. 2.
    Navigation Bar:UiSdlNavMenu component type.
  3. 3.
    Layout component:UiSdlLayoutBase component type that holds a tab panel and a table.

Step 1 - Create layout navigation for your home page.

Under ui/c3/meta subdirectory, create exampleUI.Home.json file with the following code:
1
// exampleUI.Home.json
2
{
3
"type": "UiSdlConnected<UiSdlLayoutNavigation>",
4
"component": {
5
"pageTitle": {
6
"id": "exampleUI.HomeTitle"
7
},
8
"navigation": {
9
"id": "exampleUI.ApplicationNavMenu"
10
},
11
"content": {
12
"id": "exampleUI.HomeContent"
13
}
14
}
15
}
Copied!

Step 2 - Create a home title for your home page.

Under ui/c3/meta subdirectory, create exampleUI.HomeTitle.json file with the following code:
1
// exampleUI.HomeTitle.json
2
{
3
"type":"UiSdlPageTitle",
4
"title": "Smart World"
5
}
Copied!

Step 3 - Create an application navigation menu for your home page.

Under ui/c3/meta subdirectory, create exampleUI.ApplicationNavMenu.json file with the following code:
1
// exampleUI.ApplicationNavMenu.json
2
{
3
"type": "UiSdlConnected<UiSdlNavMenu>",
4
"component": {
5
"itemSections": [
6
{
7
"items": [
8
{
9
"id": "Home",
10
"icon": "HOME",
11
"title": "Home",
12
"redirectRoute": {
13
"urlPath": "/home"
14
}
15
}
16
]
17
}
18
]
19
}
20
}
Copied!

Step 4 - Create a home content for your home page.

The home content is where you refer to the component files that you desire to render on that page.
In this example, we create a component file where we render a table and named that file exampleUI.customTableTypesBasic. Then, we added the file name inside the children's array in the home content file.
If you wish to render a different component, create a JSON file that renders the desired component. Then, reference that JSON file inside the children's array. If you wish to have an empty home page, remove children.
Under ui/c3/meta subdirectory, create exampleUI.HomeContent.json file with the following code:
1
// exampleUI.HomeContent.json
2
{
3
"type": "UiSdlConnected<UiSdlLayoutBase>",
4
"component": {
5
"children": [
6
{
7
"id": "exampleUI.customTableTypesBasic"
8
}
9
]
10
11
}
12
}
Copied!

Step 5 - Create a table component. This is required if you placed the table file name in the home content.

The table component pulls data from SDLDemoMachine. You may need additional dependencies in order to pull from SDLDemoMachine.
If you would like to pull your own data, change the dataSpec in order to pull your desired data.
Under ui/c3/meta subdirectory, create exampleUI.customTableTypesBasic file with the following code:
1
// exampleUI.customTableTypesBasic
2
{
3
"type": "UiSdlConnected<UiSdlDataGrid>",
4
"component": {
5
"paginationConfig": {
6
"pageSize": 5,
7
"pagination": true
8
},
9
"reorderableColumns": false,
10
"filterBar": false,
11
"dataSpec": {
12
"dataType": {
13
"typeName": "SDLDemoMachine"
14
},
15
"columnFields": [
16
{
17
"fieldName": "name",
18
"label": "SDLDemoMachine.name",
19
"searchable": true,
20
},
21
{
22
"fieldName": "category",
23
"label": "SDLDemoMachine.category",
24
"searchable": true
25
},
26
{
27
"fieldName": "location.id",
28
"label": "SDLDemoMachine.location"
29
},
30
{
31
"fieldName": "statusLabel",
32
"label": "SDLDemoMachine.status"
33
}
34
]
35
}
36
}
37
}
Copied!

Step 3 - Create URL

We have created pages and rendered components, but since we do not have a route, we can not access them. We must create routes in order for users to have the ability to access or navigate to different pages and components.
The UiSdlRoute folder must be exactly named and spelled UiSdlRoute.
You can create a URL using either JSON or CSV files. These files must live under the UiSdlRoute folder. The UiSdlRoute folder lives in your seed folder.
1
exampleRepository
2
| └── seed
3
│   | └── UiSdlRoute
4
│   └── ...
5
│   └── package.json
6
└── repository.json
Copied!
Here are examples of routes files. The two files below are functionally equivalent.

MyPage.json

1
{
2
"type":"UiRoute",
3
"id":"/mypagename",
4
"urlPath":"/mypagename",
5
"targetModuleName":"MyModuleName",
6
"targetPageName":"MyPageHome"
7
}
Copied!

pages.csv

1
targetModuleName,targetPageName,id,urlPath
2
MyModuleName,MyPagename,/mypagename,/mypagename
Copied!
Best Practice is to have the urlPath and id fields match.
The targetPageName must match the name of JSON file specific to the page, located in the meta folder; this is how the route is connected to that specific page.
We show an example of how a route is created for a home page.
The urlPath is added to the URL of the website hosting your application.
The URL files can be organized in one of the following ways:
  • Use one CSV file for all of your page routes.
  • Use one JSON file for all of your page routes. Each route is an element in a JSON array.
  • Use one JSON file for each page route.

Example - Create a route for your home page

In order to access the home page, we must create a route. This example builds on top of the previous example.

Step 1 - Create UiSdlRoute folder.

The routes file must live under the UiSdlRoute folder which lives in your seed folder.

Step 2 - Create routes file.

We create a page.csv file. This file is created for the purpose to hold all other routes. You may use other methods mentioned to create routes. To create the home page route, the page.csv file has the following code:
1
targetModuleName,targetPageName,id,urlPath
2
exampleUI,Home,/home,/home
Copied!

Step 4 - Provision your package

Provisioning is the act of compiling and deploying files from your local computer to the C3 AI Suite. In order to see your changes, you must provision. To learn how to provision, go to Provisioning the package.
Common causes of errors are:
- File names not matching Type names
- Reference or collection Fields definitions have misspellings
- Not defining a schema name for an entity type

Step 5 - Check the status of UiBundler

Check the status of UiBundler until the status is completed. UiBundler generates code bundles for front-end code delivery to browsers. For more information on commands on UiBundler, go to Monitor UI deployment.

UiBundler console commands

Check the latest bundling status:
1
UiBundler.latestStatus();
Copied!
Image shows the UiBundler.latestStatus(); and the response.
Force bundling to start:
1
UiBundler.generateBundles()
Copied!

Step 6 - Create Vanity URL

When the application package is deployed, create a VanityUrl to make the application available. If you have a Vanity URL set up for this environment, do not do this step.
The id and name should not be named localhost or have any capitalization.
From the web console, open the developer tools and run:
1
VanityUrl.create({id: "wildcard", name: "wildcard", tenant: "<yourTenant>", tag: "<yourTag>", defaultContent: "c3/index.html"})
Copied!
Run in the static console: c3Grid(VanityUrl.fetch()) to see if it was successfully made.
If the Vanity URL is not created, check your tentant and tag. The tenant and tag must be the same as the tentant and tag in your C3 environment.

Step 7 - Create a DNS entry

You must add a DNS entry for your application Vanity URL.
To add a DNS entry, edit /etc/hosts by doing the following:
  1. 1.
    Add entry for: 127.0.0.1 wildcard
    • If you do not name your vanity URL wildcard, replace wildcard with the name of your Vanity URL.

Step 8 - View the output

You can view your application through your vanity URL, or you can also view the output through UI IDE. The best development practice is to use UI IDE in order to view and troubleshoot your application. To set up UI IDE, go to Set up UI IDE.
You have the basic UI Framework structure. For beginner tutorial, navigate to How To make your mini-app.