Favourites API: Difference between revisions
mNo edit summary |
|||
| Line 7: | Line 7: | ||
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'''. | 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 '''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 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. | 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== | ==Using the API== | ||
Revision as of 23:39, 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.
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.
