Skip to content

Ui

ui : object

Interact with and modify the PostalPoint user interface.

Kind: global namespace

ui.addToolsPage(page, title, id, description, cardTitle, icon, type)

Add a page to the Tools screen. If type is set to "function", the page argument will be run as a function and will not be expected to return a page component. Framework7 Page Component documentation

Kind: static method of ui

Param Type Default Description
page string | function Page content as a Framework7 component page. If page is a string ending in .f7 it is treated as a file path and the page content will be loaded from disk. If page is any other string, it is treated as the page content. If page is a function, it will be called and must return the page content (unless type is set to "function", see examples)
title string Page title.
id string Page ID. Make it unique, or pass an empty string to be assigned a random ID.
description string Description of this tool for its card on the Tools screen.
cardTitle string Title of the card for this page on the Tools screen.
icon string FontAwesome icon class, for example, "fa-solid fa-globe". FontAwesome Pro solid, regular, light, and duotone icons are available.
type string "page" What kind of data is supplied by page: "page" or "function".

Example

// Full plugin that displays an alert when the card is clicked on the Tools page
exports.init = function () {
    global.apis.ui.addToolsPage(
                                 displayMessage,
                                 "click me",
                                 "clickmecard",
                                 "Click here to see a message",
                                 "Click This Card",
                                 "fa-solid fa-arrow-pointer",
                                 "function"
                               );
}

function displayMessage() {
    global.apis.alert("Card clicked");
}
Example
// Open a dynamically-generated page
function rollDice() {
    var randomNumber = Math.round(Math.random() * 6) + 1;
    return `<div class="page">
        <div class="navbar">
            <div class="navbar-bg"></div>
            <div class="navbar-inner">
                <a href="#" class="link back">
                    <i class="icon icon-back"></i>
                </a>
                <div class="title">Random Number</div>
            </div>
        </div>
        <div class="page-content">
            <div class="block">
                <h1>You rolled ${randomNumber}</h1>
            </div>
        </div>
    </div>`;
}
global.apis.ui.addToolsPage(
                             rollDice,
                             "Random",
                             "randomnumbercard",
                             "Click here for a random number",
                             "Random Number",
                             "fa-regular fa-dice",
                             "page"
                           );
Example
// Open a page from a file.
// See https://framework7.io/docs/router-component#single-file-component
global.apis.ui.addToolsPage(
                             global.apis.getPluginFolder("example-plugin") + "/page.f7",
                             "Page",
                             "filepage",
                             "Open page.f7 from the plugin installation folder",
                             "Open Custom Page",
                             "fa-regular fa-file",
                             "page"
                           );

ui.addHomeTab(content, title, icon, id) ⇒ undefined

Add a custom tab to the PostalPoint home screen. Works almost the same as addToolsPage.

Kind: static method of ui

Param Type Description
content string | function Tab content. It is rendered/processed when the user navigates to the Home screen and clicks the tab; if the user navigates to a different screen and back to Home, it will be re-rendered. If content is a string ending in .f7 it is treated as a file path and the content will be loaded from disk. If content is any other string, it is treated as the content. If content is a function, it will be called and must return the content.
title string Tab title. Keep it short; depending on screen size and tab count, you have as little as 150px of space.
icon string FontAwesome icon displayed above the tab title.
id string Tab ID. Make it unique, or pass an empty string to be assigned a random ID. If addHomeTab is called with a tab ID that is already registered, it will be overwritten.

Example

global.apis.ui.addHomeTab("<div class='block'>Hello</div>", "Hello Tab", "fa-duotone fa-hand-wave", "hellotab");
Example
function renderTab() {
    return "<template><div><h1>${hellovar}</h1></div></template><script>export default (props, {$on, $update, $f7}) => {var hellovar = 'hello world'; return $render;}</script>";
}
global.apis.ui.addHomeTab(renderTab, "Hello Template", "fa-duotone fa-file-code", "hellotemplatetab");

ui.showProgressSpinner(title, text, subtitle) ⇒ undefined

Show a notification with a loading icon.

Kind: static method of ui

