Favourites API: Difference between revisions
m (→Overview) |
|||
| Line 3: | Line 3: | ||
==Favourites API usage== | ==Favourites API usage== | ||
===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'''. | |||
The itemid is a unique integer identifier of the item itself. This might be a course id, or a conversation id, or the id of any entity in Moodle. | |||
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|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. | |||
Revision as of 05:53, 28 November 2018
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.
Favourites API usage
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.
The itemid is a unique integer identifier of the item itself. This might be a course id, or a conversation id, or the id of any entity in Moodle.
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.
