view mod_register_apps/README.markdown @ 5418:f2c7bb3af600

mod_http_oauth2: Add role selector to consent page List includes all roles available to the user, if more than one. Defaults to either the first role in the scope string or the users primary role. Earlier draft listed all roles, but having options that can't be selected is bad UX and the entire list of all roles on the server could be long, and perhaps even sensitive. Allows e.g. picking a role with fewer permissions than what might otherwise have been selected. UX wise, doing this with more checkboxes or possibly radio buttons would have been confusion and/or looked messier. Fixes the previous situation where unselecting a role would default to the primary role, which could be more permissions than requested.
author Kim Alvefur <zash@zash.se>
date Fri, 05 May 2023 01:23:13 +0200
parents ad9ce6750880
children
line wrap: on
line source

---
labels:
- 'Stage-Beta'
summary: 'Manage list of compatible client apps'
rockspec:
  build:
    copy_directories:
    - assets
...

Introduction
============

This module provides a way to configure a list of XMPP client apps recommended
by the current server. This list is used by other modules such as mod_invites_page
and mod_invites_register_web.

It also contains the logos of a number of popular XMPP clients, and serves
them over HTTP for other modules to reference when serving web pages.

# Configuration

| Field                | Description                                                              |
|----------------------|--------------------------------------------------------------------------|
| site_apps            | A list of apps and their metadata                                        |
| site_apps_show       | A list of app ids to only show                                           |
| site_apps_hide       | A list of app ids to never show                                          |

An "app id" is the lower case app name, with any spaces replaced by `-`. E.g. "My Chat" would be `"my-chat"`.

The module comes with a preconfigured `site_apps` containing popular clients. Patches are welcome to
add/update this list as needed!

If you want to limit to just displaying a subset of the apps on your server, use the `site_apps_show`
option, e.g. `site_apps_show = { "conversations", "siskin-im" }`. To never show specific apps, you
can use `site_apps_hide`, e.g. `site_apps_hide = { "pidgin" }`.

# App metadata format

The configuration option `site_apps` contains the list
of apps and their metadata.

``` {.lua}
-- Example site_apps config with two clients
site_apps = {
	{
		name = "Conversations";
		text = [[Conversations is a Jabber/XMPP client for Android 4.0+ smartphones that has been optimized to provide a unique mobile experience.]];
		image = "assets/logos/conversations.svg";
		link = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
		platforms = { "Android" };
		supports_preauth_uri = true;
		magic_link_format = "{app.link!}&referrer={invite.uri}";
		download = {
			buttons = {
				{
					image = "https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png";
					url = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
				};
			};
		};
	};
    {
		name  = "Gajim";
		text  = [[A fully-featured desktop chat client for Windows and Linux.]];
		image = "assets/logos/gajim.svg";
		link  = "https://gajim.org/";
		platforms = { "Windows", "Linux" };
		download = {
			buttons = {
				{ 
					text = "Download Gajim";
					url = "https://gajim.org/download/";
					target = "_blank";
				};
			};
		};
	};
}
```
The fields of each client entry are as follows:

| Field                | Description                                                              |
|----------------------|--------------------------------------------------------------------------|
| name                 | The name of the client                                                   |
| text                 | Description of the client                                                |
| image                | URL to a logo for the client, may also be a path in the assets/ directory|
| link                 | URL to the app                                                           |
| platforms            | A list of platforms the app can be installed on                          |
| supports_preauth_uri | `true` if the client supports XEP-0401 preauth URIs                      |
| magic_link_format    | A template to generate a magic installation link from an invite          |
| download             | Download instructions and buttons, described below                       |

## Download metadata

The `download` field supports an optional text prompt and one or more buttons.
Each button must contain either a `text` or `image` field and must contain
a `url` field. It is recommended to set `target = "_blank"` if the link
opens a new page, so that the user doesn't lose the invite page.

Example download field with instructions and two buttons:

``` {.lua}
download = {
    text = "Some optional instructions about downloading the client...";
    buttons = {
        {
            text = "Button 1: some text";
            url = "https://example.com/";
        };
        {
            image = "https://example.com/button2.png";
            url = "https://example.com/download/";
        };
    };
}

```