Copy page

Basics

Data-Driven Menus

Data-Driven Menus

Data-driven menus dynamically generate options from API data instead of hardcoding menu choices. The engine fetches a list from an HTTP endpoint and renders it as selectable options with automatic pagination.

Overview

A data-driven menu:

• Fetches data from an HTTP endpoint on menu entry
• Applies optional filter, sort, and limit transformations
• Renders items as numbered menu options
• Paginates long lists automatically
• Stores the selected item in session for downstream use

Basic Example

DSL Definition

Code
application "MyStore" {
  name = "My Store App"
  short_code = "*123*5#"
  version = "1.0.0"
  start_block = "MainMenu"

  options {
    http_base_url = "https://api.mystore.com"
  }

  menu "MainMenu" {
    text = "Welcome to My Store"
    
    option "1" {
      label = "Browse Products"
      goto = "ProductList"
    }
  }

  # Data-driven menu - fetches products from API
  menu "ProductList" {
    text = "Available Products:"
    
    data_source {
      type = "http"
      method = "GET"
      url = "/products?category=electronics"
      response_array_path = "data.items"
      
      display_template = "{{name}} - ${{price}}"
      selected_variable = "selectedProduct"
      on_select = "ProductDetail"
      
      page_size = 5
      empty_message = "No products available"
      error_menu = "LoadError"
    }
  }

  menu "ProductDetail" {
    text = "{{selectedProduct.name}}\nPrice: ${{selectedProduct.price}}"
    
    option "1" {
      label = "Add to Cart"
      goto = "AddToCart"
    }
    option "0" {
      label = "Back"
      goto = "ProductList"
    }
  }
}

User Experience

When user navigates to ProductList:

1. Engine fetches GET https://api.mystore.com/products?category=electronics
2. API response: {"data": {"items": [{"name": "Phone", "price": 299}, ...]}}
3. Engine renders:

Code
Available Products:
1. Phone - $299
2. Tablet - $499
3. Laptop - $899
4. Watch - $199
5. Earbuds - $79
9. More
0. Back

User presses "2" → selectedProduct = {"name": "Tablet", "price": 499, ...} → navigates to ProductDetail.

Data Source Configuration

Required Fields

Field	Description
url	HTTP endpoint URL (absolute or relative to http_base_url)
display_template	Template for rendering each item label
on_select	Menu or action to navigate to when item is selected

Optional Fields

Field	Default	Description
type	"http"	Data source type (currently only HTTP supported)
method	"GET"	HTTP method
response_array_path	(root)	JSON path to extract array from response
selected_variable	"selectedItem"	Session variable name for selected item
page_size	5	Items per page
filter	(none)	Filter expression to include/exclude items
sort_by	(none)	Field name to sort by
sort_order	"asc"	Sort direction: "asc" or "desc"
limit	(none)	Maximum items to display
empty_message	"No items available"	Message when list is empty
empty_goto	(none)	Menu to auto-redirect when empty
error_menu	(none)	Menu to navigate on fetch error
timeout_seconds	30	Request timeout
retry_count	2	Retry attempts on failure
retry_delay_ms	500	Delay between retries in milliseconds

Filtering

Filter data before display using expressions:

Equality Filter

Code
data_source {
  url = "/products"
  display_template = "{{name}}"
  on_select = "ProductDetail"
  
  # Only show active items
  filter = "status == 'active'"
}

Numeric Comparison

Code
data_source {
  url = "/products"
  display_template = "{{name}} - ${{price}}"
  on_select = "ProductDetail"
  
  # Only items under $100
  filter = "price < 100"
}

Session Variable Filter

Code
data_source {
  url = "/products"
  display_template = "{{name}}"
  on_select = "ProductDetail"
  
  # Filter by user's membership tier stored in session
  filter = "tier == '{{session.userTier}}'"
}

Supported Operators

• == - Equals
• != - Not equals
• >, >= - Greater than (numeric)
• <, <= - Less than (numeric)

Sorting

Sort items before display:

Code
data_source {
  url = "/products"
  display_template = "{{name}} - ${{price}}"
  on_select = "ProductDetail"
  
  sort_by = "price"
  sort_order = "asc"  # or "desc"
}

Limiting Results

Cap the number of items shown:

Code
data_source {
  url = "/products"
  display_template = "{{name}}"
  on_select = "ProductDetail"
  
  sort_by = "price"
  sort_order = "asc"
  limit = 10  # Top 10 cheapest products
}

Transformation order: fetch → filter → sort → limit → paginate

Pagination

Automatic Pagination

Lists longer than page_size are automatically paginated:

• First page: Shows items 1-N with "More" option (key 9)
• Middle pages: Shows items with "More" and "Previous" (keys 9 and 8)
• Last page: Shows remaining items with only "Previous" (key 8)
• Single page: No pagination options shown

Custom Labels

Code
data_source {
  url = "/items"
  display_template = "{{name}}"
  on_select = "ItemDetail"
  
  page_size = 7
  next_label = "Next Page"
  previous_label = "Go Back"
}

Display Templates

Use {{field}} syntax to render item data:

Simple Field

Code
display_template = "{{name}}"
# Output: "Phone"

Multiple Fields

Code
display_template = "{{name}} - ${{price}}"
# Output: "Phone - $299"

Nested Fields

