Adds description of append, detach and onConnect

5 years ago · 91f1c0fcf1
parent abac1d0198
commit 91f1c0fcf1
5 changed files with 182 additions and 55 deletions
--- a/mkdocs/advancedusage.md
+++ b/mkdocs/advancedusage.md
@ -214,63 +214,79 @@ void loop() {
 }
 ```

-### <i class="fa fa-caret-right"></i> Casts the HTML pages to be add-on into the menu
+### <i class="fa fa-caret-right"></i> Capture the legacy web pages as items into the menu

-If your sketch handles web pages, you can embed the pages into the AutoConnect menu in continuance enjoying the utility of the WiFi connection feature. Unlike the custom Web pages by [AutoConnectElements](acelements.md), this allows to legacy web pages registered by *ESP8266WebServer::on* or *WebServer::on* function.
+You can embed the ordinary page processed by the ESP8266WebServer request handler as an item into the AutoConnect menu. AutoConnect allows capturing the legacy web pages for ESP8266WebServer or WebServer of ESP32 and extends the menu containing these items, also Sketch can embed the legacy pages using the [*AutoConnect::append*](api.md#append) function.

-To implement embedding your legacy web pages to the AutoConnect menu, you can use AutoConnectAux only constructed with the URI of the page to be embedding. AutoConnectElements is not required. The basic procedure for this as follows:
+To process a web page using the ESP8266WebServer class (The WebServer class for ESP32), you usually register a handler with URI by the `on` function. The [*AutoConnect::append*](api.md#append) function creates internally an [**AutoConnectAux**](acintro.md) depended on its URI and integrates into the menu.

-1. Declare AutoConnectAux for each legacy page. It includes the URI of the page and item string which will display in the AutoConnect menu.
-2. Sketch the legacy page handlers.
-3. Register those handler functions to ESP8266WebServer/WebServer with the **on** function.
-4. Register AutoConnectAux declared with #1 to AutoConnect using [*AutoConnect::join*](api.md#join) function. It serves as a menu item.
-5. [Begin](api.md#begin) the portal.
-6. Performs [*AutoConnect::handleClient*](api.md#handleClient) in the **loop** function.
+The following code has a mixture of both AutoConnectAux and the legacy web page. An AutoConnectAux page is menued automatically with the [*AutoConnect::join*](api.md#join) or [*AutoConnect::load*](api.md#load) function, and a legacy page is integrated by the [*AutoConnect::append*](api.md#append) function.

-```cpp hl_lines="10 28 32"
+```cpp hl_lines="26 35"
 #include <ESP8266WiFi.h>
 #include <ESP8266WebServer.h>
 #include <AutoConnect.h>

-ESP8266WebServer  server;
-
-// Declaration for casting legacy page to AutoConnect menu.
-// Specifies an uri and the menu label.
-AutoConnect       portal(server);
-AutoConnectAux    hello("/hello", "Hello");   // Step #1 as the above procedure
+ESP8266WebServer server;
+AutoConnect      portal(server);
+
+// Definitions of AutoConnectAux page
+static const char PAGE[] PROGMEM = R"(
+{
+  "title": "PAGE",
+  "uri": "/page",
+  "menu": true,
+  "element": [
+    {
+      "name": "cap",
+      "type": "ACText",
+      "value": "This is a custom web page."
+    }
+  ]
+}
+)";

-// Step #2 as the above procedure
-// A conventional web page driven by the ESP8266WebServer::on handler.
-// This is a legacy.
-void handleHello() {
-  server.send(200, "text/html", String(F(
+void setup() {
+  // The Web page handler located to /hello
+  server.on("/hello", [](){
+    server.send(200, "text/html", String(F(
 "<html>"
 "<head><meta name='viewport' content='width=device-width,initial-scale=1.0'></head>"
-"<body>Hello, world</body>"
+"<body><h2>Hello, world</h2></body>"
 "</html>"
-  )));
-}
+    )));
+  });

-void setup() {
-  // Step #3 as the above procedure
-  // Register the "on" handler as usual to ESP8266WebServer.
-  // Match this URI with the URI of AutoConnectAux to cast.
-  server.on("/hello", handleHello);
-
-  // Step #4 as the above procedure
-  // Joins AutoConnectAux to cast the page via the handleRoot to AutoConnect.
-  portal.join({ hello });
-  portal.begin();           // Step #5 as the above procedure
+  portal.append("/hello", "HELLO");  // Adds an item as HELLO into the menu
+  portal.load(FPSTR(PAGE));               // Load AutoConnectAux custom web page
+  portal.begin();
 }

 void loop() {
-  portal.handleClient();    // Step #6 as the above procedure
+  portal.handleClient();
 }
+  
 ```

