Merge pull request #44 from Hieromon/enhance/v154

Enhance/v154

README.md

@@ -1,8 +1,9 @@
 # PageBuilder - HTML assembly aid for ESP8266/ESP32 WebServer
 
 [![GitHub release](https://img.shields.io/github/v/release/Hieromon/PageBuilder)](https://github.com/Hieromon/PageBuilder/releases)
-[![arduino-library-badge](https://www.ardu-badge.com/badge/PageBuilder.svg?)](https://www.ardu-badge.com/PageBuilder)
 [![Build Status](https://github.com/Hieromon/PageBuilder/actions/workflows/build.yml/badge.svg)](https://github.com/Hieromon/PageBuilder/actions/workflows/build.yml)
+[![arduino-library-badge](https://www.ardu-badge.com/badge/PageBuilder.svg?)](https://www.ardu-badge.com/PageBuilder)
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/hieromon/library/PageBuilder.svg?version=1.5.4)](https://registry.platformio.org/packages/libraries/hieromon/PageBuilder?version=1.5.4) 
 [![License](https://img.shields.io/github/license/Hieromon/PageBuilder)](https://github.com/Hieromon/PageBuilder/blob/master/LICENSE)
 
 *An arduino library to create html string in the sketch for ESP8266/ESP32 WebServer.* 
@@ -192,8 +193,8 @@ Returns whether the `name` parameter is specified in the current http request.
 #### PageBuilder constructor
 ```c++
 PageBuilder::PageBuilder();
-PageBuilder::PageBuilder(PageElementVT element, HTTPMethod method = HTTP_ANY, TransferEncoding_t chunked = PB_Auto);
-PageBuilder::PageBuilder(const char* uri, PageElementVT element, HTTPMethod method = HTTP_ANY, TransferEncoding_t chunked = PB_Auto);
+PageBuilder::PageBuilder(PageElementVT element, HTTPMethod method = HTTP_ANY, TransferEncoding_t chunked = PB_Auto, bool CORS = false);
+PageBuilder::PageBuilder(const char* uri, PageElementVT element, HTTPMethod method = HTTP_ANY, TransferEncoding_t chunked = PB_Auto, bool CORS = false);
 ```
 - `element` : **PageElement** container wrapper. Normally, use the brackets to specify initializer.  
   ```c++
@@ -204,6 +205,7 @@ PageBuilder::PageBuilder(const char* uri, PageElementVT element, HTTPMethod meth
 - `method` : Enum value of HTTP method as `HTTP_ANY`, `HTTP_GET`, `HTTP_POST` that page should respond.
 - `uri` : A URI string of the page.
 - `chunked` : Enumeration type for the transfer-encoding as TransferEncoding_t type. `PB_Auto`, `PB_ByteStream`, `PB_Chunk` can be specified. If `PB_Auto` is specified, would be determined automatically to switch them the chunk. Its criteria is defined with `MAX_CONTENTBLOCK_SIZE` macro in `PageBuilder.cpp` code. If `PB_ByteStream` is specified, PageBuilder will determine the way of sending either String writing or byte stream according to a size of the content.
+- `CORS` : Include a header allowing cross-origin access in the current page response.
 
 #### PageElement constructor
 ```c++
@@ -279,6 +281,9 @@ The sketch sends an http response in the *Token func* then **PageBuilder** shoul
 #### `void PageBuilder::clearElements(void)`
 Clear enrolled **PageElement** objects in the **PageBuilder**.
 
+#### `void PageBuilder::enableCORS(const bool CORS)`
+Include a header allowing [Cross-Origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) access in the current page response.
+
 #### `void PageBuilder::exitCanHandle(PrepareFuncT prepareFunc)`
 - `prepareFunc` : User function instead of canHandle. This user function would be invoked at all request received.  
 ```bool prepareFunc(HTTPMethod method, String uri);```  
@@ -377,6 +382,9 @@ Since PageBuilder 1.4.2, the default file system has changed SPIFFS to LittleFS.
 
 ## Change log
 
+#### [1.5.4] 2022-12-26
+- Supports an http response to allow CORS.
+
 #### [1.5.3] 2022-03-02
 - Supports [LittleFS_esp32](https://github.com/lorol/LITTLEFS) legacy library with ESP32 Arduino core 1.0.6 or less.
 - Migrate the CI platform to GitHub actions.

library.json

@@ -13,7 +13,7 @@
     "espressif8266",
     "espressif32"
   ],
-  "version": "1.5.3",
+  "version": "1.5.4",
   "license": "MIT",
   "headers": "PageBuilder.h"
 }

library.properties

@@ -1,5 +1,5 @@
 name=PageBuilder
-version=1.5.3
+version=1.5.4
 author=Hieromon Ikasamo <hieromon@gmail.com>
 maintainer=Hieromon Ikasamo <hieromon@gmail.com>
 sentence=HTML string assembly aid library for ESP8266/ESP32 WebServer.

src/PageBuilder.cpp

@@ -3,8 +3,8 @@
  *  PageElement.
  *  @file   PageBuilder.cpp
  *  @author hieromon@gmail.com
- *  @version    1.5.1
- *  @date   2021-11-14
+ *  @version    1.5.4
+ *  @date   2022-12-01
  *  @copyright  MIT license.
  */
 
@@ -363,10 +363,12 @@ PageBuilder::PageBuilder()
  * @param noCache   Presence or absence of cache control headers generated by this page by default.
  * @param cancel    Whether this page is HTML construction only and does not involve page submission.
  * @param chunked   Default transfer encoding.
+ * @param CORS      Allows the inclusion of Access-Control-Allow-Origin in the response header, where Origin is always `*`.
  */
-PageBuilder::PageBuilder(PageElementVT elements, HTTPMethod method, bool noCache, bool cancel, TransferEncoding_t chunked)
+PageBuilder::PageBuilder(PageElementVT elements, HTTPMethod method, bool noCache, bool cancel, TransferEncoding_t chunked, bool CORS)
 : _elements(elements)
 , _method(method)
+, _cors(CORS)
 , _noCache(noCache)
 , _cancel(cancel)
 , _enc(chunked)
@@ -380,11 +382,13 @@ PageBuilder::PageBuilder(PageElementVT elements, HTTPMethod method, bool noCache
  * @param noCache   Presence or absence of cache control headers generated by this page by default.
  * @param cancel    Whether this page is HTML construction only and does not involve page submission.
  * @param chunked   Default transfer encoding.
+ * @param CORS      Allows the inclusion of Access-Control-Allow-Origin in the response header, where Origin is always `*`.
  */
-PageBuilder::PageBuilder(const char* uri, PageElementVT elements, HTTPMethod method, bool noCache, bool cancel, TransferEncoding_t chunked)
+PageBuilder::PageBuilder(const char* uri, PageElementVT elements, HTTPMethod method, bool noCache, bool cancel, TransferEncoding_t chunked, bool CORS)
 : _uri(String(uri))
 , _elements(elements)
 , _method(method)
+, _cors(CORS)
 , _noCache(noCache)
 , _cancel(cancel)
 , _enc(chunked)
@@ -609,6 +613,14 @@ void PageBuilder::_handle(int code, WebServer& server) {
     for (auto& httpHeader : _headersNocache) {
       server.sendHeader(String(FPSTR(httpHeader.name)), String(FPSTR(httpHeader.value)));
     }
+
+  // Include Access-Control-Allow-Origin in the response header according to the
+  // _cors member of the current page. By default, _cors is false and the
+  // response header typically has no "Access-Control-Allow-Origin".
+  // PageBuilder instance with PageElements that access resources cross-origin
+  // must enable the CORS.
+  PB_DBG("%s enable CORS: %s\n", _uri.c_str(), _cors ? "true" : "false");
+  server.enableCORS(_cors);
 
   if (_enc == Auto) {
     // TransferEncoding:Auto

src/PageBuilder.h

@@ -2,8 +2,8 @@
  * Declaration of PageBuilder class and accompanying PageElement, PageArgument class.
  * @file PageBuilder.h
  * @author hieromon@gmail.com
- * @version  1.5.3
- * @date 2022-03-02
+ * @version  1.5.4
+ * @date 2022-12-01
  * @copyright  MIT license.
  */
 
@@ -320,8 +320,8 @@ class PageBuilder : public RequestHandler {
   typedef std::function<void(const String&, const HTTPUpload&)> UploadFuncT;
 
   PageBuilder();
-  explicit PageBuilder(PageElementVT elements, HTTPMethod method = HTTP_ANY, bool noCache = true, bool cancel = false, TransferEncoding_t chunked = Auto);
-  PageBuilder(const char* uri, PageElementVT elements, HTTPMethod method = HTTP_ANY, bool noCache = true, bool cancel = false, TransferEncoding_t chunked = Auto);
+  explicit PageBuilder(PageElementVT elements, HTTPMethod method = HTTP_ANY, bool noCache = true, bool cancel = false, TransferEncoding_t chunked = Auto, bool CORS = false);
+  PageBuilder(const char* uri, PageElementVT elements, HTTPMethod method = HTTP_ANY, bool noCache = true, bool cancel = false, TransferEncoding_t chunked = Auto, bool CORS = false);
   virtual ~PageBuilder() {}
   void  addElement(PageElement& element) { _elements.push_back(element); }
   void  atNotFound(WebServer& server);
@@ -332,6 +332,7 @@ class PageBuilder : public RequestHandler {
   virtual bool  canHandle(HTTPMethod requestMethod, PageBuilderUtil::URI_TYPE_SIGNATURE requestUri) override;
   virtual bool  canUpload(PageBuilderUtil::URI_TYPE_SIGNATURE uri) override;
   void  clearElements(void);
+  void  enableCORS(const bool CORS) { _cors = CORS; }
   void  exitCanHandle(PrepareFuncT prepareFunc) { _canHandle = prepareFunc; }
   bool  handle(WebServer& server, HTTPMethod requestMethod, PageBuilderUtil::URI_TYPE_SIGNATURE requestUri) override;
   void  insert(WebServer& server) { server.addHandler(this); }
@@ -348,6 +349,7 @@ class PageBuilder : public RequestHandler {
   PageElementVT _elements;            /**< Array of PageElements */
   HTTPMethod    _method;              /**< Requested HTTP method */
   UploadFuncT   _upload;              /**< Upload handler */
+  bool          _cors;                /**< Allow cross-origin */
 
  private:
   size_t  _getApproxSize(void) const; /**< Calculate an approximate generating size o the HTML */