From 659b68d3ffc09cae68f0a0e53369aa4bf751ab55 Mon Sep 17 00:00:00 2001 From: Hieromon Ikasamo Date: Wed, 23 Jan 2019 21:22:30 +0900 Subject: [PATCH] Under the work of v0.9.7 documentation --- mkdocs/acelements.md | 6 +- mkdocs/achandling.md | 106 +++++++++++++++++++++++- mkdocs/acintro.md | 10 +-- mkdocs/acjson.md | 189 +++++++++++++++++++++++++++++++++---------- mkdocs/apiaux.md | 42 ++++++++-- 5 files changed, 294 insertions(+), 59 deletions(-) diff --git a/mkdocs/acelements.md b/mkdocs/acelements.md index f09db26..308c02e 100644 --- a/mkdocs/acelements.md +++ b/mkdocs/acelements.md @@ -115,7 +115,7 @@ It becomes a value of the `value` attribute of an HTML button tag. ### 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`. +**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. @@ -225,7 +225,7 @@ A label is an optional string. A label will be arranged in the left or top of th ### order -A `order` specifies the orientation of the radio buttons. It is a value of type `ACArrange_t` and accepts one of the following: +A `order` specifies the direction to arrange 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. @@ -284,7 +284,7 @@ It is the `name` of the AutoConnectSubmit element and matches the name attribute ### value -It becomes a string of the `value` attribute of an HTML `` tag. The `value` is displayed as a label of the button. +It becomes a string of the `value` attribute of an HTML `` tag. The `value` will be displayed as a label of the button. ### uri diff --git a/mkdocs/achandling.md b/mkdocs/achandling.md index 2415678..d8033eb 100644 --- a/mkdocs/achandling.md +++ b/mkdocs/achandling.md @@ -1,6 +1,108 @@ -## Handing AutoConnectElements in the sketches +## Handing AutoConnectElements with the sketches -## Loading AutoConnectElements +AutoConnectElements (ie. they are the elements displayed on the custom Web page) must be contained in AutoConnectAux object. AutoConnectElements declared in sketch must be programmed to add to AutoConnectAux one after another. Elements are automatically included in AutoConnectAux by AutoConnect if you load it from the JSON description. In either method, it is common to use the function of AutoConnectAux to access an element with a sketch. + +The AutoConnectAux class has several functions to manipulate AutoConnectElements. The functions can add, delete, retrieve elements, and get and set values. + +### Add AutoConnectElements to the AutoConnectAux object + +To add AutoConnectElment(s) to an AutoConnectAux object, use the add function. + +```cpp +void AutoConnectAux::add(AutoConenctElement& addon) +``` +```cpp +void AutoConnectAux::add(AutoConenctElementVT addons) +``` + +The add function adds specified AutoConnectElement to the AutoConnectAux. If speficied the collection of AutoConnectElements as a `std::vector` of the references to each element, these elements added in bulk. + +The AutoConnectElements contained in the AutoConnectAux object are uniquely identified by the name. When adding an AutoConnectElement, if an element with the same name already exists in the AutoConnectAux, checking the type, and if it is the same, the value will be replaced. If another type of AutoConnectElement exists with the same name, that add operation will be invalid.[^1] In the following example, an AutoConnectButton as `button` addition is invalid. + +[^1]: The valid scope of the name is within an AutoConnectAux. + +```cpp hl_lines="3" +AutoConnectAux aux; +AutoConnectText text("hello", "hello, world"); +AutoConnectButton button("hello", "hello, world", "alert('Hello world!')"); // This is invalid. +aux.add({ text, button }); +``` + +Similarly this, the uniqueness of the name is also necessary within the JSON document + +```json hl_lines="12" +{ + "name" : "aux", + "uri" : "/aux", + "menu" : true, + "element" : [ + { + "name": "hello", + "type": "ACText", + "value": "hello, world" + }, + { + "name": "hello", + "type": "ACButton", + "value": "hello, world", + "action": "alert('Hello world!')" + } + ] +} +``` + +!!! note "Load all elements from JSON document" + If you load all AutoConnectElements from JSON document into AutoConnect, you do not need to sketch the population process of the AutoConnectElements. It is managed by the AutoConnect library automatically. + +### Get AutoConnectElement from the AutoConnectAux + +To retrieve an element from AutoConnectAux, use the getElement or getElements function. Normally, the getElement is needed when accessing the value of AutoConnectElement in the sketch. + +```cpp +AutoConnectElement* AutoConnectAux::getElement(const String& name); +``` + +```cpp +template T& AutoConnectAux::getElement(const String& name); +``` + +```cpp +AutoConnectElementVT* AutoConnectAux::getElements(void); +``` + +The [**getElement**](apiaux.md#getelement) function returns an AutoConnectElement with the specified name as a key. When you use this function, you need to know the type of AutoConnectElement in advance. To retrieve an AutoConnectElement by specifying its type, use the following method. + +```cpp +AutoConnectAux aux; +aux.load("SOME_JSON_DOCUMENT"); + +// Retrieve the pointer of the AutoConnectText +AutoConnectText* text = reinterpret_cast(aux.getElement("TEXT_ELEMENT_NAME")); + +// Retrieve the reference of the AutoConnectText +AutoConnectText& text = aux.getElement("TEXT_ELEMENT_NAME"); +``` + +The AutoConnectElement type behaves as a variant of other element types. Therefore use cast or template to convert to actual type as above. In the sketch, you access the real type of AutoConnectElement after casting it and storing into the variable. + +```cpp +const String auxJson = String("{\"title\":\"Page 1 title\",\"uri\":\"/page1\",\"menu\":true,\"element\":[{\"name\":\"caption\",\"type\":\"ACText\",\"value\":\"hello, world\"}]}"); +AutoConenct portal; +portal.load(auxJson); +AutoConnectAux* aux = portal.aux("/page1"); // Identify the AutoConnectAux instance with uri +AutoConenctText& text = aux->getElement("caption"); // Cast to real type and access members +Serial.println(text.value); +``` + +To get all the AutoConnectElements of an AutoConnectAux object use the [**getElements**](apiaux.md#getelements) function. This function returns the vector of the reference wrapper as *AutoConnectElementVT* to all AutoConnectElements registered in the AutoConnectAux. + +```cpp +AutoConnectElementVT& getElements(void) +``` + +*AutoConnectElementVT* is a predefined type for it and can use methods of [std::vector](https://en.cppreference.com/w/cpp/container/vector)<[std::reference_wrapper](https://en.cppreference.com/w/cpp/utility/functional/reference_wrapper)>. + +## Loading & saving AutoConnectElements ## Saving AutoConnectElements diff --git a/mkdocs/acintro.md b/mkdocs/acintro.md index 1ac3974..53f7fa8 100644 --- a/mkdocs/acintro.md +++ b/mkdocs/acintro.md @@ -63,10 +63,6 @@ In the sketch below, it shows the sequence of codes to integrate three custom We } ``` -## Passing parameters with sketches and custom Web pages - -A sketch can access variables of [AutoConnectElements](acelements.md) in the custom Web page. The value entered into the AutoConnectElements on the page is stored to the [member variables](acelements.md#form-and-autoconnectelements) of the element by AutoConnect whenever GET / POST transmission occurs. Your sketches can get these values with the GET / POST request handler. If you assign a value to an element before a request to the page occurs, its value will appear as the initial value when the page is displayed. - ## Basic steps to use custom Web pages So, the basic procedure for handling of the custom Web pages is as follows: @@ -163,7 +159,11 @@ void loop() { } ``` -[^3]: Installation of the [ArduinoJson](https://github.com/bblanchon/ArduinoJson) v.5.13.4 library is required. +[^3]: Installation of the [ArduinoJson](https://github.com/bblanchon/ArduinoJson) as the latest release of version 5 series is required. + +## Passing parameters with sketches and custom Web pages + +A sketch can access variables of [AutoConnectElements](acelements.md) in the custom Web page. The value entered into the AutoConnectElements on the page is stored to the [member variables](acelements.md#form-and-autoconnectelements) of the element by AutoConnect whenever GET / POST transmission occurs. Your sketches can get these values with the GET / POST request handler. If you assign a value to an element before a request to the page occurs, its value will appear as the initial value when the page is displayed. Details are explained in the [Parameter handling](achandling.md#parameter-handling).