View Source Bonfire.Boundaries.Roles (Bonfire v0.9.10-classic-beta.169)
Roles are groups of verbs associated with permissions. While not stored in the database, they are defined at the configuration level to enhance readability and user experience.
Here are some preset roles and their associated actions:
- Read: can discover the content in lists (like feeds) and read it; request permission for another verb (e.g., request to follow).
- Interact: can read, plus like an object (and notify the author); follow a user or thread; boost an object (and notify the author); pin something to highlight it.
- Participate: can interact, plus reply to an activity or post; mention a user or object (and notify them); send a message.
- Contribute: can participate, plus create a post or other object; tag a user or object or publish in a topic.
- Caretaker: can perform all of the above actions and more, including actions like deletion.
There are also negative roles, indicating actions which you specifically do not want to allow a particular circle or user to do, such as:
- Cannot Read: not discoverable in lists or readable, and also can't interact or participate.
- Cannot Interact: cannot perform any actions related to interaction, including liking, following, boosting, and pinning, and also can't participate.
- Cannot Participate: cannot perform any actions related to participation, including replying, mentioning, and sending messages.
Negative permissions always take precedence over positive or undefined permissions. For example, For example, if you share something giving permission to anyone to read and reply to it, and you assign the Cannot Participate role to your Likely to troll circle, the people in that circle will be able to read the content but will not be able to reply to it.
Note that these negative roles do not grant any additional permissions. Assigning the Cannot Participate role to someone who wouldn't otherwise be able to read the content does not mean they will now have the ability to do so. Negative roles simply limit or override any permissions defined elsewhere, ensuring that the specified actions are explicitly restricted.
Summary
Functions
Determines a matching negative role (if any) from a list of verbs.
Creates a role with given attributes and options.
Creates a role with a given name, usage, and options.
Edits a verb permission for a role
Retrieves the details of a role by role_name.
Determines the preset boundary role from an ACL summary or list of verbs.
Clears instance-wide roles from config.
Determines the matching role (if any) from a list of verbs.
Determines a matching positive role (if any) from a list of verbs.
Retrieves role verbs based on the given usage.
Returns a list of roles to be used in a user's a dropdown menu.
Splits a list of tuples into can and cannot categories.
Returns a list of positive and negative verbs for the given role.
Functions
cannot_role_from_verb(verbs, verb_field \\ :verb, all_role_verbs \\ role_verbs(:all), role_for_all \\ :read, verbs_field \\ :cannot_verbs)
View SourceDetermines a matching negative role (if any) from a list of verbs.
Examples
iex> cannot_role_from_verb(verbs)Creates a role with given attributes and options.
Examples
iex> create(attrs, opts)Creates a role with a given name, usage, and options.
Examples
iex> create("Admin", :admin, opts)
# creates an admin role with the provided optionsEdits a verb permission for a role
Examples
iex> edit_verb_permission(:admin, :read, true, opts)
# updates the read permission for the admin role to true
iex> edit_verb_permission(:admin, :read, false, opts)
# updates the read permission for the admin role to false
iex> edit_verb_permission(:admin, :read, nil, opts)
# resets the read permission for the admin role to defaultRetrieves the details of a role by role_name.
Examples
iex> get(:admin)
# returns admin role detailsDetermines the preset boundary role from an ACL summary or list of verbs.
Examples
iex> preset_boundary_role_from_acl(%{verbs: verbs})
iex> preset_boundary_role_from_acl(verbs)Clears instance-wide roles from config.
Determines the matching role (if any) from a list of verbs.
Examples
iex> role_from_grants(grants)role_from_verb(verbs, verb_field \\ :verb, all_role_verbs \\ role_verbs(:all), role_for_all \\ :administer, verbs_field \\ :can_verbs)
View SourceDetermines a matching positive role (if any) from a list of verbs.
Examples
iex> role_from_verb(verbs)Retrieves role verbs based on the given usage.
Examples
iex> role_verbs(:all, scope: :instance)
# returns all instance-level role verbs
iex> role_verbs(nil, current_user: me)
# returns my role verbs Returns a list of roles to be used in a user's a dropdown menu.
Examples
iex> roles_for_dropdown(:ops, current_user: me)Splits a list of tuples into can and cannot categories.
Examples
iex> split_tuples_can_cannot(tuples)
# splits tuples into can and cannot categoriesReturns a list of positive and negative verbs for the given role.
Examples
iex> verbs_for_role(:admin)
{:ok, positive_verbs, negative_verbs}