String formatter

Modify the formatting of one or more values according to a customizable rule.

You can use the string formatter to:
  • Add characters before or after a value, if the value of the source variable is numeric.
  • Format and parameterize SQL queries to use in database objects.
  • Link multiple strings in a series.
  • Apply numeric formatting, such as decimal places or float rounding.

Properties

Property Description

Format
The formatting rule for variable reference:

  • Index. An index number that identifies an input variable. For every {index} placeholder in the formatting rule, a new field that indicated the source appears.

  • Alignment. An integer that represents the number of characters of the source value formatted according to the rule.

  • Format. The formatting to be applied to input variables.

    The format placeholder accepts a subset of the values required by the .NET Framework notation for the String.Format method. Placeholders must use the syntax {index,alignment:format}.

Mode
The direction of the dynamic link:
  • Read from the source node to the parent.
  • Write from the parent to the source node.
  • Read from the source node to the parent and write from the parent to the source node.

Source

One or more variables identified by:
{index_number} placeholder
Progressive integer equal to or greater than zero. For example, {1}
{#placeholder_identifier} placeholder
String prefixed with #. For example, {#speed}
Tip: Use any combination of placeholders in any order. Use any number of placeholders in the expression.
You can also nest placeholders {index,alignment:format} to dynamically change the formatting of the displayed data. For example:
{0:f{1}}
  • The variable value linked with {1} defines the number of decimal places.
{0:{1}{2}}
  • The variable value linked with {1} defines the numeric data type.
  • The variable value linked with {2} defines the number of decimal places.
{0,{1}:{2}{3}}
  • The variable value linked with {1} defines the alignment.
  • The variable value linked with {2} defines the numeric data type.
  • The variable value linked with {3} defines the number of decimal places.

Data types

Table 1. DateTimeExample data: 23/04/2021 17:25:31, session with 60 minutes TimeZone offset.
Format Description Example

g

Short date and time, local

  • (en-US): 4/23/21, 06:25 PM

  • (it-IT): 23/04/21, 18:25

F

Extended date and time, local

  • (en-US): Apr 23, 2021, 6:25:31 PM

  • (it-IT): 23 apr 2021, 18:25:31

X

Short date and time, UTC

  • (en-US): 4/23/21, 4:25 PM (UTC)

  • (it-IT): 23/04/21, 16:25 (UTC)

x

Extended date and time, UTC

  • (en-US): Apr 23, 2021, 4:25:31 PM (UTC)

  • (it-IT): 23 apr 2021, 16:25:31 (UTC)

U

Complete Universal Date and Time, UTC

  • (en-US): April 23, 2021 4:25:31 PM GMT (UTC)

  • (it-IT): 23 aprile 2021 16:25:31 GMT (UTC)

p

Short date, local

  • (en-US): 4/23/21

  • (it-IT): 23/04/21

P

Extended date, local

  • (en-US): April 23, 2021

  • (it-IT): 23 apr 2021

d

Short date, UTC

  • (en-US): 4/23/21 (UTC)

  • (it-IT): 23/04/21 (UTC)

D

Extended date, UTC

  • (en-US): Apr 23, 2021 (UTC)

  • (it-IT): 23 apr 2021 (UTC)

t

Short time, local

  • (en-US): 6:25 PM

  • (it-IT): 18:25

T

Extended time, local

  • (en-US): 6:25:31 PM

  • (it-IT): 18:25:31

h

Short time, UTC

  • (en-US): 4:25 PM (UTC)

  • (it-IT): 16:25 (UTC)

H

Extended time, UTC

  • (en-US): 4:25:31 PM (UTC)

  • (it-IT): 16:25:31 (UTC)
Table 2. Numeric (Double Float Int16 Int32 Int64 Integer UInt16 UInt32 UInt64 UInteger)
Format Description Example

d

Numerical, without thousands separator.

After the format placeholder, the number of decimal places is configured with an integer (without padding).

  • d: -1234 ► -1234

  • d: 5.618 ► 5618

  • d2: 1,234.239 ► 1234.24

n

Numerical, with thousands separator.

After the format placeholder, the number of decimal places is configured with an integer (without padding).

  • n1: -1234.23 ► -1,234.2

  • n2: 5804.236 ► 5,804.24

  • n3: -1234.23 ► -1,234.230

e

Exponential notation.

After the format placeholder, the number of significant numbers is configured with an integer.

  • e10: 12345.6789 ► 1.234567890E4

  • e2: 2665.778 ► 2.7E3

f

Fixed-point notation.

After the format placeholder, the exact number of decimal places is configured with an integer.

  • f3: 123 ► 123.000

  • f3: 123.23 ► 123.230

  • f4: -1898300.678 ► -1,898,300.6780

  • f3: 123.4 ► 123.400

p

Percentage.

After the format placeholder, an integer is used to configure the number of decimal places.

  • p: 1 ► 100%

  • p3: -0.397481 ► -39.748%

x

Hexadecimal notation.

255 ► ff

b

Binary notation.

107 ► 1101011

o

Octal notation.

56 ► 70
Table 3. Duration and Timespan
Format Description Example

c

Constant format.

  • 3.17:25:30.5000000

  • 4:30:00 AM

g

General short format.

  • (en-US): 1:3:16:50.5

  • (en-US): 5:15:09:00

  • (fr-FR): 2:9:02:00,0200000

  • (fr-FR): 15:12:20:00

  • (en-US): 5:12:00

  • (fr-FR): 20:10:00

G

Extended general format.

  • (en-US): 12:08:30 AM:00.0000000

  • (fr-FR): 12:08:30 AM:00.0000000

  • (en-US): 12:18:20 AM:00.0000000

  • (fr-FR): 12:17:30 AM:00.0000000
Table 4. String
Format Description Example

l

All lowercase.

grüßEN ► grüßen

u

All uppercase.

grüßEN ► GRÜSSEN

t

All first letters uppercase.

grüßEN ► GRÜSSEN

f

Case independent.

grüßEN ► grüssen
Table 5. ANSI SQL
Format Description Example

sql_identifier

Formats a given String or LocalizedText as a table or column identifier.

-

sql_literal

Formats the value of a variable as an SQL literal value (Number, String, date, time, and so on).

-

SQL queries examples

Parameterize the name of the internal column with the condition: 
SELECT * FROM Table1 WHERE {0:sql_identifier} > 5
Comparison with a data variable: 
SELECT * FROM AlarmsDatalogger WHERE Time > {0:sql_literal}
Parameterize the LIKE operator: 
SELECT * FROM AlarmsDatalogger WHERE Name LIKE '{0}'
Parameterize a part of a query with a placeholder: 
SELECT * FROM Table1 {0}
The placeholder with index 0 is linked to a project string variable and parameterizes a column; The placeholder with index 1 is linked to a numeric variable that represents the value for the comparison operator >: 
SELECT * FROM {0:sql_identifier} WHERE Column1 > {1:sql_literal}
Parameterize the table name, the column and also the LIKE operator: 
SELECT {0:sql_identifier} FROM {1:sql_identifier} WHERE {0:sql_identifier} LIKE '{2}'

Path formatting

Consider these path formatting capabilities:
  • To format a string as a file path, you can use this syntax: {index,alignment:filepath}.
    Input
    ns=5;%PROJECTDIR%/Logo.svg
    Output
    C:\Users\UserName\AppData\Local\Rockwell Automation\FactoryTalk Optix\Emulator\Projects\ProjectName\ProjectFiles\Logo.svg
  • To format a string as a URI, you can use this syntax: {index,alignment:uri}.
    Input
    ns=5;%PROJECTDIR%/Logo.svg
    Output
    file:///C:/Users/UserName/AppData/Local/Rockwell Automation/FactoryTalk Optix/Emulator/Projects/ProjectName/ProjectFiles/Logo.svg

  • To format a part of a path, you can use this syntax: file:///C:/Reports/Report{0}.pdf.

Inverse formatting

The inverse formatting feature allows you to modify a formatted value at runtime to replace the value with a new value that the application displays with the same formatting at runtime.

The inverse formatting feature requires the following settings to operate correctly:

  • The dynamic link Mode of the converter must be Read/Write.

  • The Format field must have only one placeholder or source. The placeholder can have a suffix and/or prefix and be set with a format string such as {0:n}.

Output

The string entered in the Format property, based on the formatting rules with values in place of the placeholder or placeholders.

Example