Overview

Startup & Operation Capturing & Displaying data Styling with CSS Sale lifecycle

Examples

Hello World / minimal Online Selling Page

Overrideables

User Message User Prompt Device

In Depth

EventSource realtime feed The Fieldpine Object UI Dispatch Data Fields Global Namespace Scripts

WebView2

Barcode Handling

Creating your own HTML Selling Screen

This page is a quick start on how to create your own selling screen for instore, mobile or even B2B selling portals. The screen is hosted on your server/domain and uses Fieldpine as an API engine. The are several ways you can interface to Fieldpine but if you are just getting started, this is probably what you want to do first. And you can be up and running with changes in only a few moments

What you will have at the end of this

Your own https://mysite.com/selling.htm webpage
This selling screen is for trusted staff use, not the general public.
Use API calls (via CORS) to fieldpine.com server

PreReqs

A Fieldpine online login, or details of a private server (IP address, passwords, etc)
Your own webserver. Ideally this web server should have HTTPS support, otherwise browsers will restrict you technically. And you are dealing with potentially sensitive financial and personal information.

How it Works

Browse to https://yoursite/yourpage.htm
↓
Your page loads » private CSS » frameworks » other components	→	Your page loads webuiboot.js
		Javascript on your page initialises Fieldpine
		WebBoot loads other required JS files
		If needed, will prompt for fieldpine account details
Receives "FieldpineReady" event		↵

Ready to sell
Your page sends "sell product X" to Fieldpine	→	Fieldpine Engine updates
Receives events on your page to update		↵

Step 1 - Setup Fieldpine Account

Login to your Fieldpine account and enable CORS from your website. For security reasons you must specifically enable the websites that will be calling into Fieldpine. You are enabling the DNS names, not individual IP addresses.

TBS, Where/How

Step 2 - Copy a Fieldpine Selling Screen

The quickest way to get started is to copy a Fieldpine example screen to your server and then customise it. Some Fieldpine screens are specifically built with this purpose in mind.

Browse to /...TBS... in your browser
Select View Source, and then "Save As" to save this file to your machine
Copy that "saved_page.htm" file to your webserver
Edit "Saved_Page.htm"
1. Find this line
```
<script src="/report/elink/webuiboot.js"></script>
```
  and change it to
```
<script src="https://a1.fieldpine.com/report/elink/webuiboot.js"></script>
```
  where a1.fieldpine.com is the server you have logged into. If the webserver you are using requires authorisation to access this file, then use a1.fieldpine.com for now and refer to step NNN once you are minimally running.
2. Find the line containing WebUiBoot_DecodeAndGo. The rest of the line may vary slightly from this example
```
let args = WebUiBoot_DecodeAndGo({ "UiNum": 1, "CodeVersion": 'latest' }, function () {
```
  and add the parameter BootMethod=prompt
```
let args = WebUiBoot_DecodeAndGo({ "UiNum": 1, "CodeVersion": 'latest' ,"BootMethod": 'prompt' }, function () {
```
3. Find the HTML <BODY> tag and add some "Hello World" visible text so you can verify your page is being used.
4. Find and comment out any IFRAME. Cross origin IFrame have additional security implications and we will cover this later in Step E.
Browse to http(s)://yourserver.com/SavedPage.htm (whatever the new URL is) and the following should happen
1. Your webserver should deliver the SavedPage.htm file
2. The WebUiBoot.js script should be loaded
3. The page should prompt for your login details. This step might be skipped if you have already authorised. If you open a new browser, forcing the removal of sessionStorage information, then you should be prompted
4. Your "Hello World" text should be visible
5. The page should operate as normal

Done. You can now customise this selling screen. We've outlined some common changes you might want to make below (step A,B,C etc), and you can do these in any order, they are independant of each other.

Notes / FYI

There are few things you possibly need to know, if you don't understand all this section now, don't worry and just be aware of them.

