Note making tool functional specification
This document details the functional requirements for the note making tool and gives some
detailed design information. It is expected that developers will complete the detailed design
section for approval before development commences.
Functional requirements
The primary use of the note making tool is to allow users the ability to create notes-to-self within
the study planner on their module website(s). There will be one note per week of the study
planner on each module website (not one note per activity or resource) to give the user
somewhere within the relevant section of the planner to note information/reminders relating to
the content of that week’s activities on each module they are studying, e.g. to note
sections/activities that the user needed to return to in a subsequent study session, a skills
activity to be done, to highlight particular weaknesses or reminders about contacting their tutor.
The note making tool is a wholly personal device, for the student to make use of as s/he finds
helpful or useful. Only the creator of the note can view the note, save, edit or delete it, and there
is no collaborative/sharing activity associated with the note making tool. There is an option to
hide note-making.
Adding a note
When viewing the study planner on a module website, users will see a button ‘add note’
appearing underneath the activities & resources and module events associated with a study
week. Any personal events will appear below notes.
If the study planner is topic rather than calendar based, upcoming events are only displayed at
the top of the study planner, so the ‘add note’ button will appear directly underneath the
activities & resources for each study block. This is also true if there are no events associated
with a study week in a calendar-based planner.
Clicking the ‘add note’ button will bring up a blank text box. Five lines will be visible in the text
box, with scroll bars to scroll up and down to view more text. To add text, users must position
the cursor inside the box and click to start typing.
Notes can be added in plain text only - it will not be possible to style the text in any way.
There will be a limit of 500 characters per note. When the user is close to the limit, (50
characters remaining), a count down will appear directly below the text box on the right hand
side to indicate that the limit has nearly been reached. If the user exceeds the limit, this text will
turn red, and show the number of characters over.
Saving a note
When the note box is open, the ‘add note’ button will be replaced by ‘save’, ‘cancel’ and ‘delete’
buttons. The user clicks ‘save’ to save the note, which then also automatically closes the text
box. The user clicks ‘cancel’ to close the note without saving changes.
Viewing notes
When viewing the study planner on a module website, users will see a button ‘show note’
instead of ‘add note’ for all the sections where a note is already saved. The user clicks ‘show
note’ to open the note and view the text.
The note text is displayed, in non-editable form. Styling will be used to separate the note from
surrounding text (TBC – Action Sarah) Buttons are displayed to ‘edit’, ‘delete’ or ‘close’ the
note. Multiple notes can be viewed at the same time.
Editing an existing note
When viewing a note on the study planner on a module website, the user clicks ‘edit note’ to edit
the text. Only one note can be edited at a time.
The note text box will open, containing the existing note text. To make changes to an existing
note, the user positions the cursor on the text to start editing.
As with adding a new note, to save any changes, click ‘save’ - this will save the changes and
close the note. If the user decides not to save their changes, they click ‘cancel’. The text will
revert to the previous version without saving any changes, and the note will no longer be
editable.
Deleting a note
The user clicks on ‘show note’ and then ‘delete’. This will remove the note. The note text box
will be closed and replaced by the ‘add note’ button.
Grouped sections of the study planner
Where the module website study planner has sections grouped together, e.g. weeks 1-3, then it
there will be one note for the group, rather than one per original section. Module teams are
advised to set up these groupings before the website is opened to students.
If a note is made on a combined section which is later separated, the note is applied to the first
section from the group.
If separate notes exist on sections which are later combined, the notes are combined and
displayed as one big note for the group. Where this causes the combined note to be larger than
the 500 character limit, warning text will be displayed beneath the note box on the right when
the combined note is next viewed. The user will be unable to save the note until they reduce its
size.
Exporting note text
Users can export all their notes to a Word or Google document, for them to re-use and/or print if
they wish. It will not be possible to export notes on an individual basis: if a user wishes to do this
then they need to cut and paste the text into a Word document themselves.
An export icon will be displayed at the foot of the study planner. This will take the user to a
separate export page which offers a range of different things than be exported in different ways,
each of which can be used independently. Initially this will include the calendar export
functionality and note making (provided the user has notemaking enabled).
The note making section of the export page will offer two options: Save to GoogleDocs or
Export to Word. If the user chooses to export to Word, a Word document is sent to their
browser. If the user chooses to save to GoogleDocs, the document will be saved in whatever
Google account they are currently signed-in to (or the Google sign-in screen will be displayed).
The exported notes will be listed in the same order as on the study planner, using the section
numbering/heading from the planner as the heading for each note.
If the user chooses to synchronise their study planner with their Google calendar, notes will not
be copied into the calendar.
Hiding note making
A new option “Note making” will be added to the study planner settings screen, which offers two
radio buttons “Show” and “Hide”. Show is selected by default. Extra information “This allows
you to view note making within your module websites” will be displayed with the setting.
Changing the setting to hide note-making will hide the note-making functionality from the user in the main module website view, the export link and on mobile devices. It does not delete
existing notes. Once the user shows the note-making tool again, existing notes will become
accessible. Context-sensitive help beside the setting field will explain this to users.
Permissions
A student can only see their own notes, which are in turn not viewable by anyone else. Tutors
and module teams will be to add their own notes on the same basis - i.e. they are only viewable
by the user who created them. As there is no interactive/collaborative functionality associated
with the note making tool, restricted users such as offender learners will also be able to access
and use it.
Notes will only be editable while the module is in presentation, after which they become read
only for the length of time that users retain access to the read-only version of the module
website. At this point the text box displaying the note will become “disabled” so that it cannot be
edited.
Mobile view
The note making tool is fully editable on mobile devices, in the same way as on the desktop
view. Changing the setting to hide note making will hide notes on the mobile view as well as the
desktop.
Back up and restore
User notes will be included in Moodle back-up packages if the back-up settings are to include
“user data”. This will allow user notes to be restored onto other module websites or systems if
required. However, they will not be transferred during roll-forward of the website from one
course-presentation to another.
Guidance
QUESTION (Action Simone): where, if anywhere, will we put context-sensitive help and what it
will say!
The following guidance points have been identified. it is not yet clear when/where these will be
offered to users.
●
●
●
●
●
Use the annotation tool for activity/resource specific notes
Use your blog, or Google docs for long notes
Reminder that your notes are private to you
Explanation of what export notes does
Explanation of import to Google calendar not working with notes
Technical notes
Planning
Development of the note making tool is scheduled during April - June 2011, and is expected to
take around 30 hours to complete. This development will be undertaken as part of a larger
package implementing all the study plan settings tasks. This will be completed in-house
because of the importance of the studyplan format to the OU.
First release to students will be in September 2011. There are no requirements that have been
held over for a later release.
Plug-in
The note making tool will be made available as part of the OU’s studyplan course format Moodle
plug-in.
Database structure
The note making tool will add an extra database table {studyplan_notes} with the following
columns:
●
●
●
●
●
id - auto incrementing primary key
course - id foreign key to {course} table
user - id foreign key to {user} table
section - could be the week number within studyplan or the id in the {course_sections}
table DECISION NEEDED Action Jenny (decide based on what is easiest available at
point of use, what causes least db queries to access notes, what makes coping with
grouped sections easiest)
note - text
None of these fields can be null. Note that the 500 character limit on notes will be imposed
through the edit process not by the database. This is to allow for future flexibility.
The user setting will be stored in the user_preferences database table as
format_studyplan_notes, taking the value 1 for show and 0 for hide.
Studyplan gadget
In order to support inclusion of notes in the studyplan gadget being written as part of the
DOULS project, the studyplan_get_alldata() function in the lib.php file should be extended to
return a $notes object. This object will be structured in the same way as the studyplan_weeks
data, and give the user’s notes for each section in a separate object.
The $notes object can then be used by the gadget and the main studyplan renderer code to
output notes information consistently.
Roles & Permissions structure
Two capabilities will be added to the study plan course format, in the course context:
●
●
viewnotes
○ “read” type capability
○ default allow for all archetype roles except Guest
editnotes
○ “write” type capability
○ requires risk bitmasks to be set
○ default allow for all archetype roles except Guest
The editnotes capability will be removed from the read-only student role.
Performance
A page reload should not be required to open or edit a note. Instead this should simply be CSS
show/hide to reveal extra functionality, using the same CSS facility as the block collapsing
(which does not rely on JavaScript and so is more accessible). Editing a note should cause the
other open notes to have their “edit” button hidden. Saving, canceling or deleting a note will
however cause a page reload since this must update/refresh content from the database.
All notes should be loaded for display with one database query, which only runs if the user has
note making enabled in their studyplan settings, and has the viewnotes or editnotes capability.
Security
Saving and deleting notes should be done through POST not GET, and should be protected by
a sesskey check. This will be handled by a separate PHP script specific to this purpose, which
is marked as being MOODLE_INTERNAL.
Backup and restore
You will need to add to the existing backup and restore files in the studyplan format. In backup
you’ll need to add the new database table something like this $notes = new
backup_nested_element('studyplan_notes', array('id'),
array(‘courseid’,’userid’,’sectionid’,’note’));
$this->get_setting_value('userinfo') can be used to find out whether the backup is being made
with user data included. Then if user data is required, something like $notes>annotate_ids('user', 'userid'); will need to be added, to identify who the users are.
Similarly in restore, the same setting can be used to identify the user data is to be restored. In
the define_structure function of the restore class, you’ll need to add the notes table with
something like this $paths[] = new restore_path_element('studyplan_notes', '/studyplan/notes').
And in the process_studyplan_data function you’ll need to use something like $this>get_mappingid('user', $data->userid) to identify the new user id before inserting the new note
record.
Concern: get_setting_value() is not currently available on backup or restore class. Eloy is
adding them shortly (for 2.0.2), so hopefully when this is developed they will be available for us.
The user option to show or hide note making functionality will be backed up and restored
automatically as part of the core user preferences functionality.
Installation
An update script will be required to add the new database table defined above.
Export
If we use the same export form as Jason for calendar this causes problems with overlapping
plugins. We’ll need an export page within studyplan which includes his export stuff IF the
local/calexport plug-in is installed. This can be acheived with a function exists check, and then
calling the function.
The Word document should be forcedownload to override any user preference to open.
Test script
Code
User
Installation and upgrade
IU01 Studyplan course format installs with Moodle into empty database with no
errors
Admin
IU02 Studyplan course format installs into a Moodle 2.0 clean install with no errors
Admin
IU03 Note making tool extension to studyplan installs into existing Moodle 2.0 with
earlier version of studyplan course format
Admin
Adding a note
AD01 Viewing a course with the studyplan course format, a single “add note”
button is visible for each section of the course.
User 1
AD02 Clicking the add note button (AD01) opens a text box form field. Text can
be entered into the box.
User 1
AD03 Following on from AD02, clicking the save button closes the text box and
makes appropriate database saves
User 1
Editing an existing note
ED01 Following on from AD03, the add note button for the section chosen has
been replaced with an “edit note” button
User 1
ED02 Clicking the edit note button (AD01) opens a text box form field which holds
the text entered in AD02. Text can be altered.
User 1
ED03 Following on from ED02, clicking the save button closes the text box and
makes appropriate database saves
User 1
Canceling an edit
CA01 Following on from ED02, pressing the “cancel” button closes the text box.
Database remains unchanged.
User 1
CA02 Following on from CA01, if the note is edited again (ED01 and ED02), the
changes made earlier have been lost
User 1
Deleting a note
DE01 Following on from ED02, clicking the delete button closes the text box and
removes data from the database.
User 1
DE02 Following on from DE01, the edit note button for the section chosen has
been replaced with an add note button.
User 1
Hiding note maker
HD1 Following on from AD03, user visits their studyplan settings and can see the
notemaking section with show/hide options with “show” selected.
User 1
HD2 Following on from HD1, user chooses the hide option and saves their settings User 1
HD3 Following on from HD2, user returns to the course website. Add and edit
note buttons are no longer visible
User 1
HD4 Following on from HD3, user repeats HD1 to 3, but sees that “hide” option is
User 1
selected initially, and on changing this to “show”, Add and edit buttons return to the
course website
Exporting notes
EX01 Following on from AD03, user visits the export page and sees a notemaking
section with two options. User clicks the Word option and the browser offers a
Word document containing the notes for download.
User
EX02 Following on from AD03, user visits the export page and chooses the Save
to Google option. A document containing their notes is saved into their open
GoogleDocs account
User
EX03 Following on from AD03, user visits the export page and chooses the Save
to Google option. Because they are not logged in, the Google sign-in screen is
displayed. Once signed in, a document containing their notes is saved into their
GoogleDocs account
User
EX04 Following on from HD2, user visits the export page and does not see the
notemaking export options.
User
Grouped sections
GS01 User combines two (or more) sections on the studyplan and leaves several
other sections separate
Admin
GS02 Following on from GS01, user sees that there is a single “add note” button
on the combined sections. User adds a note to the combined section and to a two
separate but adjacent sections (these notes should in total be more than 500
characters)
User 1
GS03 User separates the combined section, and combines the separate sections
the user added the notes to in GS02 together
Admin
GS04 Following on from GS03, user sees the note which was on the combined
sections as attached to the first of those sections now they have been separated.
The other sections which were in the group now display an “add note” button
User 1
GS05 Following on from GS03, user sees a single note on the newly combined
section. On editing, they see complete note text from both original notes, and an
overflow warning that the note is now too long
User 1
Backup and restore
BR01 User makes a backup of course used in all previous testing, but excludes
user data.
Admin
BR02 User restores backup made at BR01 into a new course, enrolling the same
set of users.
Admin
BR03 Following on from BR02, user views the new course and only sees “add
note” buttons - none of their previous notes have been restored.
User
BR04 User makes a backup of course used in all previous testing, including user
data.
Admin
BR05 User restores backup made at BR04into a new course, enrolling the same
set of users.
Admin
BR06 Following on from BR05, user views the new course and sees “add note” or
“edit note” buttons as appropriate - their previous notes have been restored.
User
BR07 For completeness, all BR tests should be repeated with restore into existing
courses with merge and replace.
Admin
Permissions
RP01 Following on from AD03, user views the same course website, but sees an
“add note” button for the section chosen
User 2
RP02 Following on from RP01, user adds a note to the same section. On saving,
and editing the note again, their own note (not the AD02 one) is displayed
User 2
RP03 User edits the user role and removes the editnotes capability
Admin
RP04 Following on from RP03, user views the course website. They can no
longer see ‘add note’ buttons for sections with no existing notes. For sections with
existing notes, the ‘edit note’ button is present, but when clicked, the note text is
not editable and the save/cancel/delete buttons are disabled. Notes remain
available for export.
User 1
RP05 User edits the user role and removes the viewnotes capability
Admin
RP06 Following on from RP05, user views the course website. They cannot see
any note making functionality (add,edit,export,).
User 1
Mobile
MO01 All tests should be repeated on a mobile device