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")
File Upload
- Description: Create a file upload component.
- JSON structure:
{ "type": "file", "caption": "Title Text", "file_path": "/image", "name": "avatar", "attributes": { "accept": ".jpg,.png,.pdf", "multiple": false, "max_size": 5242880, "max_files": 5, }, "tip": "Support jpg, png and pdf format, max size 5MB", "hint": { "url": "https://my-app.com/help/abc", "label": "More details..." } }
- Field description:
- "type" (String): Component type
- "caption" (String): Component title name
- "file_path" (String): Relative path where the file is saved
- Must start with "/"
- Only lowercase letters, numbers and underscores are allowed
- Examples: "/image", "/documents/2024"
- "name"(String): Name to distinguish configuration items
- Only lowercase letters and underscores are allowed
- It is recommended to use meaningful names, such as: avatar, user_document
- "attributes"(Dict): Component attributes
- "accept"(String): File formats allowed for upload
- "multiple"(Boolean): Whether to allow multiple file uploads, default is false
- "max_size"(Number): Maximum size of a single file, in bytes
- "max_files"(Number): Maximum number of files that can be uploaded when multiple file uploads are allowed
- "min_size"(Number): Minimum size of a single file, in bytes
- "tip"(String): Tip displayed below the component
- It is recommended to explain the supported file formats and size limits
- "hint"(Dict): Generate a link with a label below the component
- "url"(String): External website to link to
- "label"(String): Label text of the link #### Usage examples ```python 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", } #Generate upload file component ,{ "type": "file", "caption": "Upload Image", "file_path": "image/", "name": "image", "attributes": {"accept": ".jpg,.png"}, }]
}
After creating the UI as described above, if the user modifies the configuration, Vobot Dock will automatically save the following configuration information in the system: ```python "your_app_id": { "username": "James Bond", "gender": "3", "hobbies": ["1", "3"], "radio_test": "1", "switch_bool": False, }
After creating the UI as described above, the files uploaded by the user through the upload file component will be saved in the 'resources/app_config/image/' path under the application directory. For example, if the application is Photo Album, the files will be saved to '/apps/Photo Album/resources/app_config/image/'. You can use MicroPython's file reading method to read these files. You can access the current configuration using the following method:
s = app_mgr.config()
username = s.get("username", "Unknown")