Skip to content

Input Parsing and Control Flow

Andy Theuninck edited this page Feb 20, 2015 · 2 revisions

Input parsing is integral to POS operations. The majority of functionality involves this sequence:

    1. POS is idle waiting for next input
    1. Cashier (or hardware) enters an input
    1. POS responds to input
    1. POS returns to idle state

In a general sense input parsing handles in many places in POS, but this document is specifically in regard to the main screen on POS which is named [for historical reasons] pos2.php. This file is in the pos/is4c-nf/gui-modules directory. The main screen needs to compare inputs against virtually every known command. The structure of input parsing here is more structured than in the rest of POS. The structure permits adding and removing commands in a modular manner and also simplifies common options.

Input parsing is generally handled via AJAX. When a string is entered into the input box and submitted, that value is passed via AJAX to ajax-parser.php (in pos/is4c-nf/ajax-callbacks). The primary reason for using AJAX here is the speedup gained by avoiding page reloads. On occasion if a different page redirects the browser to pos2.php and requests that the last input be repeated, parsing occurs directly in pos2::preprocess(). This is functionally identical to using the AJAX handler so what follows applies in either case.

Input parsing occurs in up to distinct stages although currently only the first two are in use.

The first stage is called preparsing. In the preparsing stage, POS passes the input value to all available PreParser classes. A PreParser class may modify the input value. All PreParser classes will be used however they are not guaranteed to run in any particular order. Therefore each PreParser's check() method should be narrowly written so it only modifies applicable input. The preparsing stage essentially looks like this:

foreach ($preparse_class as $class) {
    $object = new $class();
    if ($object->check($input)) {
        $input = $object->parse($input);
    }
}

The parse() method directly modifies the input string but is only called if the check() method returns true.

The second stage is called parsing. In this stage, POS gathers all the available Parser classes and passes the input value (possibly modified by preparsing) to the Parsers one at a time. Like PreParsers, the Parsers are not guaranteed to run in any particular order. Also like PreParsers, each Parser has a check() method and a parse() method. Parsers differ in two respects: the input is not passed to every available Parser. The first Parser who's check() method returns true stops the process and that class must handle the input value. The other difference is that a Parser's parse() method returns a structured value instead of a string. The parsing stage essentially looks like this:

foreach ($parse_class as $class) {
    $object = new $class();
    if ($object->check($input)) {
        $json = $object->parse($input);
        break;
    }
}

The structure returned by Parser::parse() methods is a keyed array. This is often internally referred to as $json because it will ultimately be converted to JSON in an AJAX response. The Parser class includes a method named default_json() that returns an array with all the appropriate keys set to default values. This is the recommended way of initializing a return value in a parse() method. The array returned by parse should contain the following keys:

  • main_frame [default boolean false]
    • Setting main_frame to a URL string redirects the whole browser to that URL (once upon a time there were multiple frames but that's no longer the case)
  • output [default boolean false]
    • Output contains an HTML string to draw onscreen. Output and main_frame are mutually exclusive. If both are set, the browser redirect takes precedence.
  • target [default string ".baseHeight"]
    • Target is a jQuery selector string. This specifies where the HTML from output should be inserted into the page. In practice the default value is always used.
  • redraw_footer [default boolean false]
    • If true, the five square footer boxes along the bottom of the screen are recalculated and redrawn
  • receipt [default boolean false]
    • Setting the string name of a receipt format here will print that receipt.
  • trans_num [default string current transaction identifier]
    • This is an "employee# - register# - trans#" formatted field. It's generally used in conjunction with the receipt value to decide which transaction to print from. The default is fine in the vast majority of situations.
  • scale [default boolean false]
    • If set to a string scale message, the weight box in the upper left is updated. Adjusting this from the default is pretty rare.
  • udpmsg [default boolean false]
    • A string value here will be transmitted directly to the low-level hardware driver (in most configurations this occurs via UDP)
  • retry [default boolean false]
    • Putting a string here will cause POS to wait a few milliseconds and then pass that string through input handling. The only current usage is with by-weight items that are waiting for the scale to settle on a non-zero weight. This might never be used for anything else but is documented for completeness.

Developers will likely use main_frame or output the most, occasionally use redraw_footer, udpmsg, and receipt, and almost never use any of the other keys.

The final stage is postparsing, in theory. No PostParsers have been developed yet. PostParsers provide an opportunity to modify the result of the parsing stage. Like PreParsers, each PostParser class will be used and the order is not guaranteed. Unlike the previous two stages, there is no check() method. The parse() method takes the structure from parsing as an argument and returns the same structure with or without modifications. Postparsing looks like this:

foreach ($postparse_class as $class) {
    $object = new $class();
    $json = $object->parse($json);
}

With parsing complete, POS then performs the actions specified by the JSON array (see keys above for detail).

Clone this wiki locally
You can’t perform that action at this time.