Visual Formatter Page (Advanced Script Programming)

This section shows how to create a Visual Formatter project without the use of the visual programming tool.

Project Zip File

To manually create a Visual Formatter project, the user needs to build the zip file of the project, containing at least 2 different files for each project item needed.

note

It is suggested to use only a single project item, because no dispatcher should be needed when manually creating the script file, given the fact that the dispatchers are useful only in the visual programming tool.

The 2 files that need to be created are the following:

A JSON file containing the information related to the Visual Formatter project item. It is suggested to use only a single formatter item.
A JavaScript file containing the code that implements the formatting logic. In case the user is not familiar with the JavaScript programming language, this code is usually generated through the visual programming tool.

The resulting zip file can be installed on the device using the Datalogic Settings application or through the Datalogic SDK methods.

JSON File

Sample

Below, a sample of the JSON file for a project is shown. The file name is set to formatter-1.json inside the zip.

formatter-1.json
{
    "info": {
        "version": 1,
        "name": "Formatter 1",
        "id": "formatter-1",
        "type": "formatter",
        "description": "Formatter 1 Description",
        "author": "Formatter 1 Author",
        "revision": "1",
        "date": "Mon Nov 02 2020 16:36:12 GMT+0100 (Central European Standard Time)",
        "projectId": "68e50ae3-1665-448c-82fd-e102e524988c",
        "projectName": "Sample 1 Project",
        "active": true,
        "featureLevel": 2,
        "managedEvents": 1
    },
    "flowchart": {
        "properties": [
            {
                "id": "prefix",
                "name": "Prefix",
                "description": "The prefix to add to the barcode",
                "type": "string",
                "direction": "input",
                "defaultValue": "",
                "hiddenFromUI": false
            },
            {
                "id": "suffix",
                "name": "Suffix",
                "description": "The suffix to add to the barcode",
                "type": "string",
                "direction": "input",
                "defaultValue": "",
                "hiddenFromUI": false
            }
        ]
    }
}

Description

The JSON is divided into two sections:

info: Contains the generic information about a project item, this information includes the following:
- version: The version of the info section (currently only version 1 exists).
- name: The name of the project item.
- id: The ID of the project item (it is the same as the file name).
- type: The item type. Accepted values are either "formatter" or "dispatcher". For the manual script creation it is suggested to only have a single formatter item.
- description: A description of the item's purpose.
- author: The author of the project item.
- date: The creation date.
- projectId: A UUID used to uniquely identify the project item. It is important to generate it in order to avoid rewriting a previously defined project item, unless the goal is to update a previously installed one.
- projectName: The name of the entire project.
- active: A boolean used to specify if the item should be automatically enabled after the installation on the device.
- featureLevel: The feature level of the item. For more details, please check the Feature Level section.
- managedEvents: Specifies the type of events that are managed by this item, causing an execution of the script. The event values are 1 for BARCODE, 2 for START, 4 for STOP and 8 for TIMEOUT. To manage more than one event, the users need to specify a value equal to the sum of the events they want to manage (e.g. value of 6 for both START and STOP).
flowchart: When the JSON is generated from the visual programming interface, this section contains information about the flowchart created by the tool. When created manually, only the properties field is necessary to define Custom Properties. The properties field contains an array of entries, each one containing the following fields:
- id: The ID of the property, used in the code to identify its name. Each property must have a unique ID.
- name The name of the property, visualized in the Datalogic Settings.
- description: The description of the property, visualized in the Datalogic Settings.
- type: The Type of property, valid selections are 'string', 'number' and 'boolean'.
- direction: Property direction, valid selections are 'input', 'output' and 'inout'.
- defaultValue: The default value of this property, always specified as string value (e.g. "3" instead of 3).
- hiddenFromUI: When set to true, this property will be hidden from the Datalogic Settings of the device, preventing it from being edited on the device by the user.

JavaScript File

Sample

A sample is provided below, based on the JSON properties shown in the JSON File section. The file name is set to formatter-1.js inside the zip.

formatter-1.js
const barcodeString = getInputObject("prefixIn") +
                      getInputObject("barcodeStringIn") +
                      getInputObject("suffixIn");
putOutputObject("barcodeStringOut", barcodeString);

This sample code adds a prefix and suffix to the input barcode string, setting the result as the output barcode string.

Description

Variables

