Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another member of the Core Development Team before making changes.

• Launchpad Entry: https://blueprints.launchpad.net/mira/+spec/notes-utility
• Created: 2010-06-19 by j_k9
• Contributors: j_k9

The Notes Utility allows users to create, edit, delete and read “notes” which contain text information.

The scope of this specification is to examine the design of the Notes Utility and its synchronisation system, and to propose a suitable implementation.

The Notes Utility is a plug-in module to the Utility layer. It will provide the following functionality:

• The ability to create a note (with a title and text content);
• The ability to delete a note;
• The ability to edit a note;
• The ability to read a note;
• The ability to do all of the above while offline, and to synchronise upon reconnection.

A mock-up of the Notes Utility UI is shown below (click for a larger image):

This mock-up is outdated. Since it was created, the design has been changed in the following ways:

• The Notes Utility will include forward and back buttons to cycle through notes;
• The Notes Utility will not have a list of tabs at the bottom;
• The Notes Utility will, by default, list all of the notes in a table as its main screen.

The Notes Utility will support offline usage and synchronisation upon reconnection. This will involve the resolution of any conflicts which might arise by the user who created the conflict.

The Notes Utility will use the default communication protocol for Utilities (token UT) for the transfer of notes and commands between Mira Client and Mira Server.

The procedures for each activity are described below. For ease of reference, the user of the Mira Client initiating a process will be known as “User1”, her Mira Client application will be know as the “Client” and the Mira Server to which the Client is connected will be known as “the Server”. We shall assume that there are other users (such as “User2”) connected to the same Server who are Members of the same Workplace.

The Default View is the UI of the Notes Utility when it loads. This default view displays a list of notes in a table with the following information:

• The title of the note;
• The date on which it was last modified;
• The full name of the user who last modified it.

The Reading View is the UI of the Notes Utility which is enabled when a note is opened for reading. It should show the following information:

• The title of the note;
• The date on which it was last modified;
• The full name of the user who last modified it;
• The content of the note.

And the following buttons:

• A 'Create' button, to add a new note;
• A 'Delete' button, to delete the note being displayed (this should require confirmation by the user);
• An 'Edit' button, to edit the note being displayed in the Editing View;
• A forward arrow button, to read the next note in the sequence (if another one exists);
• A backward arrow button, to read the previous note in the sequence (if another one exists).

The information should be presented in a format similar to the following mock-up:

The Editing View is the UI of the Notes Utility which is enabled when a note is opened for editing, or when a user chooses to create a new note. It should allow the following editable fields:

• A title;
• Note content.

And provide the following buttons:

• A 'Publish' button, which would publish the note as per the section: Creating a Note;
• A 'Discard' button, which would discard the note and return the UI to the Default View.

The Conflict Handling View is the UI of the Notes Utility which is enabled when a note which is published creates a conflict, as described in the section: Editing a Note. It should allow the following editable fields:

• The left pane, an uneditable textarea;
• The middle pane, an uneditable textarea;
• The right pane, an editable textarea.

And provide the following buttons:

• A 'Discard Changes' button, which removes the user's new version and reverts the local copy of the note to the latest version on the Server;
• A 'Save Changes' button, which saves the user's new version (once the conflicts have been resolved) as per the section: Editing a Note.

When a note is opened to be read (by double-clicking it from the Default View), the Reading View is loaded and the note's information is displayed as per the Reading View fields.

A button (such as 'Return to Notes') should also be provided to return the UI to the Default View.

When a note is created, the following procedure should occur:

1. User1 creates a new note in the Editing View. She enters a title for the note (such as “My Brilliant Note”), and some note content. She saves the note.
2. When the note is saved:
   • If Client is offline, it is stored locally until it next connects to the Server. When it next connects, Step 3 and onwards occur;
   • If Client is online, Step 3 and onwards occur.
3. Client transfers the new note to the Server.
4. The Server assigns the note some metadata, which include:
   • A unique, random ID specifically for the note (which will be used as a reference in the future);
   • The time at which the Server received the note;
   • The username of the user who created the note;
   • A version number (starting at 1, which will be incremented by the Server with each edit).
5. The Server transfers the note's metadata back to Client.
6. Client attaches this metadata to the local note and transfers a confirmation of the receipt of this metadata back to the Server.
7. If the Server:
   • does not receive the confirmation: it deletes the note it received. (END);
   • does receive the confirmation: it sends the note to all other online Members of the Workplace (END).

When a note is deleted, the following procedure should occur:

