EmbAJAX.h

Go to the documentation of this file.

/*
 * 
 * EmbAJAX - Simplistic framework for creating and handling displays and controls on a WebPage served by an Arduino (or other small device).
 * 
 * Copyright (C) 2018-2023 Thomas Friedrichsmeier
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published
 * by the Free Software Foundation, either version 3 of the License, or (at
 * your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 * 
**/
#ifndef EMBAJAX_H
#define EMBAJAX_H
 
#include <Arduino.h>
 
#define EMBAJAX_MAX_ID_LEN 16
 
// Set to a value above 0 for diagnostics on Serial and browser console
// #define EMBAJAX_DEBUG 3
 
//#define USE_PROGMEM_STRINGS 0
 
#if !defined USE_PROGMEM_STRINGS
 #if defined(memcpy_P) && (memcpy_P == memcpy)
  #define USE_PROGMEM_STRINGS 0
 #else
  #define USE_PROGMEM_STRINGS 1
 #endif
#endif
 
#include "macro_definitions.h"
 
class EmbAJAXOutputDriverBase;
class EmbAJAXElement;
class EmbAJAXContainerBase;
class EmbAJAXPageBase;
 
class EmbAJAXBase {
public:
    virtual void print() const = 0;
    static void setDriver(EmbAJAXOutputDriverBase *driver) {
        _driver = driver;
    }
    virtual bool sendUpdates(uint16_t since, bool first) {
        return false;
    }
    virtual EmbAJAXElement* toElement() {
        return 0;
    }
    void setVisible(bool visible) {
        setBasicProperty(Visibility, visible);
    }
    void setEnabled(bool enabled) {
        setBasicProperty(Enabledness, enabled);
    }
    enum Property {
        Visibility=0,
        Enabledness=1,
        Value=2,
        FirstElementSpecificProperty=3,
        HTMLAllowed=7
    };
    virtual EmbAJAXElement* findChild(const char*id) const {
        return 0;
    }
protected:
template<size_t NUM> friend class EmbAJAXContainer;
    virtual void setBasicProperty(uint8_t num, bool status) {};
 
    static EmbAJAXOutputDriverBase *_driver;
    static char itoa_buf[8];
    constexpr static const char null_string[1] = "";
 
    void printChildren(EmbAJAXBase** children, size_t num) const;
    bool sendUpdates(EmbAJAXBase** children, size_t num, uint16_t since, bool first);
    EmbAJAXElement* findChild(EmbAJAXBase** children, size_t num, const char*id) const;
    void printPage(EmbAJAXBase** children, size_t num, const char* _title, const char* _header, uint16_t _min_interval) const;
    void handleRequest(EmbAJAXBase** children, size_t num, void (*change_callback)());
};
 
class EmbAJAXOutputDriverBase {
public:
    EmbAJAXOutputDriverBase() {
        _revision = 1;
        next_revision = _revision;
    }
 
    virtual void printHeader(bool html) = 0;
    virtual void printContent(const char *content) = 0;
    virtual const char* getArg(const char* name, char* buf, int buflen) = 0;
    virtual void installPage(EmbAJAXPageBase *page, const char *path, void (*change_callback)()=0) = 0;
    virtual void loopHook() = 0;
 
    uint16_t revision() const {
        return _revision;
    }
    uint16_t setChanged() {
        next_revision = _revision+1;
        return (next_revision);
    }
    void nextRevision() {
        _revision = next_revision;
    }
    enum QuoteMode {
        NotQuoted,  
        JSQuoted,   
        HTMLQuoted  
    };
    void printFiltered(const char* value, QuoteMode quoted, bool HTMLescaped) {
        _printFiltered(value, quoted, HTMLescaped);
        commitBuffer();
    }
    inline void printJSQuoted (const char* value) { printFiltered (value, JSQuoted, false); }
    inline void printHTMLQuoted (const char* value) { printFiltered (value, HTMLQuoted, false); }
    void printAttribute(const char* name, const char* value);
    void printAttribute(const char* name, const int32_t value);
    void _printContentF(const char* fmt, ...);
#if USE_PROGMEM_STRINGS
    void _printContentF(const __FlashStringHelper*, ...);
#endif
private:
    void _printFiltered(const char* value, QuoteMode quoted, bool HTMLescaped);
    void _printContent(const char* content);
    void _printChar(const char content);
    void commitBuffer();
    const int _bufsize = 64;
    char _buf[64];
    int _bufpos = 0;
    uint16_t _revision;
    uint16_t next_revision;
};
 
