@data-format : The Number and Date Formatting Attribute

The data-format attribute specifies the display format for numeric values and dates in Scryber PDF documents. It uses .NET-style format strings to control how numbers, currency, percentages, and dates are rendered in <num>, <time>, and <page> elements.

Summary

The data-format attribute enables precise control over the textual representation of numeric and temporal values in PDF output. It applies .NET Standard or Custom format strings to transform raw values into human-readable, locale-appropriate text.

This attribute is essential for:

• Currency and financial displays
• Percentage calculations
• Date and time formatting
• Decimal precision control
• Custom number representations
• Page numbering formats
• Scientific notation
• Locale-specific formatting

The formatting occurs during document generation, allowing the same numeric data to be displayed differently in various contexts using different format strings.

Usage

The data-format attribute accepts .NET format strings and is applied to elements that display numeric or temporal values.

Basic Syntax

<!-- Currency formatting -->
<num value="1234.56" data-format="C2" />
<!-- Output: $1,234.56 -->

<!-- Date formatting -->
<time value="2024-10-13" data-format="MMMM d, yyyy" />
<!-- Output: October 13, 2024 -->

<!-- Custom number format -->
<num value="42" data-format="#0.00" />
<!-- Output: 42.00 -->

<!-- Page number formatting -->
<page property="page" data-format="Page {0} of {1}" />
<!-- Output: Page 3 of 10 -->

Supported Elements

The data-format attribute is supported on the following elements:

Numeric Elements

• <num> - Number display element (HTMLNumber)
  • Uses NumberFormat property
  • Formats the value or parsed text content

Temporal Elements

• <time> - Date and time display element (HTMLTime)
  • Uses DateFormat property
  • Formats date/time values

Page Numbering Elements

• <page> - Page number element (HTMLPageNumber)
  • Uses DisplayFormat property
  • Formats page numbers with placeholders

Binding Values

Standard Numeric Format Strings

Custom Numeric Format Strings

Standard Date/Time Format Strings

Custom Date/Time Format Strings

Page Number Format Placeholders

For <page> elements, the format string uses placeholders:

Notes

Format String Evaluation

1. Timing: Format is applied during layout/render phase
2. Culture: Respects document locale settings
3. Validation: Invalid format strings may cause errors
4. Fallback: Bad formats typically fall back to ToString()

Number Formatting Specifics

Integer vs Decimal

• Some formats (D, X) only work with integers
• Decimal formats work with all numeric types
• Automatic conversion where possible

Precision Control

• Default precision varies by format
• Explicit precision recommended for currency
• Trailing zeros behavior controlled by format

Negative Numbers

• Format sections can specify negative formatting
• Syntax: positive;negative;zero
• Example: #,##0;(#,##0);Zero

Date/Time Formatting Specifics

Date Parsing

• Input must be parseable as DateTime
• ISO 8601 format recommended
• Locale-specific parsing supported

Time Zones

• No automatic timezone conversion
• Display as provided
• Include timezone in format if needed

Page Number Formatting Specifics

Placeholder Formatting

• Placeholders can have their own format
• Example: {0:D3} for zero-padded page numbers
• Combine with text: Page {0} of {1}

Total Page Count

• May require multiple passes
• Use data-page-hint for optimization
• Total calculated after full layout

Culture and Localization

Format strings respect the current culture:

• Currency symbols vary by locale
• Date formats differ by region
• Decimal and thousands separators change
• Set culture at document level

Performance Considerations

• Format strings compiled once per unique format
• Caching reduces overhead
• Complex custom formats slower than standard
• Avoid format changes in tight loops

Expression Integration

Format strings can be bound from data:

<!-- Format from model -->
<num value="" data-format="" />

<!-- Conditional format -->
<num value="" data-format="" />

Examples

1. Basic Currency Formatting

Display money with currency symbol:

<!-- Value: 1234.56 -->
<num value="1234.56" data-format="C2" />
<!-- Output: $1,234.56 -->

