View Source Bonfire.Boundaries.Roles (Bonfire v0.9.10-classic-beta.156)

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

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.

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

Link to this function

cannot_role_from_verb(verbs, verb_field \\ :verb, all_role_verbs \\ role_verbs(:all), role_for_all \\ :read, verbs_field \\ :cannot_verbs)

View Source

Determines 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)
Link to this function

create(name, usage, opts)

View Source

Creates a role with a given name, usage, and options.

Examples

iex> create("Admin", :admin, opts)
# creates an admin role with the provided options
Link to this function

edit_verb_permission(role_name, verb, value, opts)

View Source

Edits 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 default
Link to this function

get(role_name, opts \\ [])

View Source

Retrieves the details of a role by role_name.

Examples

iex> get(:admin)
# returns admin role details
Link to this function

preset_boundary_role_from_acl(summary)

View Source

Determines 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.

Link to this function

role_from_grants(grants, opts)

View Source

Determines the matching role (if any) from a list of verbs.

Examples

iex> role_from_grants(grants)
Link to this function

role_from_verb(verbs, verb_field \\ :verb, all_role_verbs \\ role_verbs(:all), role_for_all \\ :administer, verbs_field \\ :can_verbs)

View Source

Determines a matching positive role (if any) from a list of verbs.

Examples

iex> role_from_verb(verbs)
Link to this function

role_verbs(usage \\ :all, opts \\ [])

View Source

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 
Link to this function

roles_for_dropdown(usage \\ nil, opts)

View Source

Returns a list of roles to be used in a user's a dropdown menu.

Examples

iex> roles_for_dropdown(:ops, current_user: me)
Link to this function

split_tuples_can_cannot(tuples)

View Source

Splits a list of tuples into can and cannot categories.

Examples

iex> split_tuples_can_cannot(tuples)
# splits tuples into can and cannot categories
Link to this function

verbs_for_role(role, opts \\ [])

View Source

Returns a list of positive and negative verbs for the given role.

Examples

iex> verbs_for_role(:admin)
{:ok, positive_verbs, negative_verbs}