Create Template for Smart Menu Editor (Open-API)

Owned by Geoffry Fang

Last updated: Sept 27, 2024

Work In Progress (Coming Soon)

Our development team is working very hard to make Open-API available to the general public in the near future. This documentation is incomplete; please only refer to this documentation per instruction from the Kuusoft team.

Table of Contents

Introduction

Smart Menu Editor (also known as Digital Menu Boards Editor System) is a model that separates contents apart from visuals. In this article, we will go over some of the basics of how to create templates that will work with the Smart Menu Editor.

Template Definition Basic Concept

The template definition is a text file consisting of definitions for both visual and content. It consists of two major elements, a Visual Template aspect and a Content Template aspect.

Visual Template Definition

The visual template is responsible for defining the look and feel of the data. It does not define the type of data or structure of data. It also defines the overall look and feel of the menu board. The Smart Menu Editor leverages the existing HTML, CSS, and Javascript technology to reduce the learning curve for developers. Keep in mind, Smart Menu Editor is only using HTML, CSS, and Javascript as a scripting languages to declare the look & feel of the layout.

Content Template Definition

The content template is defined using Smart Menu Editor Run-Time Declarative Syntax (RTDS). It will be responsible for defining the structure of the input and how the input is being used. The RTDS directive begins with "<!–@" and ends with "-->". An example looks like the following

Example of RTDS

<!--@CATEGORY.START(My Category)-->

Basic Structure of Template Definition

The basic visual structure of the template definition is identical to a basic HTML page.

Basic Visual Structure of Template

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8">
    <title></title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
</head>

<body>
	<h1>Hello World</h1>
</body>

</html>

Important

To ensure it works natively on all screen resolutions, you must define the initial-scale=1.

Here's a basic example of declaring content structure using RTDS

Basic example of content structure

<!--@CATEGORY.START(1 Price Tag)-->
<!--@CATEGORY.FIELD1.TEXT(Category Description)-->
<!--@CATEGORY.FIELD2.TEXT()-->
<!--@CATEGORY.FIELD3.TEXT()-->
<!--@CATEGORY.FIELD4.TEXT()-->
<!--@CATEGORY.FIELD5.TEXT()-->

	<h2>@CATEGORY_NAME</h2>
	<p>@CATEGORY_FIELD1</p>


	<!--@ITEM.START-->
	<!--@ITEM.FIELD1.TEXT(Price)-->
	<!--@ITEM.FIELD2.TEXT()-->
	<!--@ITEM.FIELD3.TEXT()-->
	<!--@ITEM.FIELD4.TEXT()-->
	<!--@ITEM.FIELD5.TEXT()-->
	<!--@ITEM.FIELD6.TEXT()-->
	<!--@ITEM.FIELD7.TEXT()-->
	<!--@ITEM.FIELD8.TEXT()-->
	<!--@ITEM.FIELD9.TEXT()-->
	<!--@ITEM.FIELD10.TEXT()-->
		<h3>@ITEM_NAME - @ITEM_FIELD1</h3>
		<p>@ITEM_DESCRIPTION</p>
	<!--@ITEM.END-->


<!--@CATEGORY.END-->

Let's take a look at the code block above line by line

Basic example of content structure

<!--@CATEGORY.START(1 Price Tag)-->

This command defines the beginning of a type of category with the name "1 Price Tag".

Basic example of content structure

<!--@CATEGORY.FIELD1.TEXT(Category Description)-->
<!--@CATEGORY.FIELD2.TEXT()-->
<!--@CATEGORY.FIELD3.TEXT()-->
<!--@CATEGORY.FIELD4.TEXT()-->
<!--@CATEGORY.FIELD5.TEXT()-->

The command let the system knows that we will be using one dynamic field, and the caption should display as "Heading Information". Field 2-5 is not being used, so we leave it blank.

Basic example of content structure

	<h2>@CATEGORY_NAME</h2>
	<p>@CATEGORY_FIELD1</p>

@CATEGORY_NAME will be replaced by data provided by the user. Since we declare Field1 is being used in previous lines, we can use the data provided by the user for "Category Description" by inserting @CATEGORY_FIELD1. This will automatically get replaced with user-supplied data at run-time.

