Creating your own HTML User Interfaces

Fieldpine POS allows you to create your own customised User Interfaces using standard HTML, CSS and Javascript. You can also use popular frameworks if you prefer.

Prefer to learn by examples? Dive right in Minimal Example

Operating Models

The visual presentation and user interface is only one part of the puzzle, you also need to consider where your Web page will display and how and where sale "state" is maintained

Method	Description	Scenarios	Sale State
Fieldpine Online Frontend	This is commonly developed for. This mode allows you to create your own user interfaces to replace fieldpine online screens completely with your own. Fieldpine is mainly used for API calls. User » Your Website » Fieldpine Online Or private server Quick Start. Creating a custom selling screen	Custom checkout screens Embed into other sites	Typically Fieldpine
PosGreen Frontend	This is commonly developed for. Use this mode when you want to create your own user interfaces for checkouts. User » PosGreen on Windows This interface is referred to as "WebView2" in reference to the technology used.	Primary screen at front counter/checkout	Fieldpine
PosGreen via Tablet/Mobile	User interfaces created using "PosGreen Frontend" method (above), are generally immediately functional on additional devices. These interfaces can either share and cooperate on the same sale, or have private sales that are only visible on this device User with mobile iPad » PosGreen on Windows User on any browser »	Mobile device using PosGreen as web server Queue busting apps	Fieldpine
IFrame inside PWA or web app	If you have a complete external application where sales capture is a small subfunction of the overall app, you can iframe the Fieldpine UI in that app. This uses PostMessage to communicate across domains. The iframe can be hidden or off screen Your App » iframe » PosGreen on Windows or Fieldpine Online	Primary screen at front counter/checkout	Fieldpine
Private App	If your app wants to completely control the user experience, then see Primitives or OpenApi for details. This documentation is explaining how to create HTML pages that directly interact with Fieldpine. While there is a lot of overlap, this documentation might be slightly too specific. Your App » Fieldpine APIs		Your app or Fieldpine

General Architecture

The basic architecture is as shown, Fieldpine and your HTML page exist as two seperate entities and communicate via events.

Fieldpine	UIStateEvents	»	Your HTML page
	SystemEvents	»
	SaleObjects	»
	Primitives	«
	API Calls	«

A UIStateEVent is sent from Fieldpine to your page when the overall state of the expected User Interface may need to change. This event includes a number of values and data points that you can use to control the appearance of the screen if you wish. For example, when a sale is active the UIStateEvent supplies details of what payment types are currently available, and which ones are currently enabled.

SystemEvents are sent when Fieldpine needs to alert you about something that has happened but might not directly relate to the current sale. The most common example is when a barcode is scanned you receive a SystemEvent with the details

SaleObjects are sent whenever something about the sale you are dealing with changes. It is expected you will extract information you require and update the user screen as needed. The SaleObject is only the details of the sale.

Construction Options

The Fieldpine interface is basically a series of APIs at the lowest level. Howver, building a complete Point of Sale using only the APIs might be a large task. The alternative is that you adopt Fieldpine scripts inside your web app and extend and replace those. The Fieldpine scripts are designed to be customised in this manner, but may not be suitable in all cases.

Method	Notes	Pros	Cons
API Only	With this method of construction you start from a blank HTML file and build all interface logic yourself, calling the Fieldpine APIs	Complete security seperation of scripts 'Cleaner' development if using external frameworks	Ongoing maintenence during system life
WebUI framework	This method of interface creation starts with a Fieldpine example and customises it to suit. In this model, both Fieldpine scripts and your scripts share the same page. That is, your page includes both scripts you create and standard Fieldpine scripts.	Quick and easy Some customisation options can be end user driven via config web pages	Need to learn the framework conventions

More Technical Details

How are the calls to/from Fieldpine made?

If your webpage is the primary frontend to PosGreen, such that when you start PosGreen this web page is displayed, (ie the POS is the browser) then calls in to Fieldpine are made using window.external functions. Fieldpine sends events to your webpage by calling specifically named Javascript functions directly. This interface technique is very fast and typically does not have CORS implications, if applicable

If you are using an external browser, even on localhost, then communication is via standard XMLHttpRequest, or fetch methods. You may need to poll for events depending on site configuration.

In reality you don't need to worry about the above - simply include the Fieldpine Interface Javascript and call those functions, that script will take care of the mechanics

Sessions

When a browser connects to PosGreen, that browser context is allocated a new session. A session maintains state and keeps track of that sessions sales and activity. However, and browser session can request access to any other session, so that you can have the interactive PosGreen and a mobile device working in tandem on the same sale.

Browser One	PosGreen on desktop	Browser Two
Private Session	Root Session
Fieldpine

Running two devices onto the same session is not generally recommended as it can be confusing for users when sales suddenly, appear, change or vanish. However when you need it, you really need it

• Customer Facing Displays
• Manager or support screens that can connect to authorise transactions
• Performing eftpos transactions for some providers that require a Windows screen

Deep technical information about sessions is available Sessions Internals

IFRAME Apps

If your App uses Fieldpine in an IFRAME, then it works identically to a full browser session, with the addition of support for PostMessage so that your app can communicate to Fieldpine. The IFRAME can be visible or hidden as you require.

HTTP Specifics

Your Web pages can exist on an external domain such as https://example.com or distributed internally within Fieldpine

When PosGreen starts and loads the WebPage, it first loads a standard start page and immediately does a page request and redirect operation. This initial start page is used so that if any errors occur the user is presented with a page that will help them, rather than simply a browser error.

If you are loading your webpage from an external host into a browser, you will be confronted by CORS and possibly HTTPS requirements. The solution to this varies depending on site preferences and technical availability.

If you are loading your webpage from an external host into PosGreen directly, then CORS is not currently a concern, but you may still need HTTPS depending on your page requirements

If your PosGreen server is located at fieldpine.com then HTTPS is already available and configured.

If your web page is planning to use Geolocation directly, voice input or any of the other protected services, you will need to arrange HTTPS servers. This can be easily achieved using a Cloudflare tunnel for inhouse servers without opening firewall ports.