You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
228 lines
10 KiB
228 lines
10 KiB
## Describe custom Web pages with JSON
|
|
|
|
You can embed custom Web pages written in [**JSON**](https://www.json.org/index.html) into AutoConnect without declaring AutoConnectAux & AutoConnectElements in sketches. Custom Web page declaration in JSON can be included in the sketch in advance as the fixed string, or it can be stored in the external file such as SPIFFS for stream loading. You can also load and save AutoConnectElements objects individually.[^1]
|
|
|
|
[^1]:Loading and saving AutoConnect parameters adopt this method.
|
|
|
|
By providing the following JSON document to AutoConnect, you can include the custom Web page as the bellow:
|
|
|
|
<div style="float:left;width:50%;height:470px;overflow:auto"><img src="./images/ac_json.png"></div>
|
|
<img style="margin-left:30px;width:40%;height:470px;" src="./images/ac_mqtt_setting.png">
|
|
|
|
A JSON document for AutoConnect can also contain declarations of multiple custom web pages. If you fit those multiple pages in one JSON document, sketch processing for loading AutoConnectAux will degenerate further.
|
|
|
|
!!! caution "Need ArduinoJson v5"
|
|
To process the AutoConnectAux & AutoConnectElements written in the JSON is you need to install the [ArduinoJson version 5](https://arduinojson.org/v5/doc/installation/) library.
|
|
|
|
## JSON objects & elements for the custom Web page
|
|
|
|
### <i class="fa fa-caret-right"></i> JSON document structure for AutoConnectAux
|
|
|
|
An AutoConnectAux is described by a JSON object. The elements that make up an object are as follows:
|
|
|
|
<pre>
|
|
{
|
|
"title" : <i>title</i>,
|
|
"uri" : <i>uri</i>,
|
|
"menu" : <b>true</b> | <b>false</b>,
|
|
"element" : <i>element_array</i>
|
|
}
|
|
</pre>
|
|
|
|
#### <i class="fa fa-key"></i> **title**
|
|
: A title of the custom Web page. This is string value. String specified *title* will be displayed in the AutoConnection menu.
|
|
|
|
#### <i class="fa fa-key"></i> **uri**
|
|
: String of URI path that specifies where to place the custom web page. It needs to be a location from the root path including '**/**'.
|
|
|
|
#### <i class="fa fa-key"></i> **menu**
|
|
: This is a Boolean value indicating whether to include the custom web page in the AutoConnect menu. If the page only responds to another page and you want to prevent the direct use from the menu, you can exclude from the AutoConnect menu. If this key is false, it will not appear in the menu.
|
|
|
|
#### <i class="fa fa-key"></i> **element**
|
|
: Describe an array of JSON objects as *element_array*. It is a JSON object array of the [AutoConnectElements](#json-object-for-autoconnectelements) that make up the custom Web page.
|
|
|
|
!!! note "Order of elements on a custom Web page"
|
|
The order in which AutoConnectElements are placed on a custom web page is the order in the JSON document.
|
|
|
|
### <i class="fa fa-copy"></i> Multiple custom Web pages declaration in JSON document
|
|
|
|
You can put declarations of multiple custom Web pages in one JSON document. In that case, declare an array of each custom Web page with JSON. The following JSON document contains three custom Web pages:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"title" : "Page 1 title",
|
|
"uri" : "/page1",
|
|
"menu" : true,
|
|
"element" : [
|
|
{
|
|
"name" : "caption",
|
|
"type" : "ACText",
|
|
"value" : "hello, world"
|
|
},
|
|
{
|
|
"name" : "send",
|
|
"type" : "ACSubmit",
|
|
"uri" : "/page2"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"title" : "Page 1 title",
|
|
"uri" : "/page2",
|
|
"menu" : false,
|
|
"element" : [
|
|
{
|
|
"name" : "responds",
|
|
"type" : "ACText",
|
|
"value" : "Good day"
|
|
},
|
|
{
|
|
"name" : "send",
|
|
"type" : "ACSubmit",
|
|
"uri" : "/page3"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"title" : "Page 3 title",
|
|
"uri" : "/page3",
|
|
"menu" : true,
|
|
"element" : [
|
|
{
|
|
"name" : "responds",
|
|
"type" : "ACText",
|
|
"value" : "bye"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
### <i class="fa fa-caret-right"></i> JSON object for AutoConnectElements
|
|
|
|
A JSON object of AutoConnectElements is described by the parameters of [each constructor](acelements.md#constructor).
|
|
|
|
<pre>
|
|
{
|
|
"name" : <i>name</i>,
|
|
"type" : <i>type</i>,
|
|
<i>key_according_to_type</i> : <i>the_value</i> | <i>array_of_value</i>
|
|
<b>[</b> , <i>key_according_to_type</i> : <i>the_value</i> | <i>array_of_value</i> <b>]</b>
|
|
}
|
|
</pre>
|
|
|
|
#### <i class="fa fa-key"></i> **name**
|
|
: A string of the name for the element.
|
|
|
|
#### <i class="fa fa-key"></i> **type**
|
|
: A string of the type for the element. For this type, specify the following string corresponding to each element.
|
|
: - AutoConnectButton: [**ACButton**](#acbutton)
|
|
: - AutoConnectCheckbox: [**ACCheckbox** ](#accheckbox)
|
|
: - AutoConnectElement: [**ACElement**](#acelement)
|
|
: - AutoConnectInput: [**ACInput**](#acinput)
|
|
: - AutoConnectRadio: [**ACRadio**](#acradio)
|
|
: - AutoConnectSelect: [**ACSelect**](#acselect)
|
|
: - AutoConnectSubmit: [**ACSubmit**](#acsubmit)
|
|
: - AutoConnectText: [**ACText**](#actext)
|
|
|
|
#### <i class="fa fa-key"></i> **<i>key_according_to_type</i>**
|
|
|
|
This is different for each AutoConnectElements type, and the key that can be specified by the type is determined.
|
|
|
|
#### <i class="fa fa-caret-right"></i> ACButton
|
|
: - **value** : Specifies the button label. This value also applies to the `value` attribute of an HTML `button` tag.
|
|
: - **action** : Specifies an action to be fire on a mouse click on the button. It is mostly used with a JavaScript to activate a script, or it directly describes a JavaScript.
|
|
|
|
#### <i class="fa fa-caret-right"></i> ACCheckbox
|
|
: - **value** : Specifies the value to be supplied to the checkbox. It will be packed in the query string as `name=value` when the checkbox is ticked.
|
|
: - **label** : Specifies a label of the checkbox. Its placement is always to the right of the checkbox.
|
|
: - **checked** : Specifies checking status as a **boolean** value. The value of the checked checkbox element is packed in the query string and sent.
|
|
|
|
#### <i class="fa fa-caret-right"></i> ACElement
|
|
: - **value** : Specifies the source code of generating HTML. The value is native HTML code and is output as HTML as it is.
|
|
|
|
#### <i class="fa fa-caret-right"></i> ACInput
|
|
: - **value** : Specifies the initial text string of the input box. If this value is omitted, placeholder is displayed as the initial string.
|
|
: - **label** : Specifies a label of the input box. Its placement is always to the left of the input box.
|
|
: - **placeholder** : Specifies short hint of the input box.
|
|
|
|
#### <i class="fa fa-caret-right"></i> ACRadio
|
|
: - **value** : Specifies the collection of radio buttons as an array element.
|
|
: - **label** : Specifies a label of the collection of radio buttons, not for each button. The arrangement will be the top or left side according to the `arrange`.
|
|
: - **arrange** : Specifies the orientation of the radio buttons. Its value accepts one of the following:<p>
|
|
<b>horizontal</b> : Horizontal arrangement.<br>
|
|
<b>vertical</b> : Vertical arrangement.</p>
|
|
|
|
: - **checked** : Specifies the index number (1-based) of the radio buttons collection to be checked.
|
|
|
|
#### <i class="fa fa-caret-right"></i> ACSelect
|
|
: - **label** : Specifies a label of the drop-down list. Its placement is always to the left of the drop-down list.
|
|
: - **option** : Specifies the initial value collection of the drop-down list as an array element.
|
|
|
|
#### <i class="fa fa-caret-right"></i> ACSubmit
|
|
: - **value** : Specifies a label of the submit button.
|
|
: - **uri** : Specifies the URI to send form data when the button is clicked.
|
|
|
|
#### <i class="fa fa-caret-right"></i> ACText
|
|
: - **value** : Specifies a content and also can contain the native HTML code, but remember that your written code is enclosed by the div tag.
|
|
: - **style** : Specifies the qualification style to give to the content and can use the style attribute format as it is.
|
|
|
|
!!! caution "AutoConnect's JSON parsing process is not perfect"
|
|
It is based on ArduinoJson, but the process is simplified to save memory. As a result, even if there is an unnecessary key, it will not be an error. It is ignored.
|
|
|
|
## Loading JSON document
|
|
|
|
AutoConnect supports loading of JSON document from the following instances:
|
|
|
|
- String
|
|
- PROGMEM
|
|
- Stream
|
|
|
|
To load custom Web pages JSON document into AutoConnect, use the [load](api.md#load) function of the AutoConnect class. Its JSON document can read must be completed as a description interpretable by the ArduinoJson library. It cannot import custom Web pages if there are syntax errors for the JSON. If you can not see the custom Web page prepared by JSON, you can check the syntax with [ArduinoJson Assistant](https://arduinojson.org/v5/assistant/). It is useful for pre-checking.
|
|
|
|
```cpp
|
|
bool AutoConnect::load(const String& aux)
|
|
```
|
|
```cpp
|
|
bool AutoConnect::load(const __FlashStringHelper* aux)
|
|
```
|
|
```cpp
|
|
bool AutoConnect::load(Stream& aux)
|
|
```
|
|
An example of using each function is as follows.
|
|
```cpp
|
|
AutoConnect portal;
|
|
|
|
// Loading from String
|
|
const String aux = String("{\"title\":\"Page 1 title\",\"uri\":\"/page1\",\"menu\":true,\"element\":[{\"name\":\"caption\",\"type\":\"ACText\",\"value\":\"hello, world\"}]}");
|
|
portal.load(aux);
|
|
|
|
// Loading from PROGMEM
|
|
const char aux[] PROGMEM = R"raw(
|
|
{
|
|
"title" : "Page 1 title",
|
|
"uri" : "/page1",
|
|
"menu" : true,
|
|
"element" : [
|
|
{
|
|
"name" : "caption",
|
|
"type" : "ACText",
|
|
"value" : "hello, world"
|
|
}
|
|
]
|
|
}
|
|
)raw";
|
|
portal.load(aux);
|
|
|
|
// Loading from Stream assumes "aux.json" file should be store in SPIFFS.
|
|
File aux = SPIFFS.open("aux.json", "r");
|
|
portal.load(aux);
|
|
aux.close();
|
|
```
|
|
|
|
AutoConnect passes the given JSON document directly to the [**parseObject()**](https://arduinojson.org/v5/api/jsonbuffer/parseobject/) function of the ArduinoJson library for parsing. Therefore, the constraint of the parseObject() function is applied as it is in the parsing of the JSON document for the AutoConnect. That is, if the JSON string is read-only, duplicating the input string occurs and consumes more memory.
|
|
|
|
## Saving JSON document
|
|
|
|
However, AutoConnect does not support saving AutoConnectAux as a whole custom Web page. If you want to persist an AutoConnectElements object, you need to save it as an AutoConenctElement object unit. AutoConnectAux has a [function](achandling.md#saving-autoconnectelements) to write multiple elements to the stream in a batch.
|
|
|