Mercurial > prosody-modules

annotate mod_register_apps/README.markdown @ 4110:fdc84741258d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_register_apps: Add missing docs
author Matthew Wild <mwild1@gmail.com>
date Fri, 11 Sep 2020 16:57:09 +0100
parents
children c85af57e82e0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4110
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - 'Stage-Beta'
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: 'Manage list of compatible client apps'
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ...
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 Introduction
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 ============
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10 This module provides a way to configure a list of XMPP client apps recommended
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11 by the current server. This list is used by other modules such as mod_invites_page
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12 and mod_invites_register_web.
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 It also contains the logos of a number of popular XMPP clients, and serves
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15 them over HTTP for other modules to reference when serving web pages.
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 # Configuration
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 There is one configuration option, `site_apps`, which contains the list
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 of apps and their metadata.
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22 ``` {.lua}
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 -- Example site_apps config with two clients
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 site_apps = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 name = "Conversations";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 text = [[Conversations is a Jabber/XMPP client for Android 4.0+ smartphones that has been optimized to provide a unique mobile experience.]];
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 image = "assets/logos/conversations.svg";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 link = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 platforms = { "Android" };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 supports_preauth_uri = true;
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 magic_link_format = "{app.link!}&referrer={invite.uri}";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 download = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 buttons = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 image = "https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 url = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 name = "Gajim";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 text = [[A fully-featured desktop chat client for Windows and Linux.]];
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 image = "assets/logos/gajim.svg";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 link = "https://gajim.org/";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47 platforms = { "Windows", "Linux" };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 download = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49 buttons = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51 text = "Download Gajim";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 url = "https://gajim.org/download/";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53 target = "_blank";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 }
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 ```
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60 The fields of each client entry are as follows:
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 | Field | Description |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 |----------------------|--------------------------------------------------------------------------|
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 | name | The name of the client |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65 | text | Description of the client |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66 | image | URL to a logo for the client, may also be a path in the assets/ directory|
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67 | link | URL to the app |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68 | platforms | A list of platforms the app can be installed on |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69 | supports_preauth_uri | `true` if the client supports XEP-0401 preauth URIs |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 | magic_link_format | A template to generate a magic installation link from an invite |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 | download | Download instructions and buttons, described below |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73 ## Download metadata
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 The `download` field supports an optional text prompt and one or more buttons.
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76 Each button must contain either a `text` or `image` field and must contain
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 a `url` field. It is recommended to set `target = "_blank"` if the link
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 opens a new page, so that the user doesn't lose the invite page.
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
80 Example download field with instructions and two buttons:
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
81
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
82 ``` {.lua}
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
83 download = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
84 text = "Some optional instructions about downloading the client...";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
85 buttons = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
86 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
87 text = "Button 1: some text";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
88 url = "https://example.com/";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
89 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
90 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
91 image = "https://example.com/button2.png";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
92 url = "https://example.com/download/";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
93 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
94 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
95 }
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
96
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
97 ```