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

Functions to create, query, and manage circles, which are used to group users (for the purpose of control access to various resources).

Circles are a way of categorizing users. Each user can have their own set of circles to categorize other users. Circles allow a user to group work colleagues differently from friends for example, and to allow different interactions for users in each circle or limit content visibility on a per-item basis.

Circles are a tool that can be used to establish relationships. They are representations of multifaceted relationships that you have with people in your life. Circles can help you understand the different levels of intimacy and trust that you have with different people, as well the different contexts or topics which are relevant to particular relationships, and can help build stronger, healthier relationships.

In Bonfire, you can define circles based on your unique style of relationships and interests. For example, you might create a circle for your colleagues, which can help you keep track of work-related content and collaborate with them more efficiently. You could also have a locals circle, with which you may share and discover local events, news, and recommendations. You might also create a comrades circle, to stay connected with fellow activists and organise around shared goals. Finally, you could create a happy hour circle, to coordinate social gatherings with local friends or colleagues, and the crew for your inner circle. With circles, you have the flexibility to manage your relationships and social activities in a way that makes sense for you.

The corresponding Ecto schema are Bonfire.Data.AccessControl.Circle and Bonfire.Data.AccessControl.Encircle which is defined in a seperate repo.

Summary

Functions

Adds subject(s) to circle(s).

Returns a list of built-in circle IDs.

Converts a list of circles to circle IDs.

Returns a list of special built-in circles (e.g., guest, local, activity_pub).

Creates a new circle for the provided user.

Deletes a circle and its associated data, including membership and boundary information. This will affect all objects previously shared with members of this circle

Edits a circle's attributes.

Empties circles by removing all members.

Retrieves a circle by its slug or ID.

Retrieves a circle by name for a caretaker.

Retrieves a circle for a caretaker by ID.

Retrieves the ID of a circle by its slug.

Retrieves or creates a circle by name for a caretaker.

Retrieves stereotype circles for a subject.

Retrieves a tuple containing the name and ID of a circle by its slug or ID.

Checks if a circle is a built-in circle.

Checks if a subject is encircled by a circle or list of circles.

Checks if a circle is a stereotype circle.

Removes user(s) from all circles.

Lists all built-in circles.

Lists circles by their IDs.

Lists circles owned by a user.

Lists default circles for a user.

Lists circles owned by a user with member counts.

Lists circles owned by a user and global/built-in circles.

Lists visible circles for a user.

Generates a query for circles

Generates a query for circles owned by a user.

Generates a query for a specific circle owned by a user.

Generates a query for visible circles for a user.

Removes a user from circles.

Returns a list of stereotype circle IDs.

Returns a list of stereotype IDs for a specific category.

Converts a list of circles to circle IDs, including adding default circles (such as local or activity_pub when relevant)

Functions

Link to this function

add_to_circles(subjects, circles)

View Source

Adds subject(s) to circle(s).

Examples

iex> Bonfire.Boundaries.Circles.add_to_circles(user, circle)
{:ok, %Encircle{}}

iex> Bonfire.Boundaries.Circles.add_to_circles([user1, user2], [circle1, circle2])
[{{:ok, %Encircle{}}, {:ok, %Encircle{}}}, {{:ok, %Encircle{}}, {:ok, %Encircle{}}}]

Returns a list of built-in circle IDs.

Link to this function

changeset(circle \\ %Circle{}, attrs)

View Source
Link to this function

changeset(atom, circle, params)

View Source

Converts a list of circles to circle IDs.

Examples

iex> Bonfire.Boundaries.Circles.circle_ids([:guest, :local])
["guest_circle_id", "local_circle_id"]

iex> Bonfire.Boundaries.Circles.circle_ids(%{id: "user_id"})
"user_id"

Returns a list of special built-in circles (e.g., guest, local, activity_pub).

Creates a new circle for the provided user.

Examples

iex> Bonfire.Boundaries.Circles.create(user, %{named: %{name: "My Circle"}})
{:ok, %Circle{id: "new_circle_id", name: "My Circle"}}

Deletes a circle and its associated data, including membership and boundary information. This will affect all objects previously shared with members of this circle

Examples

iex> Bonfire.Boundaries.Circles.delete(circle, [current_user: user])

iex> Bonfire.Boundaries.Circles.delete("circle_id", [current_user: user])
Link to this function

edit(circle, user, params)

View Source

Edits a circle's attributes.

Examples

iex> Bonfire.Boundaries.Circles.edit(circle, user, %{name: "Updated Circle"})
{:ok, %Circle{id: "circle_id", name: "Updated Circle"}}

Empties circles by removing all members.

Examples

iex> Bonfire.Boundaries.Circles.empty_circles([circle1, circle2])
{10, nil}

Retrieves a circle by its slug or ID.

Examples

iex> Bonfire.Boundaries.Circles.get(:guest)
%{id: "guest_circle_id", name: "Guest"}

iex> Bonfire.Boundaries.Circles.get("circle_id")
%Circle{id: "circle_id", name: "Custom Circle"}
Link to this function

get_by_name(name, caretaker)

View Source

Retrieves a circle by name for a caretaker.

Examples

iex> Bonfire.Boundaries.Circles.get_by_name("My Circle", user)
{:ok, %Circle{id: "circle_id", name: "My Circle"}}
Link to this function

get_for_caretaker(id, caretaker, opts \\ [])

View Source

Retrieves a circle for a caretaker by ID.

Examples

iex> Bonfire.Boundaries.Circles.get_for_caretaker("circle_id", user)
{:ok, %Circle{id: "circle_id", name: "My Circle"}}

Retrieves the ID of a circle by its slug.

Examples

iex> Bonfire.Boundaries.Circles.get_id(:guest)
"guest_circle_id"

