diff --git a/docs/API.md b/docs/API.md
index 538e8b46..9f4a2f8e 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -445,7 +445,7 @@ Topics and subscriptions have `public` and `private` fields. Generally, the fiel
### Public
-The format of the `public` field in group and peer to peer topics is expected to be [theCard](./thecard.md) although only `fn` and `photo` fields are currently used by client software.
+The format of the `public` field in group, peer to peer, systems topics is expected to be [theCard](./thecard.md).
The `fnd` topic expects `public` to be a string representing a [search query](#query-language)).
diff --git a/docs/drafty.md b/docs/drafty.md
index c90d7732..6dbc1a92 100644
--- a/docs/drafty.md
+++ b/docs/drafty.md
@@ -49,27 +49,30 @@ If `tp` is provided, it means the style is a basic text decoration:
* `DL`: deleted or strikethrough text: ~~strikethrough~~.
* `CO`: code or monotyped text, possibly with different background: `monotype`.
* `BR`: line break.
- * `RW`: logical grouping of formats, a row.
+ * `RW`: logical grouping of formats, a row; may also be represented as an entity.
* `HD`: hidden text.
* `HL`: highlighted text, such as text in a different color or with a different background; the color cannot be specified.
+ * `FM`: form / set of fields; may also be represented as an entity.
-If key is provided, it's a 0-based index into the `ent` field which contains an entity definition such as an image or an URL:
- * `LN`: link (URL) [https://api.tinode.co](https://api.tinode.co)
- * `MN`: mention such as [@tinode](#)
- * `HT`: hashtag, e.g. [#hashtag](#)
- * `IM`: inline image
- * `EX`: generic attachment
- * `FM`: form / set of fields
- * `BN`: interactive button
+If key is provided, it's a 0-based index into the `ent` field which contains extended style parameters such as an image or an URL:
+ * `LN`: link (URL) [https://api.tinode.co](https://api.tinode.co).
+ * `MN`: mention such as [@tinode](#).
+ * `HT`: hashtag, e.g. [#hashtag](#).
+ * `IM`: inline image.
+ * `EX`: generic attachment.
+ * `FM`: form / set of fields; may also be represented as a basic decoration.
+ * `BN`: interactive button.
+ * `RW`: logical grouping of formats, a row; may also be represented as a basic decoration.
Examples:
* `{ "at":8, "len":4, "tp":"ST"}`: apply formatting `ST` (strong/bold) to 4 characters starting at offset 8 into `txt`.
* `{ "at":144, "len":8, "key":2 }`: insert entity `ent[2]` into position 144, the entity spans 8 characters.
* `{ "at":-1, "len":0, "key":4 }`: show the `ent[4]` as a file attachment, don't apply any styling to text.
+The clients should be able to handle missing `at`, `key`, and `len` values. Missing values are assumed to be equal to `0`.
#### `FM`: a form, an ordered set or fields
-Form provides means to add paragraph-level formatting to a logical group of elements:
+Form provides means to add paragraph-level formatting to a logical group of elements. It may be represented as a text decoration or as an entity.
| Do you agree? |
| Yes |
@@ -80,10 +83,10 @@ Form provides means to add paragraph-level formatting to a logical group of elem
{
"txt": "Do you agree? Yes No",
"fmt": [
- {"at": 0, "len": 20, "tp": "FM"},
- {"at": 0, "len": 13, "tp": "ST"}
+ {"len": 20, "tp": "FM"}, // missing 'at' is zero: "at": 0
+ {"len": 13, "tp": "ST"}
{"at": 13, "len": 1, "tp": "BR"},
- {"at": 14, "len": 3, "key": 0},
+ {"at": 14, "len": 3}, // missing 'key' is zero: "key": 0
{"at": 17, "len": 1, "tp": "BR"},
{"at": 18, "len": 2, "key": 1},
],
@@ -113,6 +116,17 @@ If a `Yes` button is pressed in the example above, the client is expected to sen
}
```
+The form may be optionally represented as an entity:
+```js
+{
+ "tp": "FM",
+ "data": {
+ "su": true
+ }
+}
+```
+The `data.su` describes how interactive form elements behave after the click. An `"su": true` indicates that the form is `single use`: the form should change after the first interaction to show that it's no longer accepting input.
+
### Entities `ent`
In general, an entity is a text decoration which requires additional (possibly large) data. An entity is represented by an object with two fields: `tp` indicates type of the entity, `data` is type-dependent styling information. Unknown fields are ignored.
diff --git a/docs/thecard.md b/docs/thecard.md
index 39b5f23d..8b8b6661 100644
--- a/docs/thecard.md
+++ b/docs/thecard.md
@@ -9,15 +9,15 @@ When `JSON` is used to represent `theCard` data, it does it differently than [jC
`theCard` is structured as an object:
```js
-vcard: {
+{
fn: "John Doe", // string, formatted name of the person or topic.
photo: { // object, avatar photo; either 'data' or 'ref' must be present, all other fields are optional.
- type: "jpeg", // MIME type but with 'image/' dropped.
- data: "Rt53jUU...iVBORw0KGgoA==", // base64-encoded binary image data
- ref: "https://api.tinode.co/file/s/abcdef12345.jpg", // URL of the image.
+ type: "jpeg", // string, MIME type but with 'image/' dropped.
+ data: "Rt53jUU...iVBORw0KGgoA==", // string, base64-encoded binary image data
+ ref: "https://api.tinode.co/file/s/abcdef12345.jpg", // string, URL of the image.
width: 512, // integer, image width in pixels.
height: 512, // integer, image height in pixels.
- size: 123456 // image size in bytes.
+ size: 123456 // integer, image size in bytes.
},
//
// None of the following fields are implemented by any known client:
diff --git a/tinode-db/data.json b/tinode-db/data.json
index 640c38d9..4d15097b 100644
--- a/tinode-db/data.json
+++ b/tinode-db/data.json
@@ -343,10 +343,10 @@
"Concentrate and ask again",
"Don't count on it",
"My reply is no",
- "My sources say no",
+ "My sources say no.",
"Outlook not so good",
- "Very doubtful",
- "All your base are belong to us"
+ "Very doubtful...",
+ "All your base are belong to us."
],
"forms": [
{
@@ -359,7 +359,7 @@
],
"ent": [
{"tp": "BN", "data": {"name": "yes", "act": "pub"}},
- {"tp": "BN", "data": {"name": "yes2", "act": "pub"}}
+ {"tp": "BN", "data": {"name": "duh", "val": "42", "act": "pub"}}
]
},
{
@@ -373,7 +373,7 @@
],
"ent": [
{"tp": "BN", "data": {"name": "ok", "act": "url", "ref": "https://github.com/tinode/chat/?key=val"}},
- {"tp": "BN", "data": {"name": "ok2", "act": "url", "ref": "https://github.com/tinode/chat"}}
+ {"tp": "BN", "data": {"name": "oops", "val": "test", "act": "url", "ref": "https://github.com/tinode/chat"}}
]
}
]