Mercurial > prosody-modules

annotate mod_register_apps/README.markdown @ 4918:9d0ec61c70a1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_rest: Catch and coerce errors in echo endpoint This should ensure problems in encode() are reported back
author Kim Alvefur <zash@zash.se>
date Thu, 07 Apr 2022 17:48:08 +0200
parents ad9ce6750880
children
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'
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 ```