Skip to main content

Barcode Scanner Component

Introduction​

The Barcode Scanner Component in CargoXplorer TMS provides fast, accurate barcode capture using the device camera or external scanners (e.g., USB/Bluetooth “keyboard wedge” devices). It is event-driven: when a barcode is successfully read, a configurable list of actions runs via props.onScan. Use name to reference this component elsewhere if needed, and props.isHidden for conditional rendering.

YAML Structure​

component: barcodeScanner
name: scannerPrimary
props:
  minBarcodeLength: 8
  isHidden: "{{ eval !store.enableScanner }}"
  onScan:
    - setStore:
        scannedBarcode: "{{ result.data }}"
    - notification:
        message: "Barcode scanned: {{ result.data }}"

Attribute Description​

Root level​

AttributeTypeRequiredAllowed/DefaultDescription
componentstringYesbarcodeScannerIdentifies the component type. Must be exactly barcodeScanner.
namestringNo—Component name identifier. Use to reference this component from other config if needed.
propsobjectNo—Configuration object for the component behavior and rendering.

props​

AttributeTypeRequiredDescription
minBarcodeLengthintegerNoMinimum length for recognized barcodes. Use to prevent partial/accidental reads.
onScanactionsListNoActions executed after a successful scan. Receives context including result.
isHiddentemplateExpressionNoBoolean expression controlling conditional rendering. When truthy, the component is hidden.

onScan context​

Actions in onScan receive a result payload with commonly used fields:

  • result.data: the decoded barcode contents (string)
  • result.format: the detected symbology/format (for example, QR_CODE, CODE_128), when available

Note: Field availability may vary by platform/scanner. Guard logic accordingly.

Examples​

1) Basic scanner with state update and notification​

component: barcodeScanner
name: scannerPrimary
props:
  minBarcodeLength: 8
  onScan:
    - setStore:
        scannedBarcode: "{{ result.data }}"
    - notification:
        message: "Barcode scanned: {{ result.data }}"

What happens:

  1. The scanned barcode is stored in application state at store.scannedBarcode.
  2. A notification displays the scanned value.

2) Conditional logic by format, navigation or mutation​

component: barcodeScanner
name: scannerConditional
props:
  minBarcodeLength: 10
  onScan:
    - if:
        condition: "{{ eval result.format === 'QR_CODE' }}"
        then:
          - setStore:
              qrCodeData: "{{ result.data }}"
          - navigate:
              to: "/qr-details"
        else:
          - mutation:
              command: "logBarcodeScan"
              variables:
                barcodeData: "{{ result.data }}"
                format: "{{ result.format }}"
          - notification:
              message: "Barcode logged: {{ result.data }}"

What happens:

  1. If the scanned code is a QR code, store its data and navigate to /qr-details.
  2. Otherwise, call logBarcodeScan and show a confirmation notification.

3) Conditional rendering (hide when disabled)​

component: barcodeScanner
name: scannerToggled
props:
  isHidden: "{{ eval !store.enableScanner }}"
  onScan:
    - notification:
        message: "Captured: {{ result.data }}"

This hides the component unless store.enableScanner is true.

Best Practices​

  • Choose a sensible minBarcodeLength:
    • Too low can admit false positives (e.g., stray keystrokes from wedge scanners).
    • Too high can reject legitimate short codes.
  • Design for both camera and wedge scanners:
    • Wedge scanners paste input quickly; ensure focus states in your UI won’t interfere with capturing.
    • For camera scanning, provide adequate lighting/contrast and test on target devices.
  • Guard your logic:
    • Check result.format only if present; add fallbacks for unknown formats.
    • Sanitize or validate result.data before using in mutations or navigation.
  • User feedback:
    • Show clear confirmations (notifications, highlights) after onScan.
    • Consider audible or haptic feedback on mobile devices.
  • Security and privacy:
    • Avoid logging sensitive barcode contents unless required.
    • Restrict actions that mutate data to authorized roles.
  • Conditional rendering:
    • Use props.isHidden to disable/hide scanners based on workflow state or permissions.