Конструктор - GyverLibs/GyverPortal GitHub Wiki

Как это работает, буфер

Внутри функции конструктора собирается страница. Это можно делать как при помощи своего HTML/CSS/JS кода (об этом см. в главе про свой код и API), так и из набора компонентов библиотеки. Конструктор является объектом с именем GP и своим набором функций, например кнопка GP.BUTTON(...). Вызов функции компонента добавляет HTML код во встроенный буфер библиотеки, который отправляется в браузер по переполнению. Это позволяет собирать и отправлять страницы максимально быстро и экономно с точки зрения использования оперативной памяти контроллера.

По умолчанию буфер имеет размер 1кб, его можно настроить через объект портала portal.setBufferSize(размер).

Минимальный код

void build() {
  GP.BUILD_BEGIN();         // начать сборку
  //GP.THEME(GP_LIGHT);     // светлая тема
  GP.THEME(GP_DARK);        // тёмная тема
  
  // собираем страницу
  // ...
  
  GP.BUILD_END();           // закончить сборку
}

Компоненты

Полный список компонентов можно посмотреть на главной странице документации.

Текстовые параметры

Почти у каждого компонента есть текстовые параметры (имя, текст, цвет), в коде они являются типом const String&. Это позволяет передавать их в функцию разными способами:

  • const string literal
GP.BUTTON("Просто текстом в кавычках");
  • FlashStringHelper macro
GP.BUTTON(F("Текстом из Flash памяти"));
  • String
GP.BUTTON(String("Стрингой") + 1234 + "в т.ч. суммой");
  • char*
char* str = "Указателем на строку";
// ...
GP.BUTTON(str);
  • PROGMEM
static const char str[] PROGMEM = "Текстом из PROGMEM";
// ...
GP.BUTTON(FPSTR(str));

Имя компонента

Почти у каждого компонента есть параметр имя. Это уникальное имя компонента (id), по которому библиотека может с ним взаимодействовать: получать с него значения, действия, обновлять значение, выводить подсказки и так далее. Требования к имени:

  • Рекомендуется использовать только латинские буквы a-z, A-Z, цифры 0-9, дефис - и подчёркивание _
  • Не должно начинаться с подчёркивания _ и слеша / (кроме FORM), чтобы исключить совпадение с системными запросами
  • Не должно содержать точку . и запятую ,
  • Символ / используется для разделения имён на под-имена (subname) для группировки компонентов, а также с него начинается имя компонента FORM

Свои компоненты

Кастомный конструктор

Конструктор GyverPortal ничем не ограничивает построение страницы:

  • Достаточно добавить любой HTML код между запуском GP.BUILD_BEGIN() и завершением конструктора GP.BUILD_END()
  • Код добавляется при помощи GP.SEND(const String& str), то есть можно прибавлять текст в кавычках, стринги, F-стринги и так далее
  • Есть вариант GP.SEND_P(PGM_P str) для отправки PSTR()-строк. Рекомендуется использовать этот вариант только для крупных конструкций (несколько сотен строк HTML кода)
void build() {
  GP.BUILD_BEGIN();
  // собираем страницу
  GP.SEND(F("some HTML code"));
  GP.BUILD_END();
}

Для справки:
Стандартный GP.BUILD_BEGIN() внутри состоит из:

  GP.PAGE_BEGIN();
  GP.JS_TOP();
  GP.PAGE_BLOCK_BEGIN();

Стандартный GP.BUILD_END() внутри состоит из:

  GP.PAGE_BLOCK_END();
  GP.JS_BOTTOM();
  GP.PAGE_END();

Файл custom.h

Для более удобного добавления своих компонентов конструктора без редактирования основных файлов библиотеки можно использовать файл custom.h (находится в папке src в папке с библиотекой). Файл содержит несколько базовых примеров создания своих компонентов:

// шаблон "сборного" блока (что-то с надписью или цветом)
void GP_MY_BLOCK(const String& data) {
    String s;               // создай строку
    s += F("some html");    // собери html код
    s += data;              // добавь данные из аргументов
    GP.SEND(s);             // отправь через GP.SEND
}

// шаблон одиночного блока (например скрипт, набор стилей итд)
void GP_MY_BLOCK() {
    // храним html код через макрос PSTR в программной памяти
    // и отправляем через GP.SEND_P
    GP.SEND_P(PSTR("some\n"
    "multi-line\n"
    "html\n"
    "code\n"));
}

// пример "текст-ссылка"
void GP_TEXT_HREF(const String& url, const String& text) {
    String s;
    s += F("<a href='");
    s += url;
    s += F("'>");
    s += text;
    s += F("</a>");
    GP.SEND(s);
}

API

Для обеспечения работоспособности механизмов библиотеки в кастомных компонентах нужно соблюдать следующие моменты:

  • Встроенные скрипты (обработка кликов и прочего) добавляется из GP.JS_TOP(). Для работы слайдеров нужен также GP.JS_BOTTOM()
  • У компонентов формы должен быть указан атрибут name для передачи данных через submit
  • У кликабельных компонентов должен быть указан атрибут onclick с параметром-функцией: onclick='GP_click(this)'. Библиотека сама перехватит вызов и направит в click().
  • У компонентов, с которых нужен сигнал click() по изменению данных, должен быть указан атрибут onchange с параметром-функцией: onchange='GP_click(this)'. Библиотека сама перехватит вызов и направит в click().
  • У компонентов, для которых нужны обновления update(), должен быть указан атрибут id. Его значение также нужно передать в GP.UPDATE().
  • Если нужен клик, который передаёт данные с другого компонента, указываем атрибут с функцией onclick="GP_clickid(btn,tar)", где btn - имя (для библиотеки) кликающего компонента, а tar - атрибут id целевого компонента, с которого нужно передать данные.
  • Для ручной передачи в библиотеку сигнала о клике нужно отправить http POST запрос вида GP_click?имя=значение
  • Для ручной передачи в библиотеку сигнала об обновлении нужно отправить http GET запрос вида GP_update?id_компонента=