From 650ab5924c23b10c7c380b0e711304c7ab41ae6a Mon Sep 17 00:00:00 2001 From: Hieromon Ikasamo Date: Fri, 25 Jan 2019 17:59:22 +0900 Subject: [PATCH] Under the work of v0.9.7 documentation --- mkdocs/achandling.md | 163 ++++- mkdocs/api.md | 11 + mkdocs/images/ac_param_flow.svg | 1133 +++++-------------------------- 3 files changed, 344 insertions(+), 963 deletions(-) diff --git a/mkdocs/achandling.md b/mkdocs/achandling.md index ab3fb70..788f658 100644 --- a/mkdocs/achandling.md +++ b/mkdocs/achandling.md @@ -104,7 +104,7 @@ AutoConnectElementVT& getElements(void) ## Loading & saving AutoConnectElements with JSON -AutoConnect supports that loading the AutoConnectAux as a set of elements, and Loading and saving individual elements. It is not possible to save all AutoConnectElements at once as AutoConnectAux. In both cases the target object is a JSON document. +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) @@ -112,11 +112,11 @@ AutoConnect supports that loading the AutoConnectAux as a set of elements, and L 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. If the JSON document is described as an array of multiple custom Web pages, all pages contained in the array will be generated. 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 [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 +```cpp hl_lines="49 55" // AutoConnectAux as a custom Web page. const char page[] PROGMEM = R"raw( { @@ -130,7 +130,7 @@ const char page[] PROGMEM = R"raw( "label": "Server" }, { - "name": "set", + "name": "set", "type": "ACSubmit", "value": "SET", "uri" : "/set" @@ -228,13 +228,164 @@ The following diagram shows the flow of the input values of a custom Web page in -### When to pick up the values +### Where to pick up the values + +The sketch receives the values of AutoConnectElements entered in a custom Web page after sending, but it is not the handler of the page where the values 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 + +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" + } + ] + }, + { + "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 and can also specify when the handler is called. 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 -### How you can reach the valuess +The `AutoConnect::on` function has a parameter indicating the timing to call a custom Web page handler. + +### 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
+
+The query string included in the HTTP request body is parsed by ESP8266WebServer class and retrieved it using the `ESP8266WebServer::arg` function in the handler with sketch side. Its argument specifies the name of the input element. WebServer.args, PageArgument Handling in 'on' handler ## Transitions of the custom Web pages + +A handler registered with ESP8266Server::on can not coexist with AutoConnectAux::on. diff --git a/mkdocs/api.md b/mkdocs/api.md index 4a7db47..b200313 100644 --- a/mkdocs/api.md +++ b/mkdocs/api.md @@ -273,3 +273,14 @@ Register the handler function for undefined URL request detected.
**Parameters**
fnA function of the "not found" handler.
+ +### where +```cpp +AutoConenctAux* where(void) +``` +Returns a pointer to the AutoConnectAux object of the custom web page that caused the request to that page. This 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, this function only returns the last AutoConnecAux page called. + +
+
**Retuen value**
+
A pointer to the AutoConnectAux that caused the request the page.
+
diff --git a/mkdocs/images/ac_param_flow.svg b/mkdocs/images/ac_param_flow.svg index 62490cf..3f6bc8a 100644 --- a/mkdocs/images/ac_param_flow.svg +++ b/mkdocs/images/ac_param_flow.svg @@ -10,9 +10,9 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="860.63983" - height="459.59912" - viewBox="0 0 227.71096 121.60225" + width="832.03271" + height="436.492" + viewBox="0 0 220.14199 115.4885" version="1.1" id="svg1212" inkscape:version="0.92.2 (5c3e80d, 2017-08-06)" @@ -213,16 +213,16 @@ inkscape:pageopacity="0.0" inkscape:pageshadow="2" inkscape:zoom="1.4" - inkscape:cx="512.21056" - inkscape:cy="211.19727" + inkscape:cx="343.2971" + inkscape:cy="197.13344" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="false" inkscape:snap-global="false" inkscape:window-width="1616" inkscape:window-height="851" - inkscape:window-x="1346" - inkscape:window-y="66" + inkscape:window-x="1667" + inkscape:window-y="103" inkscape:window-maximized="0" fit-margin-top="0" fit-margin-left="0" @@ -245,12 +245,24 @@ inkscape:label="レイヤー 1" inkscape:groupmode="layer" id="layer1" - transform="translate(-47.611264,-75.652706)"> + transform="translate(-54.981799,-75.851144)"> + + + transform="translate(18.421829,-13.844294)"> + transform="matrix(0.05237375,0,0,0.04755636,54.981799,95.989516)" + style="stroke-width:1.17960072"> + style="stroke-width:1.17960072"> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + style="stroke-width:1.17960072" /> + transform="translate(-61.780506,-30.859554)"> Web Browser - ESP8266WebServerWebServer w/ESP32 - POST /{URL}Input=Value... Value - AutoConnect - Sketch REGISTER - AutoConnectAux () } - - + + + Sketch + + + + AutoConnectAux + + + + AutoConnect + + + + ESP8266WebServerWebServer w/ESP32 + + POST /{URL}Input=Value...