Mercurial > prosody-modules
annotate mod_register_apps/README.markdown @ 4139:c6bb64a12f92
mod_muc_inject_mentions: (W213) unused loop variable i
author | Seve Ferrer <seve@delape.net> |
---|---|
date | Sun, 20 Sep 2020 13:34:18 +0200 |
parents | c85af57e82e0 |
children | ad9ce6750880 |
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 |
4113
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
19 | Field | Description | |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
20 |----------------------|--------------------------------------------------------------------------| |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
21 | site_apps | A list of apps and their metadata | |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
22 | site_apps_show | A list of app ids to only show | |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
23 | site_apps_hide | A list of app ids to never show | |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
24 |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
25 An "app id" is the lower case app name, with any spaces replaced by `-`. E.g. "My Chat" would be `"my-chat"`. |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
26 |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
27 The module comes with a preconfigured `site_apps` containing popular clients. Patches are welcome to |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
28 add/update this list as needed! |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
29 |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
30 If you want to limit to just displaying a subset of the apps on your server, use the `site_apps_show` |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
31 option, e.g. `site_apps_show = { "conversations", "siskin-im" }`. To never show specific apps, you |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
32 can use `site_apps_hide`, e.g. `site_apps_hide = { "pidgin" }`. |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
33 |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
34 # App metadata format |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
35 |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
36 The configuration option `site_apps` contains the list |
4110
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
37 of apps and their metadata. |
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 ``` {.lua} |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
40 -- Example site_apps config with two clients |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
41 site_apps = { |
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 = "Conversations"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
44 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
|
45 image = "assets/logos/conversations.svg"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
46 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
|
47 platforms = { "Android" }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
48 supports_preauth_uri = true; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
49 magic_link_format = "{app.link!}&referrer={invite.uri}"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
50 download = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
51 buttons = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
52 { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
53 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
|
54 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
|
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 name = "Gajim"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
61 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
|
62 image = "assets/logos/gajim.svg"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
63 link = "https://gajim.org/"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
64 platforms = { "Windows", "Linux" }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
65 download = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
66 buttons = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
67 { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
68 text = "Download Gajim"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
69 url = "https://gajim.org/download/"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
70 target = "_blank"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
71 }; |
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 }; |
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 } |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
76 ``` |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
77 The fields of each client entry are as follows: |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
78 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
79 | Field | Description | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
80 |----------------------|--------------------------------------------------------------------------| |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
81 | name | The name of the client | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
82 | text | Description of the client | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
83 | 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
|
84 | link | URL to the app | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
85 | 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
|
86 | 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
|
87 | 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
|
88 | download | Download instructions and buttons, described below | |
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 ## Download metadata |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
91 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
92 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
|
93 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
|
94 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
|
95 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
|
96 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
97 Example download field with instructions and two buttons: |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
98 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
99 ``` {.lua} |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
100 download = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
101 text = "Some optional instructions about downloading the client..."; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
102 buttons = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
103 { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
104 text = "Button 1: some text"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
105 url = "https://example.com/"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
106 }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
107 { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
108 image = "https://example.com/button2.png"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
109 url = "https://example.com/download/"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
110 }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
111 }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
112 } |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
113 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
114 ``` |