<!doctype html><htmllang="en"class="no-js"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width,initial-scale=1"><metahttp-equiv="x-ua-compatible"content="ie=edge"><metaname="description"content="ESP8266/ESP32 WLAN configuration at run time with web interface"><linkrel="canonical"href="https://Hieromon.github.io/AutoConnect/acelements.html"><metaname="author"content="Hieromon Ikasamo"><metaname="lang:clipboard.copy"content="Copy to clipboard"><metaname="lang:clipboard.copied"content="Copied to clipboard"><metaname="lang:search.language"content="en"><metaname="lang:search.pipeline.stopwords"content="True"><metaname="lang:search.pipeline.trimmer"content="True"><metaname="lang:search.result.none"content="No matching documents"><metaname="lang:search.result.one"content="1 matching document"><metaname="lang:search.result.other"content="# matching documents"><metaname="lang:search.tokenizer"content="[\s\-]+"><linkrel="shortcut icon"href="assets/images/favicon.png"><metaname="generator"content="mkdocs-1.0.4, mkdocs-material-4.3.1"><title>AutoConnectElements - AutoConnect for ESP8266/ESP32</title><linkrel="stylesheet"href="assets/stylesheets/application.4031d38b.css"><linkrel="stylesheet"href="assets/stylesheets/application-palette.224b79ff.css"><metaname="theme-color"content="#3f51b5"><scriptsrc="assets/javascripts/modernizr.74668098.js"></script><linkhref="https://fonts.gstatic.com"rel="preconnect"crossorigin><linkrel="stylesheet"href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700|Roboto+Mono&display=swap"><style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style><linkrel="stylesheet"href="assets/fonts/material-icons.css"><linkrel="stylesheet"href="css/paragraph.css"><linkrel="stylesheet"href="css/extra.css"><linkrel="stylesheet"href="https://use.fontawesome.com/releases/v5.6.1/css/all.css"><script>window.ga=window.ga||function(){
<h2id="layout-on-a-custom-web-page">Layout on a custom Web page<aclass="headerlink"href="#layout-on-a-custom-web-page"title="Permanent link">¶</a></h2>
<p>The elements of the page created by AutoConnectElements are aligned vertically exclude the <ahref="#autoconnectradio">AutoConnectRadio</a>. 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.</p>
<h2id="form-and-autoconnectelements">Form and AutoConnectElements<aclass="headerlink"href="#form-and-autoconnectelements"title="Permanent link">¶</a></h2>
<p>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 <ahref="#autoconnectsubmit">AutoConnectSubmit</a> using the <strong>POST</strong> method with HTTP. The post method sends the actual form data which is a query string whose contents are the <strong>name</strong> and <strong>value</strong> of AutoConnectElements. You can retrieve the value for the parameter with the sketch from the query string with <ahref="https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#getting-information-about-request-arguments">ESP8266WebServer::arg</a> function or <ahref="https://github.com/Hieromon/PageBuilder#arguments-of-invoked-user-function">PageArgument</a> class of the <ahref="api.html#on">AutoConnect::on</a> handler when the form is submitted.</p>
<h2id="autoconnectelement-a-basic-class-of-elements">AutoConnectElement - <small>A basic class of elements</small><aclass="headerlink"href="#autoconnectelement-a-basic-class-of-elements"title="Permanent link">¶</a></h2>
<p>AutoConnectElement is a base class for other element classes and has common attributes for all elements. It can also be used as a <ahref="#variant-for-autoconnectelements">variant</a> of each element. The following items are attributes that AutoConnectElement has and are common to other elements.</p>
<p>Each element has a name. The <strong>name</strong> is the String data type. You can identify each element by the name to access it with sketches. </p>
<p>The <strong>value</strong> is the string which is a source to generate an HTML code. Characteristics of Value vary depending on the element. The value of AutoConnectElement is native HTML code. A string of value is output as HTML as it is.</p>
<p>The <strong>type</strong> indicates the type of the element and represented as the <em>ACElement_t</em> enumeration type in the sketch. Since AutoConnectElement also acts as a variant of other elements, it can be applied to handle elements collectively. At that time, the type can be referred to by the <ahref="apielements.html#typeof"><strong>typeOf()</strong></a> function. The following example changes the font color of all <ahref="#autoconnecttext">AutoConnectText</a> elements of a custom Web page to gray.</p>
<p>Furthermore, to convert an entity that is not an AutoConnectElement to its native type, you must <ahref="https://en.cppreference.com/w/cpp/language/reinterpret_cast">re-interpret</a> that type with c++. Or, you can be coding the sketch more easily with using the <ahref="apielements.html#ast62"><strong>as<T></strong></a> function.</p>
<p>AutoConnectButton generates an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">button</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"button"</span><spanstyle="color: #f8f8f2">></span></code> tag and locates a clickable button to a custom Web page. Currently AutoConnectButton corresponds only to name, value, an <em>onclick</em> attribute of HTML button tag. An <em>onclick</em> attribute is generated from an <code>action</code> member variable of the AutoConnectButton, which is mostly used with a JavaScript to activate a script.</p>
<p>It is the <code>name</code> of the AutoConnectButton element and matches the name attribute of the button tag. It also becomes the parameter name of the query string when submitted.</p>
<p><strong>action</strong> is String data type and is an <em>onclick</em> attribute fire on a mouse click on the element. It is mostly used with a JavaScript to activate a script.<supid="fnref:1"><aclass="footnote-ref"href="#fn:1"rel="footnote">1</a></sup> For example, the following code defines a custom Web page that copies a content of <code>Text1</code> to <code>Text2</code> by clicking <code>Button</code>.</p>
<p>AutoConnectCheckbox generates an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">input</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"checkbox"</span><spanstyle="color: #f8f8f2">></span></code> tag and a <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">label</span><spanstyle="color: #f8f8f2">></span></code> tag. It places horizontally on a custom Web page by default.</p>
<p>It is the <code>name</code> of the AutoConnectCheckbox element and matches the name attribute of the input tag. It also becomes the parameter name of the query string when submitted.</p>
<p>It becomes a value of the <code>value</code> attribute of an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">input</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"checkbox"</span><spanstyle="color: #f8f8f2">></span></code> tag.</p>
<p>A label is an optional string. A label is always arranged on the right side of the checkbox. Specification of a label will generate an HTML <code><label></code> tag with an <code>id</code> attribute. The checkbox and the label are connected by the id attribute.
Only <iclass="far fa-square"></i> will be displayed if a label is not specified.</p>
<p>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.</p>
<p>AutoConnectFile generates asn HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">input</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"file"</span><spanstyle="color: #f8f8f2">></span></code> tag and a <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">label</span><spanstyle="color: #f8f8f2">></span></code> tag. AutoConnectFile enables file upload from the client through the web browser to ESP8266/ESP32 module. You can select the flash in the module, external SD device or any output destination as the storage of the uploaded file.</p>
<p>It is the <code>name</code> of the AutoConnectFile element and matches the name attribute of the input tag. It also becomes the parameter name of the query string when submitted.</p>
<p>File name to be upload. The value contains the value entered by the client browser to the <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">input</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"file"</span><spanstyle="color: #f8f8f2">></span></code> tag and is read-only. Even If you give a value to the constructor, it does not affect as an initial value like a default file name.</p>
<p>A <code>label</code> is an optional string. A label is always arranged on the left side of the input box. Specification of a label will generate an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">label</span><spanstyle="color: #f8f8f2">></span></code> tag with an id attribute. The input box and the label are connected by the id attribute.</p>
<p>Specifies the destination to save the uploaded file. The destination can be specified the following values in the <em>ACFile_t</em> enumeration type.</p>
<ul>
<li><strong><code>AC_File_FS</code></strong> : Save as the SPIFFS file in flash of ESP8266/ESP32 module.</li>
<li><strong><code>AC_File_SD</code></strong> : Save to an external SD device connected to ESP8266/ESP32 module.</li>
<li><strong><code>AC_File_Extern</code></strong> : Pass the content of the uploaded file to the uploader which is declared by the sketch individually. Its uploader must inherit <ahref="acupload.html#to-upload-to-a-device-other-than-flash-or-sd"><strong>AutoConnectUploadHandler</strong></a> class and implements <em>_open</em>, <em>_write</em> and <em>_close</em> function.</li>
</ul>
<divclass="admonition note">
<pclass="admonition-title">Built-in uploader is ready.</p>
<p>AutoConnect already equips the built-in uploader for saving to the SPIFFS as AC_File_FS and the external SD as AC_File_SD. It is already implemented inside AutoConnect and will store uploaded file automatically.</p>
<p>AutoConnectInput generates an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">input</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"text"</span><spanstyle="color: #f8f8f2">></span></code> tag and a <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">label</span><spanstyle="color: #f8f8f2">></span></code> 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.</p>
<p>It is the <code>name</code> of the AutoConnectInput element and matches the name attribute, the id attribute of the input tag. It also becomes the parameter name of the query string when submitted.</p>
<p>It becomes a string value of the <code>value</code> attribute of an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">input</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"text"</span><spanstyle="color: #f8f8f2">></span></code> tag. The text entered from the custom Web page will be grouped in the query string of the form submission and the string set before accessing the page will be displayed as the initial value.</p>
<p>A <code>label</code> is an optional string. A label is always arranged on the left side of the input box. Specification of a label will generate an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">label</span><spanstyle="color: #f8f8f2">></span></code> tag with an id attribute. The input box and the label are connected by the id attribute.</p>
<p>A <code>pattern</code> specifies a <ahref="https://www.w3schools.com/js/js_regexp.asp">regular expression</a> that the AutoConnectInput element's value is checked against on form submission. If it is invalid, the background color will change, but it will be sent even if the data format does not match. To check whether the entered value matches the pattern, use the <ahref="apielements.html#isvalid">isValid</a> function.</p>
<li>The password that must contain 8 or more characters that are of at least one number, and one uppercase and lowercase letter:<br><code>(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{8,}</code></li>
<p>Host name of Internet:<br><code>(([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])</code></p>
<p>AutoConnectRadio generates few HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">input</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"radio"</span><spanstyle="color: #f8f8f2">></span></code> tags as grouped and the same number of <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">label</span><spanstyle="color: #f8f8f2">></span></code> tags. AutoConnectRadio can keep the value of a radio button as a collection. The grouped values will be placed in the custom Web page to select only one exclusively.</p>
<p>It is the <code>name</code> of the AutoConnectRadio element and matches the name attribute of the input tags. It also becomes the parameter name of the query string when submitted.</p>
<p>A <code>values</code> is an array of String type for the radio button options which as actually <ahref="https://en.cppreference.com/w/cpp/container/vector">std::vector</a>. It is an initialization list can be used. The input tags will be generated from each entry in the values, the amount of which is the same as the number of items in <code>values</code>.</p>
<p>A label is an optional string. A label will be arranged in the left or top of the radio buttons according to the <strong>order</strong>. Specification of a label will generate an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">label</span><spanstyle="color: #f8f8f2">></span></code> tag with an <code>id</code> attribute. The radio buttons and the label are connected by the id attribute.</p>
<p>A <code>order</code> specifies the direction to arrange the radio buttons. It is a value of type <code>ACArrange_t</code> and accepts one of the following:</p>
<p>A <code>checked</code> specifies the index number (1-based) of the <strong>values</strong> to be checked. If this parameter is not specified neither item is checked.</p>
<p>AutoConnectSelect generates an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">select</span><spanstyle="color: #f8f8f2">></span></code> tag (drop-down list) and few <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">option</span><spanstyle="color: #f8f8f2">></span></code> tags.</p>
<p>An <code>options</code> is an array of String type for the options which as actually <ahref="https://en.cppreference.com/w/cpp/container/vector">std::vector</a> for an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">option</span><spanstyle="color: #f8f8f2">></span></code> tag. It is an initialization list can be used. The option tags will be generated from each entry in the options, the amount of which is the same as the number of items in an <code>options</code>.</p>
<p>A <code>label</code> is an optional string. A label is always arranged on the left side of the drop-down list. Specification of a label will generate an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">label</span><spanstyle="color: #f8f8f2">></span></code> tag with an id attribute. The select tag and the label are connected by the id attribute.</p>
<p>AutoConnectSubmit generates an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">input</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"button"</span><spanstyle="color: #f8f8f2">></span></code> tag attached <codeclass="codehilite">onclick</code> attribute. The native code of the <codeclass="codehilite">onclick</code> attribute is the submission of the form with the <strong>POST</strong> method.</p>
<p>It becomes a string of the <code>value</code> attribute of an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">input</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"button"</span><spanstyle="color: #f8f8f2">></span></code> tag. The <code>value</code> will be displayed as a label of the button.</p>
<p>A <code>uri</code> specifies the URI to send form data when the button declared by AutoConnectSubmit is clicked.</p>
<p>The query string of the form data sent with AutoConnectSubmit contains the URI of the page. Its parameter name is <code>_acuri</code>. In Sketch, you can know the called URI by referring to the <code>_acuri</code> parameter with the destination page handler. The actual query string is as follows:</p>
<p>AutoConnectText generates an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">div</span><spanstyle="color: #f8f8f2">></span></code> tag. A <codeclass="codehilite">style</code> attribute will be attached if a <ahref="#style">style</a> parameter is passed.</p>
<small><strong><code>AutoConnectText text("text", "Publishing the WiFi signal strength to MQTT channel. RSSI value of ESP8266 to the channel created on ThingSpeak", "font-family:serif;color:#4682b4;");</code></strong></small></p>
<p>A <code>format</code> 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 <strong>%s</strong> format. (Left and Right justification, width are also valid.)</p>
<h2id="how-to-coding-for-the-elements">How to coding for the elements<aclass="headerlink"href="#how-to-coding-for-the-elements"title="Permanent link">¶</a></h2>
<h3id="declaration-for-the-elements-in-sketches"><iclass="fa fa-edit"></i> Declaration for the elements in Sketches<aclass="headerlink"href="#declaration-for-the-elements-in-sketches"title="Permanent link">¶</a></h3>
<p>Variables of each AutoConnetElement can be declared with macros. By using the macros, you can treat element name that is String type as variable in sketches.<supid="fnref:2"><aclass="footnote-ref"href="#fn:2"rel="footnote">2</a></sup></p>
<h3id="variant-for-autoconnectelements"><iclass="fa fa-edit"></i> Variant for AutoConnectElements<aclass="headerlink"href="#variant-for-autoconnectelements"title="Permanent link">¶</a></h3>
<p>Some AutoConnectAux APIs specify AutoConnectElements as an argument. There are also functions that return a pointer to AutoConnectElements. AutoConnectElement behaves as a variant type of each element class to make these interfaces a single. Use <ahref="https://en.cppreference.com/w/cpp/language/reinterpret_cast">reinterpret_cast</a> to cast from a variant pointer to an Actual type pointer of AutoConnectElements.</p>
<p>JavaScript can be inserted into a custom Web page using AutoConnectElement. <aclass="footnote-backref"href="#fnref:1"rev="footnote"title="Jump back to footnote 1 in the text">↩</a></p>
</li>
<liid="fn:2">
<p>The square brackets in the syntax are optional parameters, the stroke is a selection parameter, the bold fonts are literal. <aclass="footnote-backref"href="#fnref:2"rev="footnote"title="Jump back to footnote 2 in the text">↩</a></p>
