Skip to content

Latest commit

 

History

History
723 lines (478 loc) · 25.7 KB

UserGuide.adoc

File metadata and controls

723 lines (478 loc) · 25.7 KB

NSync - User Guide

By: CS2113-AY1819S1-W12-2 Since: Aug 2018 Licence: MIT

1. Introduction

NSync is a program for NUS students who strive to keep their lives organised, despite their busy schedules. Interested? Jump to the Section 2, “Quick Start” to get started. Enjoy!

2. Quick Start

  1. Ensure you have Java version 9 or later installed in your Computer.

  2. Download the latest addressbook.jar here.

  3. Copy the file to the folder you want to use as the home folder for your Address Book.

  4. Double-click the file to start the app. The GUI should appear in a few seconds.

  5. Download the addressbook.xml file at this link https://github.com/CS2113-AY1819S1-W12-2/main/releases/tag/V1.4 and replace your own data file with it to get 20 normal contacts and 7 merged contacts.

    Ui

  6. Type the command in the command box and press Enter to execute it.
    e.g. typing help and pressing Enter will open the help window.

  7. Some example commands you can try:

    • list : lists all contacts

    • addn/John Doe p/98765432 e/[email protected] a/John street, block 123, #01-01 : adds a contact named John Doe to the Address Book.

    • deletemain 3 : deletes contact whose index number is 3

    • exit : exits the app

  8. Refer to Section 3, “Features” for details of each command.

3. Features

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in add n/NAME, NAME is a parameter which can be used as add n/John Doe.

  • Items in square brackets are optional e.g n/NAME [t/TAG] can be used as n/John Doe t/friend or as n/John Doe.

  • Items with …​ after them can be used multiple times including zero times e.g. [t/TAG]…​ can be used as   (i.e. 0 times), t/friend, t/friend t/family etc.

  • Items with 1..​ after them can be used multiple times, excluding zero times e.g. [ENROLLED MODULE]1..

  • Parameters can be in any order e.g. if the command specifies n/NAME p/PHONE_NUMBER, p/PHONE_NUMBER n/NAME is also acceptable.

3.1. General Commands

3.1.1. Listing entered commands : history

Lists all the commands that you have entered in reverse chronological order.
Format: history

ℹ️

  • Pressing the ↑ and ↓ arrows will display the previous and next input respectively in the command box.

  • For privacy reasons, downloadAllNotes and downloadSelectNotes commands will not be saved to history. This is because those commands contain the user’s IVLE password.

3.1.2. Exiting the program : exit

Exits the program.
Format: exit

3.1.3. Saving the data

Address book data are saved in the hard disk automatically after any command that changes the data.
There is no need to save manually.

3.2. Address Book Commands

3.2.1. Viewing help : help

Format: help

3.2.2. Adding a person: add

Adds a person to the address book
Format: add n/NAME p/PHONE e/EMAIL a/ADDRESS [t/TAG]…​[em/ENROLLED MODULE]…​

💡
 If you somehow lose your self contact, you can create a new one by adding t/self to your add command. Adding any other tag will not have any effect on the contact created. Self contacts cannot be deleted through the interface so do not add another self contact if you already have one that exists.

Examples:

ℹ️
 Contacts in this addressbook are automatically sorted in alphabetical order
ℹ️
 Trying to add a new contact (with different user fields) with the same name as an existing contact does not currently work

3.2.3. Listing all persons : list

Shows a list of all persons in the address book.
Format: list

3.2.4. Editing a person : edit

Edits an existing person in the address book.
Format: edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [em/ENROLLED MODULE]…​

  • Edits the person at the specified INDEX. The index refers to the index number shown in the displayed person list. The index must be a positive integer 1, 2, 3, …​

  • At least one of the optional fields must be provided.

  • Existing values will be updated to the input values.

  • When editing tags and enrolled modules, the existing tags and enrolled modules of the person will be removed

  • Likewise, you can remove all the person’s enrolled modules by typing em/ without specifying any enrolled modules after it. i.e adding of enrolled modules is not cumulative.

Examples:

  • edit 1 p/91234567 e/[email protected]
    Edits the phone number and email address of the 1st person to be 91234567 and [email protected] respectively.

  • edit 2 n/Betsy Crower
    Edits the name of the 2nd person to be Betsy Crower.

  • edit 3 n/Esther Daniels em/
    Edits the name of the 3rd person to be Esther Daniels and clears all existing enrolled modules.

