Create Template for Smart Menu Editor (Open-API)

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()-->
		<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()-->

		<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()-->
			<h3>@ITEM_NAME - @ITEM_FIELD1</h3>
			<p>@ITEM_DESCRIPTION</p>
		<!--@ITEM.END-->


	<!--@CATEGORY.END-->

</body>

</html>

Available Standard RTDS Command

ScopeCommandParameterDescriptionExample
CATEGORYCATEGORY.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()

CATEGORYCATEGORY.ENDNo ParameterThe end of a category scopeCATEGORY.END
ITEMITEM.STARTNo ParameterThe start of an item scopeITEM.START
ITEM

ITEM.FIELD1.TEXT()

ITEM.FIELD2.TEXT()

ITEM.FIELD3.TEXT()

ITEM.FIELD4.TEXT()

ITEM.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.

ITEM.FIELD1.TEXT(Small Price)

ITEM.FIELD1.TEXT(Large Price)

ITEM.FIELD1.TEXT()

ITEMITEM.ENDNo ParameterThe end of an item scopeITEM.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]


Available Dynamic RTDS Command

ScopeCommandParameterDescriptionExample
CATEGORYCATEGORY.START(FIELD NAME)

FIELD NAME = The name of the category.

The start of a dynamic category scope.

CATEGORY.START(MY CATEGORY)

CATEGORYCATEGORY.{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

CATEGORYDYNAMIC.CATEGORY.ENDNo ParameterThe end of a dynamic category scope.DYNAMIC.CATEGORY.END
ITEMDYNAMIC.ITEM.STARTNo ParameterThe 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

ITEMDYNAMIC.CATEGORY.ENDNo ParameterThe end of a dynamic item scope.DYNAMIC.CATEGORY.END
SHORTCODESHORTCODE.START(NAME)

NAME = The name of the shortcode


Note:

  • The name is non-case-sensitive
The starting of the shortcode.SHORTCODE.START(MY SHORTCODE)
SHORTCODESHORTCODE.ENDNo Parameter