Skip to main content

Visual Formatter Page (Basic Concepts)

The Visual Formatter page allows users to create formatting rules to manipulate the barcode data received from the scanner. The user can decide which inputs and outputs to consider and create a connection that goes from the specified inputs towards the outputs, passing through some nodes, each representing a specific operation. This data flow is used to manipulate the input data in order to obtain the desired output.

See the following sections on the next page for a more in-depth explanation of the different components available in the Visual Formatter:

Visual Formatter page

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

Project Structure

Visual and Standard Formatter

The Visual Formatter is a tool used to manipulate a barcode decoded by the scanner. It does so by presenting a user interface in which you can connect different blocks and execute operations on the input barcode, with the purpose of modifying it in the desired way.

Prior to the introduction of the Visual Formatter, the Datalogic Android devices provided only a Standard Formatter, a component used to manipulate the barcode with some customizations that the user can change from the Settings of the device. Below are a list of features implemented by the Standard Formatter:

  • Prefix and suffix customization.
  • Group Separator replacement.
  • Removal of non-printable characters from the barcode.
  • Parsing and output of a different barcode type, for example recognizing and outputting a Code 32 from a Code 39 barcode.
  • Check digit management.
  • Charset management.

While executing the Visual Formatter, the Standard Formatter can be skipped or executed before/after the Visual Formatter, depending on the requirements of the project. The methods used to control the Standard Formatter execution are described in the sections below.

Visual Formatter Items

After selecting the Visual Formatter option from the actions list, a Visual Formatter project is created and a starting chart is provided. This chart represents a single item in the Visual Formatter project. There are 2 possible types of item available for use inside a Visual Formatter project:

  • Formatter: Item used to manipulate the barcode data received from the scanner, as well as other scan events when supported, 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, including the Standard Formatter, with a given order. This enables the execution to be separated in different items, simplifying the overall flow and the readability of the charts. It can also act as a validator for the data received. The dispatcher is available starting from Feature Level 1.

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 before executing the Visual Formatter item (usually after a barcode is read from the scanner or after a specific scanner event) 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. If the item chart is a formatter executed through a dispatcher and it is not the first in the list of formatters to be executed, the barcodeStringIn input is actually set to be equals to the barcodeStringOut output of the previous formatter item.
barcodeTypeInEnum BarcodeTypeFormatter & DispatcherThe barcode symbology. If the current chart represents a formatter executed through a dispatcher and it is not the first in the list of formatters to be executed, the barcodeTypeIn input is actually set to be equals to the barcodeTypeOut output of the previous formatter item.
eventTypeInEnum EventTypeFormatter & DispatcherThe type of event that caused the current item to be executed. By default, the project only manages the BARCODE EventType (returned when a barcode is read), but it can be set to manage also the events for START, STOP and TIMEOUT of the scanner decoding session. Changing the managed events can be done from the Item Info menu (found in the UI Controls). More details on these events can be found in the Datalogic SDK documentation. This input and its management are available starting from Feature Level 3.

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.
executeStandardFormatterOut*BooleanFormatterTrue 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 ignored when the formatter is executed from a dispatcher, to avoid executing the standard formatter multiple times. In this case, the standard formatter can be specified directly in the list of formatters executed from the dispatcher.
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.
actionsOutstring[]FormatterArray of action ids, used to execute a list of actions in the given order. The action ids are created using the operations available under the Actions category. Each id identifies the type of action that created it, with the parameters provided as input of the specific Action block used. Examples of actions are: sending a barcode result, sending a key event or sending an intent. The actions are available starting from Feature Level 3.

* Value not always considered during execution.

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. The custom nodes are available starting from Feature Level 2.

Operations

Each operation is represented by a node with inputs and outputs. The inputs and outputs are shown as circles (or a rhombus for arrays) with an internal color that represents 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).
NandExecutes a logical NAND between multiple booleans (2 minimum).
NorExecutes a logical NOR 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.
!=Inequality check, works also for types different than numbers.

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.
Add AllAdds an array inside the input array, returning the array with the new items added inside.
Remove AtRemoves the element at the specified index from the input array, returning the array with the removed element as a result.
CreateCreates an array starting from a variable number of elements.

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.

