diff --git a/README.md b/README.md index 993a8d0..82e6a78 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ Full documentation is available on https://Hieromon.github.io/AutoConnect, some ## Change log -### [0.9.7] Jan. 25, 2019 +### [0.9.7] Feb. 25, 2019 - Fixed crash in some environments. Thank you @ageurtse - Supports AutoConnect menu extention by user sketch with **AutoConnectAux**. - Supports loading and saving of user-defined parameters with JSON format. @@ -128,4 +128,4 @@ Full documentation is available on https://Hieromon.github.io/AutoConnect, some ## License -License under the [MIT license](LICENSE). \ No newline at end of file +License under the [MIT license](LICENSE). diff --git a/mkdocs.yml b/mkdocs.yml index 14282ee..2cfcbe2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,6 +29,7 @@ nav: - 'How to embed': howtoembed.md - 'Tips for data conversion': datatips.md - 'Constucting menu': menuize.md + - 'Custom Web pages w/o JSON': wojson.md - 'FAQ' : faq.md - 'Change log' : changelog.md - 'License' : license.md @@ -60,6 +61,7 @@ theme: extra_css: - 'css/paragraph.css' - 'css/extra.css' + - 'https://use.fontawesome.com/releases/v5.6.1/css/all.css' extra_javascript: - 'js/gifffer.min.js' extra: diff --git a/mkdocs/achandling.md b/mkdocs/achandling.md index ebad954..f27f5c9 100644 --- a/mkdocs/achandling.md +++ b/mkdocs/achandling.md @@ -362,7 +362,7 @@ void loop() { } ``` -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. +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. @@ -490,18 +490,52 @@ portal.on("/echo", [](AutoConnectAux& aux, PageArgument& args) { portal.begin(); ``` -### Over typing ​​with LoadElement function +### Overwrite the AutoConnectElements -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. +Sketches can update the attributes of AutoConnectElements with two approaches. A one is to assign directly to the attributes of a member variable of its element. The other is to overwrite them with loading the element by [AutoConnectAux::loadElement](apiaux.md#loadelement). -### Check data against on submission +The elements for attributes described in the JSON document for AutoConnectElements overwrites the member variables of the target AutoConnectElements. However, AutoConnectAux::loadElement keeps the member variables unchanged if there is no element in the JSON document. This overwriting behavior is the same for the [AutoConnect::load](api.md#load) function. + +For example, the combination of the sketch and JSON document as follows updates only the style while keeping Captiopn (ie. "Hello, world") as AutoConnectText value. + + The sketch (part of code) + +```cpp +ACText(Caption, "Hello, world"); +AutoConnectAux helloPage("/hello", "Hello", true, { Caption }); +AutoConnect portal; + +String onHello(AutoConnectAux& aux, PageArgument& args) { + aux.loadElement(JSON); + return String(); +} + +void setup() { + helloPage.on(onHello); + portal.join(helloPage); + portal.begin(); +} + +void loop() { + portal.handleClient(); +} +``` + + External JSON document for the above sketch to modify the text style +```json +{ + "name" : "Caption", + "type" : "ACText", + "style": "text-align:center;font-family:'Avenir','Corbel','Osaka';color:Green;" +} +``` + +### 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", @@ -518,6 +552,11 @@ By giving a [pattern](apielements.md#pattern) to [AutoConnectInput](apielements. } ``` +
+ + +
+ ### Convert data to actually type ## Transitions of the custom Web pages diff --git a/mkdocs/acjson.md b/mkdocs/acjson.md index 6313649..f0b626a 100644 --- a/mkdocs/acjson.md +++ b/mkdocs/acjson.md @@ -1,4 +1,4 @@ -## 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] @@ -9,7 +9,7 @@ By providing the following JSON document to AutoConnect, you can include the cus
-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. +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. @@ -33,16 +33,16 @@ An AutoConnectAux is described by a JSON object. The elements that make up an ob : A title of the custom Web page. This is string value. String specified *title* will be displayed in the AutoConnection menu. #### **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 '**/**'. +: String of URI path that specifies where to place the custom Web page. It needs to be a location from the root path including '**/**'. #### **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. +: 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. #### **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. + The order in which AutoConnectElements are placed on a custom Web page is the order in the JSON document. ### Multiple custom Web pages declaration in JSON document @@ -104,16 +104,12 @@ You can put declarations of multiple custom Web pages in one JSON document. In t AutoConnectElements in JSON description are described as an array in the `element` with arguments of each [constructor](acelements.md#constructor). ``` -"element" : [ - { - "name" : name, - "type" : type, - key_according_to_type : the_value | array_of_value , key_according_to_type : the_value | array_of_value - }, - { - the_nect_element - } -] +{ + "name" : name, + "type" : type, + key_according_to_type : the_value | array_of_value, + [ key_according_to_type : the_value | array_of_value ] +} ``` #### **name** @@ -229,4 +225,4 @@ AutoConnect passes the given JSON document directly to the [**parseObject()**](h ## 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. +The sketch can persist AutoConnectElements as a JSON document and also uses [this function](achandling.md#saving-autoconnectelements-with-json) to save the values ​​entered on the custom Web page. And you can reload the saved JSON document into AutoConnectElements as the field in a custom Web page using the [load function](achandling.md#loading-autoconnectaux-autoconnectelements-with-json). diff --git a/mkdocs/api.md b/mkdocs/api.md index b9db43a..08fce79 100644 --- a/mkdocs/api.md +++ b/mkdocs/api.md @@ -58,7 +58,7 @@ Run the AutoConnect site using the externally ensured ESP8266WebServer for ESP82 The [**handleClient**](api.md#handleclient) function of AutoConnect can include the response of the URI handler added by the user using the "*on*" function of ESP8266WebServer/WebServer. If ESP8266WebServer/WebServer is assigned internally by AutoConnect, the sketch can obtain that reference with the [**host**](api.md#host) function.
**Parameters**
-
webServerA reference of ESP8266WebServer or WebServer instance.
+
webServerA reference of ESP8266WebServer or WebServer instance.
## Public member functions @@ -71,7 +71,7 @@ AutoConnectAux* aux(const String& uri) const Returns a pointer to AutoConnectAux with the URI specified by *uri*. If AutoConnectAux with that URI is not bound, it returns **nullptr**.
**Parameters**
-
uriA string of the URI.
+
uriA string of the URI.
**Return value**
A Pointer of the AutoConnectAux instance.
@@ -93,12 +93,12 @@ AutoConnect first invokes *WiFi.begin*. If the *ssid* and the *passphrase* are m The captive portal will not be started if the connection has been established with first *WiFi.begin*. If the connection cannot establish, switch to WIFI_AP_STA mode and activate SoftAP. Then DNS server starts.
**Parameters**
-
ssidSSID to be connected.
-
passphrasePassword for connection.
-
timeoutA time out value in milliseconds for waiting connection.
+
ssidSSID to be connected.
+
passphrasePassword for connection.
+
timeoutA time out value in milliseconds for waiting connection.
**Return value**
-
trueConnection established, AutoConnect service started with WIFI_STA mode.
-
falseCould not connected, Captive portal started with WIFI_AP_STA mode.
+
trueConnection established, AutoConnect service started with WIFI_STA mode.
+
falseCould not connected, Captive portal started with WIFI_AP_STA mode.
### config @@ -113,12 +113,12 @@ bool config(const char* ap, const char* password = nullptr) Set SoftAP's WiFi configuration and static IP configuration.
**Parameters**
-
configReference to [**AutoConnectConfig**](apiconfig.md) containing SoftAP's parameters and static IP parameters.
-
apSSID for SoftAP. The default value is **esp8266ap** for ESP8266, **esp32ap** for ESP32.
-
passwordPassword for SodtAP. The default value is **12345678**.
+
configReference to [**AutoConnectConfig**](apiconfig.md) containing SoftAP's parameters and static IP parameters.
+
apSSID for SoftAP. The default value is **esp8266ap** for ESP8266, **esp32ap** for ESP32.
+
passwordPassword for SodtAP. The default value is **12345678**.
**Return value**
-
trueSuccessfully configured.
-
falseConfiguration parameter is invalid, some values out of range.
+
trueSuccessfully configured.
+
falseConfiguration parameter is invalid, some values out of range.
### end @@ -154,13 +154,13 @@ Handling for the AutoConnect menu request. ### home ```cpp -void home(String uri) +void home(String& uri) ``` Put a user site's home URI. The URI specified by home is linked from "HOME" in the AutoConnect menu.
**Parameters**
-
uri A URI string of user site's home path.
+
uriA URI string of user site's home path.
### host @@ -205,7 +205,7 @@ void join(std::vector> aux) Join the AutoConnectAux object to AutoConnect. AutoConnectAux objects can be joined one by one, or joined altogether. The AutoConnectAux object joined by the join function can be handled from the AutoConnect menu.
**Parameters**
-
auxReference to AutoConnectAux. It can be std::vector of std::reference_wrapper of AutoConnectAux with [list initialization](https://en.cppreference.com/w/cpp/language/list_initialization).
+
auxReference to AutoConnectAux. It can be std::vector of std::reference_wrapper of AutoConnectAux with [list initialization](https://en.cppreference.com/w/cpp/language/list_initialization).
### load @@ -222,10 +222,10 @@ bool load(Stream& aux) Load JSON document of AutoConnectAux which contains AutoConnectElements. If there is a syntax error in the JSON document, false is returned.
**Parameters**
-
auxThe input string to be loaded.
+
auxThe input string to be loaded.
**Return value**
-
trueThe JSON document as AutoConnectAux successfully loaded.
-
falseLoading 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/).
+
trueThe JSON document as AutoConnectAux successfully loaded.
+
falseLoading 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/).
### on @@ -236,10 +236,9 @@ bool on(const String& uri, const AuxHandlerFunctionT handler, AutoConnectExitOrd Register the handler function of the AutoConnectAux.
**Parameters**
-
uriA string of the URI assigned to the AutoConnectAux page.
-
handlerA function that behaves when a request to the AutoConnectAux page occurs. AuxHandlerFunctionT type is defined by the following declaration.
-
`String handler(AutoConnectAux&, PageArgument&)`
-
orderSpecifies when the handler is called with the following enumeration value.
+
uriA string of the URI assigned to the AutoConnectAux page.
+
handlerA function that behaves when a request to the AutoConnectAux page occurs. AuxHandlerFunctionT type is defined by the following declaration.

