You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
368 lines
18 KiB
368 lines
18 KiB
## The elements for the custom Web pages
|
|
|
|
Representative HTML elements for making the custom Web page are provided as AutoConnectElements.
|
|
|
|
- [AutoConnectButton](#autoconnectbutton): Labeled action button
|
|
- [AutoConnectCheckbox](#autoconnectcheckbox): Labeled checkbox
|
|
- [AutoConnectElement](#autoconnectelement-a-basic-class-of-elements): General tag
|
|
- [AutoConnectInput](#autoconnectinput): Labeled text input box
|
|
- [AutoConnectRadio](#autoconnectradio): Labeled radio button
|
|
- [AutoConnectSelect](#autoconnectselect): Selection list
|
|
- [AutoConnectSubmit](#autoconnectsubmit): Submit button
|
|
- [AutoConnectText](#autoconnecttext): Style attributed text
|
|
|
|
## Layout on custom Web page
|
|
|
|
You can specify the direction to arrange the radio buttons as [**AutoConnectRadio**](#autoconnectradio) vertically or horizontally. Other elements are arranged vertically in the order of addition to AutoConnectAux. This basic layout depends on the CSS of the AutoConnect menu so it can not be changed drastically.
|
|
|
|
## Form and AutoConnectElements
|
|
|
|
All AutoConnectElements placed on a custom Web page are included in one form. Its form is fixed and created by AutoConnect. The form's value (usually the text or checkbox you entered) is sent by [AutoConnectSubmit](#autoconnectsubmit) using the POST method.
|
|
|
|
**name** and **value** of each AutoConnectElement which own form-data are reflected in the query string when the custom Web page was sent. You can retrieve the value in the sketch as the parameter's value of the query string with [**ESP8266WebServer::arg**](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#getting-information-about-request-arguments) function or **PageArgument** class of [**AutoConnect::on**](api.md#on) handler when the form is submitted.
|
|
|
|
## AutoConnectElement - <small>A basic class of elements</small>
|
|
|
|
AutoConnectElement is a base class for other element classes and has common attributes for all elements. It can also be used as a [variant](#variant-for-autoconnectelements) of each element. The following items are attributes that AutoConnectElement has and are common to other elements.
|
|
|
|
<i class="fa fa-eye"></i> **Sample**<br>
|
|
<small>`AutoConnectElement element("element", "<hr>");`</small>
|
|
|
|
<small>On the page:</small><br><img src="../images/acelement.png">
|
|
|
|
### <i class="fa fa-edit"></i> Constructor
|
|
|
|
```cpp
|
|
AutoConnectElement(const char* name, const char* value)
|
|
```
|
|
|
|
### <i class="fa fa-caret-right"></i> name
|
|
|
|
Each element has a name. **Name** is the String data type. To access its element in the sketches you can identify by the name. Its method is useful for loading elements in JSON. In the load function of AutoConnectElement(s) described [**later**](acjson.md), these objects are not created in advance by sketches. Therefore, access to the attribute of that element by the **name** as follows:
|
|
|
|
```cpp hl_lines="4 10"
|
|
AutoConnectAux customPage("/custom_page", "Custom page");
|
|
const char ELEMENT_TEXT[] PROGMEM = R"(
|
|
{
|
|
"name": "text1",
|
|
"type": "ACText",
|
|
"value": "Hello, world"
|
|
}
|
|
)";
|
|
customPage.loadElement(ELEMENT_TEXT);
|
|
AutoConnectText& text1 = customPage.getElement<AutoConnectText>("text1");
|
|
text1.style = "text-align:center;color:#2f4f4f;"
|
|
```
|
|
|
|
The above example accesses the *text1* element which loaded from JSON using AutoConnectAux's [**getElement**](apiaux.md#getelement) function by name and sets the [**style**](#style) attribute.
|
|
|
|
### <i class="fa fa-caret-right"></i> value
|
|
|
|
**Value** is the source of the HTML code generated with the element and its data type is String. Characteristics of Value vary depending on the element. The value of AutoConnectElement is native HTML code. A string of value is output as HTML as it is.<br>
|
|
|
|
### <i class="fa fa-caret-right"></i> type
|
|
|
|
**Type** indicates the type of the element and represented as the *ACElement_t* enumeration type in the sketch. Since AutoConnectElement also acts as a variant of other elements, it can be applied to handle elements collectively. At that time, the type can be referred to by the [**typeOf()**](apielements.md#typeof) function. The following example changes the font color of all [AutoConnectText](#autoconnecttext) elements of a custom Web page to gray.
|
|
|
|
```cpp hl_lines="5"
|
|
AutoConnectAux customPage;
|
|
|
|
AutoConnectElementVT& elements = customPage.getElements();
|
|
for (AutoConnectElement& elm : elements) {
|
|
if (elm.typeOf() == AC_Text) {
|
|
AutoConnectText& text = reinterpret_cast<AutoConnectText&>(elm);
|
|
text.style = "color:gray;";
|
|
}
|
|
}
|
|
```
|
|
|
|
The enumerators for *ACElement_t* are as follows:
|
|
|
|
- AutoConnectButton: **AC_Button**
|
|
- AutoConnectCheckbox: **AC_Checkbox**
|
|
- AutoConnectElement: **AC_Element**
|
|
- AutoConnectInput: **AC_Input**
|
|
- AutoConnectRadio: **AC_Radio**
|
|
- AutoConnectSelect: **AC_Select**
|
|
- AutoConnectSubmit: **AC_Submit**
|
|
- AutoConnectText: **AC_Text**
|
|
- Uninitialized element: **AC_Unknown**
|
|
|
|
Furthermore, to convert an entity that is not an AutoConnectElement to its native type, you must [re-interpret](https://en.cppreference.com/w/cpp/language/reinterpret_cast) that type with c++.
|
|
|
|
## AutoConnectButton
|
|
|
|
AutoConnectButton generates an HTML `<button type="button">` tag and locates a clickable button to a custom Web page. Currently AutoConnectButton corresponds only to name, value, an onclick attribute of HTML button tag. An onclick attribute is generated from an `action` member variable of the AutoConnectButton, which is mostly used with a JavaScript to activate a script.
|
|
|
|
<i class="fa fa-eye"></i> **Sample**<br>
|
|
<small>`AutoConnectButton button("button", "OK", "myFunction()");`</small>
|
|
|
|
<small>On the page:</small><br><img src="../images/acbutton.png">
|
|
|
|
### <i class="fa fa-edit"></i> Constructor
|
|
|
|
```cpp
|
|
AutoConnectButton(const char* name, const char* value, const String& action)
|
|
```
|
|
|
|
### <i class="fa fa-caret-right"></i> name
|
|
|
|
It is the `name` of the AutoConnectButton element and matches the name attribute of the button tag. It also becomes the parameter name of the query string when submitted.
|
|
|
|
### <i class="fa fa-caret-right"></i> value
|
|
|
|
It becomes a value of the `value` attribute of an HTML button tag.
|
|
|
|
### <i class="fa fa-caret-right"></i> action
|
|
|
|
**action** is String data type and is an onclick attribute fire on a mouse click on the element. it is mostly used with a JavaScript to activate a script.[^1] For example, the following code defines a custom Web page that copies a content of `Text1` to `Text2` by clicking `Button`.
|
|
|
|
[^1]:JavaScript can be inserted into a custom Web page using AutoConnectElement.
|
|
|
|
```cpp hl_lines="3 4 5 10"
|
|
const char* scCopyText = R"(
|
|
<script>
|
|
function CopyText() {
|
|
document.getElementById("Text2").value = document.getElementById("Text1").value;
|
|
}
|
|
</script>
|
|
)";
|
|
ACInput(Text1, "Text1");
|
|
ACInput(Text2, "Text2");
|
|
ACButton(Button, "COPY", "CopyText()");
|
|
ACElement(TextCopy, scCopyText);
|
|
```
|
|
|
|
## AutoConnectCheckbox
|
|
|
|
AutoConnectCheckbox generates an HTML `<input type="checkbox">` tag and a `<label>` tag. It places horizontally on a custom Web page by default.
|
|
|
|
<i class="fa fa-eye"></i> **Sample**<br>
|
|
<small>`AutoConnectCheckbox checkbox("checkbox", "uniqueapid", "Use APID unique", false);`</small>
|
|
|
|
<small>On the page:</small><br><img src="../images/accheckbox.png">
|
|
|
|
### <i class="fa fa-edit"></i> Constructor
|
|
|
|
```cpp
|
|
AutoConnectCheckbox(const char* name, const char* value, const char* label, const bool checked)
|
|
```
|
|
|
|
### <i class="fa fa-caret-right"></i> name
|
|
|
|
It is the `name` of the AutoConnectCheckbox element and matches the name attribute of the input tag. It also becomes the parameter name of the query string when submitted.
|
|
|
|
### <i class="fa fa-caret-right"></i> value
|
|
|
|
It becomes a value of the `value` attribute of an HTML `<input type="checkbox">` tag.
|
|
|
|
### <i class="fa fa-caret-right"></i> label
|
|
|
|
A label is an optional string. A label is always arranged on the right side of the checkbox. Specification of a label will generate an HTML `<label>` tag with an `id` attribute. The checkbox and the label are connected by the id attribute.
|
|
Only <i class="far fa-square"></i> will be displayed if a label is not specified.
|
|
|
|
### <i class="fa fa-caret-right"></i> checked
|
|
|
|
A checked is a Boolean value and indicates the checked status of the checkbox. The value of the checked checkbox element is packed in the query string and sent.
|
|
|
|
## AutoConnectInput
|
|
|
|
AutoConnectInput generates an HTML `<input type="text">` tag and a `<label>` tag. It can also have a placeholder. The value of the input box is passed to the destination in the query string and can be retrieved programmatically. You can also update from the sketches.
|
|
|
|
<i class="fa fa-eye"></i> **Sample**<br>
|
|
<small>`AutoConnectInput input("input", "", "Server", "MQTT broker server");`</small>
|
|
|
|
<small>On the page:</small><br><img src="../images/acinput.png">
|
|
|
|
### <i class="fa fa-edit"></i> Constructor
|
|
|
|
```cpp
|
|
AutoConnectInput(const char* name, const char* value, const char* label, const char* placeholder)
|
|
```
|
|
|
|
### <i class="fa fa-caret-right"></i> name
|
|
|
|
It is the `name` of the AutoConnectInput element and matches the name attribute, the id attribute of the input tag. It also becomes the parameter name of the query string when submitted.
|
|
|
|
### <i class="fa fa-caret-right"></i> value
|
|
|
|
It becomes a string value of the `value` attribute of an HTML `<input type="text">` tag. The text entered from the custom Web page will be grouped in the query string of the form submission and the string set before accessing the page will be displayed as the initial value.
|
|
|
|
### <i class="fa fa-caret-right"></i> label
|
|
|
|
A `label` is an optional string. A label is always arranged on the left side of the input box. Specification of a label will generate an HTML `<label>` tag with an id attribute. The input box and the label are connected by the id attribute.
|
|
|
|
### <i class="fa fa-caret-right"></i> placeholder
|
|
|
|
A placeholder is an option string. Specification of a placeholder will generate a `placeholder` attribute for the input tag.
|
|
|
|
## AutoConnectRadio
|
|
|
|
AutoConnectRadio generates few HTML `<input type="radio">` tags as grouped and the same number of `<label>` tags. AutoConnectRadio can keep the value of a radio button as a collection. The grouped values will be placed in the custom Web page to select only one exclusively.
|
|
|
|
<i class="fa fa-eye"></i> **Sample**<br>
|
|
<small>`AutoConnectRadio radio("radio", { "30 sec.", "60 sec.", "180 sec." }, "Update period", AC_Vertical, 1);`</small>
|
|
|
|
<small>On the page:</small><br><img src="../images/acradio.png">
|
|
|
|
### <i class="fa fa-edit"></i> Constructor
|
|
|
|
```cpp
|
|
AutoConnectRadio(const char* name, std::vector<String> const& values, const char* label, const ACArrange_t order, const uint8_t checked)
|
|
```
|
|
|
|
### <i class="fa fa-caret-right"></i> name
|
|
|
|
It is the `name` of the AutoConnectRadio element and matches the name attribute of the input tags. It also becomes the parameter name of the query string when submitted.
|
|
|
|
### <i class="fa fa-caret-right"></i> values
|
|
|
|
A `values` is an array of String type for the radio button options which as actually [std::vector](https://en.cppreference.com/w/cpp/container/vector). It is an initialization list can be used. The input tags will be generated from each entry in the values, the amount of which is the same as the number of items in `values`.
|
|
|
|
### <i class="fa fa-caret-right"></i> label
|
|
|
|
A label is an optional string. A label will be arranged in the left or top of the radio buttons according to the `order`. Specification of a label will generate an HTML `<label>` tag with an `id` attribute. The radio buttons and the label are connected by the id attribute.
|
|
|
|
### <i class="fa fa-caret-right"></i> order
|
|
|
|
A `order` specifies the orientation of the radio buttons. It is a value of type `ACArrange_t` and accepts one of the following:
|
|
|
|
- **`AC_Horizontal`** : Horizontal arrangement.
|
|
- **`AC_Vertical`** : Vertical arrangement.
|
|
|
|
A label is placed in the left or the top according to `order`.
|
|
|
|
### <i class="fa fa-caret-right"></i> checked
|
|
|
|
A `checked` specifies the index number (1-based) of `values` to be checked. If this parameter is not specified neither item is checked.
|
|
|
|
## AutoConnectSelect
|
|
|
|
AutoConnectSelect generates an HTML `<select>` tag (drop-down list) and few `<option>` tags.
|
|
|
|
<i class="fa fa-eye"></i> **Sample**<br>
|
|
<small>`AutoConnectSelect select("select", { String("Europe/London"), String("Europe/Berlin"), String("Europe/Helsinki"), String("Europe/Moscow"), String("Asia/Dubai") }, "Select TZ name");`</small>
|
|
|
|
<small>On the page:</small><br><img src="../images/acselect.png">
|
|
|
|
### <i class="fa fa-edit"></i> Constructor
|
|
|
|
```cpp
|
|
AutoConnectSelect(const char* name, std::vector<String> const& options, const char* label)
|
|
```
|
|
|
|
### <i class="fa fa-caret-right"></i> name
|
|
|
|
It is the `name` of the AutoConnectSelect element and matches the name attribute of the select tags.
|
|
|
|
### <i class="fa fa-caret-right"></i> options
|
|
|
|
An `options` is an array of String type for the options which as actually [std::vector](https://en.cppreference.com/w/cpp/container/vector) for an HTML `<option>` tag. It is an initialization list can be used. The option tags will be generated from each entry in the options, the amount of which is the same as the number of items in an `options`.
|
|
|
|
### <i class="fa fa-caret-right"></i> label
|
|
|
|
A `label` is an optional string. A label is always arranged on the left side of the drop-down list. Specification of a label will generate an HTML `<label>` tag with an id attribute. The select tag and the label are connected by the id attribute.
|
|
|
|
## AutoConnectSubmit
|
|
|
|
AutoConnectSubmit generates an HTML `<input type="button">` tag attached `onclick` attribute. The native code of the `onclick` attribute is the submission of the form with the **POST** method.
|
|
|
|
<i class="fa fa-eye"></i> **Sample**<br>
|
|
<small>`AutoConnectSubmit submit("submit", "Save", "/mqtt_save");`</small>
|
|
|
|
<small>On the page:</small><br><img src="../images/acsubmit.png">
|
|
|
|
### <i class="fa fa-edit"></i> Constructor
|
|
|
|
```cpp
|
|
AutoConnectSubmit(const char* name, const char* value, const char* uri)
|
|
```
|
|
|
|
### <i class="fa fa-caret-right"></i> name
|
|
|
|
It is the `name` of the AutoConnectSubmit element and matches the name attribute of the input tag.
|
|
|
|
### <i class="fa fa-caret-right"></i> value
|
|
|
|
It becomes a string of the `value` attribute of an HTML `<input type="button">` tag. The `value` is displayed as a label of the button.
|
|
|
|
### <i class="fa fa-caret-right"></i> uri
|
|
|
|
A `uri` specifies the URI to send form data when the button declared by AutoConnectSubmit is clicked.
|
|
|
|
The query string of the form data sent with AutoConnectSubmit contains the URI of the page. Its parameter name is `_acuri`. In Sketch, you can know the called URI by referring to the `_acuri` parameter with the destination page handler. The actual query string is as follows:
|
|
|
|
\_acuri=**CALLER_URI**
|
|
|
|
## AutoConnectText
|
|
|
|
AutoConnectText generates an HTML `<div>` tag. A `style` attribute will be attached if a [style](#style) parameter is passed.
|
|
|
|
<i class="fa fa-eye"></i> **Sample**<br>
|
|
<small>`AutoConnectText text("text", "Publishing the WiFi signal strength to MQTT channel. RSSI value of ESP8266 to the channel created on ThingSpeak", "font-family:serif;color:#4682b4;");`</small>
|
|
|
|
<small>On the page:</small><br><img src="../images/actext.png">
|
|
|
|
### <i class="fa fa-edit"></i> Constructor
|
|
|
|
```cpp
|
|
AutoConnectText(const char* name, const char* value, const char* style)
|
|
```
|
|
|
|
### <i class="fa fa-caret-right"></i> name
|
|
|
|
A `name` does not exist in the generated HTML. It provides only a means of accessing elements with the sketches.
|
|
|
|
### <i class="fa fa-caret-right"></i> value
|
|
|
|
It becomes content and also can contain the native HTML code, but remember that your written code is enclosed by the div tag.
|
|
|
|
### <i class="fa fa-caret-right"></i> style
|
|
|
|
A `style` specifies the qualification style to give to the content and can use the style attribute format as it is.
|
|
|
|
## How to coding for the elements
|
|
|
|
### <i class="fa fa-edit"></i> Declaration for the elements in Sketches
|
|
|
|
Variables of each element can be declared with macros. By using the macros, you can treat element name that is String type as variable in sketches.[^2]
|
|
|
|
[^2]: The square brackets in the syntax are optional parameters, the stroke is a selection parameter, the bold fonts are literal.
|
|
|
|
ACElement ( *name* <small>\[</small> , *value* <small>\]</small> )
|
|
|
|
ACButton ( *name* <small>\[</small> , *value* <small>\]</small> <small>\[</small> , *action* <small>\]</small> )
|
|
|
|
ACCheckbox ( *name* <small>\[</small> , *value* <small>\]</small> <small>\[</small> , *label* <small>\]</small> <small>\[</small> , **true** | **false** <small>\]</small> )
|
|
|
|
ACInput ( *name* <small>\[</small> , *value* <small>\]</small> <small>\[</small> , *label* <small>\]</small> <small>\[</small> , *placeholder* <small>\]</small> )
|
|
|
|
ACRadio ( *name* <small>\[</small> , *values* <small>\]</small> <small>\[</small> , *label* <small>\]</small> <small>\[</small> , **AC\_Horizontal** | **AC\_Vertical** <small>\]</small> <small>\[</small> , *checked* <small>\]</small> )
|
|
|
|
ACSelect ( *name* <small>\[</small> , *options* <small>\]</small> <small>\[</small> , *label* <small>\]</small> )
|
|
|
|
ACSubmit ( *name* <small>\[</small> , *value* <small>\]</small> <small>\[</small> , *uri* <small>\]</small> )
|
|
|
|
ACText ( *name* <small>\[</small> , *value* <small>\]</small> <small>\[</small> , *style* <small>\]</small> )
|
|
|
|
!!! memo "Declaration macro usage"
|
|
For example, *AutoConnectText* can be declared using macros.
|
|
```cpp
|
|
AutoConnectText caption("caption", "hello, world", "color:blue;")
|
|
```
|
|
equals by using *ACText* macro.<br>
|
|
```cpp
|
|
ACText(caption, "hello, world", "color:blue;")
|
|
```
|
|
|
|
### <i class="fa fa-edit"></i> Variant for AutoConnectElements
|
|
|
|
Some AutoConnectAux APIs specify AutoConnectElement as an argument. There are also functions that returns a pointer to AutoConnectElement. In order to make these interfaces single, AutoConnectElement behaves as a variant type of other elements. Use [reinterpret_cast](https://en.cppreference.com/w/cpp/language/reinterpret_cast) to cast from a variant pointer to an Actual type pointer of AutoConnectElements.
|
|
|
|
```cpp
|
|
AutoConnectAux aux;
|
|
ACText(Text1, "hello, world");
|
|
aux.add(Text1);
|
|
AutoConnectText* text_p = reinterpret_cast<AutoConnectText>(aux.getElement("Text1"));
|
|
AutoConnectText& text = aux.getElement<AutoConnectText>("Text1");
|
|
```
|
|
|