Calendar export - technical
specification
Overview/approach/rationale
Within the current OU VLE the Moodle calendar is used as a personal student
calendar, linked from Student Home. A data load from IT inputs module assessment
and tutorial events into the Moodle database which are identified using the module
names ‘tutorgroupevent’ and ‘assessmentcalendar’. OU customisation of the
calendar code makes these, non-editable, events display within the calendar
interface (and within the study planner). These features need to be available within
the new Moodle 2 VLE, but should not involve customisations to core code.
Google Apps provides students with their own personal calendar. A requirement of
the Google Apps strand is to enable the viewing of Moodle calendar events within a
Google calendar. The standard Moodle 2 calendar already supports this feature;
however, this export would not include any assessment/tutorial events.
Within the personalisation strand there is a requirement to provide a method to assist
students with the planning of their studies and workload. It is intended that this be
accomplished by providing course information that can be imported into calendar
tools such as Google and Outlook. Any developments regarding Moodle calendar
should bear this requirement in mind.
These requirements could be met through the use of a single calendar export feature
with three main purposes:
1. Provide a functional replacement for some of the core customisations made
to the Moodle calendar within Moodle 2 - exposing assessment/tutorial events
and events for multiple modules with the export data.
2. Support the exporting of Moodle calendar events to Google Apps and other
calendar software.
3. Provide a platform from which extra data can be added to calendar exports.
Developed as a Moodle ‘plugin’, this feature would therefore need to be accessed
directly (probably via a link in the study planner).
Potentially the basic export form of the standard calendar could be changed, by
overriding its renderer in our OU theme, to use the plugin instead. The only issue
with this is that the iCal icon on the calendar page could not be changed; so this
would still make the standard export. All exporting from the standard calendar could
be turned-off to overcome this issue, if deemed an acceptable approach.
The functionality of this feature is as follows:

A selection page where users can:
o choose which data to include,
o select to download this data (iCalendar format),
o select to access this data via url (iCalendar format),
o select to add the data to their Google calendar (subscribes to url).


An export page that retrieves calendar data, based on chosen options,
and presents as iCalendar format
Set of code libraries that can be easily extended to include extra data
gathering options for calendar export and associated UI for these options.
Also note that it is not possible to represent a distinct collection of calendar events
within a single iCalendar file e.g. events related to separate modules. Students could
download/subscribe to iCalendar files for each module to overcome this limitation.
Structure
The calendar export feature should be developed as a local plugin and as such will
reside in a folder in the local directory. Suggested name for the feature is ‘calexport’;
the folder and all appropriate areas of code (libraries, functions etc) should use this
identifier.
Code should be organised in classes (with static functions if acting as a library),
named meaningfully in files named after the class name. Library type functions
should be in a file called ‘calexport_lib.php’, this can contain numerous classes if
necessary. The plugin should have all of the standard functions and ‘hooks’ Moodle
expects - as documented in local/readme.txt and moodle.org.
There are two main user functions for this plugin:
1. Selecting to export the calendar, selecting required data
2. Consuming the data selected; either as a file or feed.
There should be a file for each of these scenarios that contain the code to initiate
these functions (shared code should be in one of the library classes). The main
export selection process should be in ‘index.php’ and the export in ‘data.php’.
Config/DB/Capabilities
Config settings required are:
1. Google calendar url (local_calexport_googlecal, default:
http://www.google.com/calendar)
It is not expected that the plugin will store data or support capabilities.
Functionality
User interface
The export selection page (‘index.php’) should be a standard Moodle page, using the
$PAGE and $OUTPUT features to display the standard interface.
If a course id has been sent to the page then an option to choose whether to export
just course events should be shown. The user should have a valid role on this course
– checked via require_login.
Other data export options should then be shown (module calendar events are always
exported, other data is optional), followed by a download button (to download file)
and an iCal icon (also can be used to get calendar url) and an ‘add to Google’ button
along with appropriate instructions. These last two options are hyperlinks, so will
need to be updated via JavaScript according to the options chosen. If JavaScript is
not enabled there will need to be an ‘Update links’ button that refreshes the page to
reflect the chosen options (form which submits page to itself).
The ‘add to Google’ button should use the ‘local_calexport_googlecal’ config setting
to link to either standard Google or Google Apps domain.
The core output of this page (options etc) should be generated from a separate
function so the contents of this screen can be produced elsewhere if required, for
example in the standard calendar export. Moodle renderer should be used where
appropriate.
Data
On calling the ‘data.php’ page the following parameters will need to be sent:
1.
2.
3.
4.
user id (if safe to expose this, else username)
Moodle course id (optional)
Personal events included
authorisation token (a hash using $CFG->calendar_exportsalt and an
element of the user’s details)
5. Details of any extra export data required
Checks should be made to ensure these parameters are valid. These checks should
use the same mechanism as that initially used to create the parameters.
The course id(s) should be checked and the id of each group the user is a member of
should be found and recorded.
To get the data required for the user the existing calendar library code
(calendar/lib.php) should be used where possible; for example, calendar_get_events
function.
There should be a mechanism for extra data types to then be executed with the
appropriate information sent to their functions (user id, course and group id’s).
This should return back any calendar objects (a type from the bennu library) to add to
the export data.
The calendar should have a name (X-WR-CALNAME property) so that this
information will show in Google Calendar.
Export
The calendar data object should then be serialised and output as calendar content
mime-type. This code should mirror that of the current calendar export in
calendar/export_execute.php (unfortunately this is not in a re-usable function, so
some parts must be copied).
Extensibility
There needs to be a mechanism to easily add extra data gathering code (and
associated UI) to the plugin. This should be accomplished through the use of a class
structure that can support such a requirement. Ideally the process of discovering and
using these extra data gatherers should be automated e.g. place file in certain folder.
This process should be clearly documented within the code to make it easier for
others to add custom data gatherers at a later date.
Test script
Test requirements:
1. User with student role on a course.
2. Tutorial and assessment events defined for course (student should be
member of a tutorial group that has an associated event).
3. Google Apps account (external facing site needed to test Google calendar
export).
Setup test script for development server:
1. Access system as a user with admin/manager permissions.
2. Enrol test user on a course in a student role.
3. Add a event for that course to the calendar using the link
/calendar/view.php?course=*(id of course). Make a note of the event details.
4. The course will need to have a tutorial event set up. To do this:
a. Create a test group in the course (if none already)
b. Add the test user to the test group
c. Manually add an event to the database (table _event) with the
eventtype field set to ‘tutorgroupevent’, courseid field set to the id of
the test course and the groupid field set to the id of the test group.
5. The course will need to have an assessment date set up. To do this manually
add an event to the database with the eventtype field set to
‘assessmentcalendar’ and the courseid field set to the id of the test course.
Standard test script:
1) Log in to the system as user with permission to add a site wide event.
2) Add a site event directly to the Moodle calendar via the link
/calendar/view.php. Make a note of the event details.
3) Log in to the system as the test student user.
4) Add a personal event directly to the Moodle calendar via the link
/calendar/view.php. Make a note of the event details.
5) Access the test course.
6) Select the link to export calendar details. Alternatively, go to
/local/calexport/index.php?course=*(id of course).
7) There should be an option to include personal events (default selected).
8) Select to export the calendar as file download and as add to Google calendar.
The resulting calendars should then be checked for correct:
(1) Personal event
(2) Site wide event
(3) Tutorial event
(4) Assessment event.
9) If other courses that the student is enrolled on have calendar data then
repeat 5,6,7,8 with all these courses also.
10) Repeat with JavaScript disabled.