-<img width="232px" src="images/castmenu.png">
+<span style="display:block;margin-left:auto;margin-right:auto;width:284px;height:462px;border:1px solid lightgrey;"><img data-gifffer="images/addmenu.gif" data-gifffer-height="460" data-gifffer-width="282" /></span>

-For more details, see section [Constructing the menu](menuize.md) of Examples page.
+The [*AutoConnect::append*](api.md#append) function also has the third parameter that directly specifies the request handler. It has similar efficacy to calling the append and `ESP8266WebSever::on` at once.
+
+```cpp
+portal.append("/hello", "HELLO", [](){
+  server.send(200, "text/html", String(F(
+"<html>"
+"<head><meta name='viewport' content='width=device-width,initial-scale=1.0'></head>"
+"<body><h2>Hello, world</h2></body>"
+"</html>"
+  )));
+});
+```
+
+For more details, see section [Attach the menu](menuize.md) of Examples page.
+
+!!! note "Necessary ESP8266WebServer/WebServer has materialized"
+    The WebServer must have instantiated for calling with a request handler parameter. AutoConnect can instantiate and host a WebServer internally, but in that case, the point in time to call the [AutoConnct::append](api.md#append) function with a request handler parameter must be after [AutoConnect::begin](api.md#begin).

 ### <i class="fa fa-caret-right"></i> Change the menu labels

@ -357,7 +373,7 @@ Combining these two parameters allows you to filter the destination AP when mult
 </tr>
 <tr>
    <td>Specified with the Sketch</td>
-    <td>Not efective</td>
+    <td>Not effective</td>
    <td>By AutoConnect::begin parameters</td>
    <td>Use the specified value of AutoConnectConfig</td>
 </tr>
@ -384,6 +400,44 @@ You can output AutoConnect monitor messages to the **Serial**. A monitor message
 #define AC_DEBUG
 ```

+### <i class="fa fa-caret-right"></i> Detect WiFi connection establishment with a router
+
+[*AutoConnect::onConnect*](api.md#onconnect) allows the Sketch to detect a WiFi connection to a router. The Sketch uses [*AutoConnect::onConnect*] to register a function to call when WiFi connected.  
+For example, as the following Sketch, this can be combined with [*AutoConnectConfig::retainPortal*](apiconfig.md#retainportal) to stop **SoftAP** in a **loop()**. It avoids blocking in the captive portal state by AutoConnect and allows the loop to run even without a WiFi connection.
+
+```cpp hl_lines="13 14 15 16 17 18 19"
+#include <ESP8266WiFi.h>
+#include <ESP8266WebServer.h>
+#include <AutoConnect.h>
+
+AutoConnect Portal;
+AutoConnectConfig config;
+
+void setup() {
+  Serial.begin(115200);
+  config.portalTimeout = 1;
+  config.retainPortal = true;
+  portal.config(config);
+  portal.onConnect([](IPAddress& ip){
+    Serial.printf("Connected %s\n", ip.toString().c_str());
+    if (WiFi.getMode() == WI_AP_STA) {
+      WiFi.softAPdisconnect(false);
+      WiFi.mode(WIFI_STA);
+    }
+  });
+  portal.begin();
+}
+
+void loop() {
+  // Here, the Sketch can execute without WiFi connection.
+  // It avoids blocking the state by the captive portal even if the captive portal is available.
+  portal.handleClient();
+}
+```
+
+!!! note "It is not an event"
+    AutoConnect::onConnect has the same effect on the Sketch as the [WiFi.onStationModeConnected](https://arduino-esp8266.readthedocs.io/en/latest/esp8266wifi/generic-class.html#onevent), but AutoConnect does not use the event. Sketch can use `WiFi.onEvent` independently of AutoConnect.
+
 ### <i class="fa fa-caret-right"></i> Disable the captive portal

 It can also prevent the captive portal from starting even if the connection at the 1st-WiFi.begin fails. In this case, [*AutoConnect::begin*](api.md#begin) behaves same as *WiFi.begin*.
@ -519,7 +573,7 @@ Here section describes how to launch on demand the captive portal, and suggests
          portal = nullptr;
        }
      }
-      // Here, ordinally sketch logic.
+      // Here, ordinary sketch logic.
    }
    ```

@ -638,7 +692,7 @@ The Sketch HOME path is closely related to the [bootUri](apiconfig.md#booturi) t

 AutoConnect features a built-in OTA function to update ESP module firmware. You can easily make the Sketch that equips OTA and able to operate with the AutoConnect menu.

-<span style="display:block;margin-left:auto;margin-right:auto;width:294px;height:482px;border:1px solid lightgrey;"><img data-gifffer="images/webupdate.gif" data-gifffer-height="480" data-gifffer-width="292" /></span>
+<span style="display:block;margin-left:auto;margin-right:auto;width:284px;height:462px;border:1px solid lightgrey;"><img data-gifffer="images/webupdate.gif" data-gifffer-height="460" data-gifffer-width="282" /></span>

 [*AutoConnectConfig::ota*](apiconfig.md#ota) specifies to import the [built-in OTA update class](otabrowser.md) into the Sketch.  
 See the [Updates with the Web Browser](otabrowser.md) chapter for details.
@ -684,7 +738,7 @@ Also, you can specify the SSID, password for SoftAP with the constructor of the

 ```cpp hl_lines="2"
 AutoConnect portal;
-AutoConnectConfig config("ap_portal", "new_passwrod");
+AutoConnectConfig config("ap_portal", "new_password");

 void setup() {
  portal.config(config);
--- a/mkdocs/api.md
+++ b/mkdocs/api.md
@ -68,6 +68,40 @@ The [**handleClient**](api.md#handleclient) function of AutoConnect can include

 ## <i class="fa fa-code"></i> Public member functions

+### <i class="fa fa-caret-right"></i> append
+
+- ESP8266/ESP32 Common
+
+```cpp
+AutoConnectAux* append(const String& uri, const String& title)
+```
+
+- For ESP8266
+
+```cpp
+AutoConnectAux* append(const String& uri, const String& title, ESP8266WebServer::THandlerFunction handler)
+```
+
+- For ESP32
+
+```cpp
+AutoConnectAux* append(const String& uri, const String& title, WebServer::THandlerFunction handler)
+```
+Creates an AutoConnectAux dynamically with the specified URI and integrates it into the menu. Calls with a request handler parameter can use this function as menu registration for a legacy page of ESP8266WebServer/WebServer. If the **handler** parameter specified, also it will register the request handler for the ESP8266WebServer/WebServer.  
+AutoConnect manages the menu items using a sequence list, and this function always adds the item to the end of the list. Therefore, the order of the menu items is the additional order.  
+Returns the pointer to created AutoConnectAux instance, the `nullptr` if an AutoConnectAux with the same URI already exists.
+<dl class="apidl">
+    <dt>**Parameter**</dt>
+    <dd><span class="apidef">uri</span><span class="apidesc">A string of the URI.</span></dd>
+    <dd><span class="apidef">title</span><span class="apidesc">Title for menu item.</span></dd>
+    <dd><span class="apidef">handler</span><span class="apidesc">Request handler function as type of **ESP8266WebServer::THandlerFunction**/**WebServer::THandlerFunction**.</span></dd>
+    <dt>**Return value**</dt>
+    <dd>A Pointer to a created AutoConnectAux instance.</dd>
+</dl>
+
+!!! note "Necessary ESP8266WebServer/WebServer has materialized"
+    The WebServer must have instantiated for calling with a request handler parameter. AutoConnect can instantiate and host a WebServer internally, but in that case, the point in time to call the append function with a request handler parameter must be after AutoConnect::begin.
+
 ### <i class="fa fa-caret-right"></i> aux

 ```cpp
@ -126,6 +160,34 @@ Set SoftAP's WiFi configuration and static IP configuration.
    <dd><span class="apidef">false</span><span class="aidesc">Configuration parameter is invalid, some values out of range.</span></dd>
 </dl>

+### <i class="fa fa-caret-right"></i> detach
+```cpp
+AutoConnectAux* detach(const String& uri)
+```
+Detach the AutoConnectAux with the specified URI from the management of AutoConnect. An unmanaged AutoConnectAux will no longer appear in menu items, and its page handler will no longer respond even if the URI is accessed directly. 
+<dl class="apidl">
+    <dt>**Parameter**</dt>
+    <dd><span class="apidef">uri</span><span class="apidesc">URI of AutoConnectAux to be detached.</span></dd>
+</dl>
+
+If the request handler registered in the detaching AutoConnectAux is for a legacy page of the ESP8266WebServer/WebServer, the URI is still valid after detaching. AutoConnect does not delete the request handler registered to ESP8266WebServer/WebServer with the `on` function. (It cannot be removed)
+
+!!! hint "Deleting the AutoConnectAux"
+    You can use the return value from the AotoConnect::detach to delete the AutoConnectAux instance which dynamically created with the [AutoConnect::append](api.md#append).
+
+### <i class="fa fa-caret-right"></i> disableMenu
+
+```cpp
+void disableMenu(const uint16_t items)
+```
+
+Disable the [AutoConnect menu](menu.md) items specified by the items parameter with logical OR value using **AC_MENUITEM_t** constant.  
+This function only works for AutoConnect primary menu items. It has no effect on disable for AutoConnectAux items. To disable the items by AutoConnectAux, use the [AutoConnectAux::menu](apiaux.md#menu) function.
+<dl class="apidl">
+    <dt>**Parameter**</dt>
+    <dd><span class="apidef">items</span><span class="apidesc">Specify the combined value of **AC_MENUITEM_t** of the items deleting from the AutoConnect menu. It provides the value calculated from the **logical OR** by the AC_MENUITEM_t value of each item. Refer to the [enableMenu](#enablemenu) about AC_MENUITEM_t.</span></dd>
+</dl>
+
 ### <i class="fa fa-caret-right"></i> enableMenu

 ```cpp
@ -133,6 +195,7 @@ void enableMenu(const uint16_t items)
 ```

 Enable the [AutoConnect menu](menu.md) items specified by the items parameter with logical OR value using **AC_MENUITEM_t** constant.  
+This function only works for AutoConnect primary menu items. It has no effect on enable for AutoConnectAux items. To enable the items by AutoConnectAux, use the [AutoConnectAux::menu](apiaux.md#menu) function.
 <dl class="apidl">
    <dt>**Parameter**</dt>
    <dd><span class="apidef">items</span><span class="apidesc">Specify the combined value of **AC_MENUITEM_t** of the items applying to the AutoConnect menu. It provides the value calculated from the **logical OR** by the AC_MENUITEM_t value of each item applied as a menu. AC_MENUITEM_t is enumeration type to identify each menu item and it has the below values.</span></dd>
@ -166,18 +229,6 @@ Stops AutoConnect captive portal service. Release ESP8266WebServer/WebServer and
 !!! warning "Attention to end"
    The end function releases the instance of ESP8266WebServer/WebServer and DNSServer. It can not process them after the end function.

-### <i class="fa fa-caret-right"></i> disableMenu
-
-```cpp
-void disableMenu(const uint16_t items)
-```
-
-Disable the [AutoConnect menu](menu.md) items specified by the items parameter with logical OR value using **AC_MENUITEM_t** constant.
-<dl class="apidl">
-    <dt>**Parameter**</dt>
-    <dd><span class="apidef">items</span><span class="apidesc">Specify the combined value of **AC_MENUITEM_t** of the items deleting from the AutoConnect menu. It provides the value calculated from the **logical OR** by the AC_MENUITEM_t value of each item. Refer to the [enableMenu](#enablemenu) about AC_MENUITEM_t.</span></dd>
-</dl>
-
 ### <i class="fa fa-caret-right"></i> getEEPROMUsedSize

 ```cpp
@ -314,6 +365,28 @@ Register the handler function of the AutoConnectAux.
 !!! caution "It is not ESP8266WebServer::on, not WebServer::on for ESP32."
    This function effects to AutoConnectAux only. However, it coexists with that of ESP8266WebServer::on or WebServer::on of ESP32. 

+### <i class="fa fa-caret-right"></i> onConnct
+
+```cpp
+void onConnect(ConnectExit_ft fn)
+```
+Register the function which will call from AutoConnect at the WiFi connection established.
+<dl class="apidl">
+    <dt>**Parameter**</dt>
+    <dd><span class="apidef">fn</span><span class="apidesc">Function called at the WiFi connected.</span></dd>
+</dl>
+
+An *fn* specifies the function called when the WiFi connected. Its prototype declaration is defined as "*ConnectExit_ft*".
+
+```cpp
+typedef std::function<void(IPAddress& localIP)>  ConnectExit_ft;
+```
+<dl class="apidl">
+    <dt>**Parameter**</dt>
+    <dd><span class="apidef">localIP</span><span class="apidesc">An IP address of the ESP module as STA.</span></dd>
+</dd>
+</dl>
+
 ### <i class="fa fa-caret-right"></i> onDetect

 ```cpp
--- a/mkdocs/images/addmenu.gif
+++ b/mkdocs/images/addmenu.gif
--- a/mkdocs/images/castmenu.png
+++ b/mkdocs/images/castmenu.png
--- a/mkdocs/menu.md
+++ b/mkdocs/menu.md
@ -123,4 +123,4 @@ The AutoConnect menu can contain your sketch's web pages as extra items as a cus
 <div style="float:left;width:auto;height:420px;"><img style="width:auto;height:420px;" src="images/fsbmenu.png"></div>
 <img style="margin-left:70px;width:auto;height:420px;" src="images/fsbmenu_expand.png">

-You can improve your sketches by extending the AutoConnect menu by adding the legacy web pages according to the procedure described in section [*Advanced Usage*](advancedusage.md#casts-the-html-pages-to-be-add-on-into-the-menu).
+AutoConnect allows capturing the extra pages handled with ESP8266WebServer or WebServer's legacy into the AutoConnect menu. See Section [*Advanced Usage*](advancedusage.md#capture-the-legacy-web-pages-as-items-into-the-menu) for detailed instructions on how to add the extra pages into its menu.