3.2.5. Locating persons by name: find

Finds persons whose names contain any of the given keywords.
Format: find MAIN/MERGED KEYWORD [MORE_KEYWORDS]

  • The search is case insensitive. e.g hans will match Hans

  • The order of the keywords does not matter. e.g. Hans Bo will match Bo Hans

  • Only the name is searched.

  • Only full words will be matched e.g. Han will not match Hans

  • Persons matching at least one keyword will be returned (i.e. OR search). e.g. Hans Bo will return Hans Gruber, Bo Yang

  • Choosing MAIN will let you search in the individuals contact list while choosing Merged will let you searchi in the groups contact list.

  • Choosing of MAIN/MERGED is not case sensitive.

Examples:

  • find main John
    Returns john and John Doe from the main contact list

  • find merged CS2113 CS2101
    Returns any groups having names CS2113 and CS2101 from the group contact list

3.2.6. Deleting a person : delete

Deletes the specified person from the address book.
Format: delete MAIN/MERGED INDEX

  • Deletes the person at the specified INDEX.

  • The index refers to the index number shown in the displayed person list.

  • The index must be a positive integer 1, 2, 3, …​

  • Choosing MAIN will let you delete from the individuals contact list while choosing MERGED will let you delete from the groups contact list.

  • Choosing of MAIN/MERGED is not case sensitive.

Examples:

  • list
    delete main 2
    Deletes the 2nd person in the address book.

  • find merged CS2101
    delete merged 1
    Deletes the 1st group in the results of the find command.

3.2.7. Selecting a person : select

Selects the person identified by the index number used in the displayed person list.
Format: select INDEX

  • Selects the person and <to be confirmed> at the specified INDEX.

  • The index refers to the index number shown in the individuals contact list.

  • The index must be a positive integer 1, 2, 3, …​

Examples:

  • list
    select 2
    Selects the 2nd person in the address book.

  • find main Betsy
    select 1
    Selects the 1st person in the results of the find command.

3.2.8. Undoing previous command : undo

Restores the address book to the state before the previous undoable command was executed.
Format: undo

ℹ️

  • Undoable commands: Address Book and Timetable commands that modify the address book’s content (add, delete, edit, clear, change, share, merge, filter, free, export, import).

  • Notes commands are not compatible with undo.

Examples:

  • delete 1
    list
    undo (reverses the delete 1 command)

  • select 1
    list
    undo
    The undo command fails as there are no undoable commands executed previously.

  • delete 1
    clear
    undo (reverses the clear command)
    undo (reverses the delete 1 command)

3.2.9. Redoing the previously undone command : redo

Reverses the most recent undo command.
Format: redo

Examples:

  • delete 1
    undo (reverses the delete 1 command)
    redo (reapplies the delete 1 command)

  • delete 1
    redo
    The redo command fails as there are no undo commands executed previously.

  • delete 1
    clear
    undo (reverses the clear command)
    undo (reverses the delete 1 command)
    redo (reapplies the delete 1 command)
    redo (reapplies the clear command)

3.2.10. Clearing all entries : clear

Clears all entries from the address book and resets your self contact.
Format: clear

3.3. Timetable Commands

3.3.1. Changing Time Slots: change

You can change your own, or a contact’s timetable to reflect whether there is an activity at a specified time slot, or whether it is free or busy.

Format: change INDEX/SELF DAY TIME ACTIVITY/FREE/BUSY

  • Changes the timetable of the person specified by index or your own timetable if self is inputted.

  • The DAY refers to which day of the timetable is going to be edited.

  • The TIME refers to which time within the day will be edited.

  • The ACTIVITY/FREE/BUSY refers to what will be reflected at the seleted time slot

  • DAY must be mon, tue, wed, thu or fri (Non-case sensitive)

  • TIME must be 8am, 9am, 10am, 11am, 12pm, 1pm, 2pm, 3pm, 4pm, 5pm, 6pm, 7pm

change 1 mon 8am GER1000 Changes the mon 8am time slot of the first contact in the main contact list to GER1000

Before:

ChangeCommand1

After:

ChangeCommand2

3.3.2. Merging timetables: merge

You can select multiple contacts whose timetables you would like to merge and give it a group name. This displays a collated timetable with the number of people busy for each time slot. It also displays the names of the people in the group.

