C3 AI Documentation Home

Using URLs your application

There are many components in the C3 UI Framework that take URLs as inputs. For example, you may need to render images stored in the ui/content/assets folder of your application and you want to know how to reference the image as url using UiSdlImage. Or you may want to direct a user to a specific URL in your application after a link is clicked.

The purpose of this document is to highlight the different use cases with supported URLs in the UI Framework and how to reference them properly in different contexts.

AppUrl

With the introduction of , the same UI code can be deployed at different paths under the same URL authority, this provides flexibility for cluster managers so they can reuse the same domain for different applications but it makes UI code difficult to manage because it has to handle different paths depending on the configuration.

For example, an application named app might be hosted at the URL authority www.example.com in the following URLs:

  1. www.example.com. When the is serving only one application.
  2. www.example.com/app. When www.example.com is an environment serving multiple applications.
  3. www.example.com/env/app. When www.example.com is a cluster serving multiple environments and applications.

To solve this problem, the C3 UI Infrastructure provides the functionality such that files can be resolved at runtime from the right URL path and so that you don't have to generate different compiled assets for the UI -- one single set of assets can handle any of the scenarios.

With this solution, application developers don't have to worry about how their was configured if they follow the following guidelines.

Absolute URLs

Absolute URLs are URLs that specify the fully qualified URL. One example of an absolute url is https://www.google.com. When navigating to a link that references an absolute URL, the user will be redirected to the fully qualifed URL specified. The entire qualified URL must be specified, otherwise the url will be treated as a relative URL.

Relative URLs

Relative URLs are URLs that are relative to the current app via its AppUrl. Examples of relative URLs include:

  • /demo/demo-page
  • demo/demo-page

In the examples above, the C3 UI Framework will treat any URL with the leading / the same as those without. When specifying a relative url, the cluster, env, and app will automatically be prepended to the beginning of the url.

For example, if your cluster, env, and app are https://example.com/testenv/testapp and your relative URL is demo/page, the final URL will be https://example.com/testenv/testapp/demo/page.

In a production deployment only serving one application, the env, and app are left out. For example, if the cluster is https://example.com and the relative URL is demo/page, the final URL to the route will be https://reliability.com/demo/page.

Static URLs as links

Clicking on a link with an absolute URL will result in directing the user to the absolute URL. Clicking on a link with relative URLs will result in directing users to a page within their C3 application.

For example, components like UiSdlNavMenuItem contain fields that take in URLs. UiSdlNavMenuItem has the redirectRoute.urlPath field which takes in a UrlPath. If the redirectRoute.urlPath is a relative url, clicking on the link will route the user to a page within his or her application. For example, you can create a route to redirect a user to a page called DemoPage by creating a route in UiRoute.csv:

CSV
targetModuleName,targetPageName,name,urlPath
Reliability,DashboardPage,/dashboard/default,/dashboard/default

Then you can create a UiSdlNavMenu that contains a list of UiSdlNavMenuItem which specifies redirectRoute.urlPath field to the urlPath specified above.

JSON
{
  "type": "UiSdlConnected<UiSdlNavMenu>",
  "component": {
    "itemSections": [
      {
        "items": [
          {
            "id": "home",
            "title": "Home",
            "icon": "house",
            "redirectRoute": {
              // could also be: "dashboard/default"
              "urlPath": "/dashboard/default",
            },
          },
        ],
      },
    ],
  },
}

And clicking on the menu item will redirect the user to https://<cluster>/<AppUrl>/dashboard/default.

Static asset URLs for images

For more information on where to place and reference static assets, please see Use static assets in your application.

Static asset URLs can reference absolute URLs by specifying the fully qualified path to the image to render. Static asset URLs can reference relative URLs by specifying a relative URL to the asset stored in the ui/content folder. If you want to display an image stored in the ui/content folder of your application, you can reference the image by using a relative URL.

Below is an example of how you would use an SDL-curated component UiSdlImage to reference the triangle.jpg stored in <package>/ui/content/assets/images:

JSON
{
  "type": "UiSdlConnected<UiSdlImage>",
  "component": {
    "horizontalAlign": "CENTER",
    "altText": "sailboat",
    "size": "LARGE",
    "className": "block",
    "url": "/assets/images/triangle.jpg"
  }
}

Additionally, here also an example of how you would use a custom component with an img tag to render triangle.jpg:

Html
<div>
  <img src="assets/images/triangle.jpg" class="c3-image block" />
</div>

One difference between both examples is that the SDL-curated component has the leading / as part of the URL, but the custom component does not. In these cases, adding the leading / in url does not matter and both will reference a relative url for the image athttps://<cluster>/<AppUrl>/ui/content/assets/images/triangle.jpg.

Using Images Stored in a Blob Storage

The UI framework also supports using images stored in a blob storage such as S3 or GCS by using the server's /file endpoint. For example, the following url https://<cluster>/<env>/<app>/file/gcs://path/to/image.jpg will hit the File API endpoint and return the image stored in that GCS bucket path.

To reference an image that is stored in a GCS bucket in gcs:/c3--gkev8dev/path/to/image.jpg, we can set the url field of an UiSdlImage component to specify the encoded file path of the GCS bucket path like so: file/gcs%3A%2Fc3--gkev8dev%2Fpath%2Fto%2Fimage.jpg so that we can avoid bad request errors.

JSON
{
  "type": "UiSdlConnected<UiSdlImage>",
  "component": {
    "horizontalAlign": "CENTER",
    "size": "LARGE",
    "className": "block",
    "url": "file/gcs%3A%2Fc3--gkev8dev%2Fpath%2Fto%2Fimage.jpg"
  }
}

For a more complex example, imagine a use case where we would like to generate an image url based on a field in UiSdlApplicationState. We need to create a C3 type function to generate the proper url and use advancedDataSpec in the component to call that function. The contextVars field is then used to get the appropriate state value and pass the value as parameter to the C3 type function. Again, we need to make sure that the parameter of the /file API call is properly encoded with the encodeURIComponent function to avoid bad request errors.

JSON
{
  "type": "UiSdlConnected<UiSdlImage>",
  "component": {
    "horizontalAlign": "CENTER",
    "size": "LARGE",
    "className": "block",
    "dataSpec": {
      "dataType": {
        "typeName": "SomeType",
      },
      "contextVars": {
        "itemName": {
          "type": "UiSdlApplicationStateValueParam",
          "id": "SomePackage.ApplicationState",
          "path": "path.to.state.item",
        },
      },
      "advancedDataSpec": {
        "actionName": "getItemImage",
        "actionArgs": {
          "itemName": "${itemName}",
        },
      },
      "field": "imageSource",
    },
  },
}
JavaScript
// SomeType.js
function getItemImage(itemName) {
  const prefix = 'gcs://c3--gkev8dev/path/to/dir';
  const param = encodeURIComponent(`${prefix}/${itemName}.jpg`);
  return {
    imageSource: `file/${param}`,
  };
}

Static asset URLs in scss files

There are instances where you may want to reference a static asset from an .scss file. For example, you may have a static asset stored in <package>/ui/content/assets/grid/triangle.svg. In order to reference the asset from your .scss file, you need to declare it like so:

SCSS
.img {
  /* webpackIgnore: true */
  background-image: url(/assets/images/grid/triangle.svg);
}

You need to make sure you have the /* webpackIgnore: true */ and the / in front of the the asset folder so that the C3 UI Framework knows to retrieve the image from the ui/content folder instead of the working directory where the files are being bundled.

How static asset resolution works

We use a base HTML element to make sure all relative paths are resolved to the right path at runtime. A special cookie, named c3AppUrlPrefix, is set by the UI Infrastructure to indicate what is the path prefix that all static assets and C3 APIs must be served from.

For example, if www.example.com is a cluster , the c3AppUrlPrefix will be set to something like testenv/testapp, indicating that all requests made by the browser are going to be served by the testapp application from the testenv environment, like www.example.com/testenv/testapp/assets/images/logo.svg.

If on the other hand, www.example.com is a vanity , the c3AppUrlPrefix will be empty and the same static image would be served from www.example.com/assets/images/logo.svg.

Was this page helpful?