Basic example of content structure

	<!--@ITEM.START-->
		<!--@ITEM.FIELD1.TEXT(Price)-->
		<!--@ITEM.FIELD2.TEXT()-->
		<!--@ITEM.FIELD3.TEXT()-->
		<!--@ITEM.FIELD4.TEXT()-->
		<!--@ITEM.FIELD5.TEXT()-->
		<!--@ITEM.FIELD6.TEXT()-->
		<!--@ITEM.FIELD7.TEXT()-->
		<!--@ITEM.FIELD8.TEXT()-->
		<!--@ITEM.FIELD9.TEXT()-->
		<!--@ITEM.FIELD10.TEXT()-->

		<h3>@ITEM_NAME - @ITEM_FIELD1</h3>
		<p>@ITEM_DESCRIPTION</p>

ITEM.START signal the engine beginning of an ITEM and for this template, we also used ITEM.FIELD1 with label Price. (Similar concept as CATEGORY.FIELD1.TEXT above). The replacement field is also a similar concept as category replacement field above.

Basic example of content structure

	<!--@ITEM.END-->
<!--@CATEGORY.END-->

ITEM.END and CATEGORY.END notify the engine of the end of scope for ITEM and CATEGORY. It is important to note that failure to close the scope will cause unexpected behavior during run-time.

Put it together

Basic Visual Structure of Template

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8">
    <title></title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
</head>

<body>
	<h1>Hello World</h1>
	
	<!--@CATEGORY.START(1 Price Tag)-->
	<!--@CATEGORY.FIELD1.TEXT(Category Description)-->
	<!--@CATEGORY.FIELD2.TEXT()-->
	<!--@CATEGORY.FIELD3.TEXT()-->
	<!--@CATEGORY.FIELD4.TEXT()-->
	<!--@CATEGORY.FIELD5.TEXT()-->

	<h2>@CATEGORY_NAME</h2>
	<p>@CATEGORY_FIELD1</p>


		<!--@ITEM.START-->
		<!--@ITEM.FIELD1.TEXT(Price)-->
		<!--@ITEM.FIELD2.TEXT()-->
		<!--@ITEM.FIELD3.TEXT()-->
		<!--@ITEM.FIELD4.TEXT()-->
		<!--@ITEM.FIELD5.TEXT()-->
		<!--@ITEM.FIELD6.TEXT()-->
		<!--@ITEM.FIELD7.TEXT()-->
		<!--@ITEM.FIELD8.TEXT()-->
		<!--@ITEM.FIELD9.TEXT()-->
		<!--@ITEM.FIELD10.TEXT()-->
			<h3>@ITEM_NAME - @ITEM_FIELD1</h3>
			<p>@ITEM_DESCRIPTION</p>
		<!--@ITEM.END-->


	<!--@CATEGORY.END-->

</body>

</html>

Available Standard RTDS Command

Scope	Command	Parameter	Description	Example
CATEGORY	CATEGORY.START()	The name of the input label appears on the user's input interface for the category.	The start of a category scope.	CATEGORY.START(Simple format with 1 price tag) CATEGORY.START(Detailed info with 1 price tag)
CATEGORY	CATEGORY.FIELD1.TEXT() CATEGORY.FIELD2.TEXT() CATEGORY.FIELD3.TEXT() CATEGORY.FIELD4.TEXT() CATEGORY.FIELD5.TEXT()	The name of the dynamic replacement field label appears on the user's input interface. Note: If empty is passed into this field, it will assume the field is not being used and automatically disable it on the user's interface. If the command is not defined, the replacement field will be enabled with the default text Dynamic Field #	Control the visibility and the label of dynamic field appearing on the user's input interface.	CATEGORY.FIELD1.TEXT(Category Description) CATEGORY.FIELD1.TEXT()
CATEGORY	CATEGORY.END	No Parameter	The end of a category scope	CATEGORY.END
ITEM	ITEM.START	No Parameter	The start of an item scope	ITEM.START
ITEM	ITEM.FIELD1.TEXT() ITEM.FIELD2.TEXT() ITEM.FIELD3.TEXT() ITEM.FIELD4.TEXT() ITEM.FIELD5.TEXT() ITEM.FIELD6.TEXT() ITEM.FIELD7.TEXT() ITEM.FIELD8.TEXT() ITEM.FIELD9.TEXT() ITEM.FIELD10.TEXT()	The name of the dynamic replacement field label appears on the user's input interface. Note: If empty is passed into this field, it will assume the field is not being used and automatically disable it on the user's interface. If the command is not defined, it will assume the field is not being used and automatically disable it on the user's interface.	Control the visibility and the label of dynamic field appearing on the user's input interface.	ITEM.FIELD1.TEXT(Small Price) ITEM.FIELD1.TEXT(Large Price) ITEM.FIELD1.TEXT()
ITEM	ITEM.END	No Parameter	The end of an item scope	ITEM.END

