Tutorial - Create a Home Page with Navigation Bar
This tutorial guides you in creating a home page with a navigation bar.
What a directory of a UI Framework can look like.
1
exampleRepository
2
├── exampleUI
3
│   └── ...
4
│   └── ui/c3/meta
5
│   | └── components
6
│   | | └── Common
7
│   | | | └── exampleUI.ApplicationNavMenu
8
│   | | └── Home
9
│   | | | └── exampleUI.HomeContent.json
10
│   | | | └── exampleUI.HomeTitle.json
11
│   | └── pages
12
│   | | └── exampleUI.Home.json //Home Page
13
│   └── package.json
14
└── repository.json
Copied!

Components

All component files for your application are placed in the /ui/c3/meta subdirectory of your application package.
The files under /ui/c3/meta/ directory can be organized in any manner desired, but it is best practice to separate your pages and components into separate folders.

Home page configuration

This home page holds three components:
  1. 1.
    a title
  2. 2.
    navigational menu
  3. 3.
    content layout component.

Step 1 - Create Home page configuration

You must create a subdirectory of: /ui/c3/meta/ and must place the home page JSON file under /ui/c3/meta/ subdirectory.
The name of the JSON file that renders your home page is important because the routes refer to the file name in order to create the connection between the page and route. We name the JSON home page file exampleUI.Home because:
  • exampleUI: package name
  • Home: the name of the page
The home page holds a title, navigation menu, and home content. The home page knows what to render because we indicated the desired component in the UiSdlLayoutNavigation component. We must use the exact name of the files we want to render. Capitalization does matter.
Step 1 - Create the exampleUI.Home.json.
exampleUI.Home.json
1
{
2
"type": "UiSdlConnected<UiSdlLayoutNavigation>",
3
"component": {
4
"pageTitle": {
5
"id": "exampleUI.HomeTitle"
6
},
7
"navigation": {
8
"id": "exampleUI.ApplicationNavMenu"
9
},
10
"content": {
11
"id": "exampleUI.HomeContent"
12
}
13
}
14
}
Copied!
Step 2 - Create your page title component. Notice how exampleUI.Home.json refers to the file name of the pageTitle.
exampleUI.HomeTitle.json
1
{
2
"type":"UiSdlPageTitle",
3
"title": "Example UI Framework"
4
}
Copied!
Step 3 - Create your application navigation bar
exampleUI.ApplicationNavMenu.json
1
{
2
"type": "UiSdlConnected<UiSdlNavMenu>",
3
"component": {
4
"itemSections": [
5
{
6
"items": [
7
{
8
"id": "HOME",
9
"icon": "HOME",
10
"title": "HOME",
11
"redirectRoute": {
12
"urlPath": "/home"
13
}
14
}
15
]
16
}
17
]
18
}
19
}
Copied!
Step 3 - Create content layout component. Inside the component field is where we refer to the name of the desired component files that we want to render.
create exampleUI.HomeContent.json
1
{
2
"type": "UiSdlConnected<UiSdlLayoutBase>",
3
"component": {
4
5
}
6
}
Copied!

Step 2 - Create home page URL

This is where we are in the directory:
1
exampleRepository
2
| └── seed
3
│   | └── UiSdlRoute
4
│   └── ...
5
│   └── package.json
6
└── repository.json
Copied!
You can create URLs using JSON or CSV files.
Mandatory Practices:
UiSdlRoute folder
route files must live here.
targetPageName
must match the file name. This is not including the package name.
targetModuleName
must match the package name.
Here are some examples. The two files below are functionally equivalent.

MyPage.json

1
{
2
"type":"UiSdlRoute",
3
"id":"/home",
4
"urlPath":"/home",
5
"targetModuleName":"exampleUI",
6
"targetPageName":"Home"
7
}
Copied!

pages.csv

1
targetModuleName,targetPageName,id,urlPath
2
exampleUI,Home,/home,/home
Copied!
Best Practice is to have the urlPath and id fields match.

Step 3 - Provision your package

Provisioning is the action of compiling and deploying files from your local computer to the C3 AI Suite. In order to see your changes, you must provision. If you do not know how to provision, go to the Provisioning Guide in developer portal.
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 4 - Run UiBundler

Run UiBundler.latestStatus() to see when your UiBundler is completed.
UiBundler console commands

Step 5 - Create Vanity URL

When the application package is deployed, create a VanityUrl to make the application accessible.
When creating the VanityUrl, the id and name should not have capitalizations, alphanumerics or punctuations. From the static console, open the developer tools and run:
1
VanityUrl.upsert({id: "tester", name: "tester", tenant: "yourTenant", tag: "yourTag", defaultContent: "c3/index.html"})
Copied!
Run 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 6 - Create a DNS entry

You must add a DNS entry for your application Vanity URL.
To add a DNS entry
  1. 1.
    edit the /etc/hosts file
  2. 2.
    add entry for: 127.0.0.1 <name of Vanity URL>

Step 7 - View the output

Once the bundling is done and the vanity url is made, go to the url: <vanityUrl>/home.
You can also view your output through UI IDE.

Development Workflow

The best development workflow practice is:
  1. 1.
    Complete and save code change.
  2. 2.
    Close UI IDE.
  3. 3.
    Provision your package.
  4. 4.
    Review the status of uiBundler.
  5. 5.
    Open UI IDE once provision and bundle is complete.