UberPOS developer documentation

This document provides an overview of the functions, hooks, commands, etc. that make up UberPOS.

uberpos.module

Implemented hooks:

  • hook_block : provides the number pad, button groups and the screen
  • hook_ctools_block_info() : TODO (it says it "hides the POS interface")
  • hook_ctools_plugin_directory() : load CTools plugins
  • hook_form_alter() :
    • Alters the login form to implement POS-login.
    • Alters the payment methods form (uc_payment_methods_form) to hide POS payment methods.
  • hook_menu()
  • hook_order() :
  • hook_order_actions() : adds a link to load the order in the POS interface to the list of order actions
  • hook_order_state() : adds the three UberPOS-specific order states (pos_canceled, pos_in_progress, pos_completed)
  • hook_payment_method : adds 3 UberPOS-specific payment methods (pos_cash, pos_credit, pos_check)
  • hook_perm() : add permissions for using and administering POS systems
  • hook_theme() : adds POS templates (screens, number pads, buttons, reports, receipts_
  • hook_views_api() : loads UberPOS views
    • Prevent the completion date of an order from changing during updates.
    • Set the current user as the cashier for the current order.
    • Make sure order data is removed from the up_orders table as well.
    • Merge UberPOS data into the array with order data.

Menus:

  • UberPOS Login : Simplify the user login page using UberPOS-specific css and javascript.
    • path: pos-login
    • access callback: user_is_anonymous
    • page callback: uberpos_pos_login
  • UberPOS : The main UberPOS interface.
    • path: admin/store/pos
    • access arguments: array('use pos system')
    • page callback: uberpos_pos
  • UberPOS : Load a specific order into the main UberPOS interface
    • path: admin/store/pos/%uc_order
    • access arguments: array('use pos system')
    • page callback: uberpos_pos
  • uberpos ajax : The Ajax processor. See uberpos_ajax.png for details
    • path: admin/store/pos/ajax
    • access arguments: array('use pos system')
    • page callback: uberpos_ajax
  • UberPOS settings : Configure UberPOS settings.
    • path: admin/store/settings/pos
    • access arguments: array('administer pos')
    • page callback: drupal_get_form
  • UberPOS : Exists to provide a path to admin/store/pos from the store settings page.
    • path: admin/store/orders/%uc_order/pos
    • access arguments: array(3)
    • access callback: uberpos_can_load_order
    • page callback: uberpos_redirect_to_pos

Functions, forms and tables:

  • template_preprocess_uberpos_closing_report(&$variables) : generate data for the closing report.
  • template_preprocess_uberpos_screen_interface(&$variables) : process variables for the uberpos screen (uberpos-screen.tpl.php). Not sure what the difference is between this and template_preprocess_uberpos_screen.
  • template_preprocess_uberpos_screen(&$variables) : process variables for the uberpos screen (uberpos-screen.tpl.php)
  • uberpos_add_order() : adds an order to Ubercart, by creating a new order and setting its status to pos_in_progress.
  • uberpos_add_product($input, $order, $qty, $attributes_extra) : add a product to an order. If no order is supplied a new one is created. Returns the $order object on success.
  • uberpos_ajax : server side processing of data provided by AJAX calls. See uberpos_ajax.png
  • uberpos_button_sort_compare($a, $b) : helper function for comparing two arrays by the value of an element named "weight".
  • uberpos_calculate_refunds($order_id) : returns the total of all lines in up_log for the RF (refund) command and order id $order_id.
  • uberpos_can_load_order($order = NULL) : returns true if the current user can use pos systems and if $order is either NULL or an uberpos order.
  • uberpos_clear_message : sets the clear message and disallows UberPOS from accepting input until the cashier has pressed clear (CL).
  • uberpos_default_interpreter($order, $item, $input, $js) : the default command processing function. See uberpos_default_interpreter.png. Modules can implement their own interpreters.
  • uberpos_get_buttons() : calls hook_uberpos_buttons and returns all module defined buttons
  • uberpos_get_line_items($order, $due, $change) : returns an array of line items for order $order. $due and $change are used to calculate the value for the line item with title t('PAID').
  • uberpos_get_product($data, $attributes_extra) : return a product object. $data should be an array containing at least a "model" or an "nid" field.
  • uberpos_get_receipt($order) : return a receipt for order $order.
  • uberpos_input_form($form_state, $order) : the main UberPOS input form for commands and UPCs.
  • uberpos_method_payment_default($op, &$arg1) : handle the UberPOS payment methods. Doesn't actually do anything.
  • uberpos_order_to_js($order, $action) : create an array with order data that can be turned into JSON. If $action is supplied, the array will have an item 'action'.
  • uberpos_pos_login() : return the Uberpos login page
  • uberpos_pos($order) : return the Uberpos screen.
  • uberpos_pos_prepare($order_id) : create the shell of the main user interface.
  • uberpos_receipt_printed($order_id, $times_printed) : update the database to reflect the number of times an order has been printed.
  • uberpos_receipt_times_printed($order_id) : returns the number of times a receipt has been printed.
  • uberpos_redirect_to_pos($order) : redirect to the default Uberpos screen.
  • uberpos_welcome_screen() : prints a welcome screen. The contents of this screen come from the variables uberpos_welcome_body and uberpos_welcome_format .

Available hooks:

  • hook_uberpos_buttons() : return an array of buttons.
  • hook_uberpos_command() : should return an array of callback function names. The callback functions will be called in uberpos_default_interpreter.
  • hook_uberpos_interpreter($order, $item, $input, $js) : allows modules to run a different interpreter than the default.
  • hook_uberpos_order_js_alter(&$js, $order) : allows modules to modify the data structure that gets sent out as JSON.
  • hook_uberpos_paid($order) : called in uberpos_order_to_js when an order is paid in full and a receipt is about to be created / returned.

uberpos.install

Uberpos installs the following tables:

  • up_orders
    • order_id : the order id
    • printed : the number of times a receipt has been printed
    • cashier : the uid of the cashier / user who initially created the order
    • completed : the order completion date
  • up_log : a log of commands
    • order_id : the order id
    • order_product_id : the product id
    • command : the command that led to this log entry
    • price : the amount
    • title : the product title
    • model : the product sku
    • time : timestamp of when the log entry was made

During install Uberpos also creates four new order statuses:

  • pos_completed
  • pos_canceled
  • pos_in_progress
  • pos_refund_in_progress

includes/uberpos.commands.inc

The default interpreter (see uberpos_default_interpreter.png) runs commands that are defined in UberPOS itself and in any module that implements hook_uberpos_command(). Implementations of this hook, including the one in core UberPOS itself, should return an array of callback function names. For every module, these callbacks are executed until one of them returns a non false value (meaning every module can only expect to have a single callback executed that returns something. if its callbacks return false, it can run as many callbacks as it wants).

These callbacks all receive three parameters:

  • $order : the current order object
  • $input : a command string of some sort
  • $item : an id for a specific item in an order
  • $js : a reference to the array that will ultimately be turned into JSON and returned to the Ajax caller.

Normally, $item, if it exists, is a string consisting of a two character item type code and an item number of arbitrary length. For example: "IT1234" is item number 1234 of type "IT". The function includes/uberpos.commands.inc:uberpos_parse_item reads item strings and returns an array with keys item_no and type.

Default commands in includes/uberpos.commands.inc:

  • uberpos_command_void : if $order is set and $input is equal to "VD" the item in $item is deleted from the order. Works for items of type "IT" and for items of type "PA" (payment). Returns the string "VD"
  • uberpos_command_clear : if $input is equal to "CL" it sets $order to NULL and returns "CL". Note it does not delete anything from the database.
  • uberpos_command_open_ring : this command allows entering ("ringing up") items which don't exist in the system. From the help text: "For example, if an item doesn't have a sku, costs $5.00 and is part of the Toys category (which a taxonomy ID of, say, 22) you would enter '500DP22' or click 5, 0, 0, DEPT., 2, 2, ENTER.". $input should contain the command string (the "500DP22" from the example). If the taxonomy item exists, a new product is created with the title of the taxonomy term as the name. This new product is then added to the order. However, if I'm not mistaken, the product is never actually initialized in the code, so if you try to use this feature, it will most likely not work. TODO.
  • uberpos_command_accept_payment : this command attempts to update the balance for $order. See uberpos.command.uberpos_command_accept_payment.pdf for details. It returns the requested payment method.
  • uberpos_command_reprint : reprint the receipt for $order, if $input is equal to 'RP' and a receipt has already been printed once. Returns 'RP'.
  • uberpos_command_signout : if $input is "SO" $js['redirect'] is set to "/logout?destination=pos-login". Note the starting slash: this is a bug that prevents logging out from working in installations that do not live in the domain root. Returns 'SO'.
  • uberpos_command_load_user : loads a specific user and assign the current order to that user. The syntax for $input is [UID]ID. Returns 'ID'.
  • uberpos_command_cancel : if $order is set and $input is "CN", all items in the order are removed and $order is set to NULL. Returns 'CN'.
  • uberpos_command_refund : if $input is "RF" and $item is of type 'IT', the item is removed from the order by deleting the line from the uc_order_products table, but only if the price for the item is 0 or more. When this is done, the order is reloaded and the status of the order is set to "pos_refund_in_progress". Returns 'RF'.
  • uberpos_command_load_order : loads an order by id. The syntax for $input is [ORDERID]OR. The order will only be loaded if $order is empty (meaning it's impossible to load a new order while another order is still active). The loaded order must be a pos order, that is to say it's status string must start with pos_ . Returns 'loaded'.
  • uberpos_command_closing_report : prints a closing report. If $input is 'MG' it will set $js['receipt'] to the output of theme('uberpos_closing_report'), which is a closing report for the current day. If $input is [MMDDYYYY]MG it will set $js['receipt to a closing report for the date MMDDYYYY.. Returns 'new'.
  • uberpos_command_upc : this is the default command that is run when none of the other commands (either the ones from includes/uberpos.commands.inc or the ones from modules that implement hook_uberpos_command) have returned a true value. It adds one or more products to the order, but only if $order is empty or $order has status 'pos_in_progress'. If $input contains an asterisk (*) its syntax is assumed to be [QUANTITY]*[SKU]. Otherwise it's assumed to contain an SKU only and the quantity is considered to be 1. If the products have been added succesfully, the string 'new' is returned. Note: a "UPC" (Universal Product Code) is a product barcode.

includes/uberpos.ca.inc

Entities, triggers and actions for conditional actions can be found in includes/uberpos.ca.inc.

Entities:

  • UC Order Product object (uc_order_product)

Triggers:

  • Product added to uberpos order (uberpos_item_added). Arguments : order (uc_order) and product (uc_order_product)
  • Product removed from uberpos order (uberpos_item_removed). Arguments : order (uc_order) and product (uc_order_product). Does not apply to refunds.

Actions:

  • Decrement stock of a product with tracking activated (uberpos_action_decrement_stock). Arguments : order, product. If the product has stock enabled, decrease it by the product quantity. If this results in the stock going below the threshold, send out a warning email, if warning emails for stock are enabled.
  • Increment stock of a product with tracking activated (uberpos_action_increment_stock). Arguments : order, product. If the product has stock enabled, increase its stock by the product quantity.

js/uberpos.js

All JavaScript resides in uberpos.js. In this file an object Drupal.Uberpos is implemented. Some interface functionality is placed in a behavior named Drupal.behaviors.mainScreen and in a behavior named Drupal.behavior.uberposScreen. Finally there's some extra functions that are defined outside of any object.

  • Drupal.behaviors.mainScreen(context) : This behavior sets up the main screen. It assigns onclick listeners for uberpos_add_text_submit and for uberpos_add_text and focuses the input text field.
  • Drupal.behaviors.uberposScreen : This behavior cancels key down events for tab, enter and up arrow and down arrow. It also runs the uberpos_screen_ajax on window load to get the welcome message (see below).
  • Drupal.Uberpos.shiftFocus(holdFocus) : toggles the class "focused" for the input text field.
  • Drupal.behaviors.uberposLogin(context) : set up the login screen so users can switch between the username and password text fields using the up and down arrow keys.
  • Drupal.Uberpos.updatetime() : update the clock every second.
  • Drupal.Uberpos.jPrintArea(el) : print receipts using the jPrintArea jQuery plugin.
  • Drupal.Uberpos.keyUp : scroll the item list up by one item and focus the input text field.
  • Drupal.Uberpos.keyDown : scroll the item list down by one item and focus the input text field.
  • Drupal.Uberpos.down(prev) : scroll the item list down to the item below prev (if possible).
  • uberpos_add_text(text) : add text to the input text field and forcus the input text field.
  • uberpos_add_text_submit(text) : add text to the input field and run uberpos_screen_ajax.
  • uberpos_screen_ajax() : this function reads input from the text box, clears the text box and runs the Ajax command by feeding the input to uberpos_ajax_execute(input).
  • uberpos_ajax_execute(input) : this function executes an ajax call to admin/store/pos/ajax. It sets $_POST['input'] to its parameter. $_POST['order_id'] comes from the order_id attribute of the Drupal.settings.uberpos JavaScript object. $_POST['item'] is the value of the id attribute of the currently selected item in the products list, if any. On success the function uberpos_screen_ajax_success is called.
  • uberpos_screen_ajax_success(data) : this function updates the screen based on the result of the ajax call. See uberpos.js.uberpos_screen_ajax_success.vsd for details.
  • show_uberpos_throbber() : shows the throbber during ajax calls.
  • hide_uberpos_throbber() : hides the throbber when ajax calls are done.

view/uberpos.views.inc

UberPOS adds a new field type to views named uberpos_handler_field_custom (Custom UberPOS product field link). This field type lets you create links for adding products to the current order.

uberpos.js_.uberpos_screen_ajax_success.pnguberpos_default_interpreter.png

uberpos_ajax.pnguberpos.command.uberpos_command_accept_payment.png