<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>
<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>You can specify the direction to arrange the radio buttons as<ahref="#autoconnectradio"><strong>AutoConnectRadio</strong></a> 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.</p>
<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>
<h2id="form-and-autoconnectelements">Form and AutoConnectElements<aclass="headerlink"href="#form-and-autoconnectelements"title="Permanent link">¶</a></h2>
<p>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 <ahref="#autoconnectsubmit">AutoConnectSubmit</a> using the POST method.</p>
<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>
<p><strong>name</strong> and <strong>value</strong> 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 <ahref="https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#getting-information-about-request-arguments"><strong>ESP8266WebServer::arg</strong></a> function or <strong>PageArgument</strong> class of <ahref="api.html#on"><strong>AutoConnect::on</strong></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>
<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>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>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++.</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++.</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 onclick attribute of HTML button tag. An onclick 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>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><strong>action</strong> 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.<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><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>Host name of the 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>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>
</li>
</li>
<li>
<li>
<p>Date (MM/DD/YYYY) as range 1900-2099:<br><code>(0[1-9]|1[012])[- \/.](0[1-9]|[12][0-9]|3[01])[- \/.](19|20)\d\d</code></p>
<p>Date (MM/DD/YYYY) as range 1900-2099:<br><code>(0[1-9]|1[012])[- \/.](0[1-9]|[12][0-9]|3[01])[- \/.](19|20)\d\d</code></p>
<h3id="loading-autoconnectaux-autoconnectelements-with-json"><iclass="fa fa-upload"></i> Loading AutoConnectAux & AutoConnectElements with JSON<aclass="headerlink"href="#loading-autoconnectaux-autoconnectelements-with-json"title="Permanent link">¶</a></h3>
<h3id="loading-autoconnectaux-autoconnectelements-with-json"><iclass="fa fa-upload"></i> Loading AutoConnectAux & AutoConnectElements with JSON<aclass="headerlink"href="#loading-autoconnectaux-autoconnectelements-with-json"title="Permanent link">¶</a></h3>
<p>To load a JSON document as AutoConnectAux use the <ahref="api.html#load"><strong>AutoConnect::load</strong></a> function and load the JSON document of each AutoConnectElement using the <ahref="apiaux.html#loadelement"><strong>AutoConnectAux::loadElement</strong></a> function. Although the functions of both are similar, the structure of the target JSON document is different.</p>
<p>To load a JSON document as AutoConnectAux use the <ahref="api.html#load"><strong>AutoConnect::load</strong></a> function and load the JSON document of each AutoConnectElement using the <ahref="apiaux.html#loadelement"><strong>AutoConnectAux::loadElement</strong></a> function. Although the functions of both are similar, the structure of the target JSON document is different.</p>
<p>The <ahref="apiaux.html#load">AutoConnect::load</a> 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 <ahref="acjson.html#json-document-structure-for-autoconnectaux"><strong>here</strong></a>.</p>
<p>The <ahref="apiaux.html#load">AutoConnect::load</a> 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 <ahref="acjson.html#json-document-structure-for-autoconnectaux"><em>JSON document structure for AutoConnectAux</em></a>.</p>
<p>The <ahref="apiaux.html#loadelement">AutoConnectAux::loadElement</a> function loads the elements individually into an AutoConnectAux object. The structure of its supplying JSON document is not AutoConnectAux. It must be a <ahref="acjson.html#json-object-for-autoconnectelements">JSON structure for AutoConnectElement</a>, but you can specify an array.</p>
<p>The <ahref="apiaux.html#loadelement">AutoConnectAux::loadElement</a> function loads the elements individually into an AutoConnectAux object. The structure of its supplying JSON document is not AutoConnectAux. It must be a <ahref="acjson.html#json-object-for-autoconnectelements">JSON structure for AutoConnectElement</a>, but you can specify an array.</p>
<divclass="codehilite"style="background: #272822"><prestyle="line-height: 125%"><span></span><spanstyle="color: #75715e">// AutoConnectAux as a custom Web page.</span>
<divclass="codehilite"style="background: #272822"><prestyle="line-height: 125%"><span></span><spanstyle="color: #75715e">// AutoConnectAux as a custom Web page.</span>
@ -1418,17 +1418,17 @@ ESP8266WebServer class will parse the query string and rebuilds its arguments wh
</pre></div>
</pre></div>
<p>Also, you can choose another way to access arguments without going through the ESP8266WebServer class. The <ahref="https://github.com/Hieromon/PageBuilder#arguments-of-invoked-user-function">PageArgument</a> 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 <ahref="#get-autoconnectelement-from-the-autoconnectaux">AutoConnectAux::getElement</a> function. The following sketch code replaces the above example with JSON and PageArgument, and its behaves is equivalent basically to the above sketch.</p>
<p>Also, you can choose another way to access arguments without going through the ESP8266WebServer class. The <ahref="https://github.com/Hieromon/PageBuilder#arguments-of-invoked-user-function">PageArgument</a> 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 <ahref="#get-autoconnectelement-from-the-autoconnectaux">AutoConnectAux::getElement</a> function. The following sketch code replaces the above example with JSON and PageArgument, and its behaves is equivalent basically to the above sketch.</p>
@ -1445,10 +1445,18 @@ ESP8266WebServer class will parse the query string and rebuilds its arguments wh
<h3id="overwrite-the-autoconnectelements"><iclass="fa fa-wpforms"></i> Overwrite the AutoConnectElements<aclass="headerlink"href="#overwrite-the-autoconnectelements"title="Permanent link">¶</a></h3>
<h3id="overwrite-the-autoconnectelements"><iclass="fa fa-wpforms"></i> Overwrite the AutoConnectElements<aclass="headerlink"href="#overwrite-the-autoconnectelements"title="Permanent link">¶</a></h3>
<p>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 <ahref="apiaux.html#loadelement">AutoConnectAux::loadElement</a>. </p>
<p>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 <ahref="apiaux.html#loadelement">AutoConnectAux::loadElement</a>. </p>
<p>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 <ahref="api.html#load">AutoConnect::load</a> function.</p>
<p>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 <ahref="api.html#load">AutoConnect::load</a> function.</p>
<p>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.</p>
<p>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.</p>
<p><iclass="fa fa-code"></i> The sketch (part of code)</p>
<p><iclass="fab fa-js-square"></i> External JSON document for the below sketch to modify the text style.
<h3id="check-data-against-on-submission"><iclass="far fa-check-square"></i> Check data against on submission<aclass="headerlink"href="#check-data-against-on-submission"title="Permanent link">¶</a></h3>
<h3id="check-data-against-on-submission"><iclass="far fa-check-square"></i> Check data against on submission<aclass="headerlink"href="#check-data-against-on-submission"title="Permanent link">¶</a></h3>
<p>By giving a <ahref="apielements.html#pattern">pattern</a> to <ahref="apielements.html#autoconenctinput">AutoConnectInput</a>, you can find errors in data styles while typing in custom Web pages. The pattern is specified by <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions">regular expression</a>.<supid="fnref:2"><aclass="footnote-ref"href="#fn:2"rel="footnote">2</a></sup> 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.</p>
<p>By giving a <ahref="apielements.html#pattern">pattern</a> to <ahref="apielements.html#autoconenctinput">AutoConnectInput</a>, you can find errors in data styles while typing in custom Web pages. The pattern is specified by <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions">regular expression</a>.<supid="fnref:2"><aclass="footnote-ref"href="#fn:2"rel="footnote">2</a></sup> 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.</p>
@ -1497,9 +1499,10 @@ ESP8266WebServer class will parse the query string and rebuilds its arguments wh
</div>
</div>
<h3id="convert-data-to-actually-type"><iclass="fa fa-exchange"></i> Convert data to actually type<aclass="headerlink"href="#convert-data-to-actually-type"title="Permanent link">¶</a></h3>
<h3id="convert-data-to-actually-type"><iclass="fa fa-exchange"></i> Convert data to actually type<aclass="headerlink"href="#convert-data-to-actually-type"title="Permanent link">¶</a></h3>
<p>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 <ahref="datatips.html#convert-autoconnectelements-value-to-actual-data-type"><em>Tips for data conversion</em></a>.</p>
<h2id="transitions-of-the-custom-web-pages">Transitions of the custom Web pages<aclass="headerlink"href="#transitions-of-the-custom-web-pages"title="Permanent link">¶</a></h2>
<h2id="transitions-of-the-custom-web-pages">Transitions of the custom Web pages<aclass="headerlink"href="#transitions-of-the-custom-web-pages"title="Permanent link">¶</a></h2>
<h3id="scope-lifetime-of-autoconnectaux">Scope & Lifetime of AutoConnectAux<aclass="headerlink"href="#scope-lifetime-of-autoconnectaux"title="Permanent link">¶</a></h3>
<h3id="scope-lifetime-of-autoconnectaux">Scope & Lifetime of AutoConnectAux<aclass="headerlink"href="#scope-lifetime-of-autoconnectaux"title="Permanent link">¶</a></h3>
<p>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().</p>
<p>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().</p>
AutoConnect can handle custom Web pages prepared by user sketches individually. Custom Web pages are displayed in the <ahref="menu.html">AutoConnect menu</a> 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.</p>
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.</p>
<p>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.</p>
<h2id="how-it-works">How it works<aclass="headerlink"href="#how-it-works"title="Permanent link">¶</a></h2>
<h2id="how-it-works">How it works<aclass="headerlink"href="#how-it-works"title="Permanent link">¶</a></h2>
<p>Custom Web pages are dynamically created by AutoConnect. The Classes and APIs necessary for dynamic creation are provided. <ahref="apiaux.html#autoconnectaux"><strong>AutoConnectAux</strong></a> 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 <ahref="acelements.html"><strong>AutoConnectElement</strong></a> class. Furthermore, an input box, a check box, a submit button, etc. are implemented by classes derived from AutoConnectElement.
<p>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 <ahref="apiaux.html#autoconnectaux"><strong>AutoConnectAux</strong></a> and the variant of <ahref="acelements.html"><strong>AutoConnectElements</strong></a>. 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.</p>
<p>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.</p>
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.</p>
<p><imgsrc="./images/ac_declaration.svg"></p>
<p><imgsrc="./images/ac_declaration.svg"></p>
@ -842,13 +844,14 @@ AutoConnectAux is a container for AutoConnectElements. To make a custom Web page
<h2id="basic-steps-to-use-custom-web-pages">Basic steps to use custom Web pages<aclass="headerlink"href="#basic-steps-to-use-custom-web-pages"title="Permanent link">¶</a></h2>
<h2id="basic-steps-to-use-custom-web-pages">Basic steps to use custom Web pages<aclass="headerlink"href="#basic-steps-to-use-custom-web-pages"title="Permanent link">¶</a></h2>
<p>So, the basic procedure for handling of the custom Web pages is as follows:</p>
<p>So, the basic procedure for handling of the custom Web pages is as follows:</p>
<ol>
<ol>
<li>Create or define AutoConnectAux.</li>
<li>Create or define <ahref="apiaux.html#autoconnectaux">AutoConnectAux</a>.</li>
<li>Create or define <ahref="acelements.html">AutoConnectElement(s)</a>.</li>
<li>Create or define <ahref="acelements.html">AutoConnectElement(s)</a>.</li>
<li>Add <ahref="acelements.html">AutoConnectElement(s)</a> to AutoConnectAux.</li>
<li>Add <ahref="acelements.html">AutoConnectElement(s)</a> to AutoConnectAux.</li>
<li>Create more AutoConnectAux containing <ahref="acelements.html">AutoConnectElement(s)</a>, if necessary.</li>
<li>Create more AutoConnectAux containing <ahref="acelements.html">AutoConnectElement(s)</a>, if necessary.</li>
<li>Register the request handlers for the custom Web pages.</li>
<li><ahref="api.html#on">Register</a> the request handlers for the custom Web pages.</li>
<li><ahref="api.html#join">Join</a> prepared AutoConnectAux(s) to AutoConnect.</li>
<li><ahref="api.html#join">Join</a> prepared AutoConnectAux(s) to AutoConnect.</li>
<h2id="write-the-custom-web-page-with-json">Write the custom Web page with JSON<aclass="headerlink"href="#write-the-custom-web-page-with-json"title="Permanent link">¶</a></h2>
<h2id="write-the-custom-web-page-with-json">Write the custom Web page with JSON<aclass="headerlink"href="#write-the-custom-web-page-with-json"title="Permanent link">¶</a></h2>
<p>You can write the custom Web page in JSON without using sketch codes.<supid="fnref:3"><aclass="footnote-ref"href="#fn:3"rel="footnote">3</a></sup> It is possible to describe the entire page in JSON and can be described for each element also. The JSON document can be saved in SPIFFS or SD and read using AutoConnect's <ahref="api.html#load"><strong>load</strong></a> function. you can reduce the steps of the basic procedure with this approach, but this way consumes a lot of memory.
<p>You can write the custom Web page in JSON without using sketch codes.<supid="fnref:3"><aclass="footnote-ref"href="#fn:3"rel="footnote">3</a></sup> It is possible to describe the entire page in JSON and can be described for each element also. The JSON document can be saved in SPIFFS or SD and read using AutoConnect's <ahref="api.html#load"><strong>load</strong></a> function. you can reduce the steps of the basic procedure with this approach, but this way consumes a lot of memory.
@ -929,7 +932,7 @@ The following JSON code and sketch will execute the custom Web page as an exampl
<spanstyle="color: #f8f8f2">}</span>
<spanstyle="color: #f8f8f2">}</span>
</pre></div></p>
</pre></div></p>
<h2id="passing-parameters-with-sketches-and-custom-web-pages">Passing parameters with sketches and custom Web pages<aclass="headerlink"href="#passing-parameters-with-sketches-and-custom-web-pages"title="Permanent link">¶</a></h2>
<h2id="passing-parameters-with-sketches-and-custom-web-pages">Passing parameters with sketches and custom Web pages<aclass="headerlink"href="#passing-parameters-with-sketches-and-custom-web-pages"title="Permanent link">¶</a></h2>
<p>A sketch can access variables of <ahref="acelements.html">AutoConnectElements</a> on the custom Web page. The value entered into the AutoConnectElements is stored to the <ahref="acelements.html#form-and-autoconnectelements">member variables</a> 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 <ahref="api.html#on">AutoConnect::on</a> 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<ahref="achandling.html#custom-field-data-handling">Custom field data handling</a> section.</p>
<p>A sketch can access variables of <ahref="acelements.html">AutoConnectElements</a> on the custom Web page. The value entered into the AutoConnectElements is stored to the <ahref="acelements.html#form-and-autoconnectelements">member variables</a> 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 <ahref="api.html#on">AutoConnect::on</a> 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<ahref="achandling.html#custom-field-data-handling"><em>Custom field data handling</em></a>.</p>
<p>You can embed custom Web pages written in <ahref="https://www.json.org/index.html"><strong>JSON</strong></a> 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.<supid="fnref:1"><aclass="footnote-ref"href="#fn:1"rel="footnote">1</a></sup></p>
<p>You can embed custom Web pages written in <ahref="https://www.json.org/index.html"><strong>JSON</strong></a> 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.<supid="fnref:1"><aclass="footnote-ref"href="#fn:1"rel="footnote">1</a></sup></p>
<p>By providing the following JSON document to AutoConnect, you can include the custom Web page as the bellow:</p>
<p>By providing the following JSON document to AutoConnect, you can include the custom Web page like the below:</p>
<p>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.</p>
<p>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.</p>
<p>To process the AutoConnectAux & AutoConnectElements written in the JSON is you need to install the <ahref="https://arduinojson.org/v5/doc/installation/">ArduinoJson version 5</a> library.</p>
<p>To process the AutoConnectAux & AutoConnectElements written in the JSON is you need to install the <ahref="https://arduinojson.org/v5/doc/installation/">ArduinoJson version 5</a> library.</p>
</div>
</div>
<h2id="json-objects-elements-for-the-custom-web-page">JSON objects & elements for the custom Web page<aclass="headerlink"href="#json-objects-elements-for-the-custom-web-page"title="Permanent link">¶</a></h2>
<h2id="json-objects-elements-for-the-custom-web-page">JSON objects & elements for the custom Web page<aclass="headerlink"href="#json-objects-elements-for-the-custom-web-page"title="Permanent link">¶</a></h2>
<h3id="json-document-structure-for-autoconnectaux"><iclass="fa fa-caret-right"></i> JSON document structure for AutoConnectAux<aclass="headerlink"href="#json-document-structure-for-autoconnectaux"title="Permanent link">¶</a></h3>
<h3id="json-document-structure-for-autoconnectaux"><iclass="fa fa-caret-right"></i> JSON document structure for AutoConnectAux<aclass="headerlink"href="#json-document-structure-for-autoconnectaux"title="Permanent link">¶</a></h3>
<p>An AutoConnectAux is described by a JSON object. The elements that make up an object are as follows:</p>
<p>AutoConnectAux will configure custom Web pages with JSON objects. The elements that make up the object are as follows:</p>
<h3id="json-object-for-autoconnectelements"><iclass="fa fa-caret-right"></i> JSON object for AutoConnectElements<aclass="headerlink"href="#json-object-for-autoconnectelements"title="Permanent link">¶</a></h3>
<h3id="json-object-for-autoconnectelements"><iclass="fa fa-caret-right"></i> JSON object for AutoConnectElements<aclass="headerlink"href="#json-object-for-autoconnectelements"title="Permanent link">¶</a></h3>
<p>AutoConnectElements in JSON description are described as an array in the <code>element</code> with arguments of each<ahref="acelements.html#constructor">constructor</a>.</p>
<p>JSON description for AutoConnectElements describes as an array in the <em>element</em> with arguments of <ahref="acelements.html#constructor">each constructor</a>.</p>
@ -1207,7 +1207,7 @@ Also, if you want to stop AutoConnect completely when the captive portal is time
<li><ahref="api.html#begin">Begin</a> the portal.</li>
<li><ahref="api.html#begin">Begin</a> the portal.</li>
<li>Performs <ahref="api.html#handleClient">AutoConnect::handleClient</a> in the <strong>loop</strong> function.</li>
<li>Performs <ahref="api.html#handleClient">AutoConnect::handleClient</a> in the <strong>loop</strong> function.</li>
</ol>
</ol>
<p>For details see the<ahref="menuize.html">Constructing the menu</a> section of Examples page.</p>
<p>For details see <em>Example page</em> of section<ahref="menuize.html"><em>Constructing the menu</em></a>.</p>
<h3id="change-menu-title"><iclass="fa fa-caret-right"></i> Change menu title<aclass="headerlink"href="#change-menu-title"title="Permanent link">¶</a></h3>
<h3id="change-menu-title"><iclass="fa fa-caret-right"></i> Change menu title<aclass="headerlink"href="#change-menu-title"title="Permanent link">¶</a></h3>
<p>Although the default menu title is <strong>AutoConnect</strong>, you can change the title by setting <ahref="apiconfig.html#title">AutoConnectConfig::title</a>. To set the menu title properly, you must set before calling <ahref="api.html#begin">AutoConnect::begin</a>.</p>
<p>Although the default menu title is <strong>AutoConnect</strong>, you can change the title by setting <ahref="apiconfig.html#title">AutoConnectConfig::title</a>. To set the menu title properly, you must set before calling <ahref="api.html#begin">AutoConnect::begin</a>.</p>
<h2id="convert-autoconnectelements-value-to-actual-data-type">Convert AutoConnectElements value to actual data type<aclass="headerlink"href="#convert-autoconnectelements-value-to-actual-data-type"title="Permanent link">¶</a></h2>
<h2id="convert-autoconnectelements-value-to-actual-data-type">Convert AutoConnectElements value to actual data type<aclass="headerlink"href="#convert-autoconnectelements-value-to-actual-data-type"title="Permanent link">¶</a></h2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>Here, represent examples the typical method for the data type conversion for the AutoConnectElements value of custom Web pages.</p>
<p>Here, represent examples the typical method for the data type conversion for the AutoConnectElements value of custom Web pages.</p>
<p>Use <ahref="https://www.arduino.cc/reference/en/language/variables/conversion/intcast/">int()</a> or <ahref="https://www.arduino.cc/reference/en/language/variables/data-types/string/functions/toint/">toInt() of String</a>.</p>
<p>Use <ahref="https://www.arduino.cc/reference/en/language/variables/conversion/intcast/">int()</a> or <ahref="https://www.arduino.cc/reference/en/language/variables/data-types/string/functions/toint/">toInt() of String</a>.</p>
@ -939,9 +939,9 @@
</pre></div>
</pre></div>
<h2id="validation-for-the-value">Validation for the value<aclass="headerlink"href="#validation-for-the-value"title="Permanent link">¶</a></h2>
<h2id="validation-for-the-value">Validation for the value<aclass="headerlink"href="#validation-for-the-value"title="Permanent link">¶</a></h2>
<p>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 <strong>pattern</strong> of AutoConnectInput.</p>
<p>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 <ahref="achandling.html#check-data-against-on-submission"><strong>pattern</strong></a> of AutoConnectInput.</p>
<p>By giving a <ahref="achandling.html#check-data-against-on-submission"><strong>pattern</strong></a> to <ahref="apielements.html#pattern">AutoConnectInput</a>, you can find errors in data format while typing in custom Web pages. The pattern is specified by<ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions"><strong>regular expression</strong></a>. 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<ahref="achandling.html#check-data-against-on-submission">Handling the custom Web pages</a> section.</p>
<p>By giving a <ahref="acelements.html#pattern">pattern</a> to <ahref="apielements.html#pattern">AutoConnectInput</a>, you can find errors in data format while typing in custom Web pages. Specifying the input data rule as a<ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions">regular expression</a> 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<ahref="achandling.html#check-data-against-on-submission">Handling the custom Web pages</a>.</p>
<p>However, input data will be transmitted even if the value does not match the pattern. To check the value with the sketch, using the <ahref="apielements.html#isvalid"><strong>AutoConnectInput::isValid</strong></a> function. The isValid function validates whether the value member variable matches a pattern and returns true or false.</p>
<p>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 <ahref="apielements.html#isvalid">AutoConnectInput::isValid</a> function to validate it. The isValid function validates whether the value member variable matches a pattern and returns true or false.</p>
<p>Regular expressions specified in the AutoConnectInput pattern conforms to the <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions">JavaScript specification</a>.</p>
<p>Regular expressions specified in the AutoConnectInput pattern conforms to the <ahref="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions">JavaScript specification</a>.</p>
</div>
</div>
<p>Here, represent examples the typical regular expression for the input validation.</p>
<p>Here, represent examples the typical regular expression for the input validation.</p>
<h3id="dns-hostname"><iclass="far fa-check-square"></i> DNS hostname<aclass="headerlink"href="#dns-hostname"title="Permanent link">¶</a></h3>
<h3id="dns-hostname"><imgsrc="./images/regexp.png"align="top"> DNS hostname<aclass="headerlink"href="#dns-hostname"title="Permanent link">¶</a></h3>
<h3id="date-as-mmddyyyy-2"><iclass="far fa-check-square"></i> Date as MM/DD/YYYY <supid="fnref:2"><aclass="footnote-ref"href="#fn:2"rel="footnote">2</a></sup><aclass="headerlink"href="#date-as-mmddyyyy-2"title="Permanent link">¶</a></h3>
<h3id="date-as-mmddyyyy-2"><imgsrc="./images/regexp.png"align="top"> Date as MM/DD/YYYY <supid="fnref:2"><aclass="footnote-ref"href="#fn:2"rel="footnote">2</a></sup><aclass="headerlink"href="#date-as-mmddyyyy-2"title="Permanent link">¶</a></h3>
<p>You can extend the AutoConnect menu to match legacy sketches and according to the procedure described in the <ahref="advancedusage.html#cast-the-legacy-html-pages-as-the-add-on-menu-items">Advanced Usage section</a>.</p>
<p>You can extend the AutoConnect menu to match legacy sketches and according to the procedure described in the sectio <ahref="advancedusage.html#cast-the-legacy-html-pages-as-the-add-on-menu-items"><em>Advanced Usage</em></a>.</p>
<dd>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 <ahref="api.html#begin">AutoConnect::begin</a> and <ahref="api.html#handleclient">AutoConnect::handleClient</a>.</dd>
<dd>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 <ahref="api.html#begin">AutoConnect::begin</a> and <ahref="api.html#handleclient">AutoConnect::handleClient</a>.</dd>
<dt><iclass="fa fa-desktop"></i> <strong>Extra menu with custom Web pages which is consisted by <ahref="acelements.html">AutoConnectElements</a></strong></dt>
<dt><iclass="fa fa-desktop"></i> <strong>Extra menu with custom Web pages which is consisted by <ahref="acelements.html">AutoConnectElements</a></strong></dt>
<dd>It is an extended menu that appears when the sketch consists of the custom Web pages with <ahref="acintro.html#how-it-works">AutoConnectAux</a> and AutoConnectElements. Refer to <ahref="acintro.html#custom-web-pages-in-autoconnect-menu">Custom Web pages section</a>.</dd>
<dd>It is an extended menu that appears when the sketch consists of the custom Web pages with <ahref="acintro.html#how-it-works">AutoConnectAux</a> and AutoConnectElements. Refer to section <ahref="acintro.html#custom-web-pages-in-autoconnect-menu"><em>Custom Web pages section</em></a>.</dd>
<dt><iclass="fa fa-desktop"></i> <strong>Extra menu which contains legacy pages</strong></dt>
<dt><iclass="fa fa-desktop"></i> <strong>Extra menu which contains legacy pages</strong></dt>
<dd>It is for the legacy sketches using the <strong>on</strong> handler of ESP8266WebServer/WebServer(for ESP32) class natively and looks the same as the extra menu as above.</dd>
<dd>It is for the legacy sketches using the <strong>on</strong> handler of ESP8266WebServer/WebServer(for ESP32) class natively and looks the same as the extra menu as above.</dd>
Hieromon Ikasamo
6 years ago