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

Class name	Purpose
\totara_engage\resource\resource_item	The abstract model class for engage resource type. It unifies the process of saving record into data layer and centralise the validation of input data. The class contains CRUD functionalities and several capabilities/visibilities checks related. The visibilities/capabilities checks are included because they behave likely to each other and there is one visibility check API that the implementation can just use it against the resource type model and it will be have consistency across the system.
\totara_engage\modal\modal	The abstract class that provides the ability to inject TUI modal component to engage page. This class is optional to be extended. However if the resource type wants to share the same WEB page to allow users to create a record then extend this modal class and it will provide enough information (declared in the class itself) to allow the front-end framework to auto pick up and lazy load to the page.
\totara_engage\card\card	The abstract class that provides the ability to inject TUI card component to engage page. This class is optional to be extended. However, if the resource type wants to share the same WEB page, to allow users to view the information about resource type as a card, then extend this class. It provides enough information (declared in the class itself) to allow the front-end framework to auto pick up and lazy load the component to the page.
\totara_engage\card\card_loader	Those classes above are more likely for representing the data. This class is about loading data to the page. If you are familiar with how Totara catalog works then this loader behaves no different from catalog. Except that the loader use a modern way - which is Totara query builder.

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':

Engage wether

// 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

The file weather.php has to be in the special namespace - directory in order to allow the factory auto pick up:

/totara/engage/resources/weather/classes/totara_engage/resource/weather.php

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 modal

// 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.

Modal

<?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 modal

// 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.

Weather card

<?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.

Browser not supported