OmEspHelpers
OmWebPages.h
1 /*
2  * OmWebPages.h
3  * 2016-11-20
4  *
5  * This class implements a description for simple,
6  * structured web pages. It offers simplicity at the
7  * expense of flexibility. It's intended for simple
8  * IoT user interfaces, and very basic text & information
9  * display. Also, designed for small screens like phones.
10  *
11  * This code is platform agnostic.
12  *
13  * EXAMPLE
14  *
15  * your callback proc:
16  * void buttonProc(const char *page, const char *item, int value, int ref1, void *ref2)
17  * {
18  * digitalWrite(LED_BUILTIN, ref1);
19  * }
20  *
21  * void buttonMomentaryProc(const char *page, const char *item, int value, int ref1, void *ref2)
22  * {
23  * digitalWrite(LED_BUILTIN, value);
24  * }
25  *
26  * in setup():
27  * OmWebPages p
28  * p.beginPage("Home");
29  * p.addButton("ledOn", buttonProc, 0);
30  * p.addButton("ledOff", buttonProc, 1);
31  * p.addButton("ledMomentary", buttonMomentaryProc);
32  *
33  * OmWebServer s;
34  * s.addWifi("My Network", "password1234");
35  * s.setHandler(p);
36  * s.setStatusLedPin(-1);
37  *
38  * in loop():
39  * s.tick(); // in turn calls OmWebPages
40  *
41  *
42  * OmWebPages p;
43  */
44 
45 #ifndef __OmWebPages__
46 #define __OmWebPages__
47 
48 #include <vector>
49 #include "OmXmlWriter.h"
50 #include "OmUtil.h"
51 #include "OmWebRequest.h"
52 
53 // just for IPAddress :-/
54 #ifdef ARDUINO_ARCH_ESP8266
55 #include "ESP8266WiFi.h"
56 #endif
57 #ifdef ARDUINO_ARCH_ESP32
58 #include "WiFi.h"
59 #endif
60 #if NOT_ARDUINO
61 #include <string>
62 #define String std::string
63 typedef unsigned char IPAddress[4];
64 #endif
65 
66 #ifndef UNUSED
67 #define UNUSED(x) (void)(x)
68 #endif
69 
71 typedef void (* OmWebActionProc)(const char *pageName, const char *parameterName, int value, int ref1, void *ref2);
72 
74 typedef void (* HtmlProc)(OmXmlWriter &writer, int ref1, void *ref2);
75 
77 typedef void (* OmUrlHandlerProc)(OmXmlWriter &writer, OmWebRequest &request, int ref1, void *ref2);
78 
80 class Page;
82 class PageItem;
84 class UrlHandler;
85 
88 {
89 public:
90  OmWebPageItem(PageItem *privateItem);
92  const char *getName();
94  void setName(const char *name);
96  void setVisible(bool visible);
98  void setVisible(bool visible, const char *name, int value);
100  int getValue();
102  void setValue(int value);
103 
104  PageItem *privateItem;
105 };
106 
108 {
109 public:
110  IPAddress clientIp;
111  int clientPort;
112  IPAddress serverIp;
113  int serverPort;
114  const char *bonjourName = "";
115  long long uptimeMillis;
116  const char *ssid = "";
117  const char *ap = "";
118 };
119 
122 {
123 public:
125  OmWebPages();
126  ~OmWebPages();
127 
131  void setBuildDateAndTime(const char *date, const char *time, const char *file = NULL);
132 
133  // +----------------------------------
134  // | Setting up your pages
135  // |
136 
141  void beginPage(const char *pageName);
142 
144  void addPageLink(const char *pageLink, OmWebActionProc proc = NULL, int ref1 = 0, void *ref2 = 0);
145 
147  OmWebPageItem *addButton(const char *buttonName, OmWebActionProc proc = NULL, int ref1 = 0, void *ref2 = 0);
148 
152  OmWebPageItem *addButtonWithLink(const char *buttonName, const char *url, OmWebActionProc proc = NULL, int ref1 = 0, void *ref2 = 0);
153 
155  OmWebPageItem *addSlider(const char *sliderName, OmWebActionProc proc = NULL, int value = 0, int ref1 = 0, void *ref2 = 0);
156 
158  OmWebPageItem *addSlider(int rangeLow, int rangeHigh, const char *sliderName, OmWebActionProc proc = NULL, int value = 0, int ref1 = 0, void *ref2 = 0);
159 
161  OmWebPageItem *addTime(const char *itemName, OmWebActionProc proc = NULL, int value = 0, int ref1 = 0, void *ref2 = 0);
162 
164  OmWebPageItem *addColor(const char *itemName, OmWebActionProc proc = NULL, int value = 0, int ref1 = 0, void *ref2 = 0);
165 
167  OmWebPageItem *addSelect(const char *itemName, OmWebActionProc proc = NULL, int value = 0, int ref1 = 0, void *ref2 = 0);
169  void addSelectOption(const char *optionName, int optionValue);
170 
175  OmWebPageItem *addCheckbox(const char *itemName, const char *checkboxName, OmWebActionProc proc = NULL, int value = 0, int ref1 = 0, void *ref2 = 0);
177  void addCheckboxX(const char *checkboxName, int value = 0); // additional checkboxes.
178 
179 
181  void addHtml(HtmlProc proc, int ref1 = 0, void *ref2 = 0);
182 
184  void addStaticHtml(String staticHtml);
185 
187  void allowHeader(bool allowHeader);
188 
190  void allowFooter(bool allowFooter);
191 
192  // +----------------------------------
193  // | Setting up arbitrary handler procs
194  // |
195 
197  void addUrlHandler(const char *path, OmUrlHandlerProc proc, int ref1 = 0, void *ref2 = 0);
198 
200  void addUrlHandler(OmUrlHandlerProc proc, int ref1 = 0, void *ref2 = 0);
201 
202 
203  // +----------------------------------
204  // | Handling Requests
205  // |
206 
213  bool handleRequest(OmIByteStream *consumer, const char *pathAndQuery, OmRequestInfo *requestInfo);
214 
215  // +----------------------------------
216  // | HtmlProc helpers
217  // | Call these from within your HtmlProc to use the builtin styling and formatting.
218  // |
219 
221  void renderPageButton(OmXmlWriter &w, const char *pageName);
222 
223  // +----------------------------------
224  // | Global Settings
225  // | Setup calls that affect all pages
226  // |
227 
229  void setHeaderProc(HtmlProc headerProc);
231  void setFooterProc(HtmlProc footerProc);
232 
234  void setBgColor(int bgColor); // like 0xff0000 red, 0xffffff white.
235 
236  // +----------------------------------
237  // | Statistics
238  // | Publicly readable variables giving insight into the server behavior.
239  // |
240 
242  unsigned int requestsAll = 0;
243 
245  unsigned int requestsParam = 0;
246 
248  unsigned int greatestRenderLength = 0;
249 
250  // +----------------------------------
251  // | Internal methods
252  // | But you could use them in a urlHandler.
253  // |
254  void renderInfo(OmXmlWriter &w); // builtin "_info" page
255  void renderStatusXml(OmXmlWriter &w); // builtin "_status" url
256 
258  void renderHttpResponseHeader(const char *contentType, int response);
259 
261  static void renderPageBeginning(OmXmlWriter &w, const char *pageTitle = "", int bgColor = 0xffffff);
262  void renderDefaultFooter(OmXmlWriter &w); // builtin footer nav buttons
263 
264  static void renderPageBeginningWithRedirect(OmXmlWriter &w, const char *redirectUrl, int redirectSeconds, const char *pageTitle = "", int bgColor = 0xffffff);
265 
266  void setValue(const char *pageName, const char *itemName, int value);
267  int getValue(const char *pageName, const char *itemName);
268 
269  char httpBase[32]; // string of form "http://10.0.1.1/" that can prefix all internal links, esp since OTA update doesnt play well with bonjour addresses
270 private:
271 
273  class UrlHandler
274  {
275  public:
276  const char *url = "";
277  OmUrlHandlerProc handlerProc = NULL;
278  int ref1 = 0;
279  void *ref2 = 0;
280  };
281 
282  bool doAction(const char *pageName, const char *itemName);
283  static void renderStyle(OmXmlWriter &w, int bgColor = 0xffffff);
284  static void renderScript(OmXmlWriter &w);
285 
287  void renderTopMenu(OmXmlWriter &w);
288 
289  Page *findPage(const char *pageName, bool byId = false);
290  PageItem *findPageItem(const char *pageName, const char *itemName, bool byId = false);
291 
292  Page *homePage = NULL;
293  std::vector<Page *> pages;
294  std::vector<UrlHandler *>urlHandlers;
295  Page *currentPage = 0; // if a page is active.
296 
297  UrlHandler urlHandler; // generic handler if no specific urls match. Over to you!
298 
299  PageItem *currentSelect = 0; // addSelectOption applies to the most recently begun select.
300  PageItem *currentCheckboxes = 0; // addCheckboxX adds another checkbox here
301 
302  HtmlProc headerProc = NULL;
303  HtmlProc footerProc = NULL;
304 
305  OmXmlWriter *wp = 0; // writer pointer during callbacks.
306 
307  int bgColor = 0xffffff;
308 
309  const char *__date__;
310  const char *__time__;
311  const char *__file__;
312 public:
313  OmRequestInfo *ri = 0; // request metadate during callbacks
314 };
315 
316 extern OmWebPages OmWebPagesSingleton;
317 
318 #endif /* defined(__OmWebPages__) */
OmWebPages::addSelectOption
void addSelectOption(const char *optionName, int optionValue)
Add one selectable item, and its integer value if selected.
Definition: OmWebPages.cpp:809
OmWebPageItem::setValue
void setValue(int value)
changes the value, but only visible on next browser load or refresh
Definition: OmWebPages.cpp:91
OmWebPages::renderHttpResponseHeader
void renderHttpResponseHeader(const char *contentType, int response)
in a OmUrlHandlerProc, set the mimetype (like "text/plain") and response code (200 is OK)
Definition: OmWebPages.cpp:1467
OmXmlWriter
Definition: OmXmlWriter.h:91
OmWebPages::allowHeader
void allowHeader(bool allowHeader)
By default, any header proc is used on every page. Disable for current page here.
Definition: OmWebPages.cpp:703
OmWebPages::greatestRenderLength
unsigned int greatestRenderLength
Definition: OmWebPages.h:248
OmWebPages::addStaticHtml
void addStaticHtml(String staticHtml)
Add a string of static prebuilt HTML. Included in web page unchecked, you're on your own!
Definition: OmWebPages.cpp:852
OmWebPages::addButtonWithLink
OmWebPageItem * addButtonWithLink(const char *buttonName, const char *url, OmWebActionProc proc=NULL, int ref1=0, void *ref2=0)
Add a button on the current page, which fires a page redirect after the button-up....
Definition: OmWebPages.cpp:745
OmWebPages::addButton
OmWebPageItem * addButton(const char *buttonName, OmWebActionProc proc=NULL, int ref1=0, void *ref2=0)
Add a button on the current page. Calls the action proc with value 1 for press, 0 for release.
Definition: OmWebPages.cpp:734
OmWebPages::addPageLink
void addPageLink(const char *pageLink, OmWebActionProc proc=NULL, int ref1=0, void *ref2=0)
Add a link on the current page that goes to another page. Also can call an action proc.
Definition: OmWebPages.cpp:723
OmWebPages::addSelect
OmWebPageItem * addSelect(const char *itemName, OmWebActionProc proc=NULL, int value=0, int ref1=0, void *ref2=0)
Begin a menu select control. Choices are added with addSelectOption()
Definition: OmWebPages.cpp:796
OmWebPages::requestsParam
unsigned int requestsParam
Definition: OmWebPages.h:245
OmWebRequest
Definition: OmWebRequest.h:54
OmWebPages::addUrlHandler
void addUrlHandler(const char *path, OmUrlHandlerProc proc, int ref1=0, void *ref2=0)
Add an arbitrary URL handler.
Definition: OmWebPages.cpp:1447
OmWebPages::setBgColor
void setBgColor(int bgColor)
set the background color for next web request, 0xRRGGBB
Definition: OmWebPages.cpp:1442
OmWebPages::addHtml
void addHtml(HtmlProc proc, int ref1=0, void *ref2=0)
Add a block of custom dynamic HTML to the page. Your proc is called each time the page is requested.
Definition: OmWebPages.cpp:842
OmWebPages::handleRequest
bool handleRequest(OmIByteStream *consumer, const char *pathAndQuery, OmRequestInfo *requestInfo)
Explicitly process a request. (Not typically used.) If you used omWebServer.setHandler(omWebPages),...
Definition: OmWebPages.cpp:1293
OmWebPages::addCheckbox
OmWebPageItem * addCheckbox(const char *itemName, const char *checkboxName, OmWebActionProc proc=NULL, int value=0, int ref1=0, void *ref2=0)
Add a single checkbox. If checkboxName is NULL, then the first checkbox will be added by addCheckboxX...
Definition: OmWebPages.cpp:818
OmIByteStream
Definition: OmXmlWriter.h:53
OmWebPages::allowFooter
void allowFooter(bool allowFooter)
By default, any footer proc is used on every page. Disable for current page here.
Definition: OmWebPages.cpp:708
OmWebPageItem::setVisible
void setVisible(bool visible)
show or hide
Definition: OmWebPages.cpp:74
OmWebPageItem::getValue
int getValue()
current value
Definition: OmWebPages.cpp:87
OmWebPageItem::getName
const char * getName()
current name
Definition: OmWebPages.cpp:64
OmWebPages::setHeaderProc
void setHeaderProc(HtmlProc headerProc)
Override the default header html.
Definition: OmWebPages.cpp:713
OmWebPages::addTime
OmWebPageItem * addTime(const char *itemName, OmWebActionProc proc=NULL, int value=0, int ref1=0, void *ref2=0)
Add a time-input.
Definition: OmWebPages.cpp:772
OmWebPages
A class that routes and serves web pages, and manages control values, typically works with OmWebServe...
Definition: OmWebPages.h:122
OmWebPages::renderPageButton
void renderPageButton(OmXmlWriter &w, const char *pageName)
Within an HtmlProc: Adds a floating link-button to another page.
Definition: OmWebPages.cpp:1230
PageItem
Definition: OmWebPages.cpp:31
OmWebPages::requestsAll
unsigned int requestsAll
Definition: OmWebPages.h:242
OmWebPageItem::setName
void setName(const char *name)
change name
Definition: OmWebPages.cpp:69
OmWebPages::addSlider
OmWebPageItem * addSlider(const char *sliderName, OmWebActionProc proc=NULL, int value=0, int ref1=0, void *ref2=0)
Add a slider control on the current page. The range is 0 to 100, and calls your param proc when chang...
Definition: OmWebPages.cpp:753
OmWebPages::addColor
OmWebPageItem * addColor(const char *itemName, OmWebActionProc proc=NULL, int value=0, int ref1=0, void *ref2=0)
Add a color-input, int value is 0xRRGGBB.
Definition: OmWebPages.cpp:784
OmWebPages::OmWebPages
OmWebPages()
Definition: OmWebPages.cpp:625
OmWebPages::setFooterProc
void setFooterProc(HtmlProc footerProc)
Override the default footer html.
Definition: OmWebPages.cpp:718
OmWebPages::addCheckboxX
void addCheckboxX(const char *checkboxName, int value=0)
Add additional checkboxes.
Definition: OmWebPages.cpp:833
OmWebPages::setBuildDateAndTime
void setBuildDateAndTime(const char *date, const char *time, const char *file=NULL)
say p.setBuildDateAndTime(DATE, TIME) so the info web page can display it.
Definition: OmWebPages.cpp:660
OmWebPages::beginPage
void beginPage(const char *pageName)
Start defining a new page. Subsequent calls like addButton() affect this page. If a page of this name...
Definition: OmWebPages.cpp:679
OmWebPageItem
Definition: OmWebPages.h:88
OmRequestInfo
Definition: OmWebPages.h:108
Page
Definition: OmWebPages.cpp:97
OmWebPages::renderPageBeginning
static void renderPageBeginning(OmXmlWriter &w, const char *pageTitle="", int bgColor=0xffffff)
in a OmUrlHandlerProc Render the beginning of the page, leaving <body> element open and ready.
Definition: OmWebPages.cpp:1148