`String handler(AutoConnectAux&, PageArgument&)`

+
orderSpecifies 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** : @@ -259,7 +258,7 @@ void onDetect(DetectExit_ft fn) Register the function which will call from AutoConnect at the start of the captive portal.
**Parameters**
-
fnFunction called at the captive portal start.
+
fnFunction called at the captive portal start.
@@ -270,10 +269,10 @@ typedef std::function DetectExit_ft ```
**Parameters**
-
softapIPAn IP address of SoftAP for the captive portal.
+
softapIPAn IP address of SoftAP for the captive portal.
**Retuen value**
-
trueContinues captive portal handling.
-
falseCancel the captive portal. AutoConnect::begin function will return with a false.
+
trueContinues captive portal handling.
+
falseCancel the captive portal. AutoConnect::begin function will return with a false.
### onNotFound @@ -292,14 +291,14 @@ void onNotFound(WebServer::THandlerFunction fn) Register the handler function for undefined URL request detected.
**Parameters**
-
fnA function of the "not found" handler.
+
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. +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/apiaux.md b/mkdocs/apiaux.md index af0c68b..f1a4853 100644 --- a/mkdocs/apiaux.md +++ b/mkdocs/apiaux.md @@ -7,9 +7,10 @@ AutoConnectAux(const String& uri = String(""), const String& title = String(""), ```
**Parameters**
-
uriURI of this custom Web Page.
-
titlePage title of this custom web page. It will appear on the auto connection menu and at the top of that page.
-
addonsReference to AutoConnectElement collection. +
uriURI of this custom Web Page.
+
titlePage title of this custom Web page. It will appear on the auto connection menu and at the top of that page.
+
menuSpecifies whether to display this page on menu.
+
addonsReference to AutoConnectElement collection.
## Public member functions @@ -23,17 +24,27 @@ void add(AutoConnectElement& addon) void add(AutoConnectElementVT addons) ``` Add an element to the AutoConnectAux. An added element is displayed on the custom Web page invoked from the AutoConnect menu. +
+
**Parameters**
+
addonReference of AutoConnectElements. Specifies one of the AutoConnectElements classes.
+
addonsAn array list of reference of AutoConnectElements. An [list initialization](https://en.cppreference.com/w/cpp/language/list_initialization) of the [std::vector](https://en.cppreference.com/w/cpp/container/vector) can be used for the addons parameter cause the actual definition of type **AutoConnectElementVT** is `std::vector>`.
+
### getElement ```cpp -template T& getElement(const String& name) +T& getElement(const String& name) ``` ```cpp AutoConnectElement* getElement(const String& name) ``` - -Get registered AutoConnectElement as specified name. +Get a registered AutoConnectElement as specified name. If **T** is specified as an actual type of AutoConnectElements, it returns a reference to that instance. +
+
**Parameters**
+
TActual type name of AutoConnectElements as [AutoConnectButton](apielements.md#autoconnectbutton), [AutoConnectCheckbox](apielements.md#autoconnectcheckbox), [AutoConnectElement](apielements.md#autoconnectelement), [AutoConnectInput](apielements.md#autoconnectinput), [AutoConnectRadio](apielements.md#autoconnectradio), [AutoConnectSelect](apielements.md#autoconnectselect), [AutoConnectSubmit](apielements.md#autoconnectsubmit), [AutoConnectText](apielements.md#autoconnecttext).
+
nameName of the AutoConnectElements to be retrieved.
+
**Return value**
A reference of the AutoConnectElements. If a type is not specified returns a pointer.
+
### getElements @@ -41,6 +52,22 @@ Get registered AutoConnectElement as specified name. AutoConnectElementVT& getElements(void) ``` Get vector of reference of all elements. +
+
**Return value**
+
A reference to std::vector of reference to AutoConnecctElements.
+
+ +The getElements returns a reference to std::vector of reference to AutoConnecctElements. This function is provided to handle AutoConnectElemets owned by AutoConnectAux in bulk, and you can use each method of std::vector for a return value. + +```cpp +// An example of getting type and name of all AutoConnectElements registered in AutoConnectAux. +AutoConnectAux aux; +// some code here... +AutoConnectElementVt& elements = aux.getElements(); +for (AutoConnectElement& elm : elements) { + Serial.printf("name<%s> as type %d\n", elm.name.c_str(), (int)elm.typeOf()); +} +``` ### load @@ -53,7 +80,22 @@ bool load(const __FlashStringHelper* in) ```cpp bool load(Stream& in) ``` -Load whole elements to AutoConnectAux Pages. +Load all AutoConnectElements elements from JSON document into AutoConnectAux as custom Web pages. The JSON document specified by the load function must be the [document structure](acjson.md#json-objects-elements-for-the-custom-web-page) of AutoConnectAux. Its JSON document can describe multiple pages as an array. +
+
**Parameters**
+
inSpecifies the JSON document to be load. The load function can input the following objects. + +- String : Read-only String +- PROGMEM : Character array contained in the flash +- Stream : An entity that inherits stream class, generally SPIFFS or SD. +
+
**Return value**
+
trueJSON document as the custom Web pages successfully loaded.
+
falseJSON document loading failed.
+
+ +!!! hint "Load multiple custom Web pages separately" + Multiple custom Web pages can be loaded at once with JSON as an array. But it will consume a lot of memory. By loading a JSON document by page as much as possible, you can reduce memory consumption. ### loadElement @@ -66,14 +108,49 @@ bool loadElement(const __FlashStringHelper* in, const String& name = String("")) ```cpp bool loadElement(Stream& in, const String& name = String("")) ``` -Load specified element. +Load specified element from JSON document into AutoConnectAux. The JSON document specified by the loadElement function must be the [AutoConnectElement document structure](acjson.md#json-object-for-autoconnectelements). When loading from a JSON document that describes multiple elements, its description must be an array syntax. +
+
**Parameters**
+
inSpecifies the JSON document to be load. The load function can input the following objects. + +- String : Read-only String +- PROGMEM : Character array contained in the flash +- Stream : An entity that inherits stream class, generally SPIFFS or SD. +
+
nameSpecifies the name to be load. If the name is not specified, the loadElement function will load all elements contained in the JSON document.
+
**Return value**
+
trueSpecified AutoConnectElements successfully loaded.
+
falseJSON document loading failed.
+
+ +!!! caution "Maybe it is an array" + Please note that the JSON document that is the input for loadElement is an array syntax of AutoConnectElements when there are multiple elements. For example, the following JSON document has a syntax error: + + ```json + { + "name": "Caption", + "type": "ACText", + "value": "Hello, world" + }, + { + "name": "Server", + "type": "ACInput", + "label": "Server address" + } + ``` + The outermost `[`, `]` is missing. ### menu ```cpp void menu(const bool post) ``` -Set or reset the display as menu item for this AutoConnectAux. +Set or reset the display as menu item for this AutoConnectAux. This function programmatically manipulates the menu parameter of the [AutoConenctAux constructor](apiaux.md#autoconnectaux). +
+
**Parameters**
+
trueShow on the menu.
+
falseHidden on the menu.
+
### on @@ -83,15 +160,14 @@ void on(const AuxHandlerFunctionT handler, const AutoConnectExitOrder_t order = Register the handler function of the AutoConnectAux.
**Parameters**
-
handlerA function that behaves when a request to the AutoConnectAux page occurs. AuxHandlerFunctionT type is defined by the following declaration.
-
`String handler(AutoConnectAux&, PageArgument&)`
-
orderSpecifies when the handler is called with the following enumeration value.
+
handlerA function that behaves when a request to the AutoConnectAux page occurs. AuxHandlerFunctionT type is defined by the following declaration.

`String handler(AutoConnectAux&, PageArgument&)`

+
orderSpecifies 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. + Called even before generating HTML and after generated.
### release @@ -99,14 +175,31 @@ Register the handler function of the AutoConnectAux. ```cpp bool release(const String& name) ``` -Release a specified AutoConnectElement. +Release a specified AutoConnectElement from AutoConenctAux. The release function is provided to dynamically change the structure of the custom Web pages with the sketch. By combining the release function and the [add](apiaux.md#add) function or the [loadElement](apiaux.md#loadelement) function, the sketch can change the style of the custom Web page according to its behavior. +
+
**Parameters**
+
nameSpecifies the name of AutoConnectElements to be released.
+
**Return value**
+
trueThe AutoConnectElement successfully released.
+
falseThe AutoConnectElement can not be released.
+
### saveElement ```cpp size_t saveElement(Stream& out, std::vector const& names = {}) ``` -Write elements of AutoConnectAux to the stream. +Write elements of AutoConnectAux to the stream. The saveElement function outputs the specified AutoConenctElements as a JSON document using the [prettyPrintTo](https://arduinojson.org/v5/api/jsonobject/prettyprintto/) function of the [ArduinoJson](https://arduinojson.org/) library. +
+
**Parameters**
+
outOutput stream to be output. SPIFFS, SD also Serial can be specified generally.
+
namesThe array of the name of AutoConnectElements to be output. If the names parameter is not specified, all AutoConnectElements registered in AutoConnectAux are output.
+
**Return value**
+
The number of bytes written.
+
+ +!!! note "The output format is pretty" + The saveElement function outputs a prettified JSON document. ### setElementValue @@ -116,10 +209,43 @@ bool setElementValue(const String& name, const String value) ```cpp bool setElementValue(const String& name, std::vector const& values) ``` +Sets the value of the specified AutoConnectElement. If values ​​is specified as a *std::vector* of String, the element that can set the values is the [AutoConnectRadio](apielements.md#autoconnectradio) or the [AutoConnectSelect](apielements.md#autoconnectselect). +
+
**Parameters**
+
nameSpecifies the name of the AutoConnectElements that you want to set the value.
+
valueSpecifies the value to be set.
+
valuesSpecifies a reference of a *std::vector* of String. It contains the values of the AutoConnectRadio or the AutoConnectSelect.
+
**Return value**
+
trueThe value has been set.
+
falseAutoConnectElements with the specified name are not registered. Or the type of the value is not consistent with the specified AutoConnectElements.
+
+ +!!! hint "You can directly access the value member variable." + If you are gripping with the sketch to the AutoConnectElements of the target that sets the value, you can access the value member variable directly. The following sketch code has the same effect. + ```cpp + AutoConnectAux aux; + // ... Griping the AutoConnectText here. + aux.setElementValue("TEXT_FIELD", "New value"); + ``` + ```cpp + AutoConnectAux aux; + // ... Griping the AutoConnectText here. + AutoConnectText& text = aux.getElement("TEXT_FIELD"); + text.value = "New value"; + ``` + The difference between the setElementValue and the value access with the [getElement](apiaux.md#getelement) is the certainty of the registration state for the element. The [getElement](apiaux.md#getelement) returns an empty object if the element is not registered then a sketch assigns the value to it. May occur unexpected results and crashes. You should use the setElementValue if its registration is unsettled. ### setTitle ```cpp void setTitle(const String& title) ``` -Set the title string of the AutoConnectAux page. +Set the title string of the custom Web page. This title will be displayed as the menu title of the custom Web page. +
+
**Parameter**
+
titleTitle string to be display.
+
+ +!!! caution "Not the menu title" + The setTitle function is not set for the AutoConnect menu title. The effect of this function is that custom Web page only. To change the AutoConnect menu title use [AutoConnectConfig::title](apiconfig.md#title). + \ No newline at end of file diff --git a/mkdocs/apiconfig.md b/mkdocs/apiconfig.md index dfe42af..4a98021 100644 --- a/mkdocs/apiconfig.md +++ b/mkdocs/apiconfig.md @@ -16,10 +16,10 @@ AutoConnectConfig(const char* ap, const char* password, const unsigned long time ```
**Parameters**
-
apSSID for SoftAP. The length should be up to 31. The default value is **esp8266ap** for ESP8266, **esp32ap** for ESP32.
-
passwordPassword for SodtAP. The length should be from 8 to up to 63. The default value is **12345678**.
-
timeoutThe timeout value of the captive portal in [ms] units. The default value is 0.
-
channelThe channel number of WIFi when SoftAP starts. The default values is 1.
+
apSSID for SoftAP. The length should be up to 31. The default value is **esp8266ap** for ESP8266, **esp32ap** for ESP32.
+
passwordPassword for SodtAP. The length should be from 8 to up to 63. The default value is **12345678**.
+
timeoutThe timeout value of the captive portal in [ms] units. The default value is 0.
+
channelThe channel number of WIFi when SoftAP starts. The default values is 1.
## Public member variables @@ -37,7 +37,7 @@ SoftAP's SSID. Sets IP address for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this.
**Type**
-
IPAddressThe default value is **192.168.244.1**
+
IPAddressThe default value is **192.168.244.1**
### autoReconnect @@ -48,8 +48,8 @@ If the connection fails, starts the captive portal in SoftAP + STA mode.
**Type**
bool
**Value**
-
trueReconnect automatically.
-
falseStarts Captive Portal in SoftAP + STA mode without trying to reconnect. This is the default.
+
trueReconnect automatically.
+
falseStarts Captive Portal in SoftAP + STA mode without trying to reconnect. This is the default.
When the autoReconnect option is enabled, an automatic connection will behave if the following conditions are satisfied. @@ -64,8 +64,8 @@ Reset ESP8266 module automatically after WLAN disconnected.
**Type**
bool
**Value**
-
trueReset after WiFi disconnected automatically.
-
falseNo reset.
+
trueReset after WiFi disconnected automatically.
+
falseNo reset.
### autoRise @@ -75,8 +75,8 @@ Captive portal activation switch. False for disabling the captive portal. It pre
**Type**
bool
**Value**
-
trueEnable the captive portal. This is the default.
-
falseDisable the captive portal.
+
trueEnable the captive portal. This is the default.
+
falseDisable the captive portal.
### autoSave @@ -86,8 +86,8 @@ The credential saved automatically at the connection establishment.
**Type**
AC_SAVECREDENTIAL_t
**Value**
-
AC_SAVECREDENTIAL_AUTOThe credential saved automatically. This is the default.
-
AC_SAVECREDENTIAL_NEVERThe credential no saved.
+
AC_SAVECREDENTIAL_AUTO The credential saved automatically. This is the default.
+
AC_SAVECREDENTIAL_NEVER The credential no saved.
### bootUri @@ -97,8 +97,8 @@ Specify the location to be redirected after module reset in the AutoConnect menu
**Type**
AC_ONBOOTURI_t
**Value**
-
AC_ONBOOTURI_ROOTResetting the module redirects it to the AutoConnect root path. The root path is assumed to be AUTOCONNECT_URI defined in AutoConnectDefs.h.
-
AC_ONBOOTURI_HOMEIt is redirected to the uri specified by [**AutoConnectConfig::homeUri**](apiconfig.md#homeuri).
+
AC_ONBOOTURI_ROOT Resetting the module redirects it to the AutoConnect root path. The root path is assumed to be AUTOCONNECT_URI defined in AutoConnectDefs.h.
+
AC_ONBOOTURI_HOME It is redirected to the uri specified by [**AutoConnectConfig::homeUri**](apiconfig.md#homeuri).
### boundaryOffset @@ -147,7 +147,7 @@ Set secondary DNS server address when using static IP address. Sets gateway address for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this.
**Type**
-
IPAddressThe default value is **192.168.244.1**
+
IPAddressThe default value is **192.168.244.1**
### hidden @@ -157,8 +157,8 @@ Sets SoftAP to hidden SSID.
**Type**
uint8_t
**Value**
-
0SSID will be appeared. This is the default.
-
1SSID will be hidden.
+
0SSID will be appeared. This is the default.
+
1SSID will be hidden.
### homeUri @@ -184,8 +184,8 @@ Disable the first WiFi.begin() and start the captive portal. If this option is e
**Type**
bool
**Value**
-
trueStart the captive portal with [**AutoConnect::begin**](api.md#begin).
-
falseEnable the first WiFi.begin() and it will start captive portal when connection failed. This is default.
+
trueStart the captive portal with [**AutoConnect::begin**](api.md#begin).
+
falseEnable the first WiFi.begin() and it will start captive portal when connection failed. This is default.
### netmask @@ -193,7 +193,7 @@ Disable the first WiFi.begin() and start the captive portal. If this option is e Sets subnet mask for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this.
**Type**
-
IPAddressThe default value is **255.255.255.0**
+
IPAddressThe default value is **255.255.255.0**
### portalTimeout @@ -201,7 +201,7 @@ Sets subnet mask for Soft AP in captive portal. When AutoConnect fails the initi Specify the timeout value of the captive portal in [ms] units. It is valid when the station is not connected and does not time out if the station is connected to the ESP module in SoftAP mode (ie Attempting WiFi connection with the portal function). If 0, the captive portal will not be timed-out.
**Type**
-
unsigned longCaptive portal timeout value. The default value is 0.
+
unsigned longCaptive portal timeout value. The default value is 0.
### psk @@ -219,8 +219,8 @@ Specify whether to continue the portal function even if the captive portal timed
**Type**
bool
**Value**
-
trueContinue the portal function even if the captive portal times out. The STA + SoftAP mode of the ESP module continues and accepts the connection request to the AP.
-
falseWhen the captive portal times out, STA + SoftAP mode of the ESP module is stopped. This is default.
+
trueContinue the portal function even if the captive portal times out. The STA + SoftAP mode of the ESP module continues and accepts the connection request to the AP.
+
falseWhen the captive portal times out, STA + SoftAP mode of the ESP module is stopped. This is default.
!!! hint "Connection request after timed-out" diff --git a/mkdocs/apielements.md b/mkdocs/apielements.md index 4ec611d..d416271 100644 --- a/mkdocs/apielements.md +++ b/mkdocs/apielements.md @@ -7,9 +7,9 @@ AutoConnectButton(const char* name = "", const char* value = "", const String& a ```
**Parameters**
-
nameThe element name.
-
valueValue of the element.
-
actionNative code of the action script executed when the button is clicked.
+
nameThe element name.
+
valueValue of the element.
+
actionNative code of the action script executed when the button is clicked.
### Public member variables @@ -19,7 +19,7 @@ AutoConnectButton(const char* name = "", const char* value = "", const String& a The element name.
**Type**
-
String
+
String
#### value @@ -27,7 +27,7 @@ The element name. Value of the element.
**Type**
-
String
+
String
#### action @@ -35,7 +35,7 @@ Value of the element. HTML native code of the action script to be executed when the button is clicked. It is mostly used with a JavaScript to activate a script.[^1]
**Type**
-
String
+
String
[^1]:JavaScript can be inserted into a custom Web page using AutoConnectElement. @@ -62,10 +62,10 @@ Returns type of AutoConnectElement. ```
**Parameters**
-
nameThe element name.
-
valueValue of the element.
-
labelA label string prefixed to the checkbox.
-
checkChecked state of the checkbox.
+
nameThe element name.
+
valueValue of the element.
+
labelA label string prefixed to the checkbox.
+
checkChecked state of the checkbox.
### Public member variables @@ -75,7 +75,7 @@ Returns type of AutoConnectElement. The element name.
**Type**
-
String
+
String
#### value @@ -83,7 +83,7 @@ The element name. Value of the element. It becomes a value attribute of an HTML `#!html ` tag.
**Type**
-
String
+
String
#### label @@ -91,7 +91,7 @@ Value of the element. It becomes a value attribute of an HTML `#!html ` tag with an `id` attribute. The checkbox and the label are connected by the id attribute.
**Type**
-
String
+
String
#### checked @@ -99,7 +99,7 @@ A label is an optional string. A label is always arranged on the right side of t It indicates the checked status of the checkbox. The value of the checked checkbox element is packed in the query string and sent by submit.
**Type**
-
Boolean
+
Boolean
### Public member functions @@ -124,8 +124,8 @@ AutoConnectElement(const char* name = "", const char* value = "") ```
**Parameters**
-
nameThe element name.
-
valueValue of the element.
+
nameThe element name.
+
valueValue of the element.
### Public member variables @@ -135,7 +135,7 @@ AutoConnectElement(const char* name = "", const char* value = "") The element name.
**Type**
-
String
+
String
#### value @@ -143,7 +143,7 @@ The element name. Value of the element. It is output as HTML as it is as a source for generating HTML code.
**Type**
-
String
+
String
### Public member functions @@ -168,11 +168,11 @@ AutoConnectInput(const char* name = "", const char* value = "", const char* labe ```
**Parameters**
-
nameThe element name.
-
valueValue of the element.
-
labelLabel string.
-
patternRegular expression string for checking data format.
-
placeholderA placeholder string.
+
nameThe element name.
+
valueValue of the element.
+
labelLabel string.
+
patternRegular expression string for checking data format.
+
placeholderA placeholder string.
### Public member variables @@ -182,7 +182,7 @@ AutoConnectInput(const char* name = "", const char* value = "", const char* labe The element name.
**Type**
-
String
+
String
#### value @@ -190,7 +190,7 @@ The element name. Value of the element. It becomes a value attribute of an HTML `#!html ` tag. An entered text in the custom Web page will be sent with a query string of the form. The value set before accessing the page is displayed as the initial value.
**Type**
-
String
+
String
#### label @@ -198,7 +198,7 @@ Value of the element. It becomes a value attribute of an HTML `#!html ` tag with an id attribute. The input box and the label are connected by the id attribute.
**Type**
-
String
+
String
#### pattern @@ -206,7 +206,7 @@ A label is an optional string. A label is always arranged on the left side of th A pattern specifies a regular expression that the input-box's value is checked against on form submission.
**Type**
-
String
+
String
#### placeholder @@ -214,7 +214,7 @@ A pattern specifies a regular expression that the input-box's value is checked a A placeholder is an option string. Specification of a placeholder will generate a `placeholder` attribute for the input tag.
**Type**
-
String
+
String
### Public member functions @@ -239,11 +239,11 @@ AutoConnectRadio(const char* name = "", std::vector const& values = {}, ```
**Parameters**
-
nameThe element name.
-
valuesAn array of values of the radio buttons. Specifies an [std::vector](https://en.cppreference.com/w/cpp/container/vector) object.
-
labelLabel string.
-
orderThe direction to arrange the radio buttons.
-
checkedAn index to be checked in the radio buttons.
+
nameThe element name.
+
valuesAn array of values of the radio buttons. Specifies an [std::vector](https://en.cppreference.com/w/cpp/container/vector) object.
+
labelLabel string.
+
orderThe direction to arrange the radio buttons.
+
checkedAn index to be checked in the radio buttons.
### Public member variables @@ -253,7 +253,7 @@ AutoConnectRadio(const char* name = "", std::vector const& values = {}, The element name.
**Type**
-
String
+
String
#### values @@ -261,7 +261,7 @@ The element name. An array of String type for the radio button options. It is an initialization list can be used. The `#!html ` tags will be generated from each entry in the values.
**Type**
-
std::vector<String>
+
std::vector<String>
#### label @@ -269,18 +269,19 @@ An array of String type for the radio button options. It is an initialization li A label is an optional string. A label will be arranged in the left or top of the radio buttons according to the [order](#order).
**Type**
-
String
+
String
#### order Specifies the direction to arrange the radio buttons. A label will place in the left or the top according to the **_order_**. It is a value of **ACArrange_t** type and accepts one of the following: - -- **`AC_Horizontal`** : Horizontal arrangement. -- **`AC_Vertical`** : Vertical arrangement.
**Type**
-
ACArrange_t
+
ACArrange_t + +- **`AC_Horizontal`** : Horizontal arrangement. +- **`AC_Vertical`** : Vertical arrangement. +
#### checked @@ -288,7 +289,7 @@ Specifies the direction to arrange the radio buttons. A label will place in the Specifies the index number (1-based) of the **values** to be checked. If this parameter is not specified neither item is checked.
**Type**
-
uint8_t
+
uint8_t
### Public member functions @@ -312,7 +313,7 @@ void add(const String& value) Adds an option for the radio button.
**Parameters**
-
valueAn option string to add to the radio button.
+
valueAn option string to add to the radio button.
#### check @@ -323,7 +324,7 @@ void check(const String& value) Indicates the check of the specified option for the radio buttons. You can use the **check** function for checking dynamically with arbitrary of the radio button.
**Parameters**
-
valueAn option string to be checked.
+
valueAn option string to be checked.
#### empty @@ -334,7 +335,7 @@ void empty(const size_t reserve = 0) Clear the array of option strings that AutoConnectRadio has in values. When a **_reserve_** parameter is specified, a vector container of that size is reserved.
**Parameters**
-
reserveReserved size of a container for option strings.
+
reserveReserved size of a container for option strings.
#### operator [ ] @@ -345,7 +346,7 @@ const String& operator[] (const std::size_t n) Returns the option string of the index specified by **_n_**.
**Parameters**
-
nIndex of values array to return.
+
nIndex of values array to return.
#### value @@ -361,6 +362,81 @@ Returns current checked option of the radio buttons. ## AutoConnectSelect +### Constructor + +```cpp +AutoConnectSelect(const char* name = "", std::vector const& options = {}, const char* label = "") +``` +
+
**Parameters**
+
nameThe element name.
+
optionsAn array of options of the select element. Specifies an [std::vector](https://en.cppreference.com/w/cpp/container/vector) object.
+
labelLabel string.
+
+ +### Public member variables + +#### name + +The element name. +
+
**Type**
+
String
+
+ +#### options + +An array of String type for the selection options. It is an initialization list can be used. The `#!html