Merge branch 'release-1.8.1' of https://github.com/HomeSpan/HomeSpan into release-1.8.1

README.md

@@ -62,10 +62,9 @@ HomeSpan requires version 2.0.0 or later of the [Arduino-ESP32 Board Manager](ht
   * example: `homeSpan.setControlPin(21).setStatusPin(13);`
   * see [HomeSpan API Reference](docs/Reference.md) for details
     
-* **Upgrades to HomeSpan Web Log output**
+* **New Web Log Customizations**
 
-  * adds new method `void homeSpan.setWebLogCSS(const char *css)` that allows you to define *Custom Style Sheets (CSS)* for the Web Log text, tables, and background
+  * adds new method `setWebLogCallback(void (*f)(String &))` that provides a callback allowing you to extend the initial Web Log table with additional data of your own, as well as add an other custom HTML
-  * adds version numbers for the Sodium and MbedTLS libraries, HomeKit pairing status, and a text description of Reset Reason code
   * see [Message Logging](docs/Logging.md) for details
     
 See [Releases](https://github.com/HomeSpan/HomeSpan/releases) for details on all changes and bug fixes included in this update.

docs/Logging.md

@@ -81,7 +81,28 @@ For example, the following CSS changes the background color of the Web Log page
  ```
  
 Note that HomeSpan outputs the full content of the Web Log HTML, including whatever CSS you may have specified above, to the Serial Monitor whenever the Log Level is set to 1 or greater.  Reviewing this output can be helpful when creating your own CSS.
- 
+
+### Adding User-Defined Data and/or Custom HTML
+
+Homespan provides a hook into the text used to generate the Web Log that you can extend to add your own data to the initial table as well as more generally add any custom HTML.
+
+To access this text, set a Web Log callback using `homeSpan.setWebLogCallback(void (*func)(String &htmlText))` where
+
+  * *func* is a function of type *void* that takes a single argument of type *String*, and
+  * *htmlText* will be set by HomeSpan to a String reference containing all the HTML text that the Web Log has already generated to produce the initial table.
+
+To add your own data to the table, simply extend the String *htmlText* by adding as many `<tr>` and `<td>` HTML tags as needed.  If you wish to end the table and add any other HTML, simple include the `</table>` tag in *htmlText*, and then add any other custom HTML.  For example, the following function could be used to extend the initial Web Log table to show free DRAM, end the table, and provide a hot link to the HomeSpan Repo:
+
+```C++
+void extraData(String &r){
+  r+="<tr><td>Free DRAM:</td><td>" + String(esp_get_free_internal_heap_size()) + " bytes</td></tr>\n"; 
+  r+="</table><p><a href=\"https://github.com/HomeSpan/HomeSpan\">Click Here to Access HomeSpan Repo</a><p>";
+}
+```
+
+To embed this custom HTML text in the Web Log, call `homeSpan.setWebLogCallback(extraWebData)` in your sketch.
+
+Note that *r* is being passed as a reference and already includes all the HTML text the Web Log has produced to set up the page and create the initial table.  You should therefore *extend* this String using  `+=`.  Do not simple assign this variable to a new String with `=` or you will overwrite all the HTML already produced!
  
 ---
 

docs/Reference.md

@@ -208,6 +208,12 @@ The following **optional** `homeSpan` methods enable additional features and pro
 * `Span& setWebLogCSS(const char *css)`
   * sets the format of the HomeSpan Web Log to the custom style sheet specified by *css*
   * see [Message Logging](Logging.md) for details on how to construct *css*
+
+* `Span& setWebLogCallback(void (*func)(String &htmlText))`
+  * sets an optional user-defined callback function, *func*, to be called by HomeSpan whenever the Web Log is produced
+  * allows user to add additional custom data to the initial table of the Web Log by **extending** the String *htmlText*, which is passed as a reference to *func*
+  * the function *func* must be of type *void* and accept one argument of type String
+  * see [Message Logging](Logging.md) for details on how to construct *htmlText*
  
 * `void processSerialCommand(const char *CLIcommand)`
   * processes the *CLIcommand* just as if were typed into the Serial Monitor