@ -115,7 +115,7 @@ It becomes a value of the `value` attribute of an HTML button tag.
### <iclass="fa fa-caret-right"></i> action
**action** is String data type and is an onclick attribute fire on a mouse click on the element. it is mostly used with a JavaScript to activate a script.[^1] For example, the following code defines a custom Web page that copies a content of `Text1` to `Text2` by clicking `Button`.
**action** is String data type and is an onclick attribute fire on a mouse click on the element. It is mostly used with a JavaScript to activate a script.[^1] For example, the following code defines a custom Web page that copies a content of `Text1` to `Text2` by clicking `Button`.
[^1]:JavaScript can be inserted into a custom Web page using AutoConnectElement.
@ -225,7 +225,7 @@ A label is an optional string. A label will be arranged in the left or top of th
### <iclass="fa fa-caret-right"></i> order
A `order` specifies the orientation of the radio buttons. It is a value of type `ACArrange_t` and accepts one of the following:
A `order` specifies the direction to arrange the radio buttons. It is a value of type `ACArrange_t` and accepts one of the following:
- **`AC_Horizontal`** : Horizontal arrangement.
- **`AC_Vertical`** : Vertical arrangement.
@ -284,7 +284,7 @@ It is the `name` of the AutoConnectSubmit element and matches the name attribute
### <iclass="fa fa-caret-right"></i> value
It becomes a string of the `value` attribute of an HTML `<input type="button">` tag. The `value`is displayed as a label of the button.
It becomes a string of the `value` attribute of an HTML `<input type="button">` tag. The `value`will be displayed as a label of the button.
AutoConnectElements (ie. they are the elements displayed on the custom Web page) must be contained in AutoConnectAux object. AutoConnectElements declared in sketch must be programmed to add to AutoConnectAux one after another. Elements are automatically included in AutoConnectAux by AutoConnect if you load it from the JSON description. In either method, it is common to use the function of AutoConnectAux to access an element with a sketch.
The AutoConnectAux class has several functions to manipulate AutoConnectElements. The functions can add, delete, retrieve elements, and get and set values.
### <iclass="fa fa-edit"></i> Add AutoConnectElements to the AutoConnectAux object
To add AutoConnectElment(s) to an AutoConnectAux object, use the add function.
The add function adds specified AutoConnectElement to the AutoConnectAux. If speficied the collection of AutoConnectElements as a `std::vector` of the references to each element, these elements added in bulk.
The AutoConnectElements contained in the AutoConnectAux object are uniquely identified by the name. When adding an AutoConnectElement, if an element with the same name already exists in the AutoConnectAux, checking the type, and if it is the same, the value will be replaced. If another type of AutoConnectElement exists with the same name, that add operation will be invalid.[^1] In the following example, an AutoConnectButton as `button` addition is invalid.
[^1]: The valid scope of the name is within an AutoConnectAux.
```cpp hl_lines="3"
AutoConnectAux aux;
AutoConnectText text("hello", "hello, world");
AutoConnectButton button("hello", "hello, world", "alert('Hello world!')"); // This is invalid.
aux.add({ text, button });
```
Similarly this, the uniqueness of the name is also necessary within the JSON document
```json hl_lines="12"
{
"name" : "aux",
"uri" : "/aux",
"menu" : true,
"element" : [
{
"name": "hello",
"type": "ACText",
"value": "hello, world"
},
{
"name": "hello",
"type": "ACButton",
"value": "hello, world",
"action": "alert('Hello world!')"
}
]
}
```
!!! note "Load all elements from JSON document"
If you load all AutoConnectElements from JSON document into AutoConnect, you do not need to sketch the population process of the AutoConnectElements. It is managed by the AutoConnect library automatically.
### <iclass="fa fa-edit"></i> Get AutoConnectElement from the AutoConnectAux
To retrieve an element from AutoConnectAux, use the getElement or getElements function. Normally, the getElement is needed when accessing the value of AutoConnectElement in the sketch.
The [**getElement**](apiaux.md#getelement) function returns an AutoConnectElement with the specified name as a key. When you use this function, you need to know the type of AutoConnectElement in advance. To retrieve an AutoConnectElement by specifying its type, use the following method.
```cpp
AutoConnectAux aux;
aux.load("SOME_JSON_DOCUMENT");
// Retrieve the pointer of the AutoConnectText
AutoConnectText* text = reinterpret_cast<AutoConnectText*>(aux.getElement("TEXT_ELEMENT_NAME"));
// Retrieve the reference of the AutoConnectText
AutoConnectText& text = aux.getElement<AutoConnectText>("TEXT_ELEMENT_NAME");
```
The AutoConnectElement type behaves as a variant of other element types. Therefore use cast or template to convert to actual type as above. In the sketch, you access the real type of AutoConnectElement after casting it and storing into the variable.
AutoConnectAux* aux = portal.aux("/page1"); // Identify the AutoConnectAux instance with uri
AutoConenctText& text = aux->getElement<AutoConnectText>("caption"); // Cast to real type and access members
Serial.println(text.value);
```
To get all the AutoConnectElements of an AutoConnectAux object use the [**getElements**](apiaux.md#getelements) function. This function returns the vector of the reference wrapper as *AutoConnectElementVT* to all AutoConnectElements registered in the AutoConnectAux.
```cpp
AutoConnectElementVT& getElements(void)
```
*AutoConnectElementVT* is a predefined type for it and can use methods of [std::vector](https://en.cppreference.com/w/cpp/container/vector)<[std::reference_wrapper](https://en.cppreference.com/w/cpp/utility/functional/reference_wrapper)>.
@ -63,10 +63,6 @@ In the sketch below, it shows the sequence of codes to integrate three custom We
}
```
## Passing parameters with sketches and custom Web pages
A sketch can access variables of [AutoConnectElements](acelements.md) in the custom Web page. The value entered into the AutoConnectElements on the page is stored to the [member variables](acelements.md#form-and-autoconnectelements) of the element by AutoConnect whenever GET / POST transmission occurs. Your sketches can get these values with the GET / POST request handler. If you assign a value to an element before a request to the page occurs, its value will appear as the initial value when the page is displayed.
## Basic steps to use custom Web pages
So, the basic procedure for handling of the custom Web pages is as follows:
@ -163,7 +159,11 @@ void loop() {
}
```
[^3]: Installation of the [ArduinoJson](https://github.com/bblanchon/ArduinoJson) v.5.13.4 library is required.
[^3]: Installation of the [ArduinoJson](https://github.com/bblanchon/ArduinoJson) as the latest release of version 5 series is required.
## Passing parameters with sketches and custom Web pages
A sketch can access variables of [AutoConnectElements](acelements.md) in the custom Web page. The value entered into the AutoConnectElements on the page is stored to the [member variables](acelements.md#form-and-autoconnectelements) of the element by AutoConnect whenever GET / POST transmission occurs. Your sketches can get these values with the GET / POST request handler. If you assign a value to an element before a request to the page occurs, its value will appear as the initial value when the page is displayed. Details are explained in the [Parameter handling](achandling.md#parameter-handling).
@ -22,15 +22,15 @@ An AutoConnectAux is described by a JSON object. The elements that make up an ob
<pre>
{
"title" : <i>title</i>,
"uri" : <i>uri</i>,
"menu" : <b>true</b> | <b>false</b>,
"element" : <i>element_array</i>
"title" : <i>title</i>,
"uri" : <i>uri</i>,
"menu" : <b>true</b> | <b>false</b>,
"element" : <i>element_array</i>
}
</pre>
#### <iclass="fa fa-key"></i> **title**
: A title of the custome Web page. This is string value. String specified *title* will be displayed in the AutoConnection menu.
: A title of the custom Web page. This is string value. String specified *title* will be displayed in the AutoConnection menu.
#### <iclass="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 '**/**'.
@ -39,11 +39,66 @@ An AutoConnectAux is described by a JSON object. The elements that make up an ob
: 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.
#### <iclass="fa fa-key"></i> **element**
: Describe an array of JSON objects as *element_array*. It is a JSON object array of the AutoConnectElements that make up the custom Web page.
: 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.
### <iclass="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"
}
]
}
]
```
### <iclass="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).
@ -53,6 +108,7 @@ A JSON object of AutoConnectElements is described by the parameters of [each con
: - **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.
#### <iclass="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.
: - **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.
<iclass="fa fa-caret-right"></i> AutoConnectInput
: - **value** :
: - **label** :
: - **placeholder** :
#### <iclass="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>
: - **value** : Specifies a label of the submit button.
: - **uri** : Specifies the URI to send form data when the button is clicked.
<iclass="fa fa-caret-right"></i> AutoConnectText
: - **value** :
: - **style** :
#### <iclass="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.
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.
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
AutoConnect supports writing of JSON document to the stream.
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.
Hieromon Ikasamo
6 years ago