Skip to content

Commit

Permalink
Merge pull request #969 from andrewnicols/communicationApiExampleTidyups
Browse files Browse the repository at this point in the history
[docs] Tidy up examples to meet coding style
  • Loading branch information
sarjona authored Apr 17, 2024
2 parents 5c9b8cc + 686916c commit 6b989bf
Showing 1 changed file with 67 additions and 62 deletions.
129 changes: 67 additions & 62 deletions docs/apis/subsystems/communication/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,12 +47,12 @@ the enabled provider for that instance.

```php
$communication = \core_communication\api::load_by_instance(
context: $context,
component: 'core_course',
instancetype: 'coursecommunication',
instanceid: $courseid,
provider: 'communication_matrix',
);
context: $context,
component: 'core_course',
instancetype: 'coursecommunication',
instanceid: $courseid,
provider: 'communication_matrix',
);
```

### Create and configure a room
Expand All @@ -61,10 +61,10 @@ $communication = \core_communication\api::load_by_instance(

```php
public function create_and_configure_room(
string $communicationroomname,
?\stored_file $avatar = null,
?\stdClass $instance = null,
)
string $communicationroomname,
?\stored_file $avatar = null,
?\stdClass $instance = null,
);
```

This method takes the following parameters:
Expand All @@ -79,23 +79,27 @@ field named topic which sets the topic of the room, the instance object can be u
Please refer to [Communication plugin](../../plugintypes/communication/index.md) documentation for more details.

```php
// First initialize the communication instance, provided the context is already initialized and the selected provider is available
// First initialize the communication instance,
// provided the context is already initialized
// and the selected provider is available
// though a form or other means.
$communication = \core_communication\api::load_by_instance(
context: $context,
component: 'core_course',
instancetype: 'coursecommunication',
instanceid: $course->id,
provider: 'communication_matrix',
);

// Now call the create_and_configure_room() method to add an ad-hoc to create a room in the communication provider and configure it
// with the required settings.
context: $context,
component: 'core_course',
instancetype: 'coursecommunication',
instanceid: $course->id,
provider: 'communication_matrix',
);

// Now call the create_and_configure_room() method
// to add an ad-hoc to create a room in the
// communication provider and configure it with the
// required settings.
$communication->create_and_configure_room(
communicationroomname: $course->fullname,
avatar: $courseimage ?: null,
instance: $course,
);
communicationroomname: $course->fullname,
avatar: $courseimage ?: null,
instance: $course,
);
```

### Update a room and its associated information
Expand All @@ -104,11 +108,11 @@ $communication->create_and_configure_room(

```php
public function update_room(
?int $active = null,
?string $communicationroomname = null,
?\stored_file $avatar = null,
?\stdClass $instance = null,
)
?int $active = null,
?string $communicationroomname = null,
?\stored_file $avatar = null,
?\stdClass $instance = null,
);
```

This method takes the following parameters:
Expand All @@ -121,21 +125,22 @@ This method takes the following parameters:
```php
// First initialize the instance.
$communication = \core_communication\api::load_by_instance(
context: $context,
component: 'core_course',
instancetype: 'coursecommunication',
instanceid: $course->id,
provider: 'communication_matrix',
);

// Now update the room with the required settings. The instance will be used by dynamic fields feature of the plugin to allow the plugin
// to get the required information from the instance.
context: $context,
component: 'core_course',
instancetype: 'coursecommunication',
instanceid: $course->id,
provider: 'communication_matrix',
);

// Now update the room with the required settings.
// The instance will be used by dynamic fields feature of the plugin
// to allow the plugin to get the required information from the instance.
$communication->update_room(
active: $active,
communicationroomname: $communicationroomname,
avatar: $courseimage ?: null,
instance: $course,
);
active: $active,
communicationroomname: $communicationroomname,
avatar: $courseimage ?: null,
instance: $course,
);
```

### Delete a room
Expand All @@ -156,9 +161,9 @@ the provider room is also stored in the communication_user table for user mappin

```php
public function add_members_to_room(
array $userids,
bool $queue = true,
)
array $userids,
bool $queue = true,
);
```

This method accepts the following parameters:
Expand All @@ -169,16 +174,16 @@ This method accepts the following parameters:
```php
// First initialize the instance, provider is not required here, it will initialize the enabled instance.
$communication = \core_communication\api::load_by_instance(
context: $context,
component: 'core_course',
instancetype: 'coursecommunication',
instanceid: $course->id,
);
context: $context,
component: 'core_course',
instancetype: 'coursecommunication',
instanceid: $course->id,
);

// Now add the members.
$communication->add_members_to_room(
userids: $enrolledusers,
);
userids: $enrolledusers,
);
```

### Update the membership of a room
Expand All @@ -188,9 +193,9 @@ The user mapping for each of the users are also reset to allow task to update th

```php
public function update_room_membership(
array $userids,
bool $queue = true,
)
array $userids,
bool $queue = true,
);
```

This method accepts the same parameters as the `add_members_to_room()` method and the usage is also the same.
Expand All @@ -202,9 +207,9 @@ The users are flagged as deleted in the communication_user table to allow the ta

```php
public function remove_members_from_room(
array $userids,
bool $queue = true
)
array $userids,
bool $queue = true
);
```

This method accepts the same parameters as the `add_members_to_room()` method and the usage is also the same.
Expand All @@ -225,9 +230,9 @@ It will also be required to use `set_data()` method in order to set the data to

```php
public function form_definition(
\MoodleQuickForm $mform,
string $selectdefaultcommunication = processor::PROVIDER_NONE,
)
\MoodleQuickForm $mform,
string $selectdefaultcommunication = processor::PROVIDER_NONE,
);
```

This method accepts the following parameters:
Expand Down

0 comments on commit 6b989bf

Please sign in to comment.