Block myoverview

Overview

The myoverview block was designed as a replacement to the existing block_course_overview. The block displays a subset of the calendar events, those that have a corresponding action for a user to complete by a given date, for example an assignment due (calendar event) would expect the student to submit their answer by the given date (action). The intention is for the content of the block to show the logged in user an ordered list of actions they need to complete. As each item is completed it should be removed from the list.

What is a calendar event action?

A calendar event action represents the action a user must take to satisfy the event. The actions should be discrete and finite. Each action is made up of 4 properties:

name: A human readable name for the action, for example "add submission"
url: A URL to direct the user to the page in which they can complete the action
item count: How many items are required for this action, for example it may be a count of the number of assignments that need grading for a teacher
actionable: Represents if the action can currently be actioned by the user. A true value means it is currently actionable and a false values means it will be actionable some time in the future

Plugin developers

How do you get events to show in block_myoverview?

Note: Due to the limitations of the calendar event data structure we only support module plugins (plugins in /mod/) in block_myoverview.

In order for your events to show in this block they will need to be action events. That means they must have a few specific properties:

The "type" property must be set to CALENDAR_EVENT_TYPE_ACTION to indicate that this calendar event is intended to be accompanied by an action
The "timesort" property must be set to a timestamp. This value represents the time by which the user must complete the action. It is used for sorting the events and grouping them into time blocks ('Today', 'Next 7 days' etc)
The "modulename" property must be the name of your module on disk, e.g. mod/lesson/ has "modulename" set to "lesson"

Once your events are being created with required properties you'll need to add the mod_<plugin>_core_calendar_provide_event_action callback to provide the appropriate action for the logged in user for a given event.

How do you get events from your non-module plugins to show in block_myoverview?

Unfortunately this isn't currently supported. Only plugins in the 'mod/' directory are supported due to limitations of the current calendar data structure.

How do you stop your event from showing in block_myoverview once the user has completed the action?

You simply return null from your mod_<plugin>_core_calendar_provide_event_action callback once the user satisfies the criteria for completion of the action. The action events are given to your mod_<plugin>_core_calendar_provide_event_action callback each time they are request by block_myoverview so the user will only see the current state of each action they must complete. When the user has nothing left to do (indicated by returning null) it is removed from the list.

Action events that don't have a corresponding action will still be displayed in the calendar.

Note: There is no need to check in your callback that the user can see your activity or that they are enrolled in the course. These checks are done prior to providing the event to the callback. By the time you see the event in the callback you know that the user at least has permission to view your activity.

How do you get events to show in the calendar but not in block_myoverview?

You can still create an event with it's "type" property set to CALENDAR_EVENT_TYPE_STANDARD. Anything other than CALENDAR_EVENT_TYPE_ACTION will be ignored by block_myoverview.

How do you hide an action event from both the calendar and block_myoverview?

You can use the mod_<plugin>_core_calendar_is_event_visible to control the visibility of action events globally throughout Moodle. If you return false from this callback then the action event will no appear in neither the calendar nor block_myoverview. If you do not implement this callback then it is assumed that the event should be visible.

Typically, this callback would be used to check that the user has sufficient permissions to ever be able perform the action. For example, the assign activity ensures that a user without the appropriate role shouldn't see the grading event (i.e. a student shouldn't see the teacher's grading event).

This callback is called after the mod_<plugin>_core_calendar_provide_event_action callback which means it has access to the properties generated in that callback. In addition, there is a default rule that any action event with an "itemcount" set to zero is deemed not to be visible.

How do you display the item count for an action in block_myoverview?

By default the item count will not be displayed in block myoverview. However if you would like to explicitly change this behaviour then you can implement the mod_<plugin>_core_calendar_event_action_shows_item_count. If the result of that callback is true then the item count will be displayed in the block UI. Some times you may want to show the number of items left to action, for example the assign grading event for teachers shows them the count of the number of submissions left to grade.

Why isn't the action name a URL when it shows in block_myoverview?

Whether the action name (i.e. the "name" property on your action) is rendered as plain text or as a hyperlink is determined by the "actionable" property of the action. If "actionable" is true then it means the user can complete the action now, so we render the hyperlink to take them to the place to complete it. However if "actionable" is false then it means the user is unable to complete the action now but will be able to some time in the future, so the action name is rendered in plain text.

Why isn't your event being given to your *_provide_event_action callback?

Some common reasons that you may not see your events in your callback:

The callback is not located in lib.php within your module's directory. It should be in mod/<your_plugin>/lib.php.
The callback function is not named correctly, it should be mod_<your_plugin>_core_calendar_provide_event_action. For example, the callback for the assign module would be named mod_assign_core_calendar_provide_event_action.
The incorrect modulename property is being set on your calendar event.
The calendar event is not being set to type CALENDAR_EVENT_TYPE_ACTION.
The calendar event does not have a timesort property set.
The logged in user does not have the capability to view your activity.
The logged in user is not enrolled in the course that has your activity.
The eventtype property for your event is a completion event but completion is not enabled in the course.

Why is your event not showing in block_myoverview even though it's being passed into your *_provide_event_action callback?

Some common reasons that you may not see events in block_myoverview even though they are hitting your callback are:

Your callback is returning null, which indicates there is no action for the user.
Your callback is returning an item count of zero, which indicates there is no action for the user.
Your mod_<your_plugin>_core_calendar_is_event_visible is returning false.
The timesort value is more than 20 events into the future. The myoverview block will only load 20 events at a time in the timeline sort by dates view and 10 events at a time for each course in the sort by courses view.
In the sort by courses view only in progress courses are shown, so if your event belongs to a past or future course then it won't display on that view.

Documentation