Software /
code /
prosody-modules
Annotate
mod_register_apps/README.markdown @ 4418:8c31d4b872c3
mod_groups_internal: fix log message not appearing
"warning" vs "warn", sigh
author | Jonas Schäfer <jonas@wielicki.name> |
---|---|
date | Sun, 31 Jan 2021 12:20:03 +0100 |
parent | 4183: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' |
4183
ad9ce6750880
mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents:
4113
diff
changeset
|
5 rockspec: |
ad9ce6750880
mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents:
4113
diff
changeset
|
6 build: |
ad9ce6750880
mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents:
4113
diff
changeset
|
7 copy_directories: |
ad9ce6750880
mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents:
4113
diff
changeset
|
8 - assets |
4110
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 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
11 Introduction |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
12 ============ |
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 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
|
15 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
|
16 and mod_invites_register_web. |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
17 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
18 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
|
19 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
|
20 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
21 # Configuration |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
22 |
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
|
23 | 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
|
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 | 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
|
26 | 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
|
27 | 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
|
28 |
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 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
|
30 |
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 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
|
32 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
|
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 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
|
35 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
|
36 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
|
37 |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
38 # 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
|
39 |
c85af57e82e0
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents:
4110
diff
changeset
|
40 The configuration option `site_apps` contains the list |
4110
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
41 of apps and their metadata. |
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 ``` {.lua} |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
44 -- Example site_apps config with two clients |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
45 site_apps = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
46 { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
47 name = "Conversations"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
48 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
|
49 image = "assets/logos/conversations.svg"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
50 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
|
51 platforms = { "Android" }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
52 supports_preauth_uri = true; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
53 magic_link_format = "{app.link!}&referrer={invite.uri}"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
54 download = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
55 buttons = { |
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 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
|
58 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
|
59 }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
60 }; |
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 }; |
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 = "Gajim"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
65 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
|
66 image = "assets/logos/gajim.svg"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
67 link = "https://gajim.org/"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
68 platforms = { "Windows", "Linux" }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
69 download = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
70 buttons = { |
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 text = "Download Gajim"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
73 url = "https://gajim.org/download/"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
74 target = "_blank"; |
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 }; |
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 } |
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 The fields of each client entry are as follows: |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
82 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
83 | Field | Description | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
84 |----------------------|--------------------------------------------------------------------------| |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
85 | name | The name of the client | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
86 | text | Description of the client | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
87 | 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
|
88 | link | URL to the app | |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
89 | 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
|
90 | 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
|
91 | 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
|
92 | download | Download instructions and buttons, described below | |
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 ## Download metadata |
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 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
|
97 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
|
98 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
|
99 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
|
100 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
101 Example download field with instructions and two buttons: |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
102 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
103 ``` {.lua} |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
104 download = { |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
105 text = "Some optional instructions about downloading the client..."; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
106 buttons = { |
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 text = "Button 1: some text"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
109 url = "https://example.com/"; |
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 image = "https://example.com/button2.png"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
113 url = "https://example.com/download/"; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
114 }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
115 }; |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
116 } |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
117 |
fdc84741258d
mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
118 ``` |