Param Type Description
title string The message to show on the spinner.
text string Optional. Body text on the spinner.
subtitle string Optional. Sub-heading under the title.

ui.hideProgressSpinner()

Close the notification opened by showProgressSpinner.

Kind: static method of ui

ui.openSystemWebBrowser(url)

Open the native OS default browser to the URL given.

Kind: static method of ui

Param Type
url string

ui.openInternalWebBrowser(url)

Open a web browser inside PostalPoint. The browser has forward/back/close buttons.

Kind: static method of ui

Param Type
url string

Example

global.apis.ui.openInternalWebBrowser("https://postalpoint.app");
global.apis.eventbus.on("browserNavigate", function (newUrl) {
    global.apis.alert(`New URL: ${newUrl}`, "Browser Navigated");
    if (newUrl == "https://closeme.com") {
        global.apis.eventbus.emit("browserCloseRequest");
    }
});

ui.clearCustomerScreen()

Clear any custom content on the customer-facing display, defaulting back to blank/receipt/shipping rates, as applicable.

Kind: static method of ui

ui.setCustomerScreen(content, type, displayInCard, cardSize, displayStatusBar)

Render content on the customer-facing display. 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. To display the iframe in a card centered on the screen, set displayInCard to true and pass the desired dimensions (w, h) of the card in px. If the requested size is larger than the available screen space, the card will instead fill the available space. Warning: Do not load third-party websites, this is a security risk. Wrap it in a tag if you need to display one.

Kind: static method of ui

Param Type Default Description
content string Page content.
type string "html" Format of the content. One of "html", "pdf", "raw", "body", or "text".
displayInCard boolean false Set to true to wrap the content in a card UI.
cardSize Array.<number> [300,300 Size of the card UI if displayInCard == true.
displayStatusBar boolean true Whether the bar on the bottom of the screen should be visible, containing the store logo and scale weight.

Example

// How content is converted by PostalPoint before display:
if (type == "html") {
    customerScreenContent = `data:text/html;charset=utf-8,${content}`;
} else if (type == "pdf") {
    customerScreenContent = `data:application/pdf,${content}`;
} else if (type == "raw") {
    global.customerScreenContent = `${content}`;
} else if (type == "body") {
    customerScreenContent = `data:text/html;charset=utf-8,<!DOCTYPE html>
    <meta charset="utf-8">
    <title></title>
    <style>
        html, body {margin: 0; padding: 0; font-family: Roboto, Ubuntu, Arial, sans-serif;}
        h1, h2, h3 {margin: 0;}
    </style>
    <div id="maindiv">${content}</div>`;
} else {
    customerScreenContent = `data:text/plain;charset=utf-8,${content}`;
}

ui.collectSignatureFromCustomerScreen(title, terms, termstype)

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,..."}

Kind: static method of ui

Param Type Default Description
title string null Display a title/header on the customer screen. Currently ignored, but may be used in the future.
terms string | boolean false Set to a string to display terms and conditions or other text content next to the signature pad.
termstype string "body" "html", "pdf", "raw", or "body". See setCustomerScreen()

Example

global.apis.ui.collectSignatureFromCustomerScreen("", "<p>By signing, you agree to pay us lots of money</p>", "body");
global.apis.eventbus.on("customerSignatureCollected", function (sigdata) {
    const pngDataURL = sigdata.png;
    const svgDataURL = sigdata.svg;
});

ui.cancelSignatureCollection()

Cancels customer signature collection and returns the customer-facing display to normal operation.

Kind: static method of ui
Example

global.apis.ui.cancelSignatureCollection();

ui.clearSignaturePad()

Erase the signature drawn on the customer-facing display. Note that the customer is also provided a button to do this.

Kind: static method of ui
Example

global.apis.ui.clearSignaturePad();

ui.getCustomerDisplayInfo() ⇒ Object

Describes if the customer-facing display is currently enabled, and if it supports customer touch interaction.

Kind: static method of ui
Returns: Object - {"enabled": true, "touch": true}
Example

var info = global.apis.ui.getCustomerDisplayInfo();