Basic Concepts

This section explains the Visual Formatter project structure, as well as the types and components available in the tool.

Project Structure

After selecting the Visual Formatter option from the actions list, you will be prompted to select a Project name and an Item name.

The item is represented by a single chart and can have 2 different types:

  • Formatter: Item used to manipulate the barcode data received from the scanner, using the Operations available.
  • Dispatcher: Item used to allow for a cleaner management of the Formatter items. With the dispatcher it is possible to specify a list of Formatter items to execute, with a given order. This enables the execution in different formatters to be separated, simplifying the overall flow. It can also act as a validator for the data received.

The project represents a list of items. Every project starts with a single Formatter item, but can be expanded by adding more formatters and dispatchers as desired by the user. The item that will execute can be changed at runtime using the Datalogic SDK APIs.

Data Types

Supported data types (also available as arrays):

NameColorRepresents
String#7B68EEA text.
Number#C70D3AA numeric value that can be integer or floating point.
Boolean#006064True or false value, generally used to check on some condition.
Enum#36802DDepending on the sub-type, it is used to set a value from a predefined list of constants. Mainly used to represent the BarcodeType or the Formatter enumerations.

For input connectors, you can specify a data type value directly inside the nodes representing various Operations. You can also drag and drop the Constant block of the Parameters tab inside the flowchart area, as shown in the video below.

Inputs, Outputs and Variables

Inside the chart you can specify some input and output nodes. The inputs are set when a barcode is read and will be manipulated depending on the connected operations. The outputs are set at the end of the chart's execution, if they have been connected to other nodes. Some inputs and outputs are predefined, but the user can also add custom nodes, called Properties in the Datalogic SDK. These nodes can be inputs, outputs or variables representing both an input and an output node (for example, a counter that is incremented after each successful read). You can add inputs, outputs or variables by dragging and dropping the Input, Output or Variable block of the Parameters tab inside the flowchart area, as shown in the video below.

Predefined

Inputs

NameTypeAvailable inRepresents
barcodeStringInStringFormatter & DispatcherThe barcode text read from the scanner.
barcodeTypeInEnum BarcodeTypeFormatter & DispatcherThe barcode symbology.

Outputs

NameTypeAvailable inRepresents
barcodeStringOutStringFormatterThe barcode text as it has been modified by the tool. If it is not included in the chart, it will assume the value of barcodeStringIn.
barcodeTypeOutEnum BarcodeTypeFormatterThe barcode symbology as it has been modified by the tool. If it is not included in the chart, it will assume the value of barcodeTypeIn.
executeStandardFormatterOutBooleanFormatterTrue to also run the Standard Formatter after the Visual Formatter has executed, false to skip it. If not included in the chart, it will assume the true value. This parameter is always considered false when the dispatcher is run, to avoid executing the standard formatter multiple times.
propagateResultOutBooleanFormatterTrue to propagate the result in the system and eventually receive the resulting barcode, false to not propagate, thus ignoring the barcode data completely. If not included in the chart, it will assume the true value.
formattersOutEnum Formatter[]DispatcherArray of formatters that will be executed sequentially in the order specified. The Formatter enumeration is updated depending on the available formatters, with the STANDARD formatter always available. If it is not included in the chart, it will be considered as an empty array.

Custom (Properties)

In order to create custom nodes, also called properties, you need to specify the following info:

  • Id: The identifier of the property, unique inside the flowchart. A suffix will be added during the creation of the node, depending on the direction. An input node will have the suffix "In", an output node the suffix "Out" and the variable node will create 2 separate nodes, one for the input and the other for the output.
  • Name: The name of the property.
  • Description: A description related to the purpose of the property (optional).
  • Type: Data type of the property.
  • Default Value: The default value that the property will assume in case it is not set during the execution of the chart.
  • Hide from UI: If enabled, the property will be hidden from the device Settings, preventing the user to modify its value if not through the Datalogic SDK APIs.

All the custom nodes will be available in the Datalogic SDK APIs through the list of properties available for every item the project contains.

Operations

Each operation is represented by a node with inputs and outputs. The inputs and outputs are shown as circles with an internal color that represent the type of input/output to use and have a unique name. The inputs can be connected to other nodes outputs, as well as to input blocks or constants, while the outputs work in the opposite way. The inputs can also be initialized without an explicit connection by using the UI component to the right of the name. Below the graphical representation of the SubString node is shown.

