HMI Menu System - Configuration Guide

This guide explains how to configure the HMI menu system using a JSON configuration file.

---

Table of Contents

1. Menu Toggle Button
2. Setting Menu Title
3. Setting Menu Position
4. Customizing Styles
5. Adding Custom Icons
6. Configuring Menu Items

---

Menu Toggle Button

Creating a Button to Toggle the Menu

To make a button toggle the menu, set the @MENU property on the button.

This allows users to open/close the menu from anywhere in your HMI interface by clicking the configured button.

---

Setting Menu Title

The menuTitle property sets the text displayed in the menu header.

Example:

{
  "menuTitle": "Plant Control System"
}

Default:

If not specified, the default title is "HMI Menu".

---

Setting Menu Position

Control where the menu appears on screen using menuPosition and menuIconPosition.

Properties:

Property	Options	Description
menuPosition	"left" or "right"	Side where the menu panel slides from
menuIconPosition	"left" or "right"	Position of the menu icon button

Examples:

Menu on the right side:

{
  "menuPosition": "right",
  "menuIconPosition": "right"
}

Menu on the left side:

{
  "menuPosition": "left",
  "menuIconPosition": "left"
}

Icon right, panel left:

{
  "menuPosition": "left",
  "menuIconPosition": "right"
}

Default:

Both default to "right" if not specified.

---

Customizing Styles

Use the customStyles object to customize the menu appearance.

Available Properties:

Property	Description	Default	Example
menuWidth	Width of menu panel	320px	"380px"
panelBg	Panel background color	#263238	"#1A237E"
headerBg	Header background color	#1976D2	"#283593"
submenuBg	Submenu background color	#1C2529	"#1A1F71"
itemHoverBg	Hover background color	#37474F	"#303F9F"
textColor	Text color	#ECEFF1	"#FFFFFF"
iconColor	Icon color	#90A4AE	"#BBDEFB"
borderColor	Border color between items	#37474F	"#3F51B5"
fontSize	Menu item font size	14px	"15px"
headerFontSize	Header font size	18px	"20px"
buttonBg	Menu button background	#2196F3	"#3F51B5"
buttonHoverBg	Button hover background	#1976D2	"#303F9F"
shadowColor	Shadow color	rgba(0,0,0,0.3)	"rgba(0,0,0,0.5)"

Example:

{
  "customStyles": {
    "menuWidth": "380px",
    "panelBg": "#1A237E",
    "headerBg": "#283593",
    "submenuBg": "#1A1F71",
    "itemHoverBg": "#303F9F",
    "textColor": "#FFFFFF",
    "iconColor": "#BBDEFB",
    "borderColor": "#3F51B5",
    "fontSize": "15px",
    "headerFontSize": "20px",
    "buttonBg": "#3F51B5",
    "buttonHoverBg": "#303F9F",
    "shadowColor": "rgba(0,0,0,0.5)"
  }
}

Notes:

• All properties are optional
• Only specify the properties you want to change
• If not specified, default values will be used

---

Adding Custom Icons

You can add custom SVG icons to your menu using Google Material Icons or any SVG source.

Step-by-Step Process:

1. Find an Icon on Google Fonts

• Go to https://fonts.google.com/icons
• Browse or search for the icon you want (e.g., "factory", "electrical", "settings")

2. Customize the Icon

• Click on the icon you like
• On the right panel, adjust the settings:
  • Fill: Choose your color (or leave default, as it will be styled by CSS)
  • Weight: Keep at default (400)
  • Grade: Keep at default (0)
  • Optical size: Set to 24 (important!)

3. Download the SVG

• Click the download button (download icon)
• The SVG file will be downloaded to your computer

4. Extract the SVG Code

• Open the downloaded .svg file with a text editor (Notepad, VS Code, etc.)
• Copy the entire <svg> tag and its contents

Example of what you'll see:

<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#5f6368">
    <path d="M480-120v-80h280v-560H480v-80h280q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H480Zm-80-160-55-58 102-102H120v-80h327L345-622l55-58 200 200-200 200Z"/>
</svg>

5. Prepare the SVG for JSON

