Each element has a name. **Name** is the String data type. To access its element in the sketches you can identify by the name. Its method is useful for loading elements in JSON. In the load function of AutoConnectElement(s) described [**later**](acjson.md), these objects are not created in advance by sketches. Therefore, access to the attribute of that element by the **name** as follows:
The above example accesses the *text1* element which loaded from JSON using AutoConnectAux's [**getElement**](apiaux.md#getelement) function by name and sets the [**style**](#style) attribute.
Each element has a name. The **name** is the String data type. You can identify each element by the name to access it with sketches.
### <iclass="fa fa-caret-right"></i> value
**Value** is the source of the HTML code generated with the element and its data type is String. Characteristics of Value vary depending on the element. The value of AutoConnectElement is native HTML code. A string of value is output as HTML as it is.<br>
The **value** is the string which is a source to generate an HTML code. Characteristics of Value vary depending on the element. The value of AutoConnectElement is native HTML code. A string of value is output as HTML as it is.
### <iclass="fa fa-caret-right"></i> type
**Type** indicates the type of the element and represented as the *ACElement_t* enumeration type in the sketch. Since AutoConnectElement also acts as a variant of other elements, it can be applied to handle elements collectively. At that time, the type can be referred to by the [**typeOf()**](apielements.md#typeof) function. The following example changes the font color of all [AutoConnectText](#autoconnecttext) elements of a custom Web page to gray.
The **type** indicates the type of the element and represented as the *ACElement_t* enumeration type in the sketch. Since AutoConnectElement also acts as a variant of other elements, it can be applied to handle elements collectively. At that time, the type can be referred to by the [**typeOf()**](apielements.md#typeof) function. The following example changes the font color of all [AutoConnectText](#autoconnecttext) elements of a custom Web page to gray.
### <iclass="fa fa-edit"></i> Variant for AutoConnectElements
Some AutoConnectAux APIs specify AutoConnectElement as an argument. There are also functions that returns a pointer to AutoConnectElement. In order to make these interfaces single, AutoConnectElement behaves as a variant type of other elements. Use [reinterpret_cast](https://en.cppreference.com/w/cpp/language/reinterpret_cast) to cast from a variant pointer to an Actual type pointer of AutoConnectElements.
Some AutoConnectAux APIs specify AutoConnectElements as an argument. There are also functions that return a pointer to AutoConnectElements. AutoConnectElement behaves as a variant type of each element class to make these interfaces a single. Use [reinterpret_cast](https://en.cppreference.com/w/cpp/language/reinterpret_cast) to cast from a variant pointer to an Actual type pointer of AutoConnectElements.
ESP8266WebServer class will parse the query string and rebuilds its arguments when the above request arrives. In the sketches as a handler, you can reach it using with the [ESP8266WebServer::arg](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#getting-information-about-request-arguments) function. The `arg`'s argument specifies the name of the AutoConnectElements. Also, you can choose another way to access arguments without going through the ESP8266WebServer class. The [PageArgument](https://github.com/Hieromon/PageBuilder#arguments-of-invoked-user-function) object of the custom Web page handler argument is a copy of the arg object of the ESP8266WebServer class. Either of these methods is a simple and easy way to access parameters in custom Web page handlers. However, if you need to access from outside of the handler to the value of AutoConnectElements, you need to accomplish it using with the [AutoConnectAux::getElement](#get-autoconnectelement-from-the-autoconnectaux) function.
ESP8266WebServer class will parse the query string and rebuilds its arguments when the above request arrives. A custom page handler registered with the [ESP8266WebServer::on](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#client-request-handlers) function can access the value of AutoConnectElements with [ESP8266WebServe::arg](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#getting-information-about-request-arguments) function. It reaches the values of AutoConnectElements without the intermediation of AutoConnect. Therefore, its handler will not be AutoConnectAux and can send a response to the client directly. The following example is part of a server sketch which has two web pages. The `/hello` page is a custom Web page of AutoConnectAux which has an input box named "input1". Another `/echo` page is a page handler for ESP8266WebServer, which uses the [ESP8266WebServer::send](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#sending-responses-to-the-client) function to echo back the value of an input1 as an http response.
### <iclass="fa fa-desktop"></i> Overtyping with LoadElement function
```cpp hl_lines="3 8"
ESP8266WebServer server;
AutoConnect portal(server);
ACInput(input1, "", "INPUT");
ACSubmit(send, "HELLO", "/echo");
AutoConnectAux aux("/hello", { input1, send });
server.on("/echo", []() {
String echo = server.arg("input1");
Serial.println(echo);
server.send(200, "text/plain", echo);
});
portal.join(aux);
portal.begin();
```
Also, you can choose another way to access arguments without going through the ESP8266WebServer class. The [PageArgument](https://github.com/Hieromon/PageBuilder#arguments-of-invoked-user-function) object of the custom Web page handler argument is a copy of the arg object of the ESP8266WebServer class. Either of these methods is a simple and easy way to access parameters in custom Web page handlers. However, if you need to access from outside of the handler to the value of AutoConnectElements, you need to accomplish it using with the [AutoConnectAux::getElement](#get-autoconnectelement-from-the-autoconnectaux) function. The following sketch code replaces the above example with JSON and PageArgument, and its behaves is equivalent basically to the above sketch.
### <iclass="fa fa-desktop"></i> Over typing with LoadElement function
The [AutoConnectAux::loadElement](apiaux.md#loadelement) function overwrites its value when loading an AutoConnectElement. If the loadElement function wields an element with an input value, the previous value will be lost by the loaded value. If you need to preserve input values even during page transition operations, we recommend that you load parameters only once at an early stage in the `setup()` of sketches.
## Transitions of the custom Web pages
### The URI of the custom Web pages
The transition of the custom Web page follows the URI of the page, but the ESP8266WebServer class does not know the URI of an AutoConnectAux page. (Registering a custom Web page does not use the *ESP8266WebServer::on*/*WebServer::on* function.) Therefore ESP8266WebServer class does not detect its URI access. If you want to detect an http request to AutoConnectAux's custom Web page, you need to register its URI with the [AutoConnectAux::on](apiaux.md#on) function.
In addition to this, there are restrictions in the handler for the custom Web page as shown in the following section.
### Restrictions
The transition of the custom Web page follows the URI of the page, but the ESP8266WebServer class does not know its URI. (Registering a custom Web page does not use the *ESP8266WebServer::on*/*WebServer::on* function.) Therefore, the custom Web page handler has the following restrictions.
The custom Web pages handler has the following restrictions.
- Do not send HTTP responses from the handler.
@ -466,9 +516,11 @@ The transition of the custom Web page follows the URI of the page, but the ESP82
- Can not handle the custom Web pages during a connection is not established yet.
During the connection attempt, the web browser on the client will send a probe for a captive portal. Its request will cause unintended custom Web page transitions.
During the connection attempt, the web browser of the client will send a probe for a captive portal. Its request will cause unintended custom Web page transitions.
- Can not place URI of the custom Web pages to AUTOCONNECT_URI].
- Can not place URI of the custom Web pages to [AUTOCONNECT_URI](https://).
AutoConnect will not work if you place a custom Web page to [AUTOCONNECT_URI](api.md#defined-macros).
!!! hint "302 Redirect Alternatives"
To transition from a custom Web page to a sketch owned page, execute the link function of JavaScript with the AutoConnectElement element.
Load JSON document of AutoConnectAux which contains AutoConnectElements. If there is a syntax error in the JSON document, false is returned.
<dlclass="apidl">
<dt>**Parameters**</dt>
<dd><spanclass="apidef">aux</span>The input string to be loaded.</dd>
<dt>**Return value**</dt>
<dd><spanclass="apidef">true</span>The JSON document as AutoConnectAux successfully loaded.</dd>
<dd><spanclass="apidef">false</span>Loading JSON document unsuccessful, probably syntax errors have occurred or insufficient memory. You can diagnose the cause of loading failure using the [ArduinoJson Assistant](https://arduinojson.org/v5/assistant/).</dd>
Register the handler function of the AutoConnectAux.
<dlclass="apidl">
<dt>**Parameters**</dt>
<dd><spanclass="apidef">uri</span>A string of the URI assigned to the AutoConnectAux page.</dd>
<dd><spanclass="apidef">handler</span>A function that behaves when a request to the AutoConnectAux page occurs. AuxHandlerFunctionT type is defined by the following declaration.</dd>
<dd><spanclass="apidef">order</span>Specifies when the handler is called with the following enumeration value.</dd>
: - **AC_EXIT_AHEAD** :
Called before AutoConnect generates the HTML of the page. You set the value of AutoConnectElements in the handler then its value will be displayed on the page.
: - **AC_EXIT_LATER** :
Called after AutoConnect generates the HTML of the page. You can append to HTML generated by AutoConnect.
: - **AC_EXIT_BOTH** :
Called even before generating HTML and after generated.
</dl>
!!! caution "It is not ESP8266WebServer::on, not WebServer::on for ESP32."
This function effects to AutoConnectAux only. However, it coexists with that of ESP8266WebServer::on or WebServer::on of ESP32.
@ -40,34 +40,86 @@ Get registered AutoConnectElement as specified name.
```cpp
AutoConnectElementVT& getElements(void)
```
Get vector of reference of all elements.
### <iclass="fa fa-caret-right"></i> load
```cpp
bool load(const String& in)
```
```cpp
bool load(const __FlashStringHelper* in)
```
```cpp
bool load(Stream& in)
```
Load whole elements to AutoConnectAux Pages.
### <iclass="fa fa-caret-right"></i> loadElement
```cpp
bool loadElement(const String& in, const String& name = String(""))
```
```cpp
bool loadElement(const __FlashStringHelper* in, const String& name = String(""))
```
```cpp
bool loadElement(Stream& in, const String& name = String(""))
```
Load specified element.
### <iclass="fa fa-caret-right"></i> menu
```cpp
void menu(const bool post)
```
Set or reset the display as menu item for this AutoConnectAux.
### <iclass="fa fa-caret-right"></i> on
```cpp
void on(const AuxHandlerFunctionT handler, const AutoConnectExitOrder_t order = AC_EXIT_AHEAD)
```
Register the handler function of the AutoConnectAux.
<dlclass="apidl">
<dt>**Parameters**</dt>
<dd><spanclass="apidef">handler</span>A function that behaves when a request to the AutoConnectAux page occurs. AuxHandlerFunctionT type is defined by the following declaration.</dd>
<dd><spanclass="apidef">order</span>Specifies when the handler is called with the following enumeration value.</dd>
: - **AC_EXIT_AHEAD** :
Called before AutoConnect generates the HTML of the page. You set the value of AutoConnectElements in the handler then its value will be displayed on the page.
: - **AC_EXIT_LATER** :
Called after AutoConnect generates the HTML of the page. You can append to HTML generated by AutoConnect.
: - **AC_EXIT_BOTH** :
Called even before generating HTML and after generated.
Hieromon Ikasamo
6 years ago