Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Favourites API

From MoodleDocs

Overview

The favourites API allows you to mark items as favourites for a given user. Marking an item as a favourite is akin to adding a web page to your browser favourites (or bookmarks), or marking someone in your contacts as a favourite. The API provides a means to create, read, update and delete favourite items, allowing any component to favourite arbitrary items as they see fit.

What can be marked as a favourite?

Almost any 'item' can be marked as a favourite, provided it is something which can be identified by a unique integer id.

Identifying items

In order to store a favourite, and be able to uniquely identify it for later retrieval, 4 fields are required. These are: component, itemtype, itemid and contextid. You will see these in a range of API calls.

The itemid is a unique integer identifier of the item itself. This might be a course id, or conversation id, or the id of any entity in Moodle. In fact, it does not have to be the id of a record from the database either; it can be any arbitrary id, so long as the component storing the item knows what it represents.

The two fields component and itemtype make up a pairing representing the type of each favourite. Within this pair, the component must be a valid frankenstyle component name and is the name of the component wishing to set/unset the item as a favourite. The itemtype can be any identifying string, provided it is unique within the respective component. The type pairing allows us to distinguish between favourites of different types (from different areas of Moodle), which may have identical itemid values.

The contextid is the id of the context in which the item is being marked as a favourite. For example, a user's course might be marked as a favourite at the course context, whereas a user's conversation with another user might be marked as a favourite at the user context. It's also possible that items of a certain type (remember, this is the {component, itemtype} pairing) will be marked as favourites in different contexts, based on the context of the item itself. For example, consider the case where we have a group conversation which is linked to a course group, and an individual conversation. Marking the group conversation as a favourite would require a course context to be used, whereas doing the same for the individual conversation would require a user context. This is entirely up to the component storing the favourite to manage.

Using the API

High level overview

Creating a favourite

Reading favourites