diff --git a/README.md b/README.md index 0965806..14ac02d 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,8 @@ PostalPoint® supports plugin extensions. Plugins can hook into PostalPoint to a ## Plugin Package Structure -A plugin is distributed as a simple ZIP file, containing a folder. That folder's name is the plugin -name. The folder then has at least one file, named `plugin.js`. -he `exports.init` function in `plugin.js` is executed when PostalPoint launches, allowing the plugin +A plugin is distributed as a simple ZIP file, containing a folder. The folder then has at least one file, named `plugin.js`. +The `exports.init` function in `plugin.js` is executed when PostalPoint launches, allowing the plugin to request involvement with various events in PostalPoint. PostalPoint installs plugin packages by unzipping their contents into a plugins folder. @@ -34,13 +33,41 @@ exports.init = function () { Yes, the smallest plugin really is just two lines of code, and accessing PostalPoint features really is that easy. +## Plugin Metadata File + +While not strictly required, a `package.json` is encouraged, and allows specifying the plugin's +display name, PostalPoint version compatibility, and using a filename other than `plugin.js` +for the main plugin script. + +Sample: + +```js +{ + "name": "plugin-id-here", + "main": "plugin.js", + "description": "Human-readable description of the plugin", + "version": "1.0.0", + "author": "Your Name", + "license": "Code license name", + "postalpoint": { + "pluginname": "Display Name for Plugin", + "minVersion": "000034", + "maxVersion": "001000" + } +} + +``` + +PostalPoint version codes are MMMnnn where MMM is the major version and nnn is the minor version, zero-padded. +So version 0.35 is "000035", and 1.23 is "001023". + ## Example Plugins Check out the `examples` folder for sample plugins demonstrating the API features. ## PostalPoint Plugin API -The PostalPoint plugin API is a globally-available object. +The PostalPoint plugin API is a globally-available object named `global.apis`. ### API List @@ -173,6 +200,12 @@ Use `setBig` and `getBig` for storing data except for very short string or numbe * `hideProgressSpinner()`: hide the UI element created by `showProgressSpinner`. * `openInternalWebBrowser(url)`: Open a web browser UI, navigating to the URL. The browser has forward/back/close buttons. * `openSystemWebBrowser(url)`: Open the native OS default browser to the URL given. +* `getCustomerDisplayInfo()`: Describes if the customer-facing display is currently enabled, and if it supports customer touch interaction: `{"enabled": true, "touch": true}`. +* `clearCustomerScreen()`: Clear any custom content on the customer-facing display, defaulting back to blank/receipt/shipping rates, as applicable. +* `setCustomerScreen(content, type = "html")`: Encodes `content` as a data URI (example: `` `data:text/html;charset=utf-8,${content}` ``) and renders on the customer-facing display. If `type` is `html`, renders the string as HTML. If `type` is `pdf`, displays a PDF viewer. If `type` is `raw`, functions like setting an iframe's src to `content`. All other `type` values are rendered as `text/plain`. Warning: Do not load third-party websites, this is a security risk. Wrap it in a `` tag if you need to display one. +* `collectSignatureFromCustomerScreen()`: Show a signature pad on the customer-facing display. When the customer indicates the signature is finished, the `customerSignatureCollected` event is emitted with the data `{"svg": "data:image/svg+xml;base64,...", "png": "data:image/png;base64,..."}` +* `cancelSignatureCollection()`: Cancels customer signature collection and returns the customer-facing display to normal operation. +* `clearSignaturePad()`: Erase the signature on the customer-facing display. Note that the customer is also provided a button to do this. #### Utilities diff --git a/docs/Events.md b/docs/Events.md index 7f2d5b1..18b103b 100644 --- a/docs/Events.md +++ b/docs/Events.md @@ -7,7 +7,10 @@ Plugins can use `global.apis.eventbus` to receive events when certain actions ha * `barcodeScanned`: Contents of a barcode that was just scanned. * `browserCloseRequest`: The embedded web browser listens for this event, and closes itself when received. * `browserNavigate`: Contains the URL the embedded web browser just navigated to. +* `sendToCustomerScreen`: Emit to send data via `window.postMessage` to a custom HTML interface on the customer-facing display. * `transactionFinished`: Contains a receipt object of a transaction that was just finalized. +* `receiveFromCustomerScreen`: Contains the event sent from the customer-facing display's custom HTML interface via `window.parent.postMessage` +* `customerSignatureCollected`: Contains a signature image from the customer-facing display, in the structure `{"svg": "data:image/svg+xml;base64,...", "png": "data:image/png;base64,..."}`. ## Example Code