1. User1 selects a note (with ID 'uuu123'), which opens in the Reading View, and chooses to delete it.
2. Client sends a command to the Server to delete the note with ID 'uuu123'.
3. The Server deletes the note.
4. The Server sends a command to all online Members of the Workplace to delete the note. (END).

When a note is edited, the following procedure should occur:

1. User1 starts editing an existing note (for example, with unique ID 'uuu123') in the Editing View. Client automatically creates a back-up of the original note.
2. User1 makes her changes to the note and either:
   • discards them, in which case the back-up of the original note is deleted and the locally stored note is left unchanged. (END);
   • saves them, in which case continue to Step 3.
3. When the note is saved:
   • If Client is offline, it is stored locally until it next connects to the Server. When it next connects, Step 4 and onwards occur;
   • If Client is online, Step 4 and onwards occur.
4. Client downloads the latest version of the note with ID 'uuu123' from the Server. If:
   • the note has been deleted from the Server, the edited note is treated as a new note and transferred to the Server (see the section: Creating a Note). (END);
   • the note has not changed (i.e. the latest version on the Server is identical to the back-up of the original stored on Client):
     1. Client transfers the updated note to the Server.
     2. The Server receives this and replaces its version of the note which has the same unique ID, 'uuu123'.
     3. The Server updates the metadata of the note with a new timestamp, a new version number (incremented by one) and the username of the user who edited the note.
     4. The Server transfers the updated note (with updated metadata) to the Members of the Workplace, including User1. (END).
   • the note has been edited (i.e. the latest version on the Server is different to the back-up of the original stored on Client), continue to Step 5.
5. Client changes the Notes Utility to its default UI, which lists all the notes, and highlights the note with ID 'uuu123' in red and marks it as a 'CONFLICT'.
6. When User1 opens the note with the conflict, a three-pane window is opened. This window consists of:
   • The left pane, an uneditable textarea showing the back-up of the original version of the note which the user edited;
   • The middle pane, an uneditable textarea showing the latest version of the note on the Server;
   • The right pane, an editable textarea showing the user's edited copy of the note.
7. User1 edits the note on the right accordingly, to resolve the conflict. User1 can then choose to either:
   • 'Discard Changes', which deletes the user's edited copy of the note and the back-up of the original, and stores the latest version of the note downloaded from the Server as the correct local version of the note with ID 'uuu123'. (END);
   • 'Save Changes', in which case continue to Step 8.
8. Client downloads the latest version of the note with ID 'uuu123' from the Server. If:
   • the note has been deleted from the Server, the edited note is treated as a new note and transferred to the Server (see the section: Creating a Note). (END);
   • the note has been edited (i.e. the latest version on the Server is different to the latest version downloaded from the Server in Step 4), replace the back-up of the original note with the local latest version, and download the latest version from the Server as the new local latest version, and handle this as another 'CONFLICT'. (LOOP TO STEP 5).
   • the note has not changed (i.e. the latest version on the Server is identical to the latest version downloaded from the Server in Step 4), continue to Step 9.
9. Client transfers the updated note to the Server.
10. The Server receives this and replaces its version of the note which has the same unique ID, 'uuu123'.
11. The Server updates the metadata of the note with a new timestamp, a new version number (incremented by one) and the username of the user who edited the note.
12. The Server transfers the updated note (with updated metadata) to the Members of the Workplace, including User1. (END).

When a user reconnects to the Server, the following procedure should occur:

1. Any changes that are queued for transmission to the Server, such as note creations, deletions or edits, are transferred from Client to the Server using the procedures described above.
2. Client checks for edits of existing notes:
   • Client sends a list of the IDs of the notes it has stored locally, with their metadata, to the Server;
   • Server compares the metadata of those notes with the metadata of its notes with the same IDs to determine which notes have been updated since Client was last online;
   • Server sends Client the title and content of those notes which have been updated (linked to their note IDs);
   • Client updates the data and metadata of its locally stored notes.
3. Client checks for deletions of existing notes:
   • Server compares the note IDs from the list sent by the Client to the IDs of its stored notes;
   • Server sends a command to the Client to delete those notes with IDs which do not exist on the Server.
4. Client checks for new notes:
   • Server sends Client the full data and metadata of the notes which the Server has stored which were not on Client's list;
   • Client stores the full data and metadata of the new notes locally. (END).

Each of the above events should publish alerts to the user via “The Notifier”, Mira Client's built-in alert bubbles. This would take a format similar to the mock-up shown below: