Skip to main content

JavaScript API

TheFlex provides a JavaScript API that allows websites or Fiori apps opened inside TheFlex to access native device features (e.g. scanner integrations, intents, keyboard control, logging, device information).

API Overview​

  • flx.zebra – Zebra DataWedge / scanning
  • flx.cipherlab – Cipherlab OCR trigger
  • flx.deviceInfo – device / terminal information
  • flx.log – logging (fatal/error/warn/info/…)
  • flx.backhandscanner – paired backhand scanner
  • flx.keyboard – keyboard + barcode “input”
  • flx.intents – generic Android intent listeners
  • flx.copyAndPaste – enable/disable copy & paste blocking

The API is available after deviceready and can be loaded via Cordova require:

document.addEventListener("deviceready", function () {
  const flx = cordova.require("de.flexus.flxcoreplugin.flxmainplugin");

  // Example: hide keyboard
  flx.keyboard.hide();

  // Example: logging
  flx.log.info("TheFlex API ready");
});
Note

The underlying objects/plugins (e.g. flxDatawedge, Keyboard, …) are provided by TheFlex. In most cases you do not need to install them into your web project separately.

Zebra Datawedge​

DataWedge Intent Configuration​

To use intent-based scanning:

  1. Open the DataWedge app
  2. Select an existing profile (or create one)
  3. Disable Keyboard output
  4. Enable Intent output
    • Action: zebra.scan
    • Intent delivery: choose “Send via Intent”

After this, scanned data is delivered to the web application via intent.

Zebra API (flx.zebra)​

flx.zebra.createProfile(profileName, success, error)

Creates a new DataWedge profile.

flx.zebra.createProfile(
  "MY_PROFILE",
  () => console.log("Profile created"),
  (e) => console.error("Error", e),
);

flx.zebra.enableScanner(success, error)

Enables the scanner.

flx.zebra.enableScanner(
  () => console.log("Scanner enabled"),
  (e) => console.error(e),
);

flx.zebra.disableScanner(success, error)

Disables the scanner.

flx.zebra.setActiveProfile(success, error)

Sets a profile as active.

Note

In the current wrapper signature, no profileName is passed. If you need to activate by name, adjust the wrapper or use the underlying implementation.

flx.zebra.enableDecoders(profileName, decoders, success, error)

Enables specific decoders for a profile.

flx.zebra.resetDecoders(profileName, success, error)

Resets all decoder settings for a profile.

Zebra scan listener​

flx.zebra.startScanListener(success, error)

Starts a listener to process scan results in JavaScript.

Common result fields:

  • result.data
  • result.decodeMode
  • result.barcodeType

Example: show scan result

document.addEventListener("deviceready", function () {
  const flx = cordova.require("de.flexus.flxcoreplugin.flxmainplugin");

  flx.zebra.startScanListener(
    function (result) {
      alert(result.decodeMode + " " + result.barcodeType + " " + result.data);
    },
    function (e) {
      alert("Error in scan listener: " + e);
    },
  );
});

Example: trim scan result and insert into focused input

document.addEventListener("deviceready", function () {
  const flx = cordova.require("de.flexus.flxcoreplugin.flxmainplugin");

  flx.zebra.startScanListener(
    function (result) {
      const scanData =
        typeof result === "object" && result.data ? result.data : "";
      if (!scanData) return;

      const cut =
        scanData.length > 6 ? scanData.substr(3, scanData.length - 6) : "";
      const active = document.activeElement;

      if (
        active &&
        (active.tagName === "INPUT" || active.tagName === "TEXTAREA")
      ) {
        active.value = cut;
        active.dispatchEvent(new Event("input"));
      } else {
        alert("No input field focused!");
      }
    },
    function (e) {
      alert("Error in scan listener: " + e);
    },
  );
});

flx.zebra.stopScanListener(success, error)

Stops the listener and restores default scan behavior.

Cipherlab (OCR)​

To use the OCR plugin on your website, make sure to follow these points:

Optional Parameters:

From the parameter limit_area, all subsequent parameters are optional. If you do not need to limit the capture area, set limit_area to 0. The subsequent parameters can then be set to 0 or omitted:

  • limit_area_width_for_portrait
  • limit_area_height_for_portrait
  • limit_area_width_for_landscape
  • limit_area_height_for_landscape
  • limit_area_width_for_real_time
  • limit_area_height_for_real_time
  • limit_area_width_for_reader_camera
  • limit_area_height_for_reader_camera
  • limit_area_width_for_reader_camera_real_time
  • limit_area_height_for_reader_camera_real_time

In addition, you can adjust or remove text_rules if no custom text recognition rules are required.

Example Usage:

To use the OCR plugin, you can use the following JavaScript code:

var config = {
  enable_settings: true,
  reader_camera_mode: 0,
  action_mode: 1,
  text_recognition_mode: 1,
  remove_blank_chars: 1,
  zoom_ratio: 1.5,
  save_picture: 0,
  limit_area: 1, // Set to 0 if no limit is needed
  limit_area_width_for_portrait: 0.8, // Optional
  limit_area_height_for_portrait: 0.1, // Optional
  limit_area_width_for_landscape: 0.6, // Optional
  limit_area_height_for_landscape: 0.3, // Optional
  limit_area_width_for_real_time: 0.8, // Optional
  limit_area_height_for_real_time: 0.1, // Optional
  limit_area_width_for_reader_camera: 0.8, // Optional
  limit_area_height_for_reader_camera: 0.1, // Optional
  limit_area_width_for_reader_camera_real_time: 0.8, // Optional
  limit_area_height_for_reader_camera_real_time: 0.1, // Optional
  text_rules: [
    // Optional
    "([0-9])([0-9])([0-9])([0-9])([-|/])([0-1])([0-9])([-|/])([0-3])([0-9])",
    "^[-+]{0,1}[0-9]*$",
  ],
};

flxOcrTrigger.triggerOCR(
  config,
  function (result) {
    console.log("OCR Result:", result);
  },
  function (error) {
    console.error("OCR Error:", error);
  },
);

Device Info​

flx.deviceInfo.getDeviceData(success)

Returns device information.

flx.deviceInfo.getDeviceData(function (data) {
  console.log("deviceData", data);
});

flx.deviceInfo.getTerminalData(success)

Returns terminal / TheFlex related terminal information.

flx.deviceInfo.getTerminalData(function (data) {
  console.log("terminalData", data);
});

flx.deviceInfo.getWebviewVersion()

Returns the WebView version.

const version = flx.deviceInfo.getWebviewVersion();
console.log("webview", version);

Logging​

  • flx.log.fatal(message)
  • flx.log.error(message)
  • flx.log.warn(message)
  • flx.log.info(message)
  • flx.log.log(message)
  • flx.log.debug(message)
  • flx.log.trace(message)

Example

flx.log.info("User opened page X");
flx.log.warn("Slow response on endpoint Y");
flx.log.error("Login failed");

Backhand Scanner​

You can find more information on how to configure a backhand scanner here.

flx.backhandscanner.init()

Initializes the scanner integration.

flx.backhandscanner.connect()

Connects the scanner.

flx.backhandscanner.disconnect()

Disconnects the scanner.

flx.backhandscanner.checkConnection(success, error)

Checks connection state.

flx.backhandscanner.checkConnection(
  (status) => console.log("connected?", status),
  (e) => console.error(e),
);

flx.backhandscanner.typeBarcodeScan(data)

Types/sends barcode data into the active input channel.

flx.backhandscanner.setDisplayXML(xml)

Sets display content via XML (device specific).

flx.backhandscanner.setDisplay(arg, success, error)

Sets display content via an argument object (device specific).

Keyboard​

flx.keyboard.show()

Shows the keyboard.

flx.keyboard.hide()

Hides the keyboard.

Note

Internally this uses the Cordova Keyboard plugin. You usually do not have to add it to your web project, because TheFlex provides it.

flx.keyboard.enterBarcodeData(value)

Programmatically forwards barcode data to the internal input channel.

flx.keyboard.enterBarcodeData("1234567890");

NFC​

You can find more information to the NFC integration here.

If the device supports NFC, TheFlex provides the Cordova NFC API. This allows you to detect NFC tags, read NDEF data, and write NDEF data.

Note

NFC must be enabled on the device. If window.nfc does not exist, NFC is not available on this device/setup.

Check if NFC is available/enabled

document.addEventListener("deviceready", function () {
  if (!window.nfc) {
    console.log("NFC not available on this device.");
    return;
  }

  nfc.enabled(
    () => console.log("NFC enabled"),
    (err) => console.log("NFC not enabled: " + JSON.stringify(err)),
  );
});

Read NDEF

document.addEventListener("deviceready", function () {
  if (!window.nfc) return;

  nfc.addNdefListener(
    function (nfcEvent) {
      const tag = nfcEvent.tag;
      const uid = nfc.bytesToHexString(tag.id);
      const msg = tag.ndefMessage || [];

      console.log("NFC UID:", uid);
      if (msg.length > 0) {
        const text = ndef.textHelper.decodePayload(msg[0].payload);
        console.log("NDEF text:", text);
      }
    },
    () => console.log("NDEF listener registered"),
    (e) => console.log("Failed to register listener: " + JSON.stringify(e)),
  );
});

Write NDEF (text record)

function writeNfcText(text) {
  const message = [ndef.textRecord(text)];

  nfc.write(
    message,
    () => console.log("NFC tag written"),
    (e) => console.log("Write failed: " + JSON.stringify(e)),
  );
}

Intents​

Generic intent handling (independent of DataWedge wrapper methods).

flx.intents.startScanListener(success, error)

Starts an intent-based scan listener (plugin: flxIntentPlugin).

flx.intents.stopScanListener(success, error)

Stops the listener.

flx.intents.addIntentListener(params, success, error)

Registers a listener for specific intent parameters.

flx.intents.addIntentListener(
  { action: "zebra.scan" },
  (intent) => console.log("intent received", intent),
  (e) => console.error(e),
);

flx.intents.removeAllIntentReceivers()

Removes all registered intent receivers.

Copy & Paste​

flx.copyAndPaste.enableBlock()

Enables copy/paste blocking.

flx.copyAndPaste.disableBlock()

Disables copy/paste blocking.

flx.copyAndPaste.isBlockEnabled(success, error)

Checks whether blocking is enabled.

flx.copyAndPaste.isBlockEnabled(
  (enabled) => console.log("blockEnabled", enabled),
  (e) => console.error(e),
);

(Deprecated) Launchpad Data​

When creating a startpage, you can store a username and password. These credentials can be used to prefill login fields in Fiori apps.

If the automated prefilling does not work, you can implement a custom login script. TheFlex provides launchpad data via:

FlxMultiUrls.currentLaunchpadData;

To access individual fields:

FlxMultiUrls.currentLaunchpadData.Name;
FlxMultiUrls.currentLaunchpadData.URL;
FlxMultiUrls.currentLaunchpadData.Username;
FlxMultiUrls.currentLaunchpadData.Password;
Caution

Any website can read these data. Only store username/password if you only open internal websites/apps you fully control.

Migration Note (old → new)​

If you previously used global objects directly (e.g. flxDatawedge.startScanListener(...) or Keyboard.hide()), prefer the new structured API:

  • flxDatawedge.* → flx.zebra.*
  • Keyboard.hide()/show() → flx.keyboard.hide()/show()
  • flxlog.* → flx.log.*
  • flxPairedDevice.* → flx.backhandscanner.*
  • plugins.flxIntentPlugin.* → flx.intents.*
  • flxBlockCopyPaste.* → flx.copyAndPaste.*