Mercurial > prosody-modules

annotate mod_invites_page/README.markdown @ 5356:959dc350f2ad

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_oauth2: Declare https as required of URIs in schema If util.jsonschema happens to gain support for 'pattern' (regular expression validation) then this would be picked up. Until then, declarative annotations are nice.
author Kim Alvefur <zash@zash.se>
date Sat, 22 Apr 2023 14:06:41 +0200
parents 027fb71ad509
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4094
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - 'Stage-Beta'
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: 'Generate friendly web page for invitations'
4104
476afcbfb3e9 various: Add some dependency metadata
Kim Alvefur <zash@zash.se>
parents: 4094
diff changeset
5 rockspec:
476afcbfb3e9 various: Add some dependency metadata
Kim Alvefur <zash@zash.se>
parents: 4094
diff changeset
6 dependencies:
4105
233e170eb027 various: Dependency metadata needs the mod_ prefix
Kim Alvefur <zash@zash.se>
parents: 4104
diff changeset
7 - mod_register_apps
4104
476afcbfb3e9 various: Add some dependency metadata
Kim Alvefur <zash@zash.se>
parents: 4094
diff changeset
8 build:
476afcbfb3e9 various: Add some dependency metadata
Kim Alvefur <zash@zash.se>
parents: 4094
diff changeset
9 copy_directories:
476afcbfb3e9 various: Add some dependency metadata
Kim Alvefur <zash@zash.se>
parents: 4094
diff changeset
10 - html
476afcbfb3e9 various: Add some dependency metadata
Kim Alvefur <zash@zash.se>
parents: 4094
diff changeset
11 - static
4094
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12 ...
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 Introduction
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15 ============
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 This module is part of the suite of modules that implement invite-based
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 account registration for Prosody. The other modules are:
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4201
diff changeset
20 - [mod_invites]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4201
diff changeset
21 - [mod_invites_adhoc]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4201
diff changeset
22 - [mod_invites_register]
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4201
diff changeset
23 - [mod_invites_register_web]
4224
816c2fa1ca84 mod_invites*: Also link to mod_invites_api
Kim Alvefur <zash@zash.se>
parents: 4223
diff changeset
24 - [mod_invites_api]
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4201
diff changeset
25 - [mod_register_apps]
4094
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26
4223
4ec755c13e9b mod_invites*: Link to each other
Kim Alvefur <zash@zash.se>
parents: 4201
diff changeset
27 For details and a full overview, start with the [mod_invites] documentation.
4094
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 Details
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 =======
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 mod_invites_page provides a unique web page for each generated invitation.
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 Without this module, Prosody will only be able to generate invite links as
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 `xmpp:` URIs (they look something like `xmpp:example.com?register;preauth=29Xbxr91`).
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 URIs will only work if the invited user already has an XMPP client installed.
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 This is usually not the case.
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38 This module transforms the URI into a friendly web page that can be shared
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 via any method (email, SMS, etc.), and opened in any browser. The page explains
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40 the invitation and guides the user to set up their account using one of a
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 configurable list of XMPP clients (to configure the list, see mod_register_apps
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 documentation).
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 Configuration
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 =============
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46
4402
85c11eb4331b mod_invites_page: Allow disabling of built-in pages with invites_page_external option
Matthew Wild <mwild1@gmail.com>
parents: 4224
diff changeset
47 | Name | Description | Default |
85c11eb4331b mod_invites_page: Allow disabling of built-in pages with invites_page_external option
Matthew Wild <mwild1@gmail.com>
parents: 4224
diff changeset
48 |---------------------------|--------------------------------------------------------------------------------|-----------------------------------------------------|
85c11eb4331b mod_invites_page: Allow disabling of built-in pages with invites_page_external option
Matthew Wild <mwild1@gmail.com>
parents: 4224
diff changeset
49 | invites_page | The format of an invite page URL (must begin with `https://`) | `"https://{host}:5281/invites_page?{invite.token}"` |
85c11eb4331b mod_invites_page: Allow disabling of built-in pages with invites_page_external option
Matthew Wild <mwild1@gmail.com>
parents: 4224
diff changeset
50 | invites_registration_page | The format of an invite registration page URL (may be relative to invites_page)| `"register?t={invite.token}&c={app.id}"` |
85c11eb4331b mod_invites_page: Allow disabling of built-in pages with invites_page_external option
Matthew Wild <mwild1@gmail.com>
parents: 4224
diff changeset
51 | site_name | The friendly name of the server | `"example.com"` |
85c11eb4331b mod_invites_page: Allow disabling of built-in pages with invites_page_external option
Matthew Wild <mwild1@gmail.com>
parents: 4224
diff changeset
52 | invites_page_external | Set this to true if your invitation pages will be rendered by something else | `false` |
4094
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 The `invites_page` and `invites_registration_page` options are templates
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 that support a number of variables. The most useful being `{host}` and
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 `{invite.token}`.
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 All the usual [HTTP configuration options](https://prosody.im/doc/http)
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 can be used to configure this module. In particular, if you run Prosody
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60 behind a reverse proxy such as nginx or Apache, you will probably want
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61 to set `http_external_url` so that Prosody knows what URLs should look
dd00a2b9927c mod_invites_page: New module to generate landing page for invites
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 like for users.
4402
85c11eb4331b mod_invites_page: Allow disabling of built-in pages with invites_page_external option
Matthew Wild <mwild1@gmail.com>
parents: 4224
diff changeset
63
85c11eb4331b mod_invites_page: Allow disabling of built-in pages with invites_page_external option
Matthew Wild <mwild1@gmail.com>
parents: 4224
diff changeset
64 If you want to disable this module's built-in pages and use an external
85c11eb4331b mod_invites_page: Allow disabling of built-in pages with invites_page_external option
Matthew Wild <mwild1@gmail.com>
parents: 4224
diff changeset
65 invitation page generator (such as [ge0rg/easy-xmpp-invitation](https://github.com/ge0rg/easy-xmpp-invitation)
85c11eb4331b mod_invites_page: Allow disabling of built-in pages with invites_page_external option
Matthew Wild <mwild1@gmail.com>
parents: 4224
diff changeset
66 then set `invites_page_external = true` and set `invites_page` to the
85c11eb4331b mod_invites_page: Allow disabling of built-in pages with invites_page_external option
Matthew Wild <mwild1@gmail.com>
parents: 4224
diff changeset
67 appropriate URL for your installation.