Operation Block

Operation nodes are divided into subsections depending on the type of operation executed. Every subsection has a different color to help during the editing of the formatter flow.

Arithmetic Operations

NameAppearanceDescription
+Addition between numbers (2 minimum).
-Subtraction between 2 numbers.
*Multiplication between numbers (2 minimum).
/Division between 2 numbers.

Boolean Operations

NameAppearanceDescription
NotInverts the value of the input boolean.
AndExecutes a logical AND between multiple booleans (2 minimum).
OrExecutes a logical OR between multiple booleans (2 minimum).

Inequality Operations

NameAppearanceDescription
>=Checks if n1 >= n2, with n1 and n2 both numbers, returning a boolean with the result of the check.
>Checks if n1 > n2, with n1 and n2 both numbers, returning a boolean with the result of the check.
==Equality check, works also for types different than numbers.
<Checks if n1 < n2, with n1 and n2 both numbers, returning a boolean with the result of the check.
<=Checks if n1 <= n2, with n1 and n2 both numbers, returning a boolean with the result of the check.

String Operations

NameAppearanceDescription
Remove FirstRemoves the first num characters from inStr.
Remove LastRemoves the last num character from inStr.
Remove AtRemoves from inStr the characters in the positions provided as indices (the first character is at index 0).
Remove Sub StringRemoves a substring contained in the input string. The number idBegin represents the index of the first character to remove, this number starts from 0 to remove the first character of the string (1 for the second and so on). The characters are removed until the index idEnd is reached, with the character at idEnd being included in the output string. Example: taking into consideration the string "Welcome", with idBegin = 2 and idEnd = 4 the output string will be "Weome".
Sub StringCreates a substring starting from the input string. The number idBegin represents the index of the first character to take to form the substring, this number starts from 0 to include the first character of the string (1 for the second and so on). The number idEnd is the index of the first character of the string to exclude from the substring, meaning this character will not be included in the output string. Example: taking into consideration the string "Welcome", with idBegin = 2 and idEnd = 4 the output string will be "lc".
LengthReturns the length of str.
ContainsChecks if str contains the string match and returns true in that case.
ConcatConcatenates multitple strings (minimum 2).
RepeatRepeats the input string str for num times.
Index OfReturns the index of the first occurrence of match inside str. This index represents the beginning of the first match string found in str. It returns -1 if no occurrence is found.
Last Index OfReturns the index of the last occurrence of match inside str. This index represents the beginning of the last match string found in str. It returns -1 if no occurrence is found.
SearchWorks as Index Of but the match is a regular expression. The complete regular expression is formed as "/matchPatternStr/matchFlagStr". Example: to search for the index of the first character from A to Z, the expression will be /[A-Z]/ (matchPatternStr = "[A-Z]", matchFlagStr = "").
ReplaceReplaces the first occurrence of searchValueStr (found inside inStr) with newValueStr.
Replace With RegExReplaces values (found inside inStr) corresponding to the regular expression formed by searchValuePatternStr and searchValueFlagStr with newValueStr. The complete regular expression is formed as "/searchValuePatternStr/searchValueFlagStr". Example: to replace all characters from A to Z with X, the expression will be /[A-Z]/g (searchValuePatternStr = "[A-Z]", searchValueFlagStr = "g", newValueStr = "X").
Replace AllReplaces every occurrence of searchValueStr (found inside inStr) with newValueStr.
To Upper CaseConverts the input string to uppercase letters.
To Lower CaseConverts the input string to lowercase letters.
TrimRemoves whitespaces at the start and at the end of the input string.
Trim StartRemoves whitespaces at the start of the input string.
Trim EndRemoves whitespaces at the end of the input string.
Trim CharRemoves all the occurrences of the specified character at the start and at the end of the input string.
Trim Char StartRemoves all the occurrences of the specified character at the start of the input string.
Trim Char EndRemoves all the occurrences of the specified character at the end of the input string.
Char AtExtract a single character from the string, specified by the input index (starting from 0 for the first character).
SplitSplits the string using the provided separator. The output is an array of strings.
Substitute CharsSubstitutes every character of fromChars found inside inStr in the corresponding character of toChars (found in the same position). Example: inStr = "abc", fromChars = "ab", "toChars" = "de", outStr = "dec".
Starts WithReturns true if str starts with match, false otherwise.
Ends WithReturns true if str ends with match, false otherwise.
CountReturns the number of occurrences of the match string inside str.
ReverseReverses the characters in the input string.
Create Min Length StringIf the length of inStr is lower than minLength, append fillChar to inStr for the number of times required to reach the desired length. The character is appended to the right if fillRight is set to true, otherwise it will be appended to the left. In case the length of inStr is >= minLength, the input string will be returned unmodified.
Is AlphaReturns true if str only contains alphabetic characters, false otherwise.
Is NumericReturns true if str only contains numbers, false otherwise.
Is AlphaNumericReturns true if str only contains alphanumeric characters, false otherwise.
To NumberConverts the input string into a number if possible, otherwise it will return an undefined value.
To BooleanConverts the input string into a boolean if possible, otherwise it will return an undefined value.
To StringConverts the input value into a string.

