@ -96,7 +96,7 @@ Full documentation is available on https://Hieromon.github.io/AutoConnect, some
### [0.9.7] Feb. 25, 2019
- Fixed crash in some environments. Thank you @ageurtse
- Supports AutoConnect menu extention by user sketch with **AutoConnectAux**.
- Supports AutoConnect menu extension by user sketch with **AutoConnectAux**.
- Supports loading and saving of user-defined parameters with JSON format.
- Improved the WiFi connection sequence at the first WiFi.begin. Even if **AutoConnectConfig::autoReconnect** is disabled when SSID and PSK are not specified, it will use the information of the last established access point. The autoReconnect option will achieve trying the connect after a previous connection failed.
- Supports the **AutoConnectConfig::immediateStart** option and immediately starts the portal without first trying WiFi.begin. You can start the captive portal at any time in combination with the **AutoConnectConfig::autoRise** option.
@ -13,13 +13,11 @@ Representative HTML elements for making the custom Web page are provided as Auto
## Layout on a custom Web page
You can specify the direction to arrange the radio buttons as [**AutoConnectRadio**](#autoconnectradio) vertically or horizontally. Other elements are arranged vertically in the order of addition to AutoConnectAux. This basic layout depends on the CSS of the AutoConnect menu so it can not be changed drastically.
The elements of the page created by AutoConnectElements are aligned vertically exclude the [AutoConnectRadio](#autoconnectradio). You can specify the direction to arrange the radio buttons as AutoConnectRadio vertically or horizontally. This basic layout depends on the CSS of the AutoConnect menu so you can not change drastically.
## Form and AutoConnectElements
All AutoConnectElements placed on a custom Web page are included in one form. Its form is fixed and created by AutoConnect. The form's value (usually the text or checkbox you entered) is sent by [AutoConnectSubmit](#autoconnectsubmit) using the POST method.
**name** and **value** of each AutoConnectElement which own form-data are reflected in the query string when the custom Web page was sent. You can retrieve the value in the sketch as the parameter's value of the query string with [**ESP8266WebServer::arg**](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#getting-information-about-request-arguments) function or **PageArgument** class of [**AutoConnect::on**](api.md#on) handler when the form is submitted.
All AutoConnectElements placed on custom web pages will be contained into one form. Its form is fixed and created by AutoConnect. The form value (usually the text or checkbox you entered) is sent by [AutoConnectSubmit](#autoconnectsubmit) using the **POST** method with HTTP. The post method sends the actual form data which is a query string whose contents are the **name** and **value** of AutoConnectElements. You can retrieve the value for the parameter with the sketch from the query string with [ESP8266WebServer::arg](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#getting-information-about-request-arguments) function or [PageArgument](https://github.com/Hieromon/PageBuilder#arguments-of-invoked-user-function) class of the [AutoConnect::on](api.md#on) handler when the form is submitted.
## AutoConnectElement - <small>A basic class of elements</small>
@ -76,7 +74,7 @@ Furthermore, to convert an entity that is not an AutoConnectElement to its nativ
## AutoConnectButton
AutoConnectButton generates an HTML `#!html <button type="button">` tag and locates a clickable button to a custom Web page. Currently AutoConnectButton corresponds only to name, value, an onclick attribute of HTML button tag. An onclick attribute is generated from an `action` member variable of the AutoConnectButton, which is mostly used with a JavaScript to activate a script.
AutoConnectButton generates an HTML `#!html <button type="button">` tag and locates a clickable button to a custom Web page. Currently AutoConnectButton corresponds only to name, value, an *onclick* attribute of HTML button tag. An *onclick* attribute is generated from an `action` member variable of the AutoConnectButton, which is mostly used with a JavaScript to activate a script.
@ -99,7 +97,7 @@ It becomes a value of the `value` attribute of an HTML button tag.
### <iclass="fa fa-caret-right"></i> action
**action** is String data type and is an onclick attribute fire on a mouse click on the element. It is mostly used with a JavaScript to activate a script.[^1] For example, the following code defines a custom Web page that copies a content of `Text1` to `Text2` by clicking `Button`.
**action** is String data type and is an *onclick* attribute fire on a mouse click on the element. It is mostly used with a JavaScript to activate a script.[^1] For example, the following code defines a custom Web page that copies a content of `Text1` to `Text2` by clicking `Button`.
[^1]:JavaScript can be inserted into a custom Web page using AutoConnectElement.
@ -185,7 +183,7 @@ A `pattern` specifies a [regular expression](https://www.w3schools.com/js/js_reg
- IP address:<br>`(([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])`
- Host name of the internet:<br>`(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])`
- Host name of Internet:<br>`(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])`
- Date (MM/DD/YYYY) as range 1900-2099:<br>`(0[1-9]|1[012])[- \/.](0[1-9]|[12][0-9]|3[01])[- \/.](19|20)\d\d`
@ -112,7 +112,7 @@ AutoConnect supports reading the custom Web page definitions written in JSON and
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 [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 section [*JSON document structure for AutoConnectAux*](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.
@ -466,7 +466,7 @@ 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.
@ -496,11 +496,20 @@ Sketches can update the attributes of AutoConnectElements with two approaches. A
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.
For example, the combination of the sketch and JSON document as follows updates only the style while keeping Caption (ie. "Hello, world") as AutoConnectText value.
<iclass="fa fa-code"></i> The sketch (part of code)
<iclass="fab fa-js-square"></i> External JSON document for the below sketch to modify the text style.
<iclass="fa fa-eye"></i> It's shown as like:<spanstyle="margin-left:14px;width:272px;height:118px;border:1px solid lightgray;"><imgalign="top"width="270"src="./images/acow.png"></span>
### <iclass="far fa-check-square"></i> Check data against on submission
@ -559,11 +561,13 @@ By giving a [pattern](apielements.md#pattern) to [AutoConnectInput](apielements.
### <iclass="fa fa-exchange"></i> Convert data to actually type
The values in the AutoConnectElements field of the custom Web page are all typed as String. A sketch needs to be converted to an actual data type if the data type required for sketch processing is not a String type. For the typical data type conversion method, refer to section [*Tips for data conversion*](datatips.md#convert-autoconnectelements-value-to-actual-data-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().
AutoConnectAux and AutoConnectElements must live while the custom Web pages are available. 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().
AutoConnect can handle custom Web pages prepared by user sketches individually. Custom Web pages are displayed in the [AutoConnect menu](menu.md) and can be used from there. It can also have input-output parameters and handle it with sketches. For example, you can program some sketches that publish messages by entering the URI or unique ID of the MQTT broker on a custom page. You do not need to code the processing to handle the web page, it retrieves the input parameters and passes to the MQTT broker connection API is only.
AutoConnect can handle custom Web pages prepared by user sketches individually. Custom Web pages can be integrated into the AutoConnect menu and executed as menu items and can have input-output parameters and handle them.
For example, you can program some sketches that publish messages by entering the URI or unique ID of the MQTT broker on a custom page. You do not need to code the processing to handle the web page. It retrieves the input parameters and passes to the MQTT broker connection API is only.
## How it works
Custom Web pages are dynamically created by AutoConnect. The Classes and APIs necessary for dynamic creation are provided. [**AutoConnectAux**](apiaux.md#autoconnectaux) is an object dependent on AutoConnect, which provides an easy way to incorporate custom Web pages like the one on the right figure into AutoConnect. The elements that make up a custom web page are provided as an [**AutoConnectElement**](acelements.md) class. Furthermore, an input box, a check box, a submit button, etc. are implemented by classes derived from AutoConnectElement.
AutoConnect creates the custom Web pages dynamically at runtime. Sketch describes the custom Web pages using classes and APIs necessary for dynamic creation which are [**AutoConnectAux**](apiaux.md#autoconnectaux) and the variant of [**AutoConnectElements**](acelements.md). AutoConnectAux is an object dependent on AutoConnect, which provides an easy way to incorporate custom Web pages into AutoConnect like the one on the right figure. The elements make up a custom Web page are provided as an AutoConnectElement class.
Furthermore, an input box, a check box, a submit button, etc. are implemented by classes derived from AutoConnectElement.
AutoConnectAux is a container for AutoConnectElements. To make a custom Web page, create elements that make up the page and put it in the AutoConnectAux object. Joining its AutoConnectAux object to AutoConnect will integrate the custom Web page into the AutoConnect menu.
@ -66,13 +70,14 @@ You can create multiple custom Web pages and specify pages that can be called fr
So, the basic procedure for handling of the custom Web pages is as follows:
1. Create or define AutoConnectAux.
1. Create or define [AutoConnectAux](apiaux.md#autoconnectaux).
2. Create or define [AutoConnectElement(s)](acelements.md).
3. Add [AutoConnectElement(s)](acelements.md) to AutoConnectAux.
4. Create more AutoConnectAux containing [AutoConnectElement(s)](acelements.md), if necessary.
5. Register the request handlers for the custom Web pages.
5. [Register](api.md#on) the request handlers for the custom Web pages.
6. [Join](api.md#join) prepared AutoConnectAux(s) to AutoConnect.
## Passing parameters with sketches and custom Web pages
A sketch can access variables of [AutoConnectElements](acelements.md) on the custom Web page. The value entered into the AutoConnectElements is stored to the [member variables](acelements.md#form-and-autoconnectelements) of the element by AutoConnect whenever GET / POST transmission occurs. Your sketches can get these values with the request handler which will be registered by [AutoConnect::on](api.md#on) function. And if you assign a value to an element before a request to the page occurs, its value will appear as the initial value when the page is displayed. The details are explained in the [Custom field data handling](achandling.md#custom-field-data-handling) section.
A sketch can access variables of [AutoConnectElements](acelements.md) on the custom Web page. The value entered into the AutoConnectElements is stored to the [member variables](acelements.md#form-and-autoconnectelements) of the element by AutoConnect whenever GET / POST transmission occurs. Your sketches can get these values with the request handler which will be registered by [AutoConnect::on](api.md#on) function. And if you assign a value to an element before a request to the page occurs, its value will appear as the initial value when the page is displayed. The details are explained in section [*Custom field data handling*](achandling.md#custom-field-data-handling).
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]
You can embed custom Web pages written in [**JSON**](https://www.json.org/index.html) into AutoConnect without AutoConnectAux & AutoConnectElements declaration. Custom Web page declaration by JSON can embed in the sketch as a fixed string or can store in the external file such as SPIFFS for stream loading. Also, you can also load and save AutoConnectElements objects individually.[^1]
[^1]:Loading and saving AutoConnect parameters adopt this method.
By providing the following JSON document to AutoConnect, you can include the custom Web page as the bellow:
By providing the following JSON document to AutoConnect, you can include the custom Web page like the below:
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 contain the custom Web page multiple. You can further reduce the sketch process by loading multiple pages of JSON document at once.
!!! 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.
@ -18,7 +18,7 @@ A JSON document for AutoConnect can also contain declarations of multiple custom
### <iclass="fa fa-caret-right"></i> JSON document structure for AutoConnectAux
An AutoConnectAux is described by a JSON object. The elements that make up an object are as follows:
AutoConnectAux will configure custom Web pages with JSON objects. The elements that make up the object are as follows:
```
{
@ -101,7 +101,7 @@ You can put declarations of multiple custom Web pages in one JSON document. In t
### <iclass="fa fa-caret-right"></i> JSON object for AutoConnectElements
AutoConnectElements in JSON description are described as an array in the `element` with arguments of each [constructor](acelements.md#constructor).
JSON description for AutoConnectElements describes as an array in the *element* with arguments of [each constructor](acelements.md#constructor).
```
{
@ -128,7 +128,7 @@ AutoConnectElements in JSON description are described as an array in the `elemen
## Convert AutoConnectElements value to actual data type
The value of the AutoConnectElements field of the custom Web pages consists of String type for all. Sketches will need to convert them to the actual data type. And then if the data type required for processing in the sketch is not a String type, it is necessary to convert to String type when storing to the AutoConenctElements value.
The values in the AutoConnectElements field of the custom Web page are all typed as String. A sketch needs to be converted to an actual data type if the data type required for sketch processing is not a String type.
AutoConnect library does not provide the data conversion utility, and its function depends on Arduino language functions or functions of the type class. However, commonly used data conversion methods are generally similar.
The AutoConnect library does not provide the data conversion utility, and its function depends on Arduino language functions or functions of the type class. However, commonly used data conversion methods are generally similar.
Here, represent examples the typical method for the data type conversion for the AutoConnectElements value of custom Web pages.
@ -59,11 +59,11 @@ input.value = ip.toString();
## Validation for the value
In order for data to be correctly converted from a string, the input data must be consistent with the format. How to implement strict validation in sketches depends on various perspectives and the power of tiny devices is not enough to implement a complete lexical analysis. But you can reduce the burden for data verification using the **pattern** of AutoConnectInput.
To convert input data correctly from the string, it must match its format. The validation implementation with sketches depends on various perspectives. Usually, the tiny devices have no enough power for the lexical analysis completely. But you can reduce the burden for data verification using the [**pattern**](achandling.md#check-data-against-on-submission) of AutoConnectInput.
By giving a [**pattern**](achandling.md#check-data-against-on-submission) to [AutoConnectInput](apielements.md#pattern), you can find errors in data format 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). If the value during input of AutoConnectInput does not match the regular expression specified by the pattern, its background color changes to pink. Refer to [Handling the custom Web pages](achandling.md#check-data-against-on-submission) section.
By giving a [pattern](acelements.md#pattern) to [AutoConnectInput](apielements.md#pattern), you can find errors in data format while typing in custom Web pages. Specifying the input data rule as a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) will validate the type match during input. If there is an error in the format during input, the background color of the field will change to pink. Refer to section [Handling the custom Web pages](achandling.md#check-data-against-on-submission).
However, input data will be transmitted even if the value does not match the pattern. To check the value with the sketch, using the [**AutoConnectInput::isValid**](apielements.md#isvalid) function. The isValid function validates whether the value member variable matches a pattern and returns true or false.
However, input data will be transmitted even if the value does not match the pattern. Sketches require the validation of the received data. You can use the [AutoConnectInput::isValid](apielements.md#isvalid) function to validate it. The isValid function validates whether the value member variable matches a pattern and returns true or false.
```cpp hl_lines="16 47"
#include<ESP8266WiFi.h>
@ -139,31 +139,31 @@ void loop() {
Here, represent examples the typical regular expression for the input validation.
### <iclass="far fa-check-square"></i> URL
### <imgsrc="./images/regexp.png"align="top"> URL
```
^\w+([-+.]\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*$
```
### <iclass="far fa-check-square"></i> DNS hostname
### <imgsrc="./images/regexp.png"align="top"> DNS hostname
You can extend the AutoConnect menu to match legacy sketches and according to the procedure described in the [Advanced Usage section](advancedusage.md#cast-the-legacy-html-pages-as-the-add-on-menu-items).
You can extend the AutoConnect menu to match legacy sketches and according to the procedure described in the sectio [*Advanced Usage*](advancedusage.md#cast-the-legacy-html-pages-as-the-add-on-menu-items).
@ -10,7 +10,7 @@ The sketch can display the [AutoConnect menu](menu.md) by following three patter
: It is the most basic menu for only connecting WiFi. Sketch can automatically display this menu with the basic call sequence of the AutoConnect API which invokes [AutoConnect::begin](api.md#begin) and [AutoConnect::handleClient](api.md#handleclient).
<iclass="fa fa-desktop"></i> **Extra menu with custom Web pages which is consisted by [AutoConnectElements](acelements.md)**
: It is an extended menu that appears when the sketch consists of the custom Web pages with [AutoConnectAux](acintro.md#how-it-works) and AutoConnectElements. Refer to [Custom Web pages section](acintro.md#custom-web-pages-in-autoconnect-menu).
: It is an extended menu that appears when the sketch consists of the custom Web pages with [AutoConnectAux](acintro.md#how-it-works) and AutoConnectElements. Refer to section [*Custom Web pages section*](acintro.md#custom-web-pages-in-autoconnect-menu).
<iclass="fa fa-desktop"></i> **Extra menu which contains legacy pages**
: It is for the legacy sketches using the **on** handler of ESP8266WebServer/WebServer(for ESP32) class natively and looks the same as the extra menu as above.
Hieromon Ikasamo
5 years ago