• Remove the xmlns attribute (not needed)
• Remove height and width attributes (controlled by CSS)
• Remove or keep fill (CSS will override it)
• Add class="menu-icon" attribute
• Escape all double quotes with backslashes (" becomes \")

Before:

<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#5f6368">
    <path d="M480-120v-80h280v-560H480v-80h280q33 0..."/>
</svg>

After:

"<svg viewBox=\"0 -960 960 960\" class=\"menu-icon\"><path d=\"M480-120v-80h280v-560H480v-80h280q33 0...\"/></svg>"

6. Add to JSON Configuration

Add your custom icons to the customIcons object:

{
  "customIcons": {
    "factory": "<svg viewBox=\"0 -960 960 960\" class=\"menu-icon\"><path d=\"M80-80v-480l160-120v80l160-120v120h480v520H80Zm80-80h80v-120h80v120h80v-120h80v120h80v-120h80v120h80v-120h80v120h80v-360H480v-85l-160 120v-85l-160 120v290Zm0-290v290-290Zm240-40q-17 0-28.5-11.5T360-530q0-17 11.5-28.5T400-570q17 0 28.5 11.5T440-530q0 17-11.5 28.5T400-490Zm160 0q-17 0-28.5-11.5T520-530q0-17 11.5-28.5T560-570q17 0 28.5 11.5T600-530q0 17-11.5 28.5T560-490Zm160 0q-17 0-28.5-11.5T680-530q0-17 11.5-28.5T720-570q17 0 28.5 11.5T760-530q0 17-11.5 28.5T720-490Z\"/></svg>",
    "electrical": "<svg viewBox=\"0 -960 960 960\" class=\"menu-icon\"><path d=\"m280-80 160-300H320l120-220h80L400-360h120L360-80h-80Z\"/></svg>",
    "dashboard": "<svg viewBox=\"0 -960 960 960\" class=\"menu-icon\"><path d=\"M520-600v-240h320v240H520ZM120-440v-400h320v400H120Zm400 320v-400h320v400H520Zm-400 0v-240h320v240H120Z\"/></svg>"
  }
}

7. Use the Custom Icon in Menu Items

Reference your custom icon by its key name:

{
  "menuItems": [
    {
      "text": "Factory Overview",
      "icon": "factory",
      "action": {
        "type": "navigate",
        "file": "factory.drw"
      }
    }
  ]
}

Built-in Icons Available:

You can use these icons without adding them to customIcons:

• home
• pages
• chart
• settings
• link
• code
• folder
• refresh

---

Configuring Menu Items

The menuItems array defines the structure and content of your menu.

Basic Menu Item Structure:

{
  "text": "Menu Item Text",
  "icon": "icon-name",
  "action": {
    "type": "navigate",
    "file": "filename.drw"
  }
}

Creating Submenus:

Use the submenu property to create nested menu items:

{
  "text": "Parent Menu",
  "icon": "folder",
  "submenu": [
    {
      "text": "Child Item 1",
      "action": {
        "type": "navigate",
        "file": "page1.drw"
      }
    },
    {
      "text": "Child Item 2",
      "action": {
        "type": "navigate",
        "file": "page2.drw"
      }
    }
  ]
}

Navigation Action Types:

The navigate action type supports various file formats and special commands:

Navigate to .drw files:

{
  "text": "Main Dashboard",
  "icon": "pages",
  "action": {
    "type": "navigate",
    "file": "dashboard.drw"
  }
}

Navigate with query parameters:

{
  "text": "Factory 1 Layout",
  "action": {
    "type": "navigate",
    "file": "App_Main_v2.0.1.drw?tabNo=2&tabSelectedIndex=10102"
  }
}

Special Navigation Commands:

Command	Description
@HOME or @MAIN	Navigate to home/main page
@REFRESH	Refresh current page
@NEXT	Navigate to next page
@PREVIOUS	Navigate to previous page

Examples:

{
  "text": "Home",
  "icon": "home",
  "action": {
    "type": "navigate",
    "file": "@HOME"
  }
}

{
  "text": "Refresh",
  "icon": "refresh",
  "action": {
    "type": "navigate",
    "file": "@REFRESH"
  }
}

Complete Example:

{
  "menuItems": [
    {
      "text": "Home",
      "icon": "home",
      "action": {
        "type": "navigate",
        "file": "@HOME"
      }
    },
    {
      "text": "Plant Overview",
      "icon": "factory",
      "submenu": [
        {
          "text": "Factory 1",
          "submenu": [
            {
              "text": "Plant Layout",
              "action": {
                "type": "navigate",
                "file": "factory1_layout.drw"
              }
            },
            {
              "text": "Equipment Status",
              "action": {
                "type": "navigate",
                "file": "factory1_status.drw"
              }
            }
          ]
        },
        {
          "text": "Factory 2",
          "submenu": [
            {
              "text": "Plant Layout",
              "action": {
                "type": "navigate",
                "file": "factory2_layout.drw"
              }
            }
          ]
        }
      ]
    },
    {
      "text": "Actions",
      "icon": "settings",
      "submenu": [
        {
          "text": "Refresh Page",
          "icon": "refresh",
          "action": {
            "type": "navigate",
            "file": "@REFRESH"
          }
        },
        {
          "text": "Previous Page",
          "action": {
            "type": "navigate",
            "file": "@PREVIOUS"
          }
        },
        {
          "text": "Next Page",
          "action": {
            "type": "navigate",
            "file": "@NEXT"
          }
        }
      ]
    }
  ]
}

---

Complete Configuration Example

Here's a full example combining all configuration options:

{
  "menuTitle": "Factory Control System",
  "menuPosition": "left",
  "menuIconPosition": "left",
  "customStyles": {
    "menuWidth": "380px",
    "panelBg": "#263238",
    "headerBg": "#1976D2",
    "fontSize": "15px"
  },
  "customIcons": {
    "factory": "<svg viewBox=\"0 -960 960 960\" class=\"menu-icon\"><path d=\"M80-80v-480l160-120v80l160-120v120h480v520H80Z\"/></svg>"
  },
  "menuItems": [
    {
      "text": "Home",
      "icon": "home",
      "action": {
        "type": "navigate",
        "file": "@HOME"
      }
    },
    {
      "text": "Factory Overview",
      "icon": "factory",
      "submenu": [
        {
          "text": "Factory 1",
          "action": {
            "type": "navigate",
            "file": "factory1.drw"
          }
        }
      ]
    }
  ]
}

---

Tips & Best Practices

1. Icon Size: Always use size 24 when downloading icons from Google Fonts for consistency
2. Test Your Config: Start with a simple configuration and add complexity gradually
3. Color Consistency: Use a consistent color palette throughout your customStyles
4. Menu Depth: Avoid more than 3 levels of nested submenus for better usability
5. Icon Names: Use descriptive names for custom icons (e.g., "electrical", "hvac", "water-pump")