The Visual Formatter system provides several predefined inputs/outputs, as well as some utility methods to get and set their values. The available inputs/outputs can be seen in the Predefined section. For custom properties, the names are defined as the property ID concatenated with 'In' for the input and 'Out' for the output. In the example above, both the prefix and suffix properties are inputs and therefore defined as 'prefixIn' and 'suffixIn'. For inout properties, there will be both 'In' and 'Out' names available.

Enums

Several enumerations are provided for use within Javascript, their definitions are as follows:

BarcodeType Enumeration
const BarcodeType = {
    NOT_DEFINED: 0,
    CODE39: 1,
    DISCRETE25: 2,
    MATRIX25: 3,
    INTERLEAVED25: 4,
    CODABAR: 5,
    CODE93: 6,
    CODE128: 7,
    UPCA: 8,
    UPCA_ADDON2: 9,
    UPCA_ADDON5: 10,
    UPCE: 11,
    UPCE_ADDON2: 12,
    UPCE_ADDON5: 13,
    UPCE1: 14,
    UPCE1_ADDON2: 15,
    UPCE1_ADDON5: 16,
    EAN13: 17,
    EAN13_ADDON2: 18,
    EAN13_ADDON5: 19,
    EAN8: 20,
    EAN8_ADDON2: 21,
    EAN8_ADDON5: 22,
    MSI: 23,
    GS1_14: 24,
    GS1_LIMIT: 25,
    GS1_EXP: 26,
    PDF417: 27,
    DATAMATRIX: 28,
    MAXICODE: 29,
    TRIOPTIC: 30,
    CODE32: 31,
    MICROPDF417: 32,
    QRCODE: 33,
    AZTEC: 34,
    POSTAL_PLANET: 35,
    POSTAL_POSTNET: 36,
    POSTAL_4STATE: 37,
    POSTAL_ROYALMAIL: 38,
    POSTAL_AUSTRALIAN: 39,
    POSTAL_KIX: 40,
    POSTAL_JAPAN: 41,
    GS1_128: 42,
    CODE39_FULLASCII: 43,
    EAN13_ISBN: 44,
    EAN13_ISSN: 45,
    MICRO_QR: 46,
    COMPOSITE_GS1_128_A: 47,
    COMPOSITE_GS1_128_B: 48,
    COMPOSITE_GS1_128_C: 49,
    COMPOSITE_GS1_14_A: 50,
    COMPOSITE_GS1_14_B: 51,
    COMPOSITE_GS1_LIMIT_A: 52,
    COMPOSITE_GS1_LIMIT_B: 53,
    COMPOSITE_GS1_EXP_A: 54,
    COMPOSITE_GS1_EXP_B: 55,
    COMPOSITE_CC_A: 56,
    COMPOSITE_CC_B: 57,
    DOTCODE: 58,
    ISBT_128: 59,
    ISBT_128_CONCATENATED: 60
}

EventType Enumeration
const EventType = {
    BARCODE: 0,
    START: 1,
    STOP: 2,
    TIMEOUT: 3
}

KeyCode Enumeration
const KeyCode = {
    A: 29,
    ALT_LEFT: 57,
    ALT_RIGHT: 58,
    APOSTROPHE: 75,
    AT: 77,
    B: 30,
    BACK: 4,
    BACKSLASH: 73,
    BREAK: 121,
    BRIGHTNESS_DOWN: 220,
    BRIGHTNESS_UP: 221,
    C: 31,
    CAPS_LOCK: 115,
    CLEAR: 28,
    COMMA: 55,
    COPY: 278,
    CTRL_LEFT: 113,
    CTRL_RIGHT: 114,
    CUT: 277,
    D: 32,
    DEL: 67,
    DPAD_DOWN: 20,
    DPAD_LEFT: 21,
    DPAD_RIGHT: 22,
    DPAD_UP: 19,
    E: 33,
    ENTER: 66,
    EQUALS: 70,
    ESCAPE: 111,
    F: 34,
    F1: 131,
    F10: 140,
    F11: 141,
    F12: 142,
    F2: 132,
    F3: 133,
    F4: 134,
    F5: 135,
    F6: 136,
    F7: 137,
    F8: 138,
    F9: 139,
    FORWARD: 125,
    FORWARD_DEL: 112,
    FUNCTION: 119,
    G: 35,
    GRAVE: 68,
    H: 36,
    HOME: 3,
    I: 37,
    INSERT: 124,
    J: 38,
    K: 39,
    L: 40,
    LEFT_BRACKED: 71,
    M: 41,
    MENU: 82,
    META_LEFT: 117,
    META_RIGHT: 118,
    MINUS: 69,
    MOVE_END: 123,
    MOVE_HOME: 122,
    N: 42,
    NUM_0: 7,
    NUM_1: 8,
    NUM_2: 9,
    NUM_3: 10,
    NUM_4: 11,
    NUM_5: 12,
    NUM_6: 13,
    NUM_7: 14,
    NUM_8: 15,
    NUM_9: 16,
    NUM_LOCK: 143,
    O: 43,
    P: 44,
    PAGE_DOWN: 93,
    PAGE_UP: 92,
    PASTE: 279,
    PERIOD: 56,
    PLUS: 81,
    POUND: 18,
    Q: 45,
    R: 46,
    RIGHT_BRACKET: 72,
    S: 47,
    SCROLL_LOCK: 116,
    SEMICOLON: 74,
    SHIFT_LEFT: 59,
    SHIFT_RIGHT: 60,
    SLASH: 76,
    SPACE: 62,
    STAR: 17,
    SYM: 63,
    SYSRQ: 120,
    T: 48,
    TAB: 61,
    U: 49,
    V: 50,
    W: 51,
    X: 52,
    Y: 53,
    Z: 54
}

