Skip to content

Commit fe48b17

Browse files
committed
Add missing info on formatting
1 parent 8948991 commit fe48b17

2 files changed

Lines changed: 87 additions & 0 deletions

File tree

homedocs/src/pages/docs/intro/formatting.mdx

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,30 @@ Widgets like `NumberField` and `DateField` accept a `format` property that contr
1919
<FormattingExample client:load />
2020
</CodeExample>
2121

22+
Use the `tpl` function to format multiple values into a single text property:
23+
24+
```tsx
25+
import { createAccessorModelProxy } from "cx/data";
26+
import { tpl } from "cx/ui";
27+
28+
interface Person {
29+
firstName: string;
30+
lastName: string;
31+
age: number;
32+
}
33+
34+
const m = createAccessorModelProxy<Person>();
35+
36+
// Positional placeholders {0}, {1}, etc.
37+
<div text={tpl(m.firstName, m.lastName, "{0} {1}")} />
38+
39+
// With formatting
40+
<div text={tpl(m.firstName, m.age, "{0} is {1:n;0} years old")} />
41+
42+
// With null text fallback
43+
<div text={tpl(m.firstName, "Hello, {0|Guest}!")} />
44+
```
45+
2246
## Culture-Sensitive Formatting
2347

2448
Date, currency, and number formats depend on culture settings. Enable culture-sensitive formatting before use:

homedocs/src/pages/docs/intro/migration-guide.mdx

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,69 @@ const model = createAccessorModelProxy<AppModel>();
258258
| `greaterThanOrEqual(accessor, value)` | Numeric greater than or equal |
259259
| `lessThanOrEqual(accessor, value)` | Numeric less than or equal |
260260
261+
### Format Helper
262+
263+
The `format` helper creates a selector that formats values using CxJS format strings.
264+
This is useful for displaying formatted numbers, dates, or percentages in text props:
265+
266+
```typescript
267+
import { createAccessorModelProxy } from "cx/data";
268+
import { format } from "cx/ui";
269+
270+
interface Product {
271+
name: string;
272+
price: number;
273+
discount: number;
274+
}
275+
276+
const m = createAccessorModelProxy<Product>();
277+
278+
// Format as number with 2 decimal places
279+
<div text={format(m.price, "n;2")} />
280+
281+
// Format as percentage
282+
<div text={format(m.discount, "p;0")} />
283+
284+
// With custom null text
285+
<div text={format(m.price, "n;2", "N/A")} />
286+
```
287+
288+
The format string uses CxJS format syntax (e.g., `"n;2"` for numbers, `"p;0"` for percentages,
289+
`"d"` for dates). The optional third parameter specifies text to display for null/undefined values.
290+
291+
### Template Helper with Accessor Chains
292+
293+
The `tpl` function now supports accessor chains in addition to its original string-only form.
294+
This allows you to create formatted strings from multiple values with full type safety:
295+
296+
```typescript
297+
import { createAccessorModelProxy } from "cx/data";
298+
import { tpl } from "cx/ui";
299+
300+
interface Person {
301+
firstName: string;
302+
lastName: string;
303+
age: number;
304+
}
305+
306+
const m = createAccessorModelProxy<Person>();
307+
308+
// Original string-only form still works
309+
<div text={tpl("{firstName} {lastName}")} />
310+
311+
// New accessor chain form with positional placeholders
312+
<div text={tpl(m.firstName, m.lastName, "{0} {1}")} />
313+
314+
// Supports formatting in placeholders
315+
<div text={tpl(m.firstName, m.age, "{0} is {1:n;0} years old")} />
316+
317+
// Supports null text
318+
<div text={tpl(m.firstName, "Hello, {0|Guest}!")} />
319+
```
320+
321+
The accessor chain form uses positional placeholders (`{0}`, `{1}`, etc.) and supports
322+
all StringTemplate features including formatting (`:format`) and null text (`|nullText`).
323+
261324
### Typed Config Properties
262325
263326
Several widget config properties now have improved type definitions that provide better

0 commit comments

Comments
 (0)