From 2d84f25ac4c9b95f19eaa8d39dc78b78cb68d1e2 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 28 Oct 2023 09:06:51 -0500 Subject: [PATCH 1/3] Update Reference.md --- docs/Reference.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/Reference.md b/docs/Reference.md index 8227587..11d8afd 100644 --- a/docs/Reference.md +++ b/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 From 688b51967e528709b6e659defc474e1b8c0cbd70 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 28 Oct 2023 09:55:47 -0500 Subject: [PATCH 2/3] Update Logging.md --- docs/Logging.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/Logging.md b/docs/Logging.md index 66d09f0..46ea9f0 100644 --- a/docs/Logging.md +++ b/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 `` and `` HTML tags as needed. If you wish to end the table and add any other HTML, simple include the `` 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+="Free DRAM:" + String(esp_get_free_internal_heap_size()) + " bytes\n"; + r+="

Click Here to Access HomeSpan Repo

"; +} +``` + +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! --- From b41bb653dcb23dc92016968358b6140dd3279a22 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Sat, 28 Oct 2023 09:59:52 -0500 Subject: [PATCH 3/3] Update README.md --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2cd1a82..006db2e 100644 --- a/README.md +++ b/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 version numbers for the Sodium and MbedTLS libraries, HomeKit pairing status, and a text description of Reset Reason code + * 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 * 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.