Actions

NameAppearanceDescription
Send BarcodeCreates an action used to send a barcode result, taking as input the barcode string and the barcode type.
Send Key EventCreates an action used to send a key event, taking as input the associated key code and a boolean to indicate if the key is pressed or released. The key codes available are a subset of the ones managed in Android and are sent similarly to what is done by a physical keyboard on the device.
Send Key Event NumberCreates an action used to send a key event, taking as input a number representing the associated Android key code and a boolean to indicate if the key is pressed or released. The key code is sent similarly to what is done by a physical keyboard on the device.
Send Key SequenceCreates a list of actions used to send multiple key events, allowing for a delay after each key event. The rest of the parameters is the same as the Send Key Event action, with the difference that the editing is done through a dialog instead of connecting the key codes as input.
Send IntentCreates an action used to send an intent, specifying different inputs (not all mandatory): type of intent (start activity, start service or send broadcast), action, categories, package and class name of the receiver and eventually the extras (that can be created using the Create Extra operation).
WaitCreates an action used to wait an amount of milliseconds specified as input. The delay can go from 1 to 100 milliseconds.

Utility

NameAppearanceDescription
PassthroughUtility block used only for a graphical purpose, in order to make it easy to create connections between blocks that are far away.
Create ExtraCreates an extra of different type, taking as input the extra name and its value. The result is a string that, added in an array, can be used as input of the Send Intent operation (in the extras field).
Get GS1 Field ValueGiven a GS1 formatted string and an application identifier as input, it retrieves the value of the specified application identifier, when found. If the value is not present, an empty string will be returned.
Get Base URIGiven an URI string, it retrieves the authority and hostname part of that URI. If the URI is not valid, an empty string will be returned.
Convert From GS1 Digital LinkGiven a GS1 digital link URI string, it converts it into a GS1 element string. If the GS1 digital link is not valid, an empty string will be returned.

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 project info dialog.

The currently supported feature levels are:

  • Feature Level 0: Supports only simple formatter charts.
  • Feature Level 1: Can include dispatcher items.
  • Feature Level 2: Can include custom inputs/outputs/variables.
  • Feature Level 3: Can include the actionsOut output (used to execute additional actions aside from the usual barcode, such as sending key events or intents) as well as the eventTypeIn input (used to manage the start, stop and timeout of the decoding session).
  • Feature Level 4: Includes the utility block called "GS1 Get Field Value", used to parse a GS1 element string in order to retrieve a value for a specified application identifier. Note that this block executes on the Scanner Service side, meaning that in the Visual Formatter debugging tool the results will be predefined as "VALUE_" concatenated with the application identifier specified.
  • Feature Level 5: Includes the utility blocks called "Get Base URI", used to return the authority and hostname parts of an URI, and "Convert From GS1 Digital Link", used to convert a GS1 digital link URI string into a GS1 element string. Note that the "Convert From GS1 Digital Link" block executes on the Scanner Service side, meaning that in the Visual Formatter debugging tool the results will be predefined as "CONVERTED_GS1". This feature level also adds the possibility to use the JavaScript console methods (such as console.log or console.error) when creating a Visual Formatter project with the Advanced Script Programming. These methods will be redirected to the Android Logcat.

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
32.2.0.10 r2
42.2.0.38 r1
52.2.0.42 r6

The following instead shows when support for a given feature level was added to a device's firmware:

Firmware versionRelease dateOS versionFeature level
1.14.0012024-12-18134
1.07.0072024-10-21134
1.07.0032024-09-04134
1.06.0042024-07-05134
Legacy Products
Firmware versionRelease dateOS versionFeature level
3.10.142021-01-158.1N/A
3.09.132020-10-298.1N/A
3.08.112020-06-108.1N/A
3.07.092019-09-278.1N/A
3.06.082019-06-148.1N/A
3.04.062019-03-158.1N/A

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