If you are a web designer building a page, your pages typically will not be hosted on fieldpine.com websites directly, due to security reasons. It can be hosted on sites that are using a CNAME DNS to point to fieldpine server however. The technical issue is that we cannot permit pages hosted on fieldpine.com to be controlled by third parties or include external scripts

You are free to design/build and use whatever technology you want in your webpage, it is after all your page and Fieldpine can be considered an API service with some helper Javascript

Fieldpine scripts used for selling screens assume that a modern browser exists. We offer no support for older browsers that do not conform. This statement only applies to "in store" screens, other areas of Fieldpine do support older browsers (esp those that interact with customers)

Step A - Changing the HTML, CSS

The quickest change to make is to change the HTML and CSS to alter the content and the appearance.

CSS

CSS styling is completely open to you to change. Fieldpine drawn elements (step B and step C) will create HTML elements using a standard CSS naming structure, so you can style them as well.

If an HTML element has an data-fdl-element="xyz" attribute then that element is drawn by Fieldpine scripts. Skip to Step C to learn how to customise these elements.

Add a QuickSell Button

A quicksell button is an HTML element that sells an item onto a sale.

Insert the HTML/CSS to draw the button. While this example uses a button, you can use whatever you like

<input type='button' value='Quick Sell Coffee' onclick='FieldpinePrimitive(":sale add pid 1234")'>

The call FieldpinePrimitive() instructs the Fieldpine Engine to add product id#1234 to the current sale

Not keen on inline "onclick" handlers, or cannot use them directly - it is not required, you can use AttachEventListener logic. It is much simplier for documentation purposes though, so most of our examples will use this pattern

Adding other items

In the same way you added a Quicksell button, you can add whatever elements and controls to the web page you want. Your scripts and elements interact with Fieldpine and the sale via FieldpinePrimitive() and the FieldpinePos object.

We generally suggest you override the Fieldpine Event Handlers if they exist. For example, there is a "Product Search" function that Fieldpine provides - this draws HTML onto the web page on demand. You are better to override this event handler than simply creating a function your page calls directly. If your page calls your function directly, then any Fieldpine script that calls "Product Search" will still use the Fieldpine version.

If you add an element that is reacting to the sale state, say an element that draws the current customer details, then you can use data-fdl-event="xyz" to request Fieldpine calls your custom function when the sale state changes

Step B - Replacing Fieldpine Event Handlers

FieldpinePos will often need to draw specific HTML on the screen. In order to reduce the burden of you needing to replace every function required, the engine calls a function to perform this task. You can then replace these functions with your own code. Some functions are commonly overriden, such as the "display a message to the user", while others "prompt for eftpos in progress" are rarely changed. If you do not override a Fieldpine handler, then Fieldpine HTML will be generated, using standard CSS naming though, so you can still style these elements

Replacing the "UserMessage" Handler

UserMessage is invoked whenever Fieldpine wants to display a messge to the user, be it an error message, a note, or perhaps a selling message when a product is sold. The default handler calls alert() which is not always a nice user experience, and can be disabled from displaying if the user disables them.

In your FieldpineReady event handler, insert Javascript to point to your function

window.addEventListener('FieldpineReady', function (args) {
    // This event fires at various stages so you can track the steps of Fieldpine coming online      

    if (args.detail.Stage === 2) {  // Stage=2 is when Fieldpine is "good to go"

        // Let's install a custom function
        Fieldpine.UIDispatch['usermessage'] = function(args) { /* your javascript code here */ };
        // or this style, where MyUserMessageFunction is defined elsewhere
        Fieldpine.UIDispatch['usermessage'] = MyUserMessageFunction;
    }
});

Create your own UserMessage function

function MyUserMessageFunction(arg) {
    // The arg to this function can be either a simple string to display
    // or an object with details and instructions

    var message = arg;
    if (typeof arg === 'object') message = arg.Message
    // For this simple example, we will assume everything is a simple message
    // and ignore controls (wrong, but ok for introductory example)

    // Lets not use alert()
    // alert(m);

    // Instead we will write to a HTML element
    document.getElmentById("myMessageArea").innerHTML = message;
}

More information UI Dispatch