Oracle® MICROS Simphony
Simphony HTML5 Custom Page
Control API Reference Guide
Release 19.7
June 2024
Copyright © 2024, Oracle and/or its affiliates.
Custom Page Controls allow an extensibility developer to place user-defined HTML5 controls on a POS page.
The general life cycle of a Custom Page Control is:
General notes on page controls:
The Extension Application will register the Page Control with the POS Client. Any interaction between the Extension Application and the Page Control is optional and not required if the Page Control handles any logic on its own.
The actual HTML5 that will be rendered and shown. HTML5 should be understood as any combination of HTML, CSS and JavaScript that is required.
It is suggested to pay attention to create responsive layout(s). Neither the POS client resolution can be foreseen nor the dimension of the page control on the actual page.
There are many ways to supply Page Control HTML5. The extensibility application can read it from Content, Extension Application Content, the Extensibility Package, or as an embedded resource in a C# extension application. Which source is chosen is up to the extensibility developer.
For Application Content it needs to be ensured that both Page Control HTML5 and JS/C#/SIM reside within the same Ext.App.
Page controls utilize one or more of the following API objects:
Micros.PosCore.Extensibility.UserInterface
namespaceObject | Description |
---|---|
Resource specification objects | |
PageControlInPlaceResourceParameters
|
html content is supplied in the object |
PageControlLocalDirectoryResourceParameters
|
content resides on disk |
PageControlPackageDirectoryResourceParameters
|
content resides in package |
PageControlWebDirectoryResourceParameters
|
web directory zip byte[] array content is supplied in the parameters object |
PageControlExtAppContentResourceParameters
|
web directory zip byte[] array content exists in Extension Application Content |
PageControlContentResourceParameters
|
content web directory zip byte[] array content exists in Content |
Async message to one or more page controls | |
PageControlAsyncMessageParameters
|
Micros.PosCore.Extensibility.Ops
namespaceObject | Description |
---|---|
OpsPageControlEventArgs
|
synchronous request/response event args |
OpsPageControlAsyncEventArgs
|
asynchronous event args |
Object | Description |
---|---|
SimphonyPOSAPI
|
root level API object |
SimphonyPOSAPI_ExtensibilityEventParameters
|
Used with synchronous messages from HTML5 Custom Page Control to the extension application |
SimphonyPOSAPI_ExtensibilityMethodParameters
|
Used with synchronous method call from HTML5 Custom Page Control into the extension application |
SimphonyPOSAPI_OpsCommand
|
Used with postOpsCommand() or
postOpsCommandMacro()
|
SimphonyPOSAPI_AsyncMessageType
|
Used with asynchronous messages from HTML5 Custom Page Control to the extension application |
SimphonyPOSAPI_ReadyMessage
|
Object type when msg.Type is
SimphonyPOSAPI_AsyncMessageType.Ready
|
SimphonyPOSAPI_ExtAppAsyncMessage
|
Object type when msg.Type is
SimphonyPOSAPI_AsyncMessageType.ExtApp
|
SimphonyPOSAPI_OpsContextChangeMessage
|
Object type when msg.Type is
SimphonyPOSAPI_AsyncMessageType.OpsContextPropertyChanged
|
class __SimphonyPOSAPI_BaseAsyncMessage
{// indicates the type of object for this message
;
Type
}
// object type when msg.Type == SimphonyPOSAPI_AsyncMessageType.Ready
class SimphonyPOSAPI_ReadyMessage extends __SimphonyPOSAPI_BaseAsyncMessage
{
}
// object type when msg.Type == SimphonyPOSAPI_AsyncMessageType.ExtApp
class SimphonyPOSAPI_ExtAppAsyncMessage extends __SimphonyPOSAPI_BaseAsyncMessage
{// data from the extensibility application
;
Data
}
// object type when msg.Type == SimphonyPOSAPI_AsyncMessageType.OpsContextPropertyChanged
class SimphonyPOSAPI_OpsContextChangeMessage extends __SimphonyPOSAPI_BaseAsyncMessage
{// list of names of OpsContext values that have changed, such as "TransEmployeeID"
= [];
Names }
Method / Property | Description |
---|---|
RegisterPageControlResource(string extAppName, string key, object resourceObj)
|
Registers a Page Control Resource so that OPS will be able to render it.
|
PageControlResourceParameters (base abstract class) |
|
PageControlInPlaceResourceParameters
|
|
PageControlLocalDirectoryResourceParameters
|
|
PageControlPackageDirectoryResourceParameters
|
|
PageControlWebDirectoryResourceParameters
|
|
PageControlExtAppContentResourceParameters
|
|
PageControlContentResourceParameters
|
|
Method / Property | Description |
---|---|
SendAsyncPageControlMessage(parms)
|
Sends an asynchronous message to the page control
|
PageControlAsyncMessageParameters
|
|
Method / Property | Description |
---|---|
OpsPageControlAsyncEvent
|
Triggered by any asynchronous message that is received from a Page
Control. A OpsPageControlAsyncEventArgs is passed in.
|
OpsPageControlAsyncEventArgs
|
|
OpsPageControlEvent
|
Triggered when page control sends message to ext application. A
OpsPageControlEventArgs is passed in.
|
OpsPageControlEventArgs
|
|
Method / Property | Description |
---|---|
setAsyncMessageCallback(callback)
|
Sets the callback function that handles asynchronous messages from the Ext.App |
log(level, text)
|
level is of type SimphonyPOSAPI_LogLevel , see
below
|
postShowError(text)
|
causes the text to be shown as error in OPS
|
postShowMessage(text)
|
causes the text to be shown as message in OPS
|
postOpsCommand(opsCmd)
|
opsCmd is of type SimphonyPOSAPI_OpsCommand ,
see below
|
postOpsCommandMacro(opsCmdMacro)
|
opsCmdMacro is a list of
SimphonyPOSAPI_OpsCommand , see below
|
postMessageToExtApp(message, data)
|
both message and data are string
|
runExtensibilityEvent(parms, callback)
|
parms is of type
SimphonyPOSAPI_ExtensibilityEventParameters()
|
runExtensibilityMethod(parms, callback)
|
parms is of type
SimphonyPOSAPI_ExtensibilityMethodParameters()
|
SimphonyPOSAPI_LogLevel
NONE: -99,
LOG_ALWAYS_ERROR: -3,
LOG_ALWAYS_WARN: -2,
LOG_ALWAYS_INFO: -1,
LOG_ALWAYS_DEBUG: 0,
LOG_ALWAYS: 0,
LIGHT_FLOW: 1,
GENERAL_FLOW: 2,
DETAIL_FLOW: 3,
BUFFER_DUMPS: 4,
ULTIMATE_DEBUG: 5,
SimphonyPOSAPI_OpsCommand
{
Command;
Number;
Index;
Text;
Arguments;
NextPage;
NextPanel;
}
Single extension application, single page control
Multiple extension application, each with its own page control
One extensibility application, multiple page controls
A HTML5 custom page control requires valid HTML5 to be present, i.e. as Application Content or as Content. This can be either a plain string or a Web-Directory (zipped).
A HTML5 custom page control also requires an Ext.App that will initialize it. The Ext.App will read the HTML content (see previous point) and will determine the resource key (string) to be used in the EMC page configuration. The resource key can be any value.
A HTML5 custom page control can be added to any page using the option “Custom Html Page Control” in the “Other…” menu:
In the properties of the HTML5 custom page control the Ext.App Name as well as the resource key (string) need to be specified. The argument value is optional.
The first step is to register the Custom HTML Page Control via the
OpsContext.RegisterPageControlResource()
method. The
arguments are straightforward:
string extAppName
: the name of the extension
applicationstring key
: an identifier for that Custom HTML Page
Control. This must match what is programmed on the page.object resourceObj
: the source for the html
content.There are 6 different ways to specify the html source.
PageControlInPlaceResourceParameters
: The html content
is a simple html string. This should be used if your entire Custom HTML
Page Control can be contained within a single index.html.PageControlLocalDirectoryResourceParameters
: The html
content is in a web directory on the local disk. This is usually used
during development but generally not for production machines.PageControlPackageDirectoryResourceParameters
: The
html content is in a web directory in the ext app package. If you are
using packages then this is the simplest and preferred way for complex
html content.PageControlWebDirectoryResourceParameters
: The zipped
web app is read from an external source as a byte array. This is useful
for debugging.PageControlExtAppContentResourceParameters
: The zipped
web app is in extension application content. If you are not using
packages then this is the simplest and preferred way for complex html
content.PageControlContentResourceParameters
: The zipped web
app is in content.let resourceParms = null;
// both page controls' source is in the package itself
= new _pos.Micros.PosCore.Extensibility.UserInterface.PageControlPackageDirectoryResourceParameters();
resourceParms .DirectoryName = "pagectl/app1";
resourceParms.Environment.Context.RegisterPageControlResource(_api.Runtime.ApplicationName, "app1", resourceParms);
_api
= new _pos.Micros.PosCore.Extensibility.UserInterface.PageControlPackageDirectoryResourceParameters();
resourceParms .DirectoryName = "pagectl/app2";
resourceParms.Environment.Context.RegisterPageControlResource(_api.Runtime.ApplicationName, "app2", resourceParms); _api
Similar to Custom HTML Dialogs, Custom HTML Page Control are provided
a global API object: SimphonyPOSAPI. This can be inserted into the
global namespace using the <script>
tag,
<!DOCTYPE html>
html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<script src="Simphony/POSPageControlAPI.js" type="text/javascript"></script>
<
SCRIPT LANGUAGE='JavaScript'>
<
console.log(SimphonyPOSAPI.key);SCRIPT> </
No. You must wait for the Ready message to begin using API functions.
You Custom HTML Page Control should subscribe to message callback facility in the API. By registering your callback you will receive notification of various events.
// register callback
var _api = SimphonyPOSAPI;
.setAsyncMessageCallback(asyncMessageCallback);
_api
function asyncMessageCallback(msg)
{switch (msg.Type)
{case SimphonyPOSAPI_AsyncMessageType.Ready:
// api can be accessed
break;
} }
There are two types of messages that can be sent:
The following code exists in the Custom HTML Page Control source.
var _api = SimphonyPOSAPI;
// extension application receives message in event
function runExtensibilityEvent(command, argument, callback)
{let parms = new SimphonyPOSAPI_ExtensibilityEventParameters();
.command = command;
parms.argument = argument;
parmsreturn _api.runExtensibilityEvent(parms, (parmsOut) => processResponse(parmsOut, callback));
}
// extension application method is called directly
function runExtensibilityMethod(method, argument, callback)
{let parms = new SimphonyPOSAPI_ExtensibilityMethodParameters();
.method = method;
parms.argument = argument;
parmsreturn _api.runExtensibilityMethod(parms, (parmsOut) => processResponse(parmsOut, callback));
}
function processResponse(parmsOut, callback)
{if (parmsOut.isSuccess())
callback(parmsOut.response);
else if (parmsOut.isError())
alert('Error: ' + parmsOut.response);
else if (parmsOut.isTimeout())
alert('Timeout');
}
The following code exists in the extension application.
var _api = SimphonyExtensibilityAPI;
.Eventing.SubscribeToEvent('OpsPageControlEvent', OnOpsPageControlEvent);
_api
// responds to page control _api.runExtensibilityEvent() method
function OnOpsPageControlEvent(sender, args)
{.Response = "extensibility event myresponse";
args
}
// responds to page control _api.runExtensibilityMethod() method
.mymethod = function (args)
globalThis
{.Response = 'extensibility method response';
args }
The following code exists in the Custom HTML Page Control source.
var _api = SimphonyPOSAPI;
let line = `async message from page control; ${new Date()}`;
.postMessageToExtApp('mycommand', line); _api
The following code exists in the extension application.
var _api = SimphonyExtensibilityAPI;
.Eventing.SubscribeToEvent('OpsPageControlAsyncEvent', OnOpsPageControlAsyncEvent);
_api
function OnOpsPageControlAsyncEvent(sender, args)
{let line = `OpsPageControlAsyncEvent: args sent in: ${args.ToString()}`;
console.log(line);
}
The extension application can send an asynchronous message to the Custom HTML Page Control via OpsContext.
The following code exists in the extension application.
var _api = SimphonyExtensibilityAPI;
var _poscore = _api.Common.LoadPosCore();
function sendToPageControl()
{let parms = new _poscore.Micros.PosCore.Extensibility.UserInterface.PageControlAsyncMessageParameters();
.ExtAppName = _api.Runtime.ApplicationName;
parms.Key = "app1";
parms.ID = null; // if null, all page controls with the specified key receive the message
parms.Data = "data";
parms.Environment.Context.SendAsyncPageControlMessage(parms);
_api }
The following code exists in the Custom HTML Page Control source.
var _api = SimphonyPOSAPI;
function onload() {
.setAsyncMessageCallback(asyncMessageCallback);
SimphonyPOSAPI
}
function asyncMessageCallback(msg) {
switch (msg.Type) {
case SimphonyPOSAPI_AsyncMessageType.Ready:
// API is ready
// msg is of type SimphonyPOSAPI_ReadyMessage
break;
case SimphonyPOSAPI_AsyncMessageType.OpsContextPropertyChanged:
// a OpsContext property changed
// msg is of type SimphonyPOSAPI_OpsContextChangeMessage
// you might want to check msg.Names[] array
break;
case SimphonyPOSAPI_AsyncMessageType.ExtApp:
// async message received from extension application
// msg is of type SimphonyPOSAPI_ExtAppAsyncMessage
// you might want to check msg.Data
break;
} }
This is perhaps the key question concerning the design of your page control. Communications and rendering is rather straightforward. State management can be difficult. Points to remember:
Designing an API is difficult. There is a balance of providing functionality to the consumer versus the cost of building out and maintaining a complicated API.
Technically the Custom HTML Page Control API only needs methods for communicating with the extension application. All other functionality (e.g. logging) could be implemented by the ext app and not be part of the API.
There were some very common functions that were added to the Custom HTML Page Control API. It was decided to put them into the API, rather than every extensibility developer implementing them in each of their Custom HTML Page Control applications:
The following functionality was deemed too complicated to implement in a general way for all extensibility applications:
For each of these, each extensibility writer can determine which subset of this functionality is required for their Custom HTML Page Control, and implement a customized solution.
One may be tempted to serialize all of OpsContext, check detail, or extensibility events to JSON and send them to the page control. These .Net objects are not serializable as-is. The extensibility application should create a Dictionary<> with the required elements from these objects and serialize the dictionary to JSON.