Array Operations

NameAppearanceDescription
LengthReturns the length of the input array.
GetReturns the element at the given index inside the input array. If no element is found it will return an undefined value.
AddAdds the specified item inside the input array, returning the array with the new item added inside.
Remove AtRemoves the element at the specified index from the input array, returning the array with the removed element as a result.

NOTE: The array type is identified as a rhombus in the input or output connectors of a block.

Conditions

NameAppearanceDescription
IfChooses a value based on the input condition (boolean). If condition is true, the trueValue set as input is passed as output, otherwise the falseValue will be taken. The inputs called trueValue and falseValue, as well as the output called out, can have a different type that will be selected during the node creation.
SwitchWorks as a switch condition. The selector of the switch can have a specified data type. The case corresponding to the value of the selector will be moved to the output. If the selector value is not found in the case list, the default case will be considered. The case values can also have a specified data type.

Feature Level

All visual formatter projects contain a number representing the feature level of the specific project. The feature level is used to verify the compatibility of the created project with a specific device and depends on the features included in the project. This number is always visible in the chart or in the project info dialog.

The currently supported feature levels are:

  • Feature Level 0: Simple formatter charts without any dispatcher or custom inputs/outputs/variables.
  • Feature Level 1: Can include a dispatcher item.
  • Feature Level 2: Can include custom inputs/outputs/variables.

Below the table with the scanner service versions from where the specific feature level has been introduced:

Feature LevelScanner Service Version
01.3.2.01 r5
11.3.2.01 r10
21.3.2.01 r10

Special Characters

Inside the visual formatter strings, it is possible to manage special characters in a different way.
From the input string, the special characters are not converted in any way, so they can be checked using the escape sequence related to the character.
In the output they can be specified in the same way, but they can also be specified by some tags that have been created to simplify the usage of special characters.
The table below shows the tags and the corresponding escape sequences used to specify those characters.

Special Character NameTagEscape Sequence (Unicode)Escape Sequence (Short Version)
SOH[SOH]\u0001N/A
STX[STX]\u0002N/A
ETX[ETX]\u0003N/A
EOT[EOT]\u0004N/A
ENQ[ENQ]\u0005N/A
ACK[ACK]\u0006N/A
BEL[BEL]\u0007N/A
BS[BS]\u0008\b
TAB[HT]\u0009\t
LF[LF]\u000A\n
VT[VT]\u000B\v
FF[FF]\u000C\f
CR[CR]\u000D\r
SO[SO]\u000EN/A
SI[SI]\u000FN/A
DLE[DLE]\u0010N/A
DC1[DC1]\u0011N/A
DC2[DC2]\u0012N/A
DC3[DC3]\u0013N/A
DC4[DC4]\u0014N/A
NAK[NAK]\u0015N/A
SYN[SYN]\u0016N/A
ETB[ETB]\u0017N/A
CAN[CAN]\u0018N/A
EN[EN]\u0019N/A
SUB[SUB]\u001AN/A
ESC[ESC]\u001BN/A
FS[FS]\u001CN/A
GS[GS]\u001DN/A
RS[RS]\u001EN/A
US[US]\u001FN/A
DEL[DEL]\u007FN/A