IntentType Enumeration
const IntentType = {
    START_ACTIVITY: 0,
    START_SERVICE: 1,
    SEND_BROADCAST: 2
}

These enum definitions can be used in a similar manner to what has been done within the visual programming tool.

Methods

The predefined methods available in the system are the following:

getInputObject(name): Gets the value of the input or inout object defined by the provided name (always with the 'In' suffix).
putOutputObject(name, value): Sets the value of the output or inout object defined by the provided name (always with the 'Out' suffix).
createAction(jsonString): Generates an action given a JSON string. This method requires a minimum Feature Level of 3, which introduced the actions array. The JSON format includes the "type" field used to specify the type of action. The rest of the fields depend on the action type and are defined as follows:
- Barcode: Simulates the read of the specified barcode.
  - barcodeString: field for barcode content
  - barcodeType: field for barcode symbology (values found in the BarcodeType enum provided above)
  Barcode definition
```
{
  type: "Barcode";
  barcodeString: string;
  barcodeType: number;
}
```
- KeyEvent: Simulates a key event press/release.
  - keyCode: field for the key code value (as specified by the Android SDK documentation or using the KeyCode enum provided above)
  - pressed: field to specify if the keycode has been pressed (true) or released (false)
  KeyEvent definition
```
{
  type: "KeyEvent";
  keyCode: number;
  pressed: boolean;
}
```
- Intent: Executes an Android intent.
  - intentType: field for the type of intent to send (values found in the IntentType enum provided above)
  - action: (optional) field to specify the intent action
  - categories: (optional) field to specify intent categories
  - packageName: (optional) field to specify the package name for explicit intent
  - className: (optional) field to specify the class name for explicit intent
  - extras: (optional) field to specify the intent extras specified as a JSON string containing the string fields "type" (assuming values of "string", "number" or "boolean"), "name", and "value"
  Intent definition
```
{
  type: "Intent";
  intentType: number;
  action?: string;
  categories?: string[];
  packageName?: string;
  className?: string;
  extras?: string[]; //stringified JSON Objects
}
```
- Wait: Executes a delay of the given milliseconds (maximum 100 for each action created).
  - delayMs: field for the number of milliseconds to delay
  Wait definition
```
{
  type: "Wait";
  delayMs: number;
}
```
An example of a JSON string to use when creating an action is shown below. In this case the action will send an intent to start an activity with class name "com.datalogic.test.MainActivity" contained in an application with package name "com.datalogic.test". A string extra is added, named "barcode" with value "barcodeValue". Both the extra and the entire JSON are converted in string format using the JSON.stringify method available in JavaScript.
```
JSON.stringify({
  type: "Intent",
  intentType: IntentType.START_ACTIVITY,
  action: "",
  categories: [],
  packageName: "com.datalogic.test",
  className: "com.datalogic.test.MainActivity",
  extras: [
    JSON.stringify({
      type: "string",
      name: "barcode",
      value: "barcodeValue"
    })
  ]
})
```

Project Zip File​

JSON File​

Sample​

Description​

JavaScript File​

Sample​

Description​

Variables​

Enums​

Methods​

Project Zip File

JSON File

Sample

Description

JavaScript File

Sample

Description

Variables

Enums

Methods