PostalPortal/PostalPoint_Plugins
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add customer display functions/events and package.json metadata spec

Browse Source
This commit is contained in:
Skylar Ittner 2025-06-29 01:22:04 -06:00
parent bc2ffa0e86
commit 70fb105fcc
2 changed files with 40 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
README.md
View File

@ -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 `<webview src="..."></webview>` 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

3
docs/Events.md
View File

@ -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