Field Formatting

Softools provides several ways to control how Number and Date/DateTime field values are displayed and formatted.

The appropriate approach depends on what you need the formatted value for. In particular, formatting can be used either to display a number value as currency, percentage,.. whilst still allowing editing or to create a formatted text value, of numbers or dates, for use elsewhere such as emails or export to Word/PDF, and these requirements can be combined.

There are three main approaches:

1. Format Strings – available for Number and Date/DateTime fields. A Format String creates a _Formatted backing field containing the formatted value as text. This formatted representation of the value can be used in Records, Reports as Read Only display, expressions, emails, and Word/PDF exports.

   
    

2. Formatted Date Values in Emails – Date/DateTime values can be formatted directly when using email keyword references. This is useful when formatting is only required for an email and not in the App or for Export to Word as there is no need to create a _Formatted backing field.

   

    

3. Number Formatting Properties – available for Number fields. These control how the value is displayed to users in Apps but also allows click to edit for changing the Field value. No _Formatted backing field is created.

   

For Number fields, Format Strings and Number Formatting Properties can also be used together. This is useful when a Number should be formatted and remain editable in Records, while also providing a separate formatted value for emails, exports or other outputs.

• 1. Format Strings
  • Displaying the Formatted Value
  • Using the _Formatted Value Elsewhere
  • Formatting Number Fields
    • Custom Number Formats
    • Negative Numbers
  • Formatting Date and DateTime Fields
    • Custom Date Formats
    • Time Components
• 2. Formatted Date Values in Emails
  • Example
• 3. Number Formatting Properties
  • Interactive Editing
• Using Number Formatting Properties and Format Strings Together
  • Example: Editable Financial Value with Export Formatting
  • Display Formatted with Number Formatting Properties
• Common Use Cases
  • Financial Values, Friendly Dates, Audit Completion Percentage, Hours and Rates, Large Numbers, Reference Numbers and Identifiers, Negative Financial Values, Dates and Times, Email-Specific Date Formatting, Read-Only Financial Reporting, User-Editable Financial Values
• Choosing the Right Approach
  • Use Format Strings when
  • Use Email Date Formatting when
  • Use Number Formatting Properties when
  • Use Both when
• Summary

1. Format Strings

A Format String can be added to a Number or Date/DateTime field to control how its value is represented as text.

For example:

{0:N2}

formats a Number using digit grouping and two decimal places, while:

{0:dd-MM-yyyy}

formats a date as day-month-year.

Adding a Format String creates a FieldID_Formatted backing field containing the formatted text value.

For example, if the Field ID is:

TotalValue

the backing field will be:

TotalValue_Formatted

The original field continues to contain the underlying Number or Date/DateTime value. The _Formatted field contains the formatted text representation.

This means the original value remains available for calculations and other operations, while the formatted value can be used wherever a text representation is required.

Displaying the Formatted Value

The formatted value can be displayed in Records using Display Formatted.

When Display Formatted is enabled, the formatted value is displayed instead of the raw value and the field is read-only.

The _Formatted backing field can also be selected directly when configuring a Template or Report.

This is useful when you want to control exactly where the formatted value is displayed without changing the behaviour of the original field.

Using the _Formatted Value Elsewhere

Because the _Formatted value is a separate field, it can also be used in:

• Expressions
• Emails
• Word exports
• Templates
• Reports

This makes Format Strings the appropriate option when the formatted representation needs to be reused elsewhere in the application.

Formatting Number Fields

Common reasons for adding a Format String to a Number field include:

• Displaying a value as currency.
• Adding digit grouping.
• Limiting the number of decimal places.
• Displaying percentages.
• Displaying scientific notation.
• Adding fixed text before or after a value.
• Controlling the display of positive, negative and zero values.

For example, for the value 384537.21356:

Custom Number Formats

Fixed text can be included around the formatted value.

For example:

£{0:N2}p

could produce:

£384,537.21p

The {0:N2} portion formats the Number, while the other characters are displayed as fixed text.

