## Handing AutoConnectElements with the sketches AutoConnectElements (i.e. 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. ### Add AutoConnectElements to the AutoConnectAux object To add AutoConnectElment(s) to an AutoConnectAux object, use the add function. ```cpp void AutoConnectAux::add(AutoConenctElement& addon) ``` ```cpp void AutoConnectAux::add(AutoConenctElementVT addons) ``` The add function adds specified AutoConnectElement to the AutoConnectAux. If specified 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. ### 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. ```cpp AutoConnectElement* AutoConnectAux::getElement(const String& name); ``` ```cpp template T& AutoConnectAux::getElement(const String& name); ``` ```cpp AutoConnectElementVT* AutoConnectAux::getElements(void); ``` 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(aux.getElement("TEXT_ELEMENT_NAME")); // Retrieve the reference of the AutoConnectText AutoConnectText& text = aux.getElement("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. ```cpp const String auxJson = String("{\"title\":\"Page 1 title\",\"uri\":\"/page1\",\"menu\":true,\"element\":[{\"name\":\"caption\",\"type\":\"ACText\",\"value\":\"hello, world\"}]}"); AutoConenct portal; portal.load(auxJson); AutoConnectAux* aux = portal.aux("/page1"); // Identify the AutoConnectAux instance with uri AutoConenctText& text = aux->getElement("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)>. ## Loading & saving AutoConnectElements with JSON AutoConnect supports reading the custom Web page definitions written in JSON and also supports loading and saving of AutoConnectElements. In both cases, the target object is a [JSON document for AutoConnect](acjson.md). However, it can not save all AutoConnectElements contained in the page as a custom Web page. (ie. AutoConnectAux) ### Loading AutoConnectAux & AutoConnectElements with JSON To load a JSON document as AutoConnectAux use the [**AutoConnect::load**](api.md#load) function and load the JSON document of each AutoConnectElement using the [**AutoConnectAux::loadElement**](apiaux.md#loadelement) function. Although the functions of both are similar, the structure of the target JSON document is different. The [AutoConnect::load](apiaux.md#load) function loads the entire AutoConnectAux and creates both the AutoConnectAux instance and each AutoConnectElement instance. A single JSON document can contain multiple custom Web pages. If you write JSON of AutoConnectAux as an array, the load function generates all the pages contained in that array. Therefore, it is necessary to supply the JSON document of AutoConnectAux as an input of the load function and must contain the elements described [**here**](acjson.md#json-document-structure-for-autoconnectaux). The [AutoConnectAux::loadElement](apiaux.md#loadelement) function loads the elements individually into an AutoConnectAux object. The structure of its supplying JSON document is not AutoConnectAux. It must be a [JSON structure for AutoConnectElement](acjson.md#json-object-for-autoconnectelements), but you can specify an array. ```cpp hl_lines="49 55" // AutoConnectAux as a custom Web page. const char page[] PROGMEM = R"raw( { "title": "Settings", "uri": "/settings", "menu": true, "element": [ { "name": "server", "type": "ACInput", "label": "Server" }, { "name": "set", "type": "ACSubmit", "value": "SET", "uri" : "/set" } ] } )raw"; // Additional AutoConnectElements. const char addons[] PROGMEM = R"raw( [ { "name": "notes", "type": "ACText", "value": "An update period as the below optionally." }, { "name": "period", "type": "ACRadio", "value": [ "30 sec.", "60 sec.", "180 sec." ], "arrange": "vertical", "checked": 1 } ] )raw"; AutoConnect portal; AutoConnectAux* auxPage; // Load a custom Web page. portal.load(page); // Get a '/settings' page auxPage = portal.aux("/settings"); // Also, load only AutoConnectRadio named the period. auxPage->loadElement(addons, "period"); // Retrieve a server name from an AutoConnectText value. AutoConnectText& serverName = auxPage->getElement("server"); Serial.println(serverName.value); ``` ### Saving AutoConnectElements with JSON To save the AutoConnectElement as a JSON document, use the [AutoConnectAux::saveElement](apiaux.md#saveelement) function. It serializes the contents of the object based on the type of the AutoConnectElement. You can persist a serialized AutoConnectElements as a JSON document to a stream. ```cpp // Open a parameter file on the SPIFFS. SPIFFS.begin(); FILE param = SPIFFS.open("/param", "w"); // Save elements as the parameters. auxPage->saveElement(param, { "server", "period" }); // Close a parameter file. param.close(); SPIFFS.end(); ``` The example above saves `server` and `period` elements from the AutoConnectAux object as mentioned above to the `/param` file on SPIFFS. Its JSON document of AutoConnectElements saved by its code looks like this: ```json [ { "name": "server", "type": "ACInput", "value": "An inputted server name", "label": "Server", "placeholder": "" }, { "name": "period", "type": "ACRadio", "value": [ "30 sec.", "60 sec.", "180 sec." ], "arrange": "vertical", "checked": 2 } ] ``` ## Custom field data handling A sketch can access variables of AutoConnectElements in the custom Web page. The value entered into the AutoConnectElements on the page is stored in the member variable of each element by AutoConnect whenever GET/POST transmission occurs. The following diagram shows the flow of the input values of a custom Web page into a sketch and is the basis for actions to manipulate the values of custom Web pages using sketches. ### Where to pick up the values A sketch composed of handlers can receive the value of AutoConnectElements entered in a custom Web page after sending, but that handler is different from the page where the value was entered. It is necessary to be aware that can accept the entered values by the next page handler after the transition. Usually, two ways to retrieve entered values we have. One is to use the [ESP8266WebServer::arg](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#getting-information-about-request-arguments) (or WebServer::arg for ESP32) function in the [`on handler`](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#client-request-handlers) attached by ESP8266WebServer (WebServer w/ESP32 also). ```cpp hl_lines="33" #include #include #include static const char addonJson[] PROGMEM = R"raw( { "title": "Hello", "uri": "/hello", "menu": true, "element": [ { "name": "feels", "type": "ACInput", "label": "What's up?" }, { "name": "send", "type": "ACSubmit", "value": "Just it!", "uri": "/feels" } ] } )raw"; ESP8266WebServer webServer; AutoConnect portal(webServer); // Here, /feels handler void feelsOn() { // Retrieve the value of a input-box named "feels" String feel = webServer.arg("feels"); // Echo back the value String echo = "

