Custom Field Display

Custom Field Display is a Launcher feature that enables the values retrieved from an external file to be displayed on the Launcher home screen.

Overview

Custom Field Display is a Launcher feature that enables values retrieved from an external file to be displayed on the Launcher home screen. Having this functionality ensures that device-specific content, message, or information can be quickly accessed which in turn can help users save time, stay organized, and improve productivity.

User Guide

1. The ‘format’ field is a string that determines how the external values are displayed on the UI. For example, a file containing a specific placeholder should be enclosed in braces and must match the corresponding field in the file.

2. The ‘source’ field is an array of objects that defines where the information is coming from and how it should be parsed. If there are multiple pieces of information to be parsed from the file, multiple instances of the 'source' object can be created with different regex patterns and field names.

3. The ‘pathfile’ field is a string that specifies the full path and filename of the file to be parsed. This is the location where the information is retrieved from.

4. The ‘regex’ field is a Java regular expression string that specifies how to extract the desired information from the file. The regular expression should return the information to the first match group.

5. The 'name' field is a string that specifies the field name retrieved by the regular expression. It should correspond to the placeholder in the 'format' string, which is then used to display the information on the Launcher home screen.

6. The 'data' field is a string that specifies what data we’re trying to retrieve. For example to retrieve the device’s serial number, we will reference to config extended attribute “${config.ex.deviceId}”.

Feature Configuration

The Launcher configuration allows you to define the external values that can be displayed on the Launcher home screen. Use the example below as a guide:

For example, if there is an ASCII formatted file on the device /sdcard/Download/extension_dept.txt that contains the following:

Ext=2311
Dept=Front Desk
JobCode=A300403

The following configuration will allow you to display "2311 - Front Desk" on the screen:

    ...
    "customField" : {
        "format" : "{Extension} - {Department} - {TruncatedSerial}",
        "source" : [
            {
                "pathfile": "/sdcard/Download/extension_dept.txt",
                "regex": "Ext=(.*)",
                "name": "Extension"
            },
            {
                "pathfile": "/sdcard/Download/extension_dept.txt",
                "regex": "Dept=(.*)",
                "name": "Department"
            },
            {
                "data": "${config.ex.deviceId}",
                "regex": "(.{4})$",
                "name": "TruncatedSerial"
            }
        ]
    },
    ...

The Launcher when in focus will go through the source pathfiles and extract the group value specified by the regex and assign it as a value for the field name. In the above example, the matching group for '"Ext=(.)"' from the file will yield 2311*, and is assigned to the field name 'Extension'.

The Launcher will then apply the values read into the placeholders (the name of the custom field included in braces) as defined in the format configuration field. In this example, the Launcher will replace {Extension} with the value 2311 on the display.

Since it uses Java regular expressions to parse the values from the file, this feature is not file format specific, e.g. you can use XML, JSON, or text files as long as it is ASCII formatted and the regex is correct.

To display the last four digits of the device serial number within the custom field, use the following example:

   "customField" : {
        "format" : "{TruncatedSerial}",
        "source" : [
            {
                "data": "${config.ex.deviceId}",
                "regex": "(.{4})$",
                "name": "TruncatedSerial"
            }
        ]
    }

Custom Field Display was introduced in Launcher 2.13.x.