View Source Bonfire.Boundaries.Circles (Bonfire v0.9.10-classic-beta.169)
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
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.
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])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"}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"}}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)
nilRetrieves 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"}}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.
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])
falseChecks 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")
falseRemoves 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"}]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"}]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"}]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}]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"}]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"}]Generates a query for circles
Examples
iex> Bonfire.Boundaries.Circles.query(exclude_built_ins: true)Generates a query for circles owned by a user.
Examples
iex> Bonfire.Boundaries.Circles.query_my(user)Generates a query for a specific circle owned by a user.
Examples
iex> Bonfire.Boundaries.Circles.query_my_by_id("circle_id", user)Generates a query for visible circles for a user.
Examples
iex> Bonfire.Boundaries.Circles.query_visible(user)
#Ecto.Query<...>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"]