" + feel + String(" and a bold world!

"); webServer.send(200, "text/html", echo); } void setup() { delay(1000); webServer.on("/feels", feelsOn); // Register /feels handler portal.load(addonJson); // Load a custom Web page portal.begin(); } void loop() { portal.handleClient(); } ``` An above example is the most simple sketch of handling values entered into a custom Web page. This sketch obtains the string entered in the AutoConnectInput named `feels` with the `/feels` handler after page transition, and the AutoConnectInput is an `` element wrapped in the form as the actual HTML code. !!! info "Should be accessed `/_ac` first" When you actually try the above sketch, there is no a root handler. So the URL that should be accessed first is `/_ac` concatenated with the local IP address of the esp8266 module. Another method is effective when custom Web pages have complicated page transitions. It is a way to straight access the AutoConnectElements member value. You can get the AutoConnectElement with the specified name using the [getElement](#get-autoconnectelement-from-the-autoconnectaux) function. The following sketch executes the above example with AutoConnect only, without using the function of ESP8266WebServer. ```cpp hl_lines="47 50" #include #include #include const static char addonJson[] PROGMEM = R"raw( [ { "title": "Hello", "uri": "/hello", "menu": true, "element": [ { "name": "feels", "type": "ACInput", "label": "What's up?" }, { "name": "send", "type": "ACSubmit", "value": "Just it!", "uri": "/feels" } ] }, { "title": "Hello", "uri": "/feels", "menu": false, "element": [ { "name": "echo", "type": "ACText", "style": "color:blue;font-family:verdana;font-size:300%;" } ] } ] )raw"; AutoConnect portal; // Here, /feels handler String feelsOn(AutoConnectAux& aux, PageArgument& args) { // Get the AutoConnectInput named "feels". // The where() function returns the AutoConnectAux of the page that triggered this handler. AutoConnectInput& feels = portal.where()->getElement("feels"); // Get the AutoConnectText named "echo". AutoConnectText& echo = aux.getElement("echo"); // Echo back from input-box to /feels page. echo.value = feels.value + String(" and a bold world!"); return String(""); } void setup() { delay(1000); portal.load(addonJson); // Load custom Web pages portal.on("/feels", feelsOn, AC_EXIT_AHEAD); // Register /feels handler portal.begin(); } void loop() { portal.handleClient(); } ``` The above example handles in the handler for the values of a custom web page. An [AutoConnect::on](api.md#on) function registers a handler for the AutoConnectAux page of the specified uri. The argument of the custom Web page handler is an AutoConnectAux of the page itself and the [PageArgument](https://github.com/Hieromon/PageBuilder#arguments-of-invoked-user-function) object. To retrieve the values entered in a custom Web page you need to access the AutoConnectElement of the page that caused the request to this page and to do this, you use the [AutoConnect::where](api.md#where) function. The `AutoConnect::where` function returns a pointer to the AutoConnectAux object of the custom Web page that caused the HTTP request. !!! note "The where() function is available for only AutoConnectAux." The `AutoConnect::where` function is available only for the AutoConnectAux object. It is invalid for HTTP requests from individual pages registered with the **on** handler of ESP8266WebServer/ESP32. In other words, the `AutoConnect::where` function only returns the last AutoConnecAux page called. ### When setting the initial values An AutoConnectAux page is dynamically created by AutoConnect when its uri is requested. The initial value of AutoConnectElements can be set before its page request. It is also possible during `loop()`. To set the initial value when the page is accessed it needs by the handler of its page. The [**AutoConnect::on**](api.md#on) and [**AutoConnectAux::on**](apiaux.md#on) functions register a handler for a custom Web page and also specify when to call that handler. The behavior of the two `on` functions is the same, only the class and arguments are different. ```cpp bool AutoConnect::on(const String& uri, const AuxHandlerFunctionT handler, AutoConnectExitOrder_t order) ``` ```cpp void AutoConnectAux::on(const AuxHandlerFunctionT handler, const AutoConnectExitOrder_t order) ``` Parameter `uri` specifies an URI of the custom Web page, but an AutoConnectAux object with its URI must be registered with AutoConnect via the [AutoConnect::join](api.md#join) function beforehand. !!! note "AutoConnect::on/AutoConnectAux::on is not ESP8266WebServer::on" The `on` function for AutoConnect is different from the `on` function of Arduino core ESP8266WebServer (WebServer for ESP32). You can share the same handler via wrapper, but access to AutoConnectElements is **valid only for handlers registered with `on` function for AutoConnect**. `AuxHandlerFunctionT` type is a handler declaration using with [std::function](https://en.cppreference.com/w/cpp/utility/functional/function). ```cpp String handler(AutoConnectAux& aux, PageArgument& args) ``` The handler of the custom Web page has two arguments by a reference of AutoConnectAux and a reference of PageArgument, it returns String. AutoConnect appends the string returned from the handler to the generated HTML. This allows you to add an HTML part before displaying the page. `AutoConnectExitOrder_t` specifies when the handler is called with the following enumeration value. : - **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. The following example is a part of sketch contained the handlers. ```cpp // AutoConnect object declarations ACInput(input1); AutoConnectAux aux("/aux", { input1 }); AutoConnect portal; // Pre-declare handlers String initialize(AutoConnectAux&, PageArgument&); String append(AutoConnectAux&, PageArgument&); // Register handlers and launch the portal. aux.on(initialize, AC_AHEAD); aux.on(append, AC_LATER); portal.join(aux); portal.begin(); // Some code here... // The handler called before HTML generating String initialize(AutoConnectAux& aux, PageArgument& args) { AutoConnectInput& input1 = aux.getElement("input1"); // Set initial value for the input box in a custom Web page. input1.value = "Initial value"; // Nothing appendix for a generated HTML. return String(); } // The handler called after HTML generated String append(AutoConnectAux& aux, PageArgument& args) { // Append an HTML return String("

