Mercurial > prosody-modules

comparison mod_compat_roles/README.markdown @ 4983:7c77058a1ac5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_compat_roles: New module providing compat shim for trunk's new role API The new role API is translated to is_admin() calls on older versions. On newer versions (which have the role API) this module does nothing. It allows modules to drop their use of is_admin() (which is not available in trunk) and switch to the new role API, while remaining compatible with previous Prosody versions.
author Matthew Wild <mwild1@gmail.com>
date Thu, 11 Aug 2022 17:49:33 +0100
parents
children fc6a618bfe4e
comparison
equal deleted inserted replaced
4982:8a4b17e2e984 4983:7c77058a1ac5
1 ---
2 labels:
3 - Stage-Alpha
4 summary: 'Compatibility layer for Prosody's future roles API'
5 ...
6
7 Introduction
8 ============
9
10 This module provides compatibility with Prosody's new role and permissions
11 system. It aims to run on Prosody 0.11 and 0.12, providing a limited version
12 of the new API backed by is_admin() (which is not going to be present in trunk
13 and future Prosody versions).
14
15 It is designed for use by modules which want to be compatible with Prosody
16 versions with and without the new permissions API.
17
18 Configuration
19 =============
20
21 There is no configuration.
22
23 Usage (for developers)
24 ======================
25
26 If you are a module developer, and want your module to work with Prosody trunk
27 and future releases, you should avoid the `usermanager.is_admin()` function.
28
29 Instead, depend on this module:
30
31 ```
32 module:depends("compat_roles")
33 ```
34
35 Then use `module:may()` instead:
36
37 ```
38 if module:may(":do-something") then
39 -- Blah
40 end
41 ```
42
43 For more information on the new role/permissions API, check Prosody's
44 developer documentation at https://prosody.im/doc/developers/permissions
45
46 Compatibility
47 =============
48
49 Requires Prosody 0.11 or 0.12.