Skip to content

Commit 691e847

Browse files
safatshahinsafatshahin
committed
[docs] Communication subsystem docs for MDL-79961
1 parent 665abb8 commit 691e847

File tree

2 files changed

+269
-0
lines changed

2 files changed

+269
-0
lines changed

Diff for: ‎docs/apis.md

+4
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,10 @@ The [Check API](./apis/subsystems/check/index.md) allows you to add security, pe
9292

9393
The [Comment API](https://docs.moodle.org/dev/Comment_API) allows you to save and retrieve user comments, so that you can easily add commenting to any of your code.
9494

95+
### Communication API (communication)
96+
97+
The [Communication API](./apis/subsystems/communication/index.md) provides access to the messaging system and other communication providers (such as Matrix).
98+
9599
### Competency API (competency)
96100

97101
The [Competency API](https://docs.moodle.org/dev/Competency_API) allows you to list and add evidence of competencies to learning plans, learning plan templates, frameworks, courses and activities.

Diff for: ‎docs/apis/subsystems/communication/index.md

+265
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
---
2+
title: Communication API
3+
tags:
4+
- communication
5+
- provider
6+
- Communication provider
7+
- Communication room
8+
- Communication service
9+
- Chat
10+
documentationDraft: true
11+
---
12+
13+
Communication API provides access to the messaging system and other communication providers (such as Matrix).
14+
This API the management of room and members to that room.
15+
16+
Communication API actions its tasks happens asynchronously using ad-hoc tasks. This means that the API functions will return immediately and the action will be
17+
executed in the background. Communication API has multiple interfaces which acts like a feature of the API. Each of these interface/features have one or more associated
18+
ad-hoc tasks. These tasks are responsible to action the requested feature from the provider plugin (such as Matrix) informed by the Communication API instance. For developers
19+
to interact with the API, they must use the public API (`communication\api`).
20+
21+
Communication API allows to add ad-hoc tasks to the queue to perform actions on the communication providers. This API will not allow any immediate actions to be performed on the
22+
communication providers. It will only add the tasks to the queue. The exception has been made for deletion of members in case of deleting the user. This is because the user will
23+
not be available for any checks (capability, role etc.) after deleted.
24+
25+
:::info
26+
27+
This is an experimental feature. To use this feature, you must enable the experimental feature flag for Communication in the site administration.
28+
Please follow the steps to enable the feature.
29+
30+
1. Navigate to `Site administration > Development > Experimental` settings.
31+
2. Tick the checkbox to enable the following feature: Enable communication providers (`enablecommunicationsubsystem`).
32+
33+
:::
34+
35+
## Important features of the API
36+
37+
The below are the important methods/features of the API. These methods/features are the ones which can be used to interact with the communication API.
38+
39+
### Loading a communication instance
40+
41+
To load a communication instance, you must use the `communication\api::load_by_instance()` method. This method will return a communication instance which can be
42+
used to interact with the communication API and its related methods. The below example shows how to load a communication instance for a course, where the
43+
context is the actual course context object, component is the component name (`core_course`), instance type is the custom string which can change according to
44+
the usage and instance id is the course id. The constructor of the public api is private and hence the only way to load an instance is through
45+
the `load_by_instance()` method. The provider is the name of the provider plugin which is used to load the instance. It's optional, if not provided, it will load
46+
the enabled provider for that instance.
47+
48+
```php
49+
$communication = \core_communication\api::load_by_instance(
50+
context: $context,
51+
component: 'core_course',
52+
instancetype: 'coursecommunication',
53+
instanceid: $courseid,
54+
provider: 'communication_matrix',
55+
);
56+
```
57+
58+
### Create and configure a room
59+
60+
`$communication->create_and_configure_room()` method is used to add an ad-hoc to create a room in the communication provider and configure it with the required settings.
61+
62+
```php
63+
public function create_and_configure_room(
64+
string $communicationroomname,
65+
?\stored_file $avatar = null,
66+
?\stdClass $instance = null,
67+
)
68+
```
69+
70+
This method takes the following parameters:
71+
72+
- The name of the room as a string to be created.
73+
- The avatar of the room to be created, this is a stored file object.
74+
- The instance object of the communication API.
75+
76+
For example, we want to create a room for a course with the course name as the room name and the course image as the avatar, we can use the below code.
77+
There can be other cases where information from course instance will be used by a plugin, for example, the dynamic field from matrix plugin has a form
78+
field named topic which sets the topic of the room, the instance object can be used to get the topic from the course instance and set it in the form field.
79+
Please refer to [Communication plugin](../../plugintypes/communication/index.md) documentation for more details.
80+
81+
```php
82+
// First initialize the communication instance, provided the context is already initialized and the selected provider is available
83+
// though a form or other means.
84+
$communication = \core_communication\api::load_by_instance(
85+
context: $context,
86+
component: 'core_course',
87+
instancetype: 'coursecommunication',
88+
instanceid: $course->id,
89+
provider: 'communication_matrix',
90+
);
91+
92+
// Now call the create_and_configure_room() method to add an ad-hoc to create a room in the communication provider and configure it
93+
// with the required settings.
94+
$communication->create_and_configure_room(
95+
communicationroomname: $course->fullname,
96+
avatar: $courseimage ?: null,
97+
instance: $course,
98+
);
99+
```
100+
101+
### Update a room and its associated information
102+
103+
`$communication->update_room()` method is used to add an ad-hoc to update a room in the communication provider and configure it with the required settings.
104+
105+
```php
106+
public function update_room(
107+
?int $active = null,
108+
?string $communicationroomname = null,
109+
?\stored_file $avatar = null,
110+
?\stdClass $instance = null,
111+
)
112+
```
113+
114+
This method takes the following parameters:
115+
116+
- The active status of the room to be updated. Can be either 0 or 1.
117+
- The name of the room as a string to be updated.
118+
- The avatar of the room to be updated, this is a stored file object.
119+
- The instance object of the communication API.
120+
121+
```php
122+
// First initialize the instance.
123+
$communication = \core_communication\api::load_by_instance(
124+
context: $context,
125+
component: 'core_course',
126+
instancetype: 'coursecommunication',
127+
instanceid: $course->id,
128+
provider: 'communication_matrix',
129+
);
130+
131+
// Now update the room with the required settings. The instance will be used by dynamic fields feature of the plugin to allow the plugin
132+
// to get the required information from the instance.
133+
$communication->update_room(
134+
active: $active,
135+
communicationroomname: $communicationroomname,
136+
avatar: $courseimage ?: null,
137+
instance: $course,
138+
);
139+
```
140+
141+
### Delete a room
142+
143+
`$communication->delete_room()` method is used to add an ad-hoc to delete a room in the communication provider. The associated task for this also removes all the members from
144+
the room before deleting the room.
145+
146+
:::danger
147+
148+
This is destructive and might remove all the messages and other data associated with the room. Usage of this should be done with caution.
149+
150+
:::
151+
152+
### Add members to a room
153+
154+
`$communication->add_members_to_room()` method is used to add an ad-hoc to add members to a room in the communication provider. The user id of each user to be added to
155+
the provider room is also stored in the communication_user table for user mapping with the provider.
156+
157+
```php
158+
public function add_members_to_room(
159+
array $userids,
160+
bool $queue = true,
161+
)
162+
```
163+
164+
This method accepts the following parameters:
165+
166+
- An array of user ids to be added to the provider room.
167+
- A boolean value to indicate if the task should be added to the queue or run immediately. This is false by default. This is added to ensure the cases where the mapping should be created but the task might not be needed at this point.
168+
169+
```php
170+
// First initialize the instance, provider is not required here, it will initialize the enabled instance.
171+
$communication = \core_communication\api::load_by_instance(
172+
context: $context,
173+
component: 'core_course',
174+
instancetype: 'coursecommunication',
175+
instanceid: $course->id,
176+
);
177+
178+
// Now add the members.
179+
$communication->add_members_to_room(
180+
userids: $enrolledusers,
181+
);
182+
```
183+
184+
### Update the membership of a room
185+
186+
`$communication->update_room_membership()` method is used to add an ad-hoc to update the membership of a room in the communication provider.
187+
The user mapping for each of the users are also reset to allow task to update the users from the task.
188+
189+
```php
190+
public function update_room_membership(
191+
array $userids,
192+
bool $queue = true,
193+
)
194+
```
195+
196+
This method accepts the same parameters as the `add_members_to_room()` method and the usage is also the same.
197+
198+
### Remove members from a room
199+
200+
`$communication->remove_members_from_room()` method is used to add an ad-hoc to remove members from a room in the communication provider.
201+
The users are flagged as deleted in the communication_user table to allow the task to remove the users from the provider room.
202+
203+
```php
204+
public function remove_members_from_room(
205+
array $userids,
206+
bool $queue = true
207+
)
208+
```
209+
210+
This method accepts the same parameters as the `add_members_to_room()` method and the usage is also the same.
211+
212+
### Show the communication room creation status notification
213+
214+
`$communication->show_communication_room_status_notification()` is a special method to have a UI element to show the status of the room creation. If the room is ready, it will
215+
return the notification as a string. If the room is not ready, it will return pending status. Course have this implemented and shows the status after the communication instance
216+
is configured. Please note, the status notification relies on the creation of room, not the memberships of the room.
217+
218+
### Communication instance setup using form/configuration page
219+
220+
The communication API allows to have settings to configure the basic information like room name, selection of provider etc. `$communication->form_definition()` method
221+
is used to get the form definition for the settings form. If the form elements are used in another form to include the communication form elements, `form_definition()` method
222+
will be useful. There is a configuration page (`communication/configure.php`) which can be used to configure the communication instance. Course currently uses this page to set up
223+
communication and its associated information.
224+
It will also be required to use `set_data()` method in order to set the data to the form elements while saving the data.
225+
226+
```php
227+
public function form_definition(
228+
\MoodleQuickForm $mform,
229+
string $selectdefaultcommunication = processor::PROVIDER_NONE,
230+
)
231+
```
232+
233+
This method accepts the following parameters:
234+
235+
- The moodle quick form object to add the form elements to.
236+
- The default provider to be selected in the form. This is set to none by default.
237+
238+
For example, we have a form where we want to have the communication settings, we can use the below code to add the form elements to the form.
239+
240+
```php
241+
class configure_form extends \moodleform {
242+
public function definition() {
243+
$mform = $this->_form;
244+
$communication = \core_communication\api::load_by_instance(
245+
context: $context,
246+
component: 'core_course',
247+
instancetype: 'coursecommunication',
248+
instanceid: $course->id,
249+
);
250+
$communication->form_definition(mform: $mform);
251+
$this->communication->set_data(instance: $course);
252+
}
253+
}
254+
```
255+
256+
## Building a communication plugin
257+
258+
Communication API also provides a bunch of interfaces for a communication plugin to consume. Every plugin should implement these interfaces according to the features they
259+
support.
260+
261+
:::info
262+
263+
Please refer to [Communication plugin](../../plugintypes/communication/index.md) documentation for more details about building a plugin.
264+
265+
:::

0 commit comments

Comments
 (0)