This text has been added.

"); } ``` ### How you can reach the values AutoConnectSubmit uses the POST method to send HTTP requests. A value of AutoConnectInput sent to the ESP8266 or ESP32 with POST is stored in the request body of the HTTP request: ``` POST /feels HTTP/1.1 Host: ESP8266_IP_ADDRESS name1=value1&name2=value2&name3=value3 ``` 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. ```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. ```cpp const static char auxPage[] PROGMEM = R"raw ( [ { "title":"Hello", "uri":"/hello", "menu":true, "element":[ { "name":"input1", "type": "ACInput", "label": "INPUT" }, { "name":"send", "type":"ACSubmit", "value":"HELLO", "uri":"/echo" }] }, { "title":"Echo", "uri":"/echo", "menu":false, "element":[ { "name":"echo", "type":"ACText" }] } ] )raw"; AutoConnect portal; portal.load(auxPage); portal.on("/echo", [](AutoConnectAux& aux, PageArgument& args) { AutoConnectText& ac_echo = aux.getElement("echo"); ac_echo.value = args.arg("input1"); return String(); }); portal.begin(); ``` ### 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. ### Check data against on submission By giving a [pattern](apielements.md#pattern) to [AutoConnectInput](apielements.md#autoconenctinput), you can find errors in data styles while typing in custom Web pages. The pattern is specified by [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions).[^2] If the value during input of AutoConnectInput does not match the regular expression specified in the pattern, its background color changes to pink. The following example shows the behavior when checking the IP address in the AutoConnectInput field. [^2]: The pattern of AutoConnectInput conforms to javascript specification. ```json hl_lines="10" { "title" : "Page-1", "uri" : "/page1", "menu" : true, "element" : [ { "name" : "Server", "type" : "ACInput", "label": "Server address", "pattern": "^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$" } ] } ``` ### Convert data to actually type ## Transitions of the custom Web pages ### Scope & Lifetime of AutoConnectAux The lifetime of AutoConnectAux and AutoConnectElements must remain in the period when the custom Web page can be manipulated. The implementation of the custom Web page inherits from requestHandler driven from ESP8266WebServer (WebServer for ESP32), so the instance of AutoConnectAux and AutoConnectElements must exist for the duration of effect of handleClient. The following example is incorrect for manipulating custom Web pages. Its AutoConnectAux instance will be destructed at the exit of the setup(). ```cpp hl_lines="20" #include #include #include static const auxPage[] PROGMEM = R"raw( { "title": "Page-1", "uri": "/page1", "menu": true, "element": [ { "name":"Server", "type":"ACText", "label":"Server address" } ] } )raw"; AutoConnect portal; void setup() { // This declaration is wrong. AutoConnectAux aux; aux.load(auxPage); portal.join(aux); portal.begin(); } void loop() { portal.handleClient(); } ``` ### 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 custom Web pages handler has the following restrictions. - Do not send HTTP responses from the handler. If the handler returns its own response, the custom Web page will be lost. - Use AutoConnectSubmit whenever possible. AutoConnect will hold the values of a custom Web Page is sent by AutoConnectSubmit. - Can not handle the custom Web pages during a connection is not established yet. 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]. 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.