For items with nested objects:

Code
display_template = "{{name}} ({{details.brand}})"
# Output: "Phone (Samsung)"

Using Selected Items

After selection, the item is stored as JSON in session data and accessible via the selected_variable name:

In Menu Text

Code
menu "Confirmation" {
  text = "Confirm: {{selectedProduct.name}}\nPrice: ${{selectedProduct.price}}"
  
  option "1" {
    label = "Confirm"
    goto = "ProcessOrder"
  }
}

In HTTP Actions

Code
action "ProcessOrder" {
  type = "http_call"
  method = "POST"
  url = "/orders"
  body = {
    product_id = "{{selectedProduct.id}}"
    amount = "{{selectedProduct.price}}"
    msisdn = "{{session.msisdn}}"
  }
  on_success = "OrderComplete"
}

Error Handling

Error Menu

Navigate to an error menu when data fetch fails:

Code
menu "Products" {
  text = "Products:"
  
  data_source {
    url = "/products"
    display_template = "{{name}}"
    on_select = "ProductDetail"
    
    error_menu = "LoadError"
    retry_count = 3
    timeout_seconds = 10
  }
}

menu "LoadError" {
  text = "Could not load products.\nPlease try again."
  
  option "1" {
    label = "Retry"
    goto = "Products"
  }
  option "0" {
    label = "Main Menu"
    goto = "MainMenu"
  }
}

Empty Results

Handle empty data gracefully:

Code
data_source {
  url = "/products?category={{session.category}}"
  display_template = "{{name}}"
  on_select = "ProductDetail"
  
  empty_message = "No products found in this category"
  empty_goto = "CategorySelect"  # Auto-redirect to category selection
}

Authentication

Data sources support the same authentication options as HTTP actions:

API Key

Code
data_source {
  url = "/products"
  display_template = "{{name}}"
  on_select = "ProductDetail"
  
  auth {
    type = "api_key"
    header = "X-API-Key"
    value = "{{secrets.api_key}}"
  }
}

OAuth2 Client Credentials

Code
data_source {
  url = "/products"
  display_template = "{{name}}"
  on_select = "ProductDetail"
  
  auth {
    type = "oauth2_client_credentials"
    token_url = "{{env.AUTH_URL}}/oauth/token"
    client_id = "{{secrets.client_id}}"
    client_secret = "{{secrets.client_secret}}"
    scope = "products:read"
  }
}

Best Practices

1. Keep page sizes small - USSD screens are limited; 5 items per page is usually optimal
2. Use meaningful display templates - Show enough info for users to make a selection
3. Always configure error handling - Network failures are common on mobile
4. Filter at the API when possible - For better performance, filter in the API query string rather than client-side
5. Test pagination - Verify navigation works correctly across all pages
6. Handle empty states - Provide clear messages or redirects when no data is available

Example: Complete Product Browser

Code
application "ProductBrowser" {
  name = "Product Browser"
  short_code = "*123#"
  version = "1.0.0"
  start_block = "Categories"

  options {
    http_base_url = "{{env.API_BASE_URL}}"
    global_actions {
      back_key = "0"
      home_key = "00"
    }
  }

  # Category selection (static menu)
  menu "Categories" {
    text = "Select a category:"
    
    option "1" {
      label = "Electronics"
      set = { category = "electronics" }
      goto = "ProductList"
    }
    option "2" {
      label = "Clothing"
      set = { category = "clothing" }
      goto = "ProductList"
    }
    option "3" {
      label = "Home & Garden"
      set = { category = "home" }
      goto = "ProductList"
    }
  }

  # Dynamic product list
  menu "ProductList" {
    text = "{{session.category}} products:"
    
    data_source {
      url = "/products?category={{session.category}}"
      response_array_path = "data"
      
      display_template = "{{name}} - ${{price}}"
      selected_variable = "product"
      on_select = "ProductDetail"
      
      filter = "stock > 0"
      sort_by = "popularity"
      sort_order = "desc"
      page_size = 5
      
      empty_message = "No products available"
      empty_goto = "Categories"
      error_menu = "LoadError"
    }
  }

  # Product detail (uses selected item data)
  menu "ProductDetail" {
    text = "{{product.name}}\n\nPrice: ${{product.price}}\nIn Stock: {{product.stock}}\n\n{{product.description}}"
    
    option "1" {
      label = "Add to Cart"
      goto = "AddToCart"
    }
    option "0" {
      label = "Back to List"
      goto = "ProductList"
    }
  }

  # Add to cart action
  action "AddToCart" {
    type = "http_call"
    method = "POST"
    url = "/cart/add"
    body = {
      product_id = "{{product.id}}"
      quantity = 1
      msisdn = "{{session.msisdn}}"
    }
    on_success = "CartSuccess"
    on_error = "CartError"
  }

  menu "CartSuccess" {
    text = "{{product.name}} added to cart!"
    terminal = true
  }

  menu "LoadError" {
    text = "Failed to load products."
    option "1" { label = "Retry"; goto = "ProductList" }
    option "0" { label = "Categories"; goto = "Categories" }
  }

  menu "CartError" {
    text = "Could not add to cart."
    option "1" { label = "Try Again"; goto = "AddToCart" }
    option "0" { label = "Back"; goto = "ProductDetail" }
  }
}