- [AutoConnectInput](#autoconnectinput): Labeled text input box
- [AutoConnectRadio](#autoconnectradio): Labeled radio button
- [AutoConnectSelect](#autoconnectselect): Selection list
@ -63,6 +64,7 @@ The enumerators for *ACElement_t* are as follows:
- AutoConnectButton: **AC_Button**
- AutoConnectCheckbox: **AC_Checkbox**
- AutoConnectElement: **AC_Element**
- AutoConnectFile: **AC_File**
- AutoConnectInput: **AC_Input**
- AutoConnectRadio: **AC_Radio**
- AutoConnectSelect: **AC_Select**
@ -147,6 +149,29 @@ Only <i class="far fa-square"></i> will be displayed if a label is not specified
A checked is a Boolean value and indicates the checked status of the checkbox. The value of the checked checkbox element is packed in the query string and sent.
## AutoConnectFile
AutoConnectFile generates asn HTML `#!html <input type="file">` tag and a `#!html <label>` tag.
AutoConnectInput generates an HTML `#!html <input type="text">` tag and a `#!html <label>` tag. It can also have a placeholder. The value of the input box is passed to the destination in the query string and can be retrieved programmatically. You can also update from the sketches.
@ -303,7 +328,7 @@ AutoConnectText generates an HTML `#!html <div>` tag. A `#!html style` attribute
@ -318,6 +343,10 @@ It becomes content and also can contain the native HTML code, but remember that
A `style` specifies the qualification style to give to the content and can use the style attribute format as it is.
### <iclass="fa fa-caret-right"></i> format
A `format` is a pointer to a null-terminated multibyte string specifying how to interpret the value. It specifies the conversion format when outputting values. The format string conforms to C-style printf library functions, but depends on the espressif sdk implementation. The conversion specification is valid only in **%s** format. (Left and Right justification, width are also valid.)
## How to coding for the elements
### <iclass="fa fa-edit"></i> Declaration for the elements in Sketches
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.
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 and specify its type <T\> toanargumentofthegetElement.Atypeof<T\> canbespecifiedasfollows.
To retrieve an AutoConnectElement by specifying its type, use the following method.
```cpp
AutoConnectAux aux;
@ -101,18 +115,29 @@ AutoConenctText& text = aux->getElement<AutoConnectText>("caption"); // Cast to
Serial.println(text.value);
```
You can also use the [operator **`[]`** of AutoConnectAux](apiaux.md#operator) as another way to get the desired element. An operator **`[]`** is a shortcut for [getElement](apiaux.me#getelement) function with the reference casting and makes simplify the code. Its argument is the name of the element to be acquired similarly to getElement function. For example, the following sketch code returns the same as reference of AutoConnectText element as `caption`.
You can also use the [operator **`[]`** of AutoConnectAux](apiaux.md#operator) as another way to get the desired element. An operator **`[]`** is a shortcut for [getElement](apiaux.md#getelement) function with the reference casting and makes simplify the sketch code and treats like an array with the elements placed on a custom Web page. Its argument is the name of the element to be acquired similarly to getElement function. In the sketch, by combining the [**AutoConnectElement::as<T\>**](apielements.md#ast62) function with the operator `[]`, you can access the AutoConnectElements reference according to its actual type. For example, the following sketch code returns the same as a reference of AutoConnectText element as the`caption`.
!!! note "Need cast to convert to the actual type"
An operator `[]` returns a referene of an AutoConnectElement. It is necessary to convert the type according to the actual element type.
An operator `[]` returns a referene of an AutoConnectElement. It is necessary to convert the type according to the actual element type with [AutoConnectElement::as<T\>](apielements.md#ast62) functon.
To get all the AutoConnectElements in 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.
Get a registered AutoConnectElement as specified name. If **T** is specified as an actual type of AutoConnectElements, it returns a reference to that instance.
<dlclass="apidl">
<dt>**Parameters**</dt>
<dd><spanclass="apidef">T</span><spanclass="apidesc">Actual 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).</span></dd>
<dd><spanclass="apidef">T</span><spanclass="apidesc">Actual type name of AutoConnectElements as [AutoConnectButton](apielements.md#autoconnectbutton), [AutoConnectCheckbox](apielements.md#autoconnectcheckbox), [AutoConnectElement](apielements.md#autoconnectelement), [AutoConnectFile](apielements.md#autoconnectfile), [AutoConnectInput](apielements.md#autoconnectinput), [AutoConnectRadio](apielements.md#autoconnectradio), [AutoConnectSelect](apielements.md#autoconnectselect), [AutoConnectSubmit](apielements.md#autoconnectsubmit), [AutoConnectText](apielements.md#autoconnecttext).</span></dd>
<dd><spanclass="apidef">name</span><spanclass="apidesc">Name of the AutoConnectElements to be retrieved.</span></dd>
<dt>**Return value**</dt><dd>A reference of the AutoConnectElements. If a type is not specified returns a pointer.</dd>
</dl>
@ -182,6 +182,17 @@ Register the handler function of the AutoConnectAux.
Called even before generating HTML and after generated.</dd>
Register the upload handler of the AutoConnectAux.
<dlclass="apidl">
<dt>**Parameters**</dt>
<dd><spanclass="apidef">uploadFunc</span><spanclass="apidesc">A function that behaves when request to upload with the AutoConnectAux page. UploadFuncT type is defined by the following declaration.<pclass="apidesc">`void(const String&, const HTTPUpload&)`</p></span></dd>
@ -159,6 +159,103 @@ Returns type of AutoConnectElement.
<dd>AC_Element</dd>
</dl>
#### <iclass="fa fa-caret-right"></i> as<T\>
```cpp
AutoConnectElement& as<T>(void)
```
Casts the reference to the AutoConnectElement the specified type.
<dlclass="apidl">
<dt>**Parameters**</dt>
<dd><spanclass="apidef">T</span><spanclass="apidesc">The element type. AutoConnectElements type such as [AutoConnectButton](apielements.md#autoconnectbutton), [AutoConnectCheckbox](apielements.md#autoconnectcheckbox), [AutoConnectFile](apielements.md#autoconnectfile), [AutoConnectInput](apielements.md#autoconnectinput), [AutoConnectRadio](apielements.md#autoconnectradio), [AutoConnectSelect](apielements.md#autoconnectselect), [AutoConnectSubmit](apielements.md#autoconnectsubmit), [AutoConnectText](apielements.md#autoconnecttext).</span></dd>
<dt>**Return value**</dt>
<dd>A reference to the AutoConnectElement with actual type.</dd>
</dl>
## AutoConnectFile
### <iclass="fa fa-code"></i> Constructor
```cpp
AutoConnectFile(const char* name = "", const char* value = "", const char* label = "", const ACFile_t store = AC_File_FS)
```
<dlclass="apidl">
<dt>**Parameters**</dt>
<dd><spanclass="apidef">name</span><spanclass="apidesc">The element name.</span></dd>
<dd><spanclass="apidef">value</span><spanclass="apidesc">File name to be upload.</span></dd>
A label is an optional string. A label is always arranged on the left side of the file input box. Specification of a label will generate an HTML `#!html <label>` tag with an id attribute. The file input box and the label are connected by the id attribute.
Specifies the save destination of the uploaded file. You can use the built-in uploader to save uploaded file to the flash of the ESP8266/ESP32 module or external SD media without writing a dedicated sketch code. It also supports saving to any destination using a custom uploader that inherits from the AutoConnectUploadHandler class.
- **`AC_File_FS`** : Save the uploaded file to SPIFFS in the flash.
- **`AC_File_SD`** : Save the uploaded file to SD.
- **`AC_File_Ext`** : Save the file using your own upload handler.
</span></dd>
</dl>
#### <iclass="fa fa-caret-right"></i> mimeType
The mime type of the upload file which included as Media type in the http post request. Set by the client (usually the browser) that requested the upload. It is determined by the file type as `application/octet-stream`, `text` etc. which is described in [IANA Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml).
The [PageBuilder](https://github.com/Hieromon/PageBuilder) library to build HTML for ESP8266WebServer is needed.
To install the PageBuilder library into your Arduino IDE, you can use the *Library Manager*. Select the board of ESP8266 series in the Arduino IDE, open the library manager and search keyword '**PageBuilder**' with the topic '**Communication**', then you can see the *PageBuilder*. The latest version is required **1.3.2****later**.[^1]
To install the PageBuilder library into your Arduino IDE, you can use the *Library Manager*. Select the board of ESP8266 series in the Arduino IDE, open the library manager and search keyword '**PageBuilder**' with the topic '**Communication**', then you can see the *PageBuilder*. The latest version is required **1.3.3****later**.[^1]
[^1]:Since AutoConnect v0.9.8, PageBuilder v1.3.3 later is required.
By adding the [ArduinoJson](https://github.com/bblanchon/ArduinoJson) library, AutoConnect will be able to handle the [**custom Web pages**](acintro.md) described with JSON. With AutoConnect v0.9.7 you can insert user-owned web pages that can consist of representative HTML elements as styled TEXT, INPUT, BUTTON, CHECKBOX, SELECT, SUBMIT and invoke them from the AutoConnect menu. These HTML elements can be added by sketches using the AutoConnect API. Further it possible importing the custom Web pages declarations described with JSON which stored in PROGMEM, SPIFFS, or SD. [ArduinoJson version 5](https://arduinojson.org/v5/doc/) is required to use this feature.[^2]
By adding the [ArduinoJson](https://github.com/bblanchon/ArduinoJson) library, AutoConnect will be able to handle the [**custom Web pages**](acintro.md) described with JSON. With AutoConnect v0.9.7 you can insert user-owned web pages that can consist of representative HTML elements as styled TEXT, INPUT, BUTTON, CHECKBOX, SELECT, SUBMIT and invoke them from the AutoConnect menu. These HTML elements can be added by sketches using the AutoConnect API. Further it possible importing the custom Web pages declarations described with JSON which stored in PROGMEM, SPIFFS, or SD. [ArduinoJson](https://arduinojson.org/) is required to use this feature.[^2] AutoConnect can work with ArduinoJson both [version 5](https://arduinojson.org/v5/doc/) and [version 6](https://arduinojson.org/v6/doc/).
[^2]:Using the AutoConnect API natively allows you to sketch custom Web pages without JSON.
!!! info "AutoConnect supports ArduinoJson version 5 only"
ArduinoJson version 6 is just released, Arduino Library Manager installs the ArduinoJson version 6 by default. Open the Arduino Library Manager and make sure that ArduinoJson version 5 is installed.
### Install the AutoConnect
Clone or download from the [AutoConnect GitHub repository](https://github.com/Hieromon/AutoConnect).
Several parameters as follows of [AutoConnectConfig](apiconfig.md) affect the behavior of [AutoConnect::begin](api.md#begin) function. Each parameter affects the behaves in interacted order with the priority and apply to the logic sequence of AutoConnect::begin.
Several parameters as follows of [AutoConnectConfig](apiconfig.md) affect the behavior of [AutoConnect::begin](api.md#begin) function. Each parameter affects the behaves in interacted order with the priority and apply to the logic sequence of [AutoConnect::begin](api.md#begin).
- [immediateStart](apiconfig.md#immediatestart) : The captive portal start immediately, without first WiFi.begin.
- [autoReconenct](apiconfig.md#autoreconnect) : Attempt re-connect with past SSID by saved credential.
@ -11,14 +11,13 @@ You can use these parameters in combination with sketch requirements and need to
<imgalign="center"src="images/process_begin.svg">
For example, AutoConnect::begin will not exits without the **portalTimeout** while the connection not establishes, but WebServer will start to work. A DNS server that detects the probe of the captive portal is also effective. So, your sketch may work seemingly, but it will close with inside a loop of the AutoConnect::begin function. Especially when invoking AutoConnect::begin in the **setup()**, execution control does not pass to the **loop()**.
For example, [AutoConnect::begin](api.md#begin) will not exits without the [**portalTimeout**](apiconfig.md#portaltimeout) while the connection not establishes, but WebServer will start to work. A DNS server that detects the probe of the captive portal is also effective. So, your sketch may work seemingly, but it will close with inside a loop of the [AutoConnect::begin](api.md#begin) function. Especially when invoking [AutoConnect::begin](api.md#begin) in the **setup()**, execution control does not pass to the **loop()**.
As different scenes, you may use the **immediateStart** effectively. Equipped the external switch to activate the captive portal with the ESP module, combined with the **portalTime** and the **retainPortal** it will become WiFi active connection feature. You can start AutoConnect::begin at any point in the **loop()**, which allows your sketch can behave both the offline mode and the online mode.
As different scenes, you may use the [**immediateStart**](apiconfig.md#immediatestart) effectively. Equipped the external switch to activate the captive portal with the ESP module, combined with the [**portalTime**](apiconfig.md#portaltimeout) and the [**retainPortal**](apiconfig.md#retainportal) it will become WiFi active connection feature. You can start [AutoConnect::begin](api.md#begin) at any point in the **loop()**, which allows your sketch can behave both the offline mode and the online mode.
The **retainPortal** option allows the DNS server to continue operation after exiting from AutoConnect::begin. AutoConnect traps captive portal detection from the client and redirects it to the AutoConnect menu. That trap will answer all unresolved addresses with SoftAP's IP address. If the URI handler for the source request is undefined, it returns a 302 response with `SoftAPIP/_ac` to the client. This is the mechanism of AutoConnect's captive portal. Captive portal probes will frequently occur while you are attempting on the client device's WiFi connection Apps and these implementations are varied each OS, so it not realistic to identify all probing URIs. Therefore, while retainPortal is enabled, it is not preferable to executing the sketch under the WiFi connection Apps on the client device. (Probably not work correctly) You need to exit from the WiFi connection Apps once.
The [**retainPortal**](apiconfig.md#retainportal) option allows the DNS server to continue operation after exiting from [AutoConnect::begin](api.md#begin). AutoConnect traps captive portal detection from the client and redirects it to the AutoConnect menu. That trap will answer all unresolved addresses with SoftAP's IP address. If the URI handler for the source request is undefined, it returns a 302 response with `SoftAPIP/_ac` to the client. This is the mechanism of AutoConnect's captive portal. Captive portal probes will frequently occur while you are attempting on the client device's WiFi connection Apps and these implementations are varied each OS, so it not realistic to identify all probing URIs. Therefore, while retainPortal is enabled, it is not preferable to executing the sketch under the WiFi connection Apps on the client device. (Probably not work correctly) You need to exit from the WiFi connection Apps once.
Please consider these kinds of influence when you make sketches.
!!! info "The AutoConnect::begin 3rd parameter"
Another parameter as the [3rd parameter](api.md#begin) of AutoConnect::begin related to timeout constrains the connection wait time after WiFi.begin. It is the **CONNECTED** judgment of the above chart that it has an effect.
Hieromon Ikasamo
5 years ago