Engage resources

What is a Totara Engage component?

Totara Engage only contains API(s) that are not qualified to sit in Totara Core but reused a lot within all the plugins that are related to Totara Engage functionalities - such as resource, survey and so on.

All the API(s) are mainly for sharing, rating and displaying resources on a page in a data driven way.

What is engage resource?

Resource

A rich content article that belongs to a user (can be created by authenticated user) that can be shared between users or to workspaces, and appear in the Totara catalog. Furthermore, resources can be added into multiple playlists along side with others and also surveys.

Survey

Can only have one question so far and it can either be multi or single answer only. It belongs to a user (can be created by authenticated user) and can be shared between users or to workspaces. Furthermore, it can be grouped into multiple playlists along side with others and also resources.

How Engage resources work

If you are familiar with how the course module works, the concept of a Totara Engage resource is no different from that. There will be one main table that contains all the common information related to the resource (such as name, author and time created/edited), the rest of information related to either resources or survey will be stored differently and mapped to the main table.

Each record within the resource table will have to have a value for field resourcetype and this value is used to determine whether the resource is either survey or a resource.

Since there is only one places to add the resource(s) within the WEB UI, the modal metadata abstract class is introduced - 'totara_engage\modal\modal'. This modal class will have to be implemented within a resource type in order to inject the creation modal within the creation WEB page. The modal only contains TUI path and available props in order to allow front-end framework automatically picks up and lazy loads to the page, every time the page is rendered.

Main API classes and methods

How to add new resource type 

To introduce a new resource type, a developer will have to add a sub plugin under directory /totara/engage/resources with the directory name as your resource type.

For example, introducing a new resource type called 'weather':

// Example of new engage resource - weather
 
 
/totara/engage/resources/weather
.
+-- classes
|	+-- totara_engage
|	|	+-- resource
|	|	|	+-- weather.php // This file have to be the same name as the sub plugin directory name.
|
|
+-- version.php

Modal

To add new modal for the creation, the class will have to sit under special namespace, note that the class name can be anything as it does not follow any rules comparing to the model structure.

// Example of extending modal class

/totara/engage/resources/weather
.
+-- classes
|	+-- totara_engage
|	|	+-- modal
|	|	|	+-- weather_modal.php
|
|
+-- version.php

The extended modal class can provide any TUI component - but can only provide one.

<?php
namespace engage_weather\totara_engage\modal;

use totara_engage\modal\modal;
use totara_tui\output\component;

/**
 * A modal medata for the front-end component.
 */
final class article_modal extends modal {
    /**
     * @return component
     */
    public function get_vue_component(): component {
        return new component('engage_weather/components/CreateWeather');
    }

    /**
     * @return string
     */
    public function get_label(): string {
        return get_string('resource', 'engage_weather');
    }

    /**
     * @return bool
     */
    public function is_expandable(): bool {
        return true;
    }

    /**
     * @return bool
     */
    public function show_modal(): bool {
		// Capabilities check
		return true;
    }
}

Card

To add a new card for displaying the resource type on engage page, the class will have to sit under the special namespace. Note that the class name can be anything, as it does not follow any rules comparing to the model structure.

// Example of extending modal class

/totara/engage/resources/weather
.
+-- classes
|	+-- totara_engage
|	|	+-- card
|	|	|	+-- weather_card.php
|
|
+-- version.php

The extended card class can provide any TUI component - but it can only provide one.

<?php
namespace engage_weather\totara_engage\card;

use totara_engage\card\card;
use totara_tui\output\component;

final class article_card extends card {
    /**
     * @return component
     */
    public function get_tui_component(): component {
        return new component("engage_weather/components/card/WeatherCard");
    }

    /**
     * @return array
     */
    public function get_extra_data(): array {
		return [];
    }

Best practices

All the mutation/query graphQL that are meant for resource type will have to sit under the resource type implementation.

Totara Engage is only responsible to provide several graphQL queries for fetching card/modal metadata and mutation to create sharing/rating/bookmark records only.