UI Elements (uie)

The UI Element Artifact (uie)

Filetype:{filename}.uie.lua

UI elements (.uie.lua) in TENUM® allow you to build responsive, real-time front ends using Lua. And with TENUM® ’s automatic event sourcing[GLOSSARY], you can create apps that sync data instantly across users—all without manually wiring up websockets, REST endpoints, or deployment scripts.

FrontEnd Library: TENUM® ships a React-like framework called LuAct [LINK], which lets you structure your UI with hooks, component functions, and JSX-like syntax—except everything is done in Lua.
Integrated real-time synchronozation: Due to TENUM® ’s real-time data synchronization, UI elements automatically stay in sync with the back-end entities—no extra wiring or third-party UI frameworks needed. Because TENUM® is event-sourced [GLOSSARY], UI elements can hook directly into TENUM® entities or queries.
UI Libraires: You also have built-in access to UI widgets from Chakra UI and other libraries [LINK] (exposed as a Lua-friendly API).

Usage Sample

Sample App: **TENUM®** ToDo App

Sample Module: TodoList.uie.lua

local todoList = require("todo.api.todoList")
local LuAct = require("**TENUM&reg;**.LuAct")
local uiFactory = require("uiFactory")
local VStack = uiFactory("ChakraUi::VStack")
local TodoItem = uiFactory("todo.ui::TodoItem")

return LuAct.createComponent(function(props)
  local todos = todoList.use.getTodos{
      id = props.listId
  }
  local main = VStack{}
  for _, todoId in pairs(todos or {}) do
    main = main + TodoItem{
      id = todoId,
      listId = props.listId
    }
  end
  return main
end)

When getTodos returns a new list of IDs (e.g., due to another user adding or removing items), TENUM® triggers a re-render so your UI stays current—no manual subscription needed.

Routing

If you want to handle multiple routes in a single .uie.lua, you can import TENUM® ’s router. TENUM® provides a router you can use in your .uie.lua files (e.g., **TENUM®**.router) to create single-page app experiences or multi-page flows.

You can define routes and choose which UI components to show based on the current path. By calling myEntity.use.someQuery{...}, the UI automatically re-renders whenever the underlying data changes—no extra code or manual subscriptions required.

Sample Routing: **TENUM®**.router

local router = require("**TENUM&reg;**.router").new()

router:match('home', function()
  return require("myapp.ui::HomePage"){}
end)

router:match('settings', function()
  return require("myapp.ui::SettingsPage"){}
end)

return LuAct.createComponent(function(props)
  local ok, pageContent = router:execute(props.route)
  if not ok then
    -- No match found
    pageContent = "404: Not Found"
  end
  return pageContent
end)

TENUM® automatically passes the current props.route to your .uie.lua file, which you can feed into the router. The router picks a matching path and renders the corresponding component.

Best Practices

Keep Components Small
- Like React, it’s a good idea to create multiple smaller UI components rather than one giant .uie.lua file.
Use Modules for Shared Logic
- If you have utility functions (e.g., string manipulation, date formatting), consider creating a .m.lua module that you require in your UI elements.
Leverage the TENUM® Ecosystem
- Need forms, layout, color themes? Chakra UI components are ready to go.
- Want real-time data from your back end? Call entity.use.queryName{...}.
Test UI Behavior
- While .uie.lua code itself doesn’t have a dedicated spec format, you can still test your domain logic thoroughly with .spec.lua files in your entities or message handlers. Many UI bugs are ultimately domain logic issues.
Stay Reactive
- Don’t manually set up watchers or subscriptions. Let TENUM® ’s underlying event sourcing + LuAct hooks do the heavy lifting.

Last modified: 11 April 2025