<!-- Bound value -->
<num value="" data-format="C2" />

2. Currency with Custom Symbol

Use custom currency format:

<num value="1234.56" data-format="£#,##0.00" />
<!-- Output: £1,234.56 -->

<num value="1234.56" data-format="€#,##0.00" />
<!-- Output: €1,234.56 -->

3. Percentage Display

Show values as percentages:

<!-- Value: 0.1234 -->
<num value="0.1234" data-format="P1" />
<!-- Output: 12.3% -->

<num value="0.8567" data-format="P2" />
<!-- Output: 85.67% -->

<!-- From calculation -->
<num value="" data-format="P0" />
<!-- Output: 45% -->

4. Fixed Decimal Places

Control decimal precision:

<!-- Always 2 decimal places -->
<num value="42" data-format="F2" />
<!-- Output: 42.00 -->

<num value="3.14159" data-format="F2" />
<!-- Output: 3.14 -->

<num value="" data-format="F4" />
<!-- Output: 1.4142 -->

5. Thousands Separator

Format large numbers with separators:

<num value="1234567" data-format="N0" />
<!-- Output: 1,234,567 -->

<num value="1234567.89" data-format="N2" />
<!-- Output: 1,234,567.89 -->

6. Zero-Padded Numbers

Pad with leading zeros:

<!-- Invoice numbers -->
<num value="42" data-format="D5" />
<!-- Output: 00042 -->

<!-- Item IDs -->
<num value="" data-format="D6" />
<!-- Output: 000123 -->

7. Scientific Notation

Display in exponential format:

<num value="1234567.89" data-format="E2" />
<!-- Output: 1.23E+006 -->

<num value="0.00001234" data-format="E3" />
<!-- Output: 1.234E-005 -->

8. Custom Format with Prefix/Suffix

Add custom text around numbers:

<num value="75" data-format="'Score: '#0' points'" />
<!-- Output: Score: 75 points -->

<num value="" data-format="#0.0'°C'" />
<!-- Output: 23.5°C -->

9. Positive/Negative/Zero Formats

Different formats for different values:

<!-- Format: positive;negative;zero -->
<num value="100" data-format="#,##0;(#,##0);Zero" />
<!-- Output: 100 -->

<num value="-50" data-format="#,##0;(#,##0);Zero" />
<!-- Output: (50) -->

<num value="0" data-format="#,##0;(#,##0);'No Value'" />
<!-- Output: No Value -->

10. Date - Long Format

Display full date:

<!-- Value: 2024-10-13 -->
<time value="2024-10-13" data-format="D" />
<!-- Output: Sunday, October 13, 2024 -->

11. Date - Custom Format

Create custom date display:

<time value="2024-10-13" data-format="MMMM d, yyyy" />
<!-- Output: October 13, 2024 -->

<time value="2024-10-13" data-format="MMM d, yy" />
<!-- Output: Oct 13, 24 -->

<time value="2024-10-13" data-format="dddd, MMM d" />
<!-- Output: Sunday, Oct 13 -->

12. Time Formatting

Display time values:

<time value="2024-10-13T15:45:00" data-format="t" />
<!-- Output: 3:45 PM -->

<time value="2024-10-13T15:45:30" data-format="T" />
<!-- Output: 3:45:30 PM -->

<time value="2024-10-13T15:45:00" data-format="HH:mm" />
<!-- Output: 15:45 -->

13. Date and Time Combined

Show both date and time:

<time value="2024-10-13T15:45:00" data-format="f" />
<!-- Output: Sunday, October 13, 2024 3:45 PM -->

<time value="2024-10-13T15:45:30" data-format="yyyy-MM-dd HH:mm:ss" />
<!-- Output: 2024-10-13 15:45:30 -->

14. Page Number - Simple

Basic page numbering:

<page property="page" data-format="{0}" />
<!-- Output: 3 -->

<page property="page" data-format="Page {0}" />
<!-- Output: Page 3 -->

