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

Source is one or more variables, identified by a placeholder with an
{index number}
. The index number is progressive and must be an integer greater than zero
{0}
. You can use placeholders in any order in the formatting rule. For example,
the minimum value of {3}, {0} and {2} is {1}
is a valid syntax.
You can nest placeholders in the formatting string
{index,alignment:format}
to dynamically change the formatting of the displayed data.
Nested placeholders examples:
{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
    {2}
    defines the number of decimal places.

Data types

Example data: 23/04/2021 17:25:31, session with 60 minutes TimeZone offset.
DateTime
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)
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.2
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
Duration and Timespan
Format
Description
Example
c
Constant format:
[-][d’.’]hh’:’mm’:’ss[‘.’fffffff]
  • 3.17:25:30.5000000
  • 4:30:00 AM
g
General short format:
[-][d’.’]hh’:’mm’:’ss[‘.’fffffff]
  • (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:
[-][d’.’]hh’:’mm’:’ss[‘.’fffffff]
  • (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
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
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

Provide Feedback
Have questions or feedback about this documentation? Please submit your feedback here.