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. @@ -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"}} ] } ]
Do you agree?
Yes