Mercurial > prosody-modules

annotate mod_register_apps/README.markdown @ 4113:c85af57e82e0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
author Matthew Wild <mwild1@gmail.com>
date Sat, 12 Sep 2020 10:42:37 +0100
parents fdc84741258d
children ad9ce6750880
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
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 ```