#define MAKE_EmbAJAXPage(name, title, header_add, ...) \
    EmbAJAXBase* name##_elements[] = {__VA_ARGS__}; \
    EmbAJAXPage<sizeof(name##_elements)/sizeof(EmbAJAXBase*)> name(name##_elements, title, header_add);
 
class EmbAJAXStatic : public EmbAJAXBase {
public:
    EmbAJAXStatic(const char* content) {
        _content = content;
    }
    void print() const override {
        _driver->printContent(_content);
    }
protected:
    const char* _content;
};
 
class EmbAJAXConnectionIndicator : public EmbAJAXBase {
public:
    EmbAJAXConnectionIndicator(const char* content_ok = default_ok, const char* content_fail = default_fail) {
        _content_ok = content_ok;
        _content_fail = content_fail;
    }
    void print() const override;
    static constexpr const char* default_ok = {"<span style=\"background-color:green;\">OK</span>"};
    static constexpr const char* default_fail = {"<span style=\"background-color:red;\">FAIL</span>"};
private:
    const char* _content_ok;
    const char* _content_fail;
};
 
class EmbAJAXElement : public EmbAJAXBase {
public:
    EmbAJAXElement(const char* id);
 
    const char* id() const {
        return _id;
    }
    bool sendUpdates(uint16_t since, bool first) override;
 
    virtual const char* value(uint8_t which = EmbAJAXBase::Value) const {
        if (which == EmbAJAXBase::Visibility) return (basicProperty (EmbAJAXBase::Visibility) ? "" : "none");
        if (which == EmbAJAXBase::Enabledness) return (basicProperty (EmbAJAXBase::Enabledness) ? "" : "disabled");
        return 0;
    }
 
    virtual bool valueNeedsEscaping(uint8_t which = EmbAJAXBase::Value) const {
        return false;
    }
 
    virtual const char* valueProperty(uint8_t which = EmbAJAXBase::Value) const {
        if (which == EmbAJAXBase::Visibility) return ("style.display");
        if (which == EmbAJAXBase::Enabledness) return ("disabled");
        return 0;
    }
 
    virtual void updateFromDriverArg(const char* argname) {
        return;
    }
 
    EmbAJAXElement *toElement() override final {
        return this;
    }
protected:
    void setBasicProperty(uint8_t num, bool status) override;
    bool basicProperty(uint8_t num) const {
        return (_flags & (1 << num));
    }
    byte _flags;
template<size_t NUM> friend class EmbAJAXPage;
friend class EmbAJAXBase;
    const char* _id;
    void setChanged();
    bool changed(uint16_t since);
    void printTextInput(size_t size, const char* value) const;
private:
    uint16_t revision;
};
 
class EmbAJAXMutableSpan : public EmbAJAXElement {
public:
    EmbAJAXMutableSpan(const char* id) : EmbAJAXElement(id) {
        _value = 0;
    }
    void print() const override;
    const char* value(uint8_t which = EmbAJAXBase::Value) const override;
    const char* valueProperty(uint8_t which = EmbAJAXBase::Value) const override;
    void setValue(const char* value, bool allowHTML = false);
    bool valueNeedsEscaping(uint8_t which=EmbAJAXBase::Value) const override;
private:
    const char* _value;
};
 
template<size_t SIZE> class EmbAJAXTextInput : public EmbAJAXElement {
public:
    EmbAJAXTextInput(const char* id) : EmbAJAXElement(id) {
        _value[0] = '\0';
    }
    void print() const override {
        EmbAJAXElement::printTextInput(SIZE, _value);
    }
    const char* value(uint8_t which = EmbAJAXBase::Value) const override {
        if (which == EmbAJAXBase::Value) return _value;
        return EmbAJAXElement::value(which);
    }
    const char* valueProperty(uint8_t which = EmbAJAXBase::Value) const override {
        if (which == EmbAJAXBase::Value) return "value";
        return EmbAJAXElement::valueProperty(which);
    }
    void setValue(const char* value) {
        strncpy(_value, value, SIZE);
        setChanged();
    }
    void updateFromDriverArg(const char* argname) override {
        _driver->getArg(argname, _value, SIZE);
    }
protected:
    char _value[SIZE];
};
 
class EmbAJAXSlider : public EmbAJAXElement {
public:
    EmbAJAXSlider(const char* id, int16_t min, int16_t max, int16_t initial);
    void print() const override;
    const char* value(uint8_t which = EmbAJAXBase::Value) const override;
    const char* valueProperty(uint8_t which = EmbAJAXBase::Value) const override;
    void setValue(int16_t value);
    int16_t intValue() const {
        return _value;
    }
    void updateFromDriverArg(const char* argname) override;
private:
    int16_t _min, _max, _value;
};
 
class EmbAJAXColorPicker : public EmbAJAXElement {
public:
    EmbAJAXColorPicker(const char* id, uint8_t r, uint8_t g, uint8_t b);
    void print() const override;
    const char* value(uint8_t which = EmbAJAXBase::Value) const override;
    const char* valueProperty(uint8_t which = EmbAJAXBase::Value) const override;
    void setColor(uint8_t r, uint8_t g, uint8_t b);
    uint8_t red() const;
    uint8_t green() const;
    uint8_t blue() const;
    void updateFromDriverArg(const char* argname) override;
private:
    uint8_t _r, _g, _b;
};
 
class EmbAJAXPushButton : public EmbAJAXElement {
public:
    EmbAJAXPushButton(const char* id, const char* label, void (*callback)(EmbAJAXPushButton*));
    void print() const override;
    void setText(const char* label, bool allowHTML = false);
    const char* value(uint8_t which = EmbAJAXBase::Value) const override;
    const char* valueProperty(uint8_t which = EmbAJAXBase::Value) const override;
    bool valueNeedsEscaping(uint8_t which=EmbAJAXBase::Value) const override;
    void updateFromDriverArg(const char* argname) override;
protected:
    void (*_callback)(EmbAJAXPushButton*);
    const char* _label;
};
 
class EmbAJAXMomentaryButton : public EmbAJAXPushButton {
public:
    EmbAJAXMomentaryButton(const char* id, const char* label, uint16_t timeout=600, void (*callback)(EmbAJAXPushButton*)=0);
    void print() const override;
    enum Status {
        Pressed,
        MaybePressed,
        Released
    };
    Status status() const;
    void updateFromDriverArg(const char* argname) override;
private:
    uint32_t latest_ping;
    uint16_t _timeout;
};
 
class EmbAJAXRadioGroupBase;
 
class EmbAJAXCheckButton : public EmbAJAXElement {
public:
    EmbAJAXCheckButton(const char* id, const char* label, bool checked=false);
    void print() const override;
    const char* value(uint8_t which = EmbAJAXBase::Value) const override;
    const char* valueProperty(uint8_t which = EmbAJAXBase::Value) const override;
    void setChecked(bool checked);
    bool isChecked() const {
        return _checked;
    }
    void updateFromDriverArg(const char* argname) override;
private:
    bool _checked;
    const char* _label;
template<size_t NUM> friend class EmbAJAXRadioGroup;
    EmbAJAXCheckButton() : EmbAJAXElement("") {};
    EmbAJAXRadioGroupBase* radiogroup;
};
 
class EmbAJAXRadioGroupBase {
protected:
    EmbAJAXRadioGroupBase() {};
friend class EmbAJAXCheckButton;
    virtual void selectButton(EmbAJAXCheckButton* which) = 0;
    const char* _name;
};
 
template<size_t NUM> class EmbAJAXContainer : public EmbAJAXBase {
public:
    EmbAJAXContainer(EmbAJAXBase *children[NUM]) : EmbAJAXBase() {
        _children = children;
    }
    void print() const override {
        EmbAJAXBase::printChildren(_children, NUM);
    }
    bool sendUpdates(uint16_t since, bool first) override {
        return EmbAJAXBase::sendUpdates(_children, NUM, since, first);
    }
    EmbAJAXElement* findChild(const char*id) const override final {
        return EmbAJAXBase::findChild(_children, NUM, id);
    }
protected:
    void setBasicProperty(uint8_t num, bool status) override {
        for (uint8_t i = 0; i < NUM; ++i) {
            _children[i]->setBasicProperty(num, status);
        }
    }
template<size_t> friend class EmbAJAXHideableContainer;
    EmbAJAXContainer() {};
    EmbAJAXBase** _children;
};
 
template<size_t NUM> class EmbAJAXHideableContainer : public EmbAJAXElement {
public:
    EmbAJAXHideableContainer(const char* id, EmbAJAXBase *children[NUM]) : EmbAJAXElement(id) {
        _childlist = EmbAJAXContainer<NUM>(children);
    }
    void print() const override {
        _driver->printFormatted("<div id=", HTML_QUOTED_STRING(_id), ">");
        _childlist.print();
        _driver->printContent("</div>");
    }
    EmbAJAXElement* findChild(const char* id) const override {
        return _childlist.findChild(id);
    }
    bool sendUpdates(uint16_t since, bool first) override {
        bool sent = EmbAJAXElement::sendUpdates(since, first);
        bool sent2 = _childlist.sendUpdates(since, first && !sent);
        return sent || sent2;
    }
protected:
    void setBasicProperty(uint8_t num, bool status) override {
        EmbAJAXElement::setBasicProperty(num, status);
        _childlist.setBasicProperty(num, status);
    }
    EmbAJAXContainer<NUM> _childlist;
};
 
template<size_t NUM> class EmbAJAXRadioGroup : public EmbAJAXContainer<NUM>, public EmbAJAXRadioGroupBase {
public:
    EmbAJAXRadioGroup(const char* id_base, const char* options[NUM], uint8_t selected_option = 0) : EmbAJAXContainer<NUM>(), EmbAJAXRadioGroupBase() {
        for (uint8_t i = 0; i < NUM; ++i) {
            char* childid = childids[i];
            strncpy(childid, id_base, EMBAJAX_MAX_ID_LEN-4);
            itoa(i, &(childid[strlen(childid)]), 10);
            buttons[i] = EmbAJAXCheckButton(childid, options[i], i == selected_option);
            buttons[i].radiogroup = this;
            buttonpointers[i] = &buttons[i];
        }
        _current_option = selected_option;
         EmbAJAXContainer<NUM>::_children = buttonpointers;  // Hm, why do I need to specify EmbAJAXContainer<NUM>::, explicitly?
        _name = id_base;
    }
    void selectOption(uint8_t num) {
        for (uint8_t i = 0; i < NUM; ++i) {
            buttons[i].setChecked(i == num);
        }
        _current_option = num;  // NOTE: might be outside of range, but that's ok, signifies "none selected"
    }
    uint8_t selectedOption() const {
        return _current_option;
    }
    EmbAJAXBase* button(uint8_t num) {
        if (num < NUM) return (&buttons[num]);
        return 0;
    }
private:
    EmbAJAXCheckButton buttons[NUM]; 
    EmbAJAXBase* buttonpointers[NUM];
    char childids[NUM][EMBAJAX_MAX_ID_LEN];
    int8_t _current_option;
    void selectButton(EmbAJAXCheckButton* which) override {
        _current_option = -1;
        for (uint8_t i = 0; i < NUM; ++i) {
            if (which == buttonpointers[i]) {
                _current_option = i;
            } else {
                buttons[i].setChecked(false);
            }
        }
    }
};
 
class EmbAJAXOptionSelectBase : public EmbAJAXElement {
public:
    void selectOption(uint8_t num);
    uint8_t selectedOption() const;
    const char* value(uint8_t which = EmbAJAXBase::Value) const override;
    const char* valueProperty(uint8_t which = EmbAJAXBase::Value) const override;
    void updateFromDriverArg(const char* argname) override;
protected:
    EmbAJAXOptionSelectBase(const char*id, uint8_t current_option) : EmbAJAXElement(id) {
        _current_option = current_option;
    };
    void print(const char* const* _labels, uint8_t NUM) const;
    uint8_t _current_option;
};
 
template<size_t NUM> class EmbAJAXOptionSelect : public EmbAJAXOptionSelectBase {
public:
    EmbAJAXOptionSelect(const char* id, const char* labels[NUM], uint8_t selected_option = 0) : EmbAJAXOptionSelectBase(id, selected_option) {
        for (uint8_t i = 0; i < NUM; ++i) {
            _labels[i] = labels[i];
        }
    }
    void print() const override {
        EmbAJAXOptionSelectBase::print(_labels, NUM);
    }
private:
    const char* _labels[NUM];
};
 
class EmbAJAXPageBase {
public:
    virtual void handleRequest(void (*change_callback)()=0) = 0;
    virtual void printPage() = 0;
};
 
template<size_t NUM> class EmbAJAXPage : public EmbAJAXContainer<NUM>, public EmbAJAXPageBase {
public:
    EmbAJAXPage(EmbAJAXBase* children[NUM], const char* title, const char* header_add = 0, uint16_t min_interval=100) : EmbAJAXContainer<NUM>(children),
        _title(title ? title : EmbAJAXBase::null_string), _header_add(header_add ? header_add : EmbAJAXBase::null_string), _min_interval(min_interval) {}
    void printPage() override {
        print();
    }
    void print() const override {
        EmbAJAXBase::printPage(EmbAJAXContainer<NUM>::_children, NUM, _title, _header_add, _min_interval);
    }
    void handleRequest(void (*change_callback)()=0) override {
        _latest_ping = millis();
        EmbAJAXBase::handleRequest(EmbAJAXContainer<NUM>::_children, NUM, change_callback);
    }
    bool hasActiveClient(uint64_t latency_ms=5000) const {
        return(_latest_ping && (_latest_ping + latency_ms > millis()));
    }
protected:
    const char* _title;
    const char* _header_add;
    uint16_t _min_interval;
    uint64_t _latest_ping = 0;
};
 
// If the user has not #includ'ed a specific output driver implementation, make a good guess, here
#if not defined (EMBAJAX_OUTUPUTDRIVER_IMPLEMENTATION)
#if defined (ESP8266)
#include "EmbAJAXOutputDriverESP8266.h"
#elif defined (ESP32)
#include "EmbAJAXOutputDriverESP32.h"
#elif defined (ARDUINO_ARCH_RP2040)
#include "EmbAJAXOutputDriverRP2040.h"
#else
#include <WebServer.h>
#define EmbAJAXOutputDriverWebServerClass WebServer
#include <WiFi.h>
#include "EmbAJAXOutputDriverGeneric.h"
#warning No output driver available for this hardware (yet). We try using the generic driver, but success is not guaranteed.
#warning In most cases, implementing a driver is as easy as picking the correct header file to include. Please consider submitting a patch.
#endif
#endif
 
#endif