iex> Bonfire.Boundaries.Circles.get_id(:nonexistent)
nil
Link to this function

get_or_create(name, caretaker \\ nil)

View Source

Retrieves or creates a circle by name for a caretaker.

Examples

iex> Bonfire.Boundaries.Circles.get_or_create("New Circle", user)
{:ok, %Circle{id: "new_circle_id", name: "New Circle"}}
Link to this function

get_stereotype_circles(subject, stereotypes)

View Source

Retrieves stereotype circles for a subject.

Examples

iex> Bonfire.Boundaries.Circles.get_stereotype_circles(user, [:follow, :block])
[%Circle{id: "follow_circle_id", name: "Follow"}, %Circle{id: "block_circle_id", name: "Block"}]

Retrieves a tuple containing the name and ID of a circle by its slug or ID.

Examples

iex> Bonfire.Boundaries.Circles.get_tuple(:guest)
{"Guest", "guest_circle_id"}

iex> Bonfire.Boundaries.Circles.get_tuple("circle_id")
{:my_circle, %{id: "circle_id", name: "My Circle"}}

Checks if a circle is a built-in circle.

Link to this function

is_encircled_by?(subject, circle)

View Source

Checks if a subject is encircled by a circle or list of circles.

Examples

iex> Bonfire.Boundaries.Circles.is_encircled_by?(user, circle)
true

iex> Bonfire.Boundaries.Circles.is_encircled_by?(user, [circle1, circle2])
false

Checks if a circle is a stereotype circle.

Examples

iex> Bonfire.Boundaries.Circles.is_stereotype?("7DAPE0P1E1PERM1TT0F0110WME")
true

iex> Bonfire.Boundaries.Circles.is_stereotype?("custom_circle_id")
false
Link to this function

leave_all_circles(users)

View Source

Removes user(s) from all circles.

Examples

iex> Bonfire.Boundaries.Circles.empty_circles([circle1, circle2])
{10, nil}

Lists all built-in circles.

Examples

iex> Bonfire.Boundaries.Circles.list_built_ins()
[%Circle{id: "guest_circle_id", name: "Guest"}, %Circle{id: "local_circle_id", name: "Local"}]

Lists circles by their IDs.

Examples

iex> Bonfire.Boundaries.Circles.list_by_ids(["circle_id1", "circle_id2"])
[%Circle{id: "circle_id1", name: "Circle 1"}, %Circle{id: "circle_id2", name: "Circle 2"}]
Link to this function

list_my(user, opts \\ [])

View Source

Lists circles owned by a user.

Includes circles we are the registered caretakers of that we are permitted to see. If any circles are created without permitting the user to see them, they will not be shown.

Examples

iex> Bonfire.Boundaries.Circles.list_my(user)
[%Circle{id: "circle_id1", name: "My Circle 1"}, %Circle{id: "circle_id2", name: "My Circle 2"}]
Link to this function

list_my_defaults(user \\ nil)

View Source

Lists default circles for a user.

Examples

iex> Bonfire.Boundaries.Circles.list_my_defaults()
[{"Guest", "guest_circle_id"}, {"Local", "local_circle_id"}, {"ActivityPub", "activity_pub_circle_id"}]
Link to this function

list_my_with_counts(user, opts \\ [])

View Source

Lists circles owned by a user with member counts.

Examples

iex> Bonfire.Boundaries.Circles.list_my_with_counts(user)
[%Circle{id: "circle_id1", name: "My Circle", encircles_count: 5}]
Link to this function

list_my_with_global(user, opts \\ [])

View Source

Lists circles owned by a user and global/built-in circles.

Examples

iex> Bonfire.Boundaries.Circles.list_my_with_global(user)
[%Circle{id: "circle_id1", name: "My Circle"}, %Circle{id: "global_circle_id", name: "Global Circle"}]
Link to this function

list_visible(user, opts \\ [])

View Source

Lists visible circles for a user.

Examples

iex> Bonfire.Boundaries.Circles.list_visible(user)
[%Circle{id: "circle_id1", name: "Circle 1"}, %Circle{id: "circle_id2", name: "Circle 2"}]
Link to this function

preload_encircled_by(subject, circles, opts \\ [])

View Source

Generates a query for circles

Examples

iex> Bonfire.Boundaries.Circles.query(exclude_built_ins: true)
Link to this function

query_my(caretaker, opts \\ [])

View Source

Generates a query for circles owned by a user.

Examples

iex> Bonfire.Boundaries.Circles.query_my(user)
Link to this function

query_my_by_id(id, caretaker, opts \\ [])

View Source

Generates a query for a specific circle owned by a user.

Examples

iex> Bonfire.Boundaries.Circles.query_my_by_id("circle_id", user)
Link to this function

query_visible(user, opts \\ [])

View Source

Generates a query for visible circles for a user.

Examples

iex> Bonfire.Boundaries.Circles.query_visible(user)
#Ecto.Query<...>
Link to this function

remove_from_circles(subject, circles)

View Source

Removes a user from circles.

Examples

iex> Bonfire.Boundaries.Circles.remove_from_circles(user, circle)
{1, nil}

iex> Bonfire.Boundaries.Circles.remove_from_circles(user, [circle1, circle2])
{2, nil}

Returns a list of stereotype circle IDs.

Returns a list of stereotype IDs for a specific category.

Examples

iex> Bonfire.Boundaries.Circles.stereotypes(:follow)

iex> Bonfire.Boundaries.Circles.stereotypes(:block)

Converts a list of circles to circle IDs, including adding default circles (such as local or activity_pub when relevant)

Examples

iex> Bonfire.Boundaries.Circles.to_circle_ids([:guest, :custom])
["guest_circle_id", "custom_circle_id", "local_circle_id", "activity_pub_circle_id"]