Additional Information on Dynamic RTDS

With the dynamic RTDS command, the data source will consist of different name-value pairs. The inline replacement variable to display a value will use the following syntax.

@{RTDS COMMAND}@

The replacement variable may be inlined with any code to create a dynamic visual layer, for example.

<h2>@{RTDS COMMAND}@</h2>

Shortcode Declaration and Usage

The concept of shortcode provides further flexibility to create a Smart Menu Editor that fits a wide range of requirements. The concept of shortcode is identical to the most popular website platform WordPress. In RTDS, we've embraced the concept of shortcode with a slight change of syntax to avoid the unwanted trigger of shortcodes in the production environment.

Declaring Shortcode

You can declare shortcodes anywhere in the template at the root scope. That means you can declare the shortcodes at the template's beginning, middle, or end but not within other declaration blocks (i.e., category, item, etc...)

Here's a basic example of declaring a shortcode using RTDS

<!--@SHORTCODE.START(NEW ICON)-->
<img src="https://www.mydomain.com/newicon.png">
<!--@SHORTCODE.END-->

Let's take a look at the code block above line by line

<!--@SHORTCODE.START(NEW ICON)-->

This command defines the beginning of a shortcode named "NEW ICON".

<img src="https://www.mydomain.com/newicon.png">

The HTML that will be used whenever a shortcode is called. This can be multiple lines.

<!--@SHORTCODE.END-->

This command defines the end of a shortcode block.

Using the shortcode

Once declared, the customer can use the shortcode in any text field leading with [ and ending with ]. The system will automatically replace the shortcode if it exists. If it does not exist, the shortcode will not be triggered, so the original text inputted by the user will appear.

The matching of shortcodes is non-case-sensitive

Here are examples where the shortcode will be triggered

Ham and egg breakfast [NEW ICON]
Ham and egg breakfast [new icon]
Ham and egg breakfast [NeW iCoN]

Default Value Settings

There are situations where you wish to set the default value upon initialization of a new menu board. One of the great places to use this initialization is the background video.

Default background video

To declare the default background video:

<!--@DEFAULT.BGV.URL(https://s3.amazonaws.com/s3.kuusoft.com/WebResources/SMEGlobalTemplateResource/CozyLights/background.mp4)-->

Remember to replace the URL with the pre-uploaded video file.

Available Dynamic RTDS Command

Scope	Command	Parameter	Description	Example
CATEGORY	CATEGORY.START(FIELD NAME)	FIELD NAME = The name of the category.	The start of a dynamic category scope.	CATEGORY.START(MY CATEGORY)
CATEGORY	CATEGORY.{FIELD NAME}	FIELD NAME = ID name of the field to target within the data scope from a connected data source. Note: FIELD NAME is case sensitive	Replacement variable for the category scope with the value returned from the dataset given the field name.	CATEGORY.name CATEGORY.footnote
CATEGORY	DYNAMIC.CATEGORY.END	No Parameter	The end of a dynamic category scope.	DYNAMIC.CATEGORY.END
ITEM	DYNAMIC.ITEM.START	No Parameter	The start of a dynamic item scope.	DYNAMIC.ITEM.START
ITEM	ITEM.{FIELD NAME}	FIELD NAME = ID name of the field to target within the data scope from a connected data source. Note: FIELD NAME is case sensitive	Replacement variable for item scope with the value returned from the dataset given the field name.	ITEM.name ITEM.description ITEM.cost
ITEM	DYNAMIC.CATEGORY.END	No Parameter	The end of a dynamic item scope.	DYNAMIC.CATEGORY.END
SHORTCODE	SHORTCODE.START(NAME)	NAME = The name of the shortcode Note: The name is non-case-sensitive	The starting of the shortcode.	SHORTCODE.START(MY SHORTCODE)
SHORTCODE	SHORTCODE.END	No Parameter