App Settings on Web Page

background knowledge

If the application you wrote is published to the Vobot App Gallery, after it is downloaded and installed by the user, if you want the user to modify certain parameters, please follow the instructions in this section and describe your configuration to automatically generate the Web configuration interface. Usually, there are two ways for users to modify the configuration of the App: 1. Design the UI of lvgl directly in the App you write, and let users modify it directly through LCD+Buttons; 2. Vobot Dock starts the Web Server, allowing users to access the Web page through the PC/Phone browser to modify the configuration.

The former is suitable for simple options, and you can implement the UI according to lvgl's standard practices; The latter requires you to write a description in JSON format so that the Vobot Dock system can automatically create the corresponding configuration options in the Web Server.

Overview

• Developers can create a description in JSON format that allows users to enter and select the required configuration items for this application on a web page.
• Vobot Dock automatically analyzes JSON and generates corresponding components on the web.
• Developers need to create a get_settings_json() object in your_app/__init__.py and return a JSON object containing the settings form.

Returned JSON object

• Description: JSON used to generate configuration components, which contains
• JSON structure:

      {
          "title":"Your Text Here",
          "hint": {
                  "url": "https://my-vobot-dock-app.com",
                  "label": "My App."
              },
          "form": [Components1, Components2]
      }
  

• Field Description:
  • "title"(String): Prompt information for setting detailed interface in the application
  • "hint"(Dict): generate a tagged link
    • "url"(String): the external website to be linked to
    • "label"(String): The label of the link
  • "form"(List): A list containing setting forms for component generation.

Components

The setting API provides four components: input box, drop-down form, check box, and radio button.

Input box

• Description: Create an input box component.
• JSON structure:

      { 
          "type": "input",
          "default": "Default Value",
          "caption": "Title Text",
          "name": "Key Name",
          "attributes": {"maxLength": Size, "placeholder": "Test input"},
          "tip": "Test input",
          "hint": {
              "url": "https://my-app.com/help/abc",
              "label": "More details..."
                  }
      }
  

• Field Description:
  • "type"(String): type of component
  • "default"(String): default value
  • "caption"(String): Caption name of the component
  • "name"(String): keyword for this option when saving the configuration (only lowercase letters and underscores are allowed)
  • "attributes"(Dict): attributes of the input field
    • "maxLength"(Number): maximum length limit
    • "placeholder"(String): placeholder text
  • "tip"(String): Tip information generated below the component
  • "hint"(Dict): generate a labeled link below the component
    • "url"(String): the external website to be linked to
    • "label"(String): The label of the link

Drop-down form

• Description: Create a drop-down form component.
• JSON structure:

      { 
          "type": "select",
          "default": "Default Value",
          "caption": "Title Text",
          "name": "Key Name",
          "tip": "Test dropdown select",
          "options":[("Option Name1", "Value1"), ("Option Name2", "Value2")],
          "hint": {
              "url": "https://my-app.com/help/abc",
              "label": "More details..."
          }
      }
  

• Field Description:
  • "type"(String): type of component
  • "default"(String): default value, fill in the Value in option
  • "caption"(String): Caption name of the component
  • "name"(String): keyword for this option when saving the configuration (only lowercase letters and underscores are allowed)
  • "tip"(String): Tip information generated below the component
  • "options"(List): The name of the option in the drop-down form and the value output when selected,
  • "hint"(Dict): generate a labeled link below the component
    • "url"(String): the external website to be linked to
    • "label"(String): The label of the link

Checkbox

• Description: Creates a checkbox component.
• JSON structure:

      { 
          "type": "checkbox",
          "default": ["Default Value"],
          "caption": "Title Text",
          "name": "Key Name",
          "tip": "Test checkbox",
          "options":[("Option Name1", "Value1"), ("Option Name2", "Value2")],
          "hint": {
              "url": "https://my-app.com/help/abc",
              "label": "More details..."
          }
      }
  

• Field Description:
  • "type"(String): type of component
  • "default"(List): default value, fill in the Value in option
  • "caption"(String): Caption name of the component
  • "name"(String): keyword for this option when saving the configuration (only lowercase letters and underscores are allowed)
  • "tip"(String): Tip information generated below the component
  • "options"(List): The name of the option in the check box and the value output when selected,
  • "hint"(Dict): generate a labeled link below the component
    • "url"(String): the external website to be linked to
    • "label"(String): The label of the link

Single box

• Description: Create a radio button component.
• JSON structure:

      { 
          "type": "radio",
          "default": "Default Value",
          "caption": "Title Text",
          "name": "Key Name",
          "tip": "Test radio",
          "options":[("Option Name1", "Value1"), ("Option Name2", "Value2")],
          "hint": {
              "url": "https://my-app.com/help/abc",
              "label": "More details..."
          }
      }
  

• Field Description:
  • "type"(String): type of component
  • "default"(Bool): Default value, fill in True or False
  • "caption"(String): Caption name of the component
  • "name"(String): keyword for this option when saving the configuration (only lowercase letters and underscores are allowed)
  • "tip"(String): Tip information generated below the component
  • "hint"(Dict): generate a labeled link below the component
    • "url"(String): the external website to be linked to
    • "label"(String): The label of the link

Switch button

• Description: Create a switch button component.

• JSON structure:

      { 
          "type": "switch",
          "default": "Default Value",
          "caption": "Title Text",
          "name": "Key Name",
          "tip": "Test radio",
          "hint": {
              "url": "https://my-app.com/help/abc",
              "label": "More details..."
          }
      }
  

• Field Description:

  • "type"(String): type of component
  • "default"(String): default value, fill in the Value in option
  • "caption"(String): Caption name of the component
  • "name"(String): keyword for this option when saving the configuration (only lowercase letters and underscores are allowed)
  • "tip"(String): Tip information generated below the component
  • "options"(List): The name of the option in the radio button box and the value output when selected,
  • "hint"(Dict): generate a labeled link below the component
    • "url"(String): the external website to be linked to
    • "label"(String): The label of the link

Usage examples

def get_settings_json():
    return {
        "title":"This is a sample setting for my app",
        "form": [
        # Generate an input and save the config with key 'username'
        {
            "type": "input",
            "default": "",
            "caption": "Your Name:",
            "name": "username",
            "attributes": {"maxLength": 20, "placeholder": "Enter You Name"}
        },
        # Generate a dropdown
        {
            "type": "select",
            "default": "3",
            "caption": "Gender",
            "name": "gender",
            "options":[("Male", "1"), ("Female", "2"),("Other", "3")]
        },
        # Generate a multiple selection
        {
            "type": "checkbox",
            "default": ["1", "3"],
            "caption": "Hobbies",
            "name": "hobbies",
            "options":[("Cooking", "1"), ("Gaming", "2"),("Pets", "3")],
        },
        # Generate a single selection
        {
            "type": "radio",
            "default": "1",
            "caption": "Text", 
            "name": "radio_test",
            "options":[("Label1", "1"), ("Label2", "2")],
        },
        # Generate a switch button
        {
            "type": "switch",
            "default": False,
            "caption": "Text", 
            "name": "switch_bool",
        }]
    }

• After creating the UI through the above description, if the user modifies the configuration, Vobot Dock will automatically save configuration information similar to the following in the system:

  "your_app_id": {
    "username": "James Bond",
    "gender": "3",
    "hobbies": ["1", "3"],
    "radio_test": "1",
    "switch_bool": False,
  }
  

• You can access the current configuration through the following methods:

  s = app_mgr.config()
  username = s.get("username", "Unknown")