Mercurial > prosody-modules
annotate mod_register_apps/README.markdown @ 5536:96dec7681af8
mod_firewall: Update user marks to store instantly via map store
The original approach was to keep marks in memory only, and persist them at
shutdown. That saves I/O, at the cost of potentially losing marks on an
unclean shutdown.
This change persists marks instantly, which may have some performance overhead
but should be more "correct".
It also splits the marking/unmarking into an event which may be watched or
even fired by other modules.
author | Matthew Wild <mwild1@gmail.com> |
---|---|
date | Thu, 08 Jun 2023 16:20:42 +0100 |
parents | ad9ce6750880 |
children |
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 ``` |