Format: merge m/INDEX m/INDEX…​

  • Merges the people at selected INDEXes.

  • The index refers to the index number shown in the displayed person list.

  • The index must be a positive integer 1, 2, 3, …​

  • More than 2 people can be merged at once

  • Your own timetable wil always be included in the merge

  • You may select one contat multiple times if they are deemed more important to the group

merge m/2 m/3 m/4 n/CS2101 Project
Merges your own timetable with the 2nd, 3rd and 4th people in the address book.

MergeCommandUserGuide

The merged timetable will be added to the list of groups

3.3.3. Updating group timetables: update

You can automatically update your group timetables based on whatever changes have been made to your contacts' timetables.

Format: update

  • Update will update all your groups when you use it.

  • If a contact who belongs in one of your groups is deleted, update will show who was deleted and which groups were affeccted in addition to updating the group timetables.

  • If the deletion of a contact results in your own contact being the only person left in the group, the group will be automatically deleted. This deletion will also be reflected in the command result in addition to the people who were deleted and the groups affected by their deletion.

3.3.4. Filters contacts based on free time slots and activities: filter

You can select a time slot or activity you would like to filter your contacts by. Time slot filtering filters out people who are busy at the selected time slot. Activity filtering filters out people who do not have the activity in their timetable or does not have the module in their enrolled modules if the activity is a module taken.

Format: filter ACTIVITY /DAY TIME…​

  • Entering a module code removes contacts without the module from the list.

  • Entering a day and time removes contacts without that time slot free.

  • Day must be mon, tue, wed, thu or fri.

  • Only inputs after a valid day will be treated as a time. Every other input gets treated as an activity.

  • Time must be 8am, 9am, 10am, 11am, 12am, 1pm, 2pm, 3pm, 4pm, 5pm, 6pm or 7pm.

  • Contacts can be filtered by more than one activity/day and time.

  • Filter feature is not case sensitive.

filter GER1000
Shows only contacts who have GER1000 in the timetable.

filter run
Shows only contacts who have run in their timetable.

filter mon 10am
Shows only contacts who are free at mon 10am.

filter GER1000 mon 10 am
Shows only contacts who have GER1000 in their timetable and are free at mon 10am.

3.3.5. Filters for next free time-slot: free

Want to meet up with your friends at the soonest opportunity? Or would you like to find out when is the next time you can take a break (with no scheduled activities)? free allows you to easily find the next available time-slot from the current time for one or more of your NSync contacts, giving you answers to these questions!

Format: free f/[SELF/INDEX] …​

SampleTimeTable

Example 1: free f/self
Running this command will show your next available time-slot (from current time).
With reference to the time-table found in the figure above, if the current day and time is Monday 3:00pm, your next available time-slot shown is Monday 4:00pm till 8:00pm. If the current day and time is Monday 4:34pm, your next available time-slot shown is Monday 4:34pm till 8:00pm.

Example 2: free f/1 f/7 f/9
Running this command will show the next available time-slot (from current time) for contacts whose indices are 1, 7 and 9 respectively.

ℹ️
 Running this command outside the day window of Monday to Friday or beyond the time of 8pm will return a time-slot from the next weekday.

3.3.6. Export user data: export

Met a new acquaintence who would like to have your contact details and time-table to schedule a common meeting time? export allows you to export all of a user’s (or your own) details in each respective field into an encoded string. (Once you have sent the string to another NSync user, he/she can use import to retrieve the data within the encoded string - see import for more details)
Format: export PUBLIC/PRIVATE SELF/INDEX

  • Type 'public' if you would like the user who imports your contact to see the full contents of your time-table.

  • Type 'private' if you would like the user who imports your contact to see only your free and busy time-slots respectively (i.e. specific contents of your time-table are hidden!).

All examples shown below are with reference to the sample time-table shown in the figure above.

Example 1: export public self
The importing user will see your time-table in its entirety (i.e. the full contents of the time-table), exactly as shown in the sample time-table above.

Example 2: export private self
The importing user will see only the busy and free time-slots in your time-table, marked as black and white colored slots respectively, as seen in the figure below.

ExportPrivateView
💡
 The generated string from the command will be automatically copied for you (no manual selecting and copying required)! All you have to do is to send it in its entirety to a fellow NSync user who will import it.