15. Page Number - With Total

Show current and total pages:

<page property="page" data-format="Page {0} of {1}" />
<!-- Output: Page 3 of 10 -->

<page property="page" data-format="{0}/{1}" />
<!-- Output: 3/10 -->

16. Page Number - Formatted

Apply formatting to placeholders:

<!-- Zero-padded page numbers -->
<page property="page" data-format="Page {0:D3}" />
<!-- Output: Page 003 -->

<page property="page" data-format="{0:D3} of {1:D3}" />
<!-- Output: 003 of 010 -->

17. Invoice Table with Formatted Amounts

Format currency in table:

<table style="width: 100%;">
    <thead>
        <tr>
            <th>Description</th>
            <th>Qty</th>
            <th>Price</th>
            <th>Total</th>
        </tr>
    </thead>
    <tbody>
        <template data-bind="">
            <tr>
                <td></td>
                <td></td>
                <td><num value="" data-format="C2" /></td>
                <td><num value="" data-format="C2" /></td>
            </tr>
        </template>
    </tbody>
</table>

18. Financial Report with Percentages

Show financial metrics:

<div style="padding: 10pt; border: 1pt solid #ccc;">
    <div>Revenue: <num value="" data-format="C0" /></div>
    <div>Growth: <num value="" data-format="P1" /></div>
    <div>Margin: <num value="" data-format="P2" /></div>
</div>

<!-- Output:
     Revenue: $1,234,567
     Growth: 15.3%
     Margin: 23.45%
-->

19. Measurement Display

Show measurements with units:

<div>
    <div>Length: <num value="" data-format="#0.00'm'" /></div>
    <div>Weight: <num value="" data-format="#0.0'kg'" /></div>
    <div>Temp: <num value="" data-format="#0.0'°C'" /></div>
</div>

<!-- Output:
     Length: 12.50m
     Weight: 45.3kg
     Temp: 23.5°C
-->

20. Date Header with Custom Format

Create formatted headers:

<header>
    <div style="text-align: right; font-size: 9pt; color: #666;">
        Report Date: <time value="" data-format="MMMM d, yyyy" />
    </div>
</header>

<!-- Output: Report Date: October 13, 2024 -->

21. Dynamic Format Selection

Choose format based on data:

<!-- Model: { value: 1234.56, formatType: "currency" } -->
<num value=""
     data-format="" />

22. Conditional Negative Formatting

Format negative values in red:

<span style="color: ;">
    <num value="" data-format="C2" />
</span>

23. Multi-Currency Display

Show multiple currencies:

<div>
    <div>USD: <num value="" data-format="$#,##0.00" /></div>
    <div>EUR: <num value="" data-format="€#,##0.00" /></div>
    <div>GBP: <num value="" data-format="£#,##0.00" /></div>
    <div>JPY: <num value="" data-format="¥#,##0" /></div>
</div>

24. Score Card with Conditional Formatting

Display scores with context:

<template data-bind="">
    <div style="padding: 10pt; border-bottom: 1pt solid #ddd;">
        <div style="display: inline-block; width: 50%;"></div>
        <div style="display: inline-block; width: 25%;">
            <num value="" data-format="'Score: '#0" />
        </div>
        <div style="display: inline-block; width: 25%;">
            <num value="" data-format="P0" />
        </div>
    </div>
</template>

25. Time Duration Formatting

Show elapsed time:

<!-- For TimeSpan or duration values -->
<time value="" data-format="hh\:mm\:ss" />
<!-- Output: 02:15:30 -->

<time value="" data-format="h\:mm tt" />
<!-- Output: 2:15 PM -->

See Also

• num element - Number display element
• time element - Date/time display element
• page element - Page number element
• .NET Standard Format Strings - Microsoft documentation
• .NET Custom Format Strings - Microsoft documentation
• .NET Date/Time Format Strings - Microsoft documentation
• Data Binding - Data binding guide
• Expressions - Expression syntax