C3 AI Documentation Home

Use dynamicValueSpec to create dynamic text configurations

UI components often display text that reflects inputs from the surrounding environment. These inputs can include page context, component state, or URL parameters. The UiSdlDynamicValueSpec Type provides a declarative way to inject dynamic text directly into your UI metadata.

The C3 Agentic AI Platform automatically resolves these dynamic values at runtime. It looks up context variables, replaces them in the string, and applies any configured transforms before rendering the component. This approach removes the need for custom logic to fetch or format display text.

Define a route

Configure the route to capture a URL parameter. This example defines a parameter called myUrlParam. The framework injects this value into the component context when the page loads.

CSV
/* examplePackage/metadata/UiSdlRoute/UiSdlRoute.csv */

targetModuleName,targetPageName,name,urlPath
examplePackage,PageLayout,/{{myUrlParam}},/{{myUrlParam}}

This enables the page to receive a value like /Hello and inject "Hello" as the value for myUrlParam.

Add a static translation entry

Start with a basic translation that does not include variables. This defines a label with a constant value.

CSV
/* examplePackage/metadata/Translation/en.csv */

id,locale,key,value
en.MyApp.Label,en,MyApp.Label,Button label

This label provides a default value, Button label, for the button text.

Display the static translation on a button

Reference the translation key directly in the button configuration. The UI always renders the label "Button label".

JSON
/* examplePackage/ui/c3/meta/examplePackage.BasicButton.json */

{
  "type": "UiSdlConnected<UiSdlButton>",
  "component": {
    "content": "MyApp.Label"  // Static text pulled from the translation key
  }
}

Inject a dynamic value using UiSdlDynamicValueSpec

Update the translation entry to include the variable {urlParam}.

CSV
/* examplePackage/metadata/Translation/en.csv */

id,locale,key,value
en.MyApp.Label,en,MyApp.Label,Button label {urlParam}

Modify the button component to use UiSdlDynamicValueSpec. The framework resolves the value of myUrlParam and injects it into the urlParam placeholder.

JSON
/* examplePackage/ui/c3/meta/examplePackage.DynValueSpecButton.json */

{
  "type": "UiSdlConnected<UiSdlButton>",
  "component": {
    "content": {
      "type": "UiSdlDynamicValueSpec",       // Indicates this value is resolved dynamically
      "dynamicValue": "MyApp.Label",         // Uses the translation key with a placeholder
      "vars": {
        "urlParam": {
          "type": "UiSdlPageParam",          // Specifies this value comes from a page parameter
          "path": "myUrlParam"               // Uses the route-defined parameter
        }
      }
    }
  }
}

If the user navigates to/Hello, the button label displays:

Text
Button label Hello

Provide a fallback label using a transform

Apply a transform when the URL parameter is missing or empty. The transform sets a default value to prevent rendering an incomplete label.

Button with fallback logic

This example enhances the previous one by using a dataTransforms to the urlParam definition.

JSON
/* examplePackage/ui/c3/meta/examplePackage.DynValueSpecButtonWithFallback.json */

{
  "type": "UiSdlConnected<UiSdlButton>",
  "component": {
    "content": {
      "type": "UiSdlDynamicValueSpec",        // Uses a dynamic translation string
      "dynamicValue": "MyApp.Label",          // Translation key: "Button label {urlParam}"
      "vars": {
        "urlParam": {
          "type": "UiSdlPageParam",           // Fetches from the page parameter
          "path": "myUrlParam",               // Reads from the current URL
          "dataTransforms": ["FallbackLabelTransform"]  // Applies fallback logic
        }
      }
    }
  }
}

Define the transform

Declare a new transform entity that applies fallback behavior.

Type
/* examplePackage/entity/FallbackLabelTransform.c3typ */

@typeScript
type FallbackLabelTransform mixes UiSdlDataTransform<string, string> {
  transform: ~ ts-client
}

The transform runs after the value from the URL resolves. If the value is missing or an empty string, the transform replaces it with a default fallback.

Implement the transform

Use TypeScript to define the transformation logic.

TypeScript
// examplePackage/entity/FallbackLabelTransform.ts

export function transform(input: string): string {
  // Return fallback if the input is missing or empty
  if (!input || input.trim() === "") {
    return "Default";  // Use this value when the URL provides nothing
  }

  return input;  // Use the resolved value as-is
}
  • The input parameter contains the resolved label from the URL or context.
  • If the input is empty or missing, the transform returns "Default".
  • Otherwise, the transform returns the original input.

When the URL path is not defined or empty, the button label displays:

Text
Button label Default

When a value exists (for example, /Hello), the button displays:

Text
Button label Hello

Use UiSdlDynamicValueSpec to inject dynamic text into UI components. Start with a static label. Add a dynamic variable with a URL parameter. Use a transform to supply a default when a value is missing. This approach keeps your components flexible and eliminates the need for imperative logic.

Was this page helpful?