Course overview integration

Summary

Since 5.0

The course overview table displays a summary of all activities in a course, along with relevant information such as due dates, submission state, completion status, etc. Both students and teachers can access the course overview by clicking the "Activities" tab in the course navigation. The new page replaces the old mod/PLUGINNAME/index.php page provided by the activity plugins.

To customize the information displayed in the course overview table, activity plugins must implement their own integration class.

Overview Class Structure

The integration class must be located in mod/PLUGINNAME/classes/courseformat/overview.php using the namespace mod_PLUGINNAME\courseformat\overview. The overview class should extend the core_courseformat\activityoverviewbase class and implement the necessary methods to provide the required overview data.

Class Definition

This is an example of the class definition that do not add any extra overview items. Simply by extending the activityoverviewbase class, the course overview will display the activity name, the section and, if the user has completion, the completion status of the activity.

namespace mod_PLUGINNAME\courseformat;

use core_courseformat\activityoverviewbase;

class overview extends activityoverviewbase {
    // Implement methods here.
}

Extra Overview Items

To provide extra overview items, the plugin can override the get_extra_overview_items method. This method should return an array of \core_courseformat\local\overview\overviewitem objects indexed by item shortname.

This is an example of a plugin adding an extra overview item to show if the activity has been submitted:

namespace mod_PLUGINNAME\courseformat;

use core_courseformat\activityoverviewbase;
use core_courseformat\local\overview\overviewitem;
use core\output\pix_icon;

class overview extends activityoverviewbase {
    #[\Override]
    public function get_extra_overview_items(): array {
        return [
            'submitted' => $this->get_extra_submitted_overview(),
        ];
    }

    /**
     * Get the extra overview item to show if the activity has been submitted.
     *
     * @return overviewitem|null
     */
    private function get_extra_submitted_overview(): ?overviewitem {
        // Validate if the user needs this overview information. Return null otherwise.
        if (!has_capability('mod/PLUGINNAME:complete', $this->context)) {
            return null;
        }

        // All items should have a value (for filtering purposes)-
        $value = false;

        // The overview content can be a string.
        $content = '-';

        // Logic to determine if the activity is already submitted
        if (PLUGIN_LOGIC_TO_DETECT_IF_THE_USER_HAS_SUBMITTED_ANYTHING($this->cm)) {
            $value = true;
            // The overview content can also be a renderable object.
            $content = new \pix_icon(
                'i/checkedcircle',
                alt: get_string('already_submitted', 'mod_PLUGINNAME'),
                attributes: ['class' => 'text-success'],
            );
        }

        // Return the overview item. It is mandatory to provide also a name to display.
        // The name will be used as the table header in the course overview, but it could
        // also be used in other placements in the future.
        return new overviewitem(
            name: get_string('responded', 'mod_PLUGINNAME'),
            value: $value,
            content: $content,
        );
    }
}

Fixed Overview Items

Some activity information is especial and they will be added automatically to the course overview table without declaring them in the get_extra_overview_items method.

The following are the fixed overview items:

• Activity Name: The name of the activity as a link, the section name and the visibility badge.
• Completion Status: The completion status of the activity, if enabled and apply to the current user.

However, there are other fixed overview items that are considered empty unless the plugin overrides the corresponding method:

• Due Date: The due date of the activity. Provided by the get_due_date_overview method.
• Main action: The main action of the activity. Provided by the get_actions_overview method.

Due Date Overview

To provide a due date overview, override the get_due_date_overview method. This method must return an overviewitem object or null if there is no due date.

namespace mod_PLUGINNAME\courseformat;

use core_courseformat\activityoverviewbase;
use core_courseformat\local\overview\overviewitem;

class overview extends activityoverviewbase {
    #[\Override]
    public function get_due_date_overview(): ?overviewitem {
        // Implement here how to get the due date of the activity.
        $duedate = DO_SOMETHING_TO_GET_YOUR_PLUGIN_DUE_DATE();

        if (empty($duedate)) {
            // If all overview items return null, the due date column will not be displayed.
            return new overviewitem(
                name: get_string('duedate'),
                value: null,
                content: '-',
            );
        }
        return new overviewitem(
            name: get_string('duedate'),
            value: $this->cm->name,
            content: userdate($duedate),
        );
    }
}

Main Action Overview

The main action is always displayed as the last column in the course overview table. However, by default the column is empty and it is not rendered in the table. However, the plugin can define their own action cell to provide useful links to the user. For example, the main action could be the submissions count with a link to the submissions page.

For now, the main action overview is only displayed in the course overview table. However, in the future, it could be used in other places like the course page or the activity page.

To provide a main action overview, override the get_actions_overview method.

namespace mod_PLUGINNAME\courseformat;

use core_courseformat\activityoverviewbase;
use core_courseformat\local\overview\overviewitem;
use core\output\action_link;
use core\output\local\properties\button;
use core\output\local\properties\text_align;

class overview extends activityoverviewbase {
    #[\Override]
    public function get_actions_overview(): ?overviewitem {
        // Validate if the user can do the action. Return null otherwise.
        if (!has_capability('mod/PLUGINNAME:viewreports', $this->context)) {
            return null;
        }

        $submissions = CALCULATE_YOUR_PLUGIN_SUBMISSIONS_COUNT();
        $total = CALCULATE_YOUR_PLUGIN_TOTAL_SUBMISSIONS();

        if (!$total) {
            return new overviewitem(
                name: get_string('responses', 'mod_feedback'),
                value: 0,
                content: '-',
                textalign: text_align::CENTER,
            );
        }

        // For the action content, it is recommended to style it using the
        // button enum css helper, it will make the final result consistent
        // with the rest of plugins.
        $content = new action_link(
            url: new url('/mod/feedback/show_entries.php', ['id' => $this->cm->id]),
            text: get_string(
                'count_of_total',
                'core',
                ['count' => $submissions, 'total' => $total]
            ),
            attributes: ['class' => button::SECONDARY_OUTLINE->classes()],
        );

        return new overviewitem(
            name: get_string('responses', 'mod_feedback'),
            value: $submissions,
            content: $content,
        );
    }
}

Dependency Injection

The overview class will be loaded using dependency injection. The constructor must accept a cm_info object to initialize the parent class, however, the constructor can also accept other dependencies that the plugin needs.

This is an example of a overview integration that needs access to the database and a clock interface for timestamps.

namespace mod_PLUGINNAME\courseformat;

use core_course\activityoverviewbase;

class overview extends activityoverviewbase {
    public function __construct(
        /** @var cm_info $cm the activity course module. */
        cm_info $cm,
        /** @var \moodle_database $db the database acces. */
        protected readonly \moodle_database $db,
        /** @var \core\clock $clock the clock interface */
        protected readonly \core\clock $clock
    ) {
        parent::__construct($cm);
    }

    // The rest of your code goes here. All methods must access the
    // $this->db property to interact with the database instead of
    // using the global $DB.

    // Also, to handle timestamps, use $this->clock->time() instead.
}