Examples
This section provides practical examples of using ViewText for various use cases.
Weather Dashboard
A simple weather information display.
Field Registry
from viewtext import BaseFieldRegistry
registry = BaseFieldRegistry()
registry.register("city", lambda ctx: ctx["location"]["city"])
registry.register("temp", lambda ctx: ctx["current"]["temp"])
registry.register("feels_like", lambda ctx: ctx["current"]["feels_like"])
registry.register("humidity", lambda ctx: ctx["current"]["humidity"])
registry.register("wind_speed", lambda ctx: ctx["current"]["wind_speed"])
registry.register("condition", lambda ctx: ctx["current"]["condition"])
Layout Configuration (weather.toml)
[layouts.weather]
name = "Weather Display"
[[layouts.weather.lines]]
field = "city"
index = 0
formatter = "text_uppercase"
[[layouts.weather.lines]]
field = "condition"
index = 1
formatter = "text"
[[layouts.weather.lines]]
field = "temp"
index = 2
formatter = "number"
[layouts.weather.lines.formatter_params]
suffix = "°F"
decimals = 1
[[layouts.weather.lines]]
field = "feels_like"
index = 3
formatter = "text"
[layouts.weather.lines.formatter_params]
prefix = "Feels like: "
suffix = "°F"
[[layouts.weather.lines]]
field = "humidity"
index = 4
formatter = "number"
[layouts.weather.lines.formatter_params]
prefix = "Humidity: "
suffix = "%"
decimals = 0
[[layouts.weather.lines]]
field = "wind_speed"
index = 5
formatter = "number"
[layouts.weather.lines.formatter_params]
prefix = "Wind: "
suffix = " mph"
decimals = 1
Usage
from viewtext import LayoutEngine, LayoutLoader
loader = LayoutLoader("weather.toml")
engine = LayoutEngine(field_registry=registry)
context = {
"location": {"city": "San Francisco"},
"current": {
"temp": 72.5,
"feels_like": 70.2,
"humidity": 65,
"wind_speed": 8.3,
"condition": "Partly Cloudy"
}
}
layout = loader.get_layout("weather")
lines = engine.build_line_str(layout, context)
for line in lines:
print(line)
Output
SAN FRANCISCO
Partly Cloudy
72.5°F
Feels like: 70.2°F
Humidity: 65%
Wind: 8.3 mph
Cryptocurrency Ticker
Display cryptocurrency prices and changes.
Field Registry
from viewtext import BaseFieldRegistry
from datetime import datetime
registry = BaseFieldRegistry()
registry.register("symbol", lambda ctx: ctx["symbol"])
registry.register("price", lambda ctx: ctx["price"])
registry.register("change_24h", lambda ctx: ctx["change_24h"])
registry.register("volume", lambda ctx: ctx["volume_24h"])
registry.register("last_update", lambda ctx: ctx["timestamp"])
Layout Configuration (crypto.toml)
[formatters.usd]
type = "price"
symbol = "$"
decimals = 2
thousands_sep = ","
[formatters.large_number]
type = "number"
decimals = 0
thousands_sep = ","
[layouts.crypto_ticker]
name = "Crypto Ticker"
[[layouts.crypto_ticker.lines]]
field = "symbol"
index = 0
formatter = "text_uppercase"
[[layouts.crypto_ticker.lines]]
field = "price"
index = 1
formatter = "usd"
[[layouts.crypto_ticker.lines]]
field = "change_24h"
index = 2
formatter = "text"
[layouts.crypto_ticker.lines.formatter_params]
prefix = "24h: "
suffix = "%"
[[layouts.crypto_ticker.lines]]
field = "volume"
index = 3
formatter = "usd"
[layouts.crypto_ticker.lines.formatter_params]
prefix = "Vol: "
[[layouts.crypto_ticker.lines]]
field = "last_update"
index = 4
formatter = "datetime"
[layouts.crypto_ticker.lines.formatter_params]
format = "%H:%M:%S"
Usage
from viewtext import LayoutEngine, LayoutLoader
import time
loader = LayoutLoader("crypto.toml")
engine = LayoutEngine(field_registry=registry)
context = {
"symbol": "btc",
"price": 45234.56,
"change_24h": 2.34,
"volume_24h": 28500000000,
"timestamp": time.time()
}
layout = loader.get_layout("crypto_ticker")
lines = engine.build_line_str(layout, context)
for line in lines:
print(line)
Output
BTC
$45,234.56
24h: 2.34%
Vol: $28,500,000,000.00
14:23:45
System Monitor
Display system resource usage.
Field Registry
import psutil
from viewtext import BaseFieldRegistry
registry = BaseFieldRegistry()
registry.register("cpu_percent", lambda ctx: psutil.cpu_percent())
registry.register("memory_percent", lambda ctx: psutil.virtual_memory().percent)
registry.register("disk_percent", lambda ctx: psutil.disk_usage('/').percent)
registry.register("uptime", lambda ctx: time.time() - psutil.boot_time())
Layout Configuration (system.toml)
[layouts.system_monitor]
name = "System Monitor"
[[layouts.system_monitor.lines]]
field = "cpu_percent"
index = 0
formatter = "number"
[layouts.system_monitor.lines.formatter_params]
prefix = "CPU: "
suffix = "%"
decimals = 1
[[layouts.system_monitor.lines]]
field = "memory_percent"
index = 1
formatter = "number"
[layouts.system_monitor.lines.formatter_params]
prefix = "RAM: "
suffix = "%"
decimals = 1
[[layouts.system_monitor.lines]]
field = "disk_percent"
index = 2
formatter = "number"
[layouts.system_monitor.lines.formatter_params]
prefix = "Disk: "
suffix = "%"
decimals = 1
[[layouts.system_monitor.lines]]
field = "uptime"
index = 3
formatter = "relative_time"
[layouts.system_monitor.lines.formatter_params]
format = "long"
Usage
from viewtext import LayoutEngine, LayoutLoader
loader = LayoutLoader("system.toml")
engine = LayoutEngine(field_registry=registry)
layout = loader.get_layout("system_monitor")
# Update every second
import time
while True:
lines = engine.build_line_str(layout, {})
# Clear screen and print
print("\033[2J\033[H")
for line in lines:
print(line)
time.sleep(1)
Output
CPU: 23.5%
RAM: 67.2%
Disk: 45.8%
Uptime: 5 hours ago
E-Commerce Product Display
Display product information for e-commerce.
Field Registry
from viewtext import BaseFieldRegistry
registry = BaseFieldRegistry()
registry.register("name", lambda ctx: ctx["product"]["name"])
registry.register("sku", lambda ctx: ctx["product"]["sku"])
registry.register("price", lambda ctx: ctx["product"]["price"])
registry.register("stock", lambda ctx: ctx["product"]["stock"])
registry.register("category", lambda ctx: ctx["product"]["category"])
Layout Configuration (product.toml)
[formatters.currency]
type = "price"
symbol = "$"
decimals = 2
[layouts.product_card]
name = "Product Card"
[[layouts.product_card.lines]]
field = "name"
index = 0
formatter = "text"
[[layouts.product_card.lines]]
field = "sku"
index = 1
formatter = "text"
[layouts.product_card.lines.formatter_params]
prefix = "SKU: "
[[layouts.product_card.lines]]
field = "price"
index = 2
formatter = "currency"
[[layouts.product_card.lines]]
field = "stock"
index = 3
formatter = "number"
[layouts.product_card.lines.formatter_params]
prefix = "In Stock: "
decimals = 0
[[layouts.product_card.lines]]
field = "category"
index = 4
formatter = "text"
[layouts.product_card.lines.formatter_params]
prefix = "Category: "
Usage
from viewtext import LayoutEngine, LayoutLoader
loader = LayoutLoader("product.toml")
engine = LayoutEngine(field_registry=registry)
context = {
"product": {
"name": "Wireless Headphones",
"sku": "WH-2024-001",
"price": 149.99,
"stock": 47,
"category": "Electronics"
}
}
layout = loader.get_layout("product_card")
lines = engine.build_line_str(layout, context)
for line in lines:
print(line)
Output
Wireless Headphones
SKU: WH-2024-001
$149.99
In Stock: 47
Category: Electronics
Array Indexing and Nested Data
Access array elements and nested data structures using dot notation and numeric indices.
Field Mappings (fields.toml)
[fields.first_block_fee]
context_key = "mempool_blocks.0.medianFee"
default = 0
[fields.second_block_fee]
context_key = "mempool_blocks.1.medianFee"
default = 0
[fields.fastest_fee]
context_key = "recommended_fees.fastestFee"
default = 0
Layout Configuration (mempool.toml)
[layouts.mempool_fees]
name = "Mempool Fees"
[[layouts.mempool_fees.lines]]
field = "fastest_fee"
index = 0
formatter = "number"
[layouts.mempool_fees.lines.formatter_params]
prefix = "Fastest: "
suffix = " sat/vB"
decimals = 0
[[layouts.mempool_fees.lines]]
field = "first_block_fee"
index = 1
formatter = "number"
[layouts.mempool_fees.lines.formatter_params]
prefix = "Block 1: "
suffix = " sat/vB"
decimals = 0
[[layouts.mempool_fees.lines]]
field = "second_block_fee"
index = 2
formatter = "number"
[layouts.mempool_fees.lines.formatter_params]
prefix = "Block 2: "
suffix = " sat/vB"
decimals = 0
Usage
from viewtext import LayoutEngine, LayoutLoader, RegistryBuilder
loader = LayoutLoader("mempool.toml", fields_path="fields.toml")
layout = loader.get_layout("mempool_fees")
registry = RegistryBuilder.build_from_config(loader=loader)
engine = LayoutEngine(field_registry=registry)
context = {
"recommended_fees": {
"fastestFee": 15,
"halfHourFee": 12,
"hourFee": 10
},
"mempool_blocks": [
{"medianFee": 14, "totalFees": 0.5},
{"medianFee": 12, "totalFees": 0.4},
{"medianFee": 10, "totalFees": 0.3}
]
}
lines = engine.build_line_str(layout, context)
for line in lines:
print(line)
Output
Fastest: 15 sat/vB
Block 1: 14 sat/vB
Block 2: 12 sat/vB
Array Indexing Syntax
tags.0- Access first element of arraymatrix.0.1- Access nested array elementusers.0.name- Access property of array elementitems.5.price.usd- Deep nesting with arrays and objects
See examples/mempool_layouts.toml for a complete example.
Dictionary Layout Example
Dictionary layouts produce key-value pairs instead of indexed lines. This is ideal for JSON APIs, configuration generation, or structured data export.
Field Mappings (fields.toml)
[fields.temperature]
context_key = "temp"
default = 0
[fields.price_value]
context_key = "price"
default = 0
[fields.text_value]
context_key = "message"
default = ""
[fields.timestamp]
context_key = "time"
default = 0
Layout Configuration (weather_api.toml)
[layouts.weather_dict]
name = "Weather API Response"
[[layouts.weather_dict.items]]
key = "temp"
field = "temperature"
formatter = "number"
[layouts.weather_dict.items.formatter_params]
decimals = 1
suffix = "°"
[[layouts.weather_dict.items]]
key = "price"
field = "price_value"
formatter = "price"
[layouts.weather_dict.items.formatter_params]
symbol = "$"
decimals = 2
[[layouts.weather_dict.items]]
key = "message"
field = "text_value"
formatter = "text"
[[layouts.weather_dict.items]]
key = "time"
field = "timestamp"
formatter = "datetime"
[layouts.weather_dict.items.formatter_params]
format = "%Y-%m-%d %H:%M:%S"
Usage
from viewtext import LayoutEngine, LayoutLoader, RegistryBuilder
loader = LayoutLoader("weather_api.toml", fields_path="fields.toml")
layout = loader.get_layout("weather_dict")
registry = RegistryBuilder.build_from_config(loader=loader)
engine = LayoutEngine(field_registry=registry)
context = {
"temp": 72.5,
"price": 19.99,
"message": "Partly cloudy",
"time": 1234567890
}
result = engine.build_dict_str(layout, context)
# Use as dictionary
print(result["temp"])
print(result["message"])
# Or export as JSON
import json
print(json.dumps(result, indent=2))
Output (Dictionary)
{
"temp": "72.5°",
"price": "$19.99",
"message": "Partly cloudy",
"time": "2009-02-14 00:31:30"
}
CLI Usage
# Render as key:value pairs
echo '{"temp": 72.5, "price": 19.99}' | viewtext render weather_dict
# Output as JSON
echo '{"temp": 72.5, "price": 19.99}' | viewtext render weather_dict --json
Output (CLI text format)
temp: 72.5°
price: $19.99
message: Partly cloudy
time: 2009-02-14 00:31:30
Output (CLI JSON format)
{
"temp": "72.5°",
"price": "$19.99",
"message": "Partly cloudy",
"time": "2009-02-14 00:31:30"
}
See dict_example.toml for a complete example with multiple dictionary layouts.
Custom Formatter Example
Create a custom formatter for special formatting needs.
Custom Formatter
from viewtext import get_formatter_registry
def format_status(value, **kwargs):
status_map = {
"online": "🟢 Online",
"offline": "🔴 Offline",
"away": "🟡 Away",
"busy": "🔴 Busy"
}
return status_map.get(value, f"❓ {value}")
def format_progress_bar(value, **kwargs):
width = kwargs.get("width", 20)
filled = int((value / 100) * width)
bar = "█" * filled + "░" * (width - filled)
return f"{bar} {value:.0f}%"
# Register custom formatters
registry = get_formatter_registry()
registry.register("status", format_status)
registry.register("progress", format_progress_bar)
Usage
from viewtext import BaseFieldRegistry, LayoutEngine
field_registry = BaseFieldRegistry()
field_registry.register("user_status", lambda ctx: ctx["status"])
field_registry.register("download_progress", lambda ctx: ctx["progress"])
layout = {
"name": "Custom Display",
"lines": [
{
"field": "user_status",
"index": 0,
"formatter": "status"
},
{
"field": "download_progress",
"index": 1,
"formatter": "progress",
"formatter_params": {"width": 30}
}
]
}
engine = LayoutEngine(field_registry=field_registry)
context = {
"status": "online",
"progress": 67
}
lines = engine.build_line_str(layout, context)
for line in lines:
print(line)
Output
🟢 Online
████████████████████░░░░░░░░░░ 67%