Negative Numbers

Custom numeric formats can define separate formatting for positive, negative and zero values.

For example:

{0:#,##0;(#,##0);0}

uses three sections:

positive;negative;zero

Therefore:

• 2000 → 2,000
• -2000 → (2,000)
• 0 → 0

This can be particularly useful for financial reporting, where negative values are often displayed in brackets.

Formatting Date and DateTime Fields

Format Strings can also be applied to Date and DateTime fields.

For example, for a date of 23 April 2017:

The output of culture-sensitive formats can vary depending on the applicable locale.

Custom Date Formats

Date components can be combined to create a custom format.

Year

• y – year
• yy – two-digit year
• yyy, yyyy, etc. – minimum number of digits required

Month

• M – month number
• MM – month number with a leading zero
• MMM – abbreviated month name
• MMMM – full month name

Day

• d – day number
• dd – day number with a leading zero
• ddd – abbreviated day name
• dddd – full day name

For example:

{0:dd-MM-yyyy}

could produce:

23-04-2017

Static text can also be included:

Date is: {0:d MMM, yyyy}

which could produce:

Date is: 23 Apr, 2017

Time Components

DateTime formats can also include time components:

For example:

{0:dd/MM/yyyy HH:mm}

could produce:

23/04/2017 14:30

2. Formatted Date Values in Emails

If a Date or DateTime field only needs to be formatted when it is included in an email, it is not necessary to add a Format String to the field.

The @Softools.FieldValue() email keyword supports formatting a Date/DateTime value directly.

For example:

@Softools.FieldValue(MyDateField, 'yyyy-MM-dd')

formats the value using the specified date format.

A locale can also be specified so the date is displayed according to the expectation of the local selected
eg. dd/MM/yyyy or MM/dd/yyyy:

@Softools.FieldValue(MyDateField, locale: 'en-GB')

This approach is useful when:

• The field does not otherwise need a Format String.
• The formatted value is only required in an email.
• You do not need a _Formatted backing field.
• Different emails may require different date formats or locales.

For example, the same Date field could be formatted differently in different emails without changing the field's configuration.

Example

A ReviewDate field could normally be displayed in the application as:

15/09/2026

but an email could use:

@Softools.FieldValue(ReviewDate, `dddd, d MMMM yyyy`)

to produce:

Tuesday, 15 September 2026

This allows email-specific presentation without changing the field itself.

3. Number Formatting Properties

For Number fields, formatting can alternatively be configured using Number Formatting Properties.

These properties provide formatted display without creating a _Formatted backing field.

The available properties include:

• Disable Digit Grouping
• Currency
• Percent
• Min Decimal Places
• Max Decimal Places
• Prefix
• Suffix

These properties are intended for situations where the Number needs to be presented in a readable format in Records and Reports, while users should still be able to edit the underlying Number.

Interactive Editing

When Number Formatting Properties are configured, the Number field retains its underlying raw value.

For example, a value stored as:

12345.6

could be displayed as:

£12,345.60

When the user clicks the field, it transitions into edit mode and the raw Number value can be entered.

When the user clicks away from the field, the formatted display is restored.

This allows users to work with a readable formatted value while still entering and editing the underlying Number.

Using Number Formatting Properties and Format Strings Together

A Number field can have both Number Formatting Properties and a Format String configured.

This is an important option when the Number has two separate requirements:

1. It needs to be formatted and editable when displayed to users.
2. A formatted text representation is also required for emails, exports, expressions or other outputs.

The two configurations serve different purposes.

Example: Editable Financial Value with Export Formatting

Suppose a InvoiceAmount Number field contains:

12500.5

Number Formatting Properties could be configured with:

• Currency: GBP
• Min Decimal Places: 2
• Max Decimal Places: 2

The user sees:

£12,500.50

and can click the value to edit the underlying Number.

The same field could also have the Format String:

£{0:N2}

This creates:

InvoiceAmount_Formatted

which can be selected for a Word export or used in an email.

The result is that the interactive display and the output formatting are handled independently.

Display Formatted with Number Formatting Properties

When Number Formatting Properties are configured, they control the interactive display and editing behaviour of the Number field.

Therefore, Display Formatted does not make the Number field read-only in this scenario.

The field remains clickable and can transition into editing mode so that the underlying raw Number value can be entered.

In practical terms, when Number Formatting Properties are configured:

The Number Formatting Properties take precedence over Display Formatted for the interactive field behaviour.

Therefore, enabling Display Formatted is effectively irrelevant to the interactive display of the Number field in this scenario.

The Format String still performs its separate function of creating the _Formatted backing field.

Common Use Cases

The following examples show typical situations where field formatting can improve readability and provide appropriately formatted values for users and outputs.

Financial Values

A project has a Budget Number field containing:

12500.5

Editable on-screen value

If users need to edit the amount, Number Formatting Properties can be configured with:

• Currency: British Pound
• Min Decimal Places: 2
• Max Decimal Places: 2

The user sees:

£12,500.50

but can click the field and edit the underlying Number.

Reusable formatted value

If the same value also needs to appear in an email or Word export, add a Format String:

£{0:N2}

This creates:

Budget_Formatted

The _Formatted value can then be used for the generated output.

Using both configurations is appropriate when the value needs to be both editable on screen and consistently formatted elsewhere.

Friendly Dates

A DueDate Date field contains:

2026-09-15T00:00:00Z

A Format String such as:

{0:ddd, d MMMM yyyy}

can display:

Tue, 15 September 2026

This can make dates easier for users to understand than a numeric date such as:

15/09/2026

A Format String is particularly useful if the friendly date needs to be displayed in a Report, Template, email or Word export.

If the friendly format is only required in an email, the date can instead be formatted directly using the @Softools.FieldValue(DueDate, 'ddd, d MMMM yyyy') email keyword.

Audit Completion Percentage

An audit has a Completion Number field containing:

0.875

If this represents 87.5% completion, a Format String such as:

{0:P0}

can display:

88%

If more precision is required:

{0:P1}

displays:

87.5%

If the percentage is calculated and so can always display as Read Only then the Format String is preferable. If it is manually entered, then Number Formatting Properties can be used instead by enabling Percent and setting the required decimal places.

If the percentage is manual and also needs to be included in emails or exports, both approaches can be configured:

• Number Formatting Properties for the editable on-screen display.
• Format String for the _Formatted value.

Hours and Rates

A project contains a CostPerHour Number field containing:

75.5

Number Formatting Properties could display:

£75.50

while allowing the user to click and edit the value.

A Format String such as:

£{0:N2}

can additionally create a reusable CostPerHour_Formatted value for emails and exports.

This is useful for hourly rates, labour costs and other financial values where a consistent number of decimal places is required.

Large Numbers

A Budget field contains:

1250000

A Format String such as:

{0:N0}

can display:

1,250,000

This improves readability while retaining the original numeric value for calculations.

If users need to edit the budget directly, Number Formatting Properties can instead provide the formatted interactive display while retaining the underlying Number.

If the formatted value is also required for generated output, both Number Formatting Properties and a Format String can be used.

Reference Numbers and Identifiers

A Number field may sometimes need a fixed prefix or suffix for display.

For example, a field containing:

12345

could use:

INV-{0:00000}

to display:

INV-12345

This can be useful where a numeric value needs a consistent presentation for users or reports.

A Format String should be used when this formatted representation needs to be available as a separate _Formatted value for use in other parts of the application.

If the identifier is also user-editable and needs to remain an editable Number, Number Formatting Properties can be used for the interactive display while the Format String provides the reusable _Formatted value.

Negative Financial Values

For financial reports, negative values may be easier to interpret when displayed in brackets.

For example:

£{0:#,##0.00;(#,##0.00);£0.00}

can display:

• 1250 → £1,250.00
• -1250 → (£1,250.00)
• 0 → £0.00

This can be useful for budgets, financial reports, account balances and variance calculations.

If the formatted value needs to be reused in an email or export, the Format String creates the appropriate _Formatted value.

Dates and Times

A LastUpdated DateTime field contains both a date and time.

A Format String such as:

{0:dd/MM/yyyy HH:mm}

can display:

17/08/2026 20:35

This is useful for audit information, submission dates, approval timestamps and other records where both the date and time are important.

The _Formatted value can also be used in reports, emails and Word exports where the same presentation is required.

Email-Specific Date Formatting

A ReviewDate field is normally displayed as a standard date in the application, but an email needs to contain a more friendly version.

Instead of changing the field's Format String, the email can use:

@Softools.FieldValue(ReviewDate, 'dddd, d MMMM yyyy')

This could produce:

Tuesday, 18 August 2026

This approach is preferable when the special formatting is only required for the email.

It also means different emails can use different formats without changing the field configuration.

Read-Only Financial Reporting

A calculated TotalValue field is used throughout an application for calculations, but a management report should show it as currency.

A Format String can create:

TotalValue_Formatted

The original TotalValue remains available for calculations, while TotalValue_Formatted can be selected in the Report.

In this scenario, there may be no need for Number Formatting Properties because the value is calculated and does not need to be edited by the user.

User-Editable Financial Values

A user enters an invoice amount into a Number field.

The application should show:

£12,500.00

but allow the user to click the value and edit the underlying Number.

In this situation, Number Formatting Properties are appropriate.

The field can be configured with:

• Currency: GBP
• Min Decimal Places: 2
• Max Decimal Places: 2

The user sees the formatted value during normal use but can edit the raw Number when required.

If the invoice amount also needs to appear in an email or Word export, a Format String can be added as well to create the _Formatted value.

Choosing the Right Approach

The following table summarises the main options:

* With a Format String alone, enabling Display Formatted makes the field read-only. When Number Formatting Properties are also configured, their interactive behaviour takes precedence and the field remains editable.

Use Format Strings when

The formatted value needs to exist as a separate value that can be reused throughout the application, particularly for:

• Emails
• Word exports
• Expressions
• Templates
• Reports
• Read-only display in Records

Use Email Date Formatting when

A Date/DateTime field only needs to be formatted in an email and there is no need to create a _Formatted backing field.

This is especially useful when different emails need different formats.

Use Number Formatting Properties when

A Number only needs formatted display in Records and Reports, and users should still be able to click the field and edit its underlying raw value.

This is particularly useful for:

• Currency
• Percentages
• Financial values
• Rates
• Large numbers
• Numbers requiring a specific number of decimal places

Use Both when

A Number needs to be formatted and editable on screen, while a separate formatted text value is also required for emails, Word exports, expressions, Templates or other outputs.

For example:

A TotalCost field should display as £12,500.50, allow the user to click and edit the amount, and also provide TotalCost_Formatted for use in an invoice email or Word export.

In this scenario:

• Number Formatting Properties provide the editable formatted display.
• Format String creates the reusable _Formatted value.
• Display Formatted does not control the interactive behaviour because Number Formatting Properties take precedence.

Summary

Softools provides different formatting mechanisms because formatting can serve different purposes.

Format Strings create a reusable formatted text representation through a _Formatted backing field. They are appropriate when the formatted value needs to be used beyond simple interactive display, such as in emails, Word exports, expressions, Templates or Reports.

Formatted Date Values in Emails allow Date/DateTime values to be formatted directly when constructing an email. This avoids creating a _Formatted field when the formatting is only required for that email.

Number Formatting Properties provide formatted interactive display while preserving the underlying Number and allowing users to click and edit it.

For Number fields, these mechanisms are not mutually exclusive.

A Number field can use Number Formatting Properties and a Format String together when it needs both:

• a readable, formatted and editable value for users; and
• a separate formatted text value for emails, exports, expressions or other outputs.

The key distinction is therefore:

Use Number Formatting Properties to control the interactive Number field. Use a Format String to create a reusable formatted value. Use both when you need both behaviours.