ℹ️
 When exporting a time-table with only free and busy time-slots (i.e. black and white slots), it does not matter if you select either the public or private option - the user who imports your generated string will see the same time-table.
ℹ️
 Exporting more than 1 user’s details at a time or exporting a merged time-table is currently not available (but will be implemented in future releases!).

3.3.7. Import user data: import

Did you receive an encoded string from a fellow NSync user? Use import to transfer all of the data within the string into your copy of NSync!
Format: import [PASTE_YOUR_ENCODED_STRING_HERE]

Display Message 1: Import Successful!
If you have imported a valid contact who is currently not in your NSync (i.e. no contact with the same name), all of the imported user’s details will now be found in your NSync.

ℹ️
 If you see only black and white colored slots in the time-table of the imported contact, it means that the exporting user could have chosen the private option during the export process. See export for more details.

Display Message 2: Import Successful! An existing contact has been found in NSync and has been overwritten.
If you have imported a valid contact who is currently already in your NSync (i.e. contact with the same name), all of the details found in the imported string will overwrite the existing ones found in your NSync, for that particular contact.

💡
 If you have unintentionally over-written the details of an existing contact, use undo to get back the original details of the contact!

Display Message 3: Import Failed!
If you have missed out a character, or accidentally modified one of the characters in the string, attempting to import the invalid string will result in an error displayed. Please obtain a valid string from the contact who passed it to you.

3.4. Notes Commands

ℹ️
 The download function has temporarily been disabled in accordance with NUS Information Technology Acceptable use policy for IT resources Ver4.2, Clause 4.6

You are still able to login and view available files to be downloaded. Try out downloadSelectNotes without the /file prefix!

ℹ️
 You would need to have Google Chrome installed in the default location, run Windows 8 or above and be connected to the internet to use the download commands.
ℹ️
 You would be unable to see your inputted command after inputting it, this is a security feature to prevent your login credentials from being compromised.

3.4.1. Downloading all notes from a selected module from IVLE : downloadAllNotes

Downloads the your notes from IVLE, and stores them in the folder "Notes"
Format: downloadAllNotes downloadAllNotes [user/IVLE USERNAME] [pass/IVLE PASSWORD] [mod/ENROLLED MODULE]

downloadExample

Example DownloadAllNotes command usage.

  • Automatically accesses the your IVLE account using Google Chrome, and downloads all notes and resources of the specified module.

💡
 You do not have to Enter the full module code or worry about the capitalization. Example: if you are enrolled in CS2113 and CS2101 entering mod/cs21 will select cs2101

  • You may notice a new window of Google Chrome opening up. Do not interact with it or you might interfere with the download.

chromeOpen

  • NSync might be unresponsive during the download, it is so to prevent you from accidentally introducing file corruption.

  • If your download is successful, the result window of NSync will display the exact path to your newly downloaded notes.

Examples and what you might expect :

Download Successful :

downloadAllSuccessful

Module not found :

downloadModNotFound

Password or username Incorrect :

downloadPasswordOrUsernameWrong

3.4.2. Display all notes from a selected module from IVLE : downloadSelectNotes without prefix "file/"

Displays all the available notes of a selected
Format: downloadSelectNotes [user/IVLE USERNAME] [pass/IVLE PASSWORD] [mod/ENROLLED MODULE]

ℹ️
 Currently the files are not sorted in any order. In a future version we will make its sorted by file type
downloadSelectFileExample

Example DownloadSelectFile without file/ prefix usage

  • All available notes from the selected module would be sourced and displayed

  • if a file is not shown, it could be either a private folder or a submission folder, consult your lecturer for more information

Examples and what you might expect :

File Fetch Successful :

downloadSelectFileSuccess1
downloadSelectFileSuccess2
ℹ️
 the number on the left of the file represents the file ID, it is static. Example: "0:LP41_More_UML_Inheritence.pptx" 0 is the file index.

3.4.3. Downloading selective notes from a selected module from IVLE : downloadSelectNotes with prefix "file/"

Download a selective number of notes from IVLE, and stores them in the folder "notes".

Format: downloadSelectNotes [user/IVLE USERNAME] [pass/IVLE PASSWORD] [mod/ENROLLED MODULE] [file/0,1,2…​n]

💡
 Use downloadSelectFile without the file\ prefix to obtain the file indexes.
downloadSelectExample

Example DownloadSelectFile with file/ prefix usage

  • The files would be downloaded one by one from IVLE to your "notes" folder.

  • if you entered a mix of invalid and valid file IDs, NSync will only only download the correct files, up till it encounters a invalid ID.

    Example: file/0,1,2,90000000,3
if 0,1,2,3 are valid file IDs, only file 0,1,2 will be downloaded.

Examples and what you might expect :

Download Successful :

downloadSelectSuccess

File not found :

downloadSelectFileNotFound

3.4.4. Show all downloaded notes: showNotes

Displays all the downloaded notes in the UI
Format: showNotes

ℹ️
 the files are displayed in the order that it is in your directory

  • It recursively searches your notes folder and displays all the files available

Examples of usage:

showNotes1
showNotes2
showNotes3

3.4.5. Clearing all downloaded notes : clearNotes

Clears all downloaded notes.
Format: clearNotes

3.4.6. Deleting notes from one or more selected modules : deleteSelectNotes

Deletes the notes that belong to the specified module, from storage
Format: deleteSelectNotes [ENROLLED MODULE]1..

  • Deletes notes of the ENROLLED MODULE.

  • The notes of the ENROLLED MODULE would be deleted, if they were downloaded using the command downloadAllnotes or downloadSelectNotes.

Examples:

  • deleteSelectNotes CS2100
    Deletes the notes belonging to the module CS2100.

  • deleteSelectNotes CS2105 CS2106
    Deletes the notes belongs to the modules CS2105 and CS2106.

  • deleteSelectNotes CS
    Deletes the notes belongs to modules that have "CS" in their names

  • deleteSelectNotes PL3232
    Will not delete anything if "PL3232" does not exist as your downloaded notes.

  • deleteSelectNotes PL3232 CS2106
    Will not delete anything if "PL3232" does not exist as your downloaded notes, however notes belonging to "CS2106" would be deleted.

4. Upcoming Features

4.1. Encrypting data files [coming in v2.0]

NSync will automatically encrypt your data upon exiting the program.
Before exiting, NSync will prompt you for a password, which it uses to encrypt your data.
Upon start up, NSync will prompt you for the same password, which it uses to decrypt your data.

  • Searches ST’s friends for the same module code

  • Parses the information and displays it as a list

ℹ️
 NSync will only encrypt you data if you enter a password when prompted upon exit. If no password is entered, NSync will not encrypt your data

4.2. Display of notes in the Graphical User interface upon download [coming in v2.0]

NSync will automatically display your notes, after the download has completed.
This allows you to have an immediate idea of exactly what you downloaded.

Example:

automaticallyDisplayedNotes

5. FAQ

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous Address Book folder. The downloaded notes can be transferred in the same way.

Q: What is IVLE?
A: According to the National University of Singapore (NUS), Integrated Virtual Learning Environment (IVLE) is a NUS' custom designed and built Learning Management System for the NUS community. It is designed to facilitate and supplement teaching at the National University of Singapore (NUS).

6. Command Summary

  • Add add n/NAME p/PHONE e/EMAIL a/ADDRESS [t/TAG]…​[em/ENROLLED MODULE]…​
    e.g. add n/James Ho p/22224444 e/[email protected] a/123, Clementi Rd, 1234665 t/friend t/colleague em/CS2101 em/CS2113

  • Clear : clear

  • Clear Notes : clearNotes

  • Delete selected notes : deleteSelectedNotes [ENROLLED MODULE]1.."
    e.g. `deleteSelectedNotes CS2105 CS2106

  • Download All Notes : downloadAllNotes user/e1234567 pass/password1 mod/CS2113

  • Download Selected Notes (selected notes) : downloadSelectNotes user/e1234567 pass/password1 mod/CS2113 file/1,2,3…​

  • Download Selected Notes (show all notes) : downloadSelectNotes user/e1234567 pass/password1 mod/CS2113

  • Show notes : showNotes

  • Delete : delete INDEX
    e.g. delete 3

  • Edit : edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [t/TAG]…​ [em/ENROLLED MODULE]…​
    e.g. edit 2 n/James Lee e/[email protected]

  • Find : find KEYWORD [MORE_KEYWORDS]
    e.g. find James Jake

  • Help : help

  • History : history

  • List : list

  • Merge Timetables : merge [index 1] [index 2] <add more indices if required> e.g. merge 1 2 5

  • Redo : redo

  • Select : select INDEX
    e.g.select 2

  • Undo : undo