VolunTier User Guide

---

Introduction

VolunTier is a top Tier solution for volunteer organizations specializing in teaching students and managing a growing clientele efficiently. Designed for those comfortable with the Command Line Interface (CLI) and quick typing, VolunTier is ideal for Singapore-based users with extensive tutor and tutee data to manage across three subjects. It streamlines the process of adding, editing, and deleting records for volunteers, students, and shared lessons.

Quick start

Installation of application

1. Ensure you have Java 17 or above installed in your Computer.

2. Download the latest .jar file from here.

3. Copy the file to the folder you want to use as the home folder for your VolunTier app.

4. Open a command terminal, cd into the folder you put the jar file in, and use the java -jar VolunTier.jar command to run the application.
   A GUI similar to the below should appear in a few seconds. Note how the app contains some sample data.
   

5. 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.
   Some example commands you can try:

• list : Lists all contacts.

• addTutor \n John Doe \p 98765432 \e johndoe@example.com \a 311, Clementi Ave 2, 123456 \h 6 : Adds a tutor named John Doe with the phone number 98765432, email johndoe@example.com, residing at 311, Clementi Ave 2, 123456, and records 6 hours of tutoring.

• delete 3 : Deletes the 3rd contact shown in the current list.

• clear : Deletes all contacts.

• exit : Exits the app.

7. Refer to the Features below for details of each command.

---

CLI tutorial

Skip to Features if you are proficient in CLI.

This tutorial introduces you to the basics of using the Command Line Interface (CLI) on Unix-based systems (Linux/macOS) and Windows. By the end, you’ll be comfortable navigating the file system, managing files, and running basic commands through the terminal.

1. What is the CLI?

The CLI is a text-based interface where users interact with the operating system by typing commands. It allows for:

• Efficient operations compared to GUI
• Advanced automation with scripts and batch commands

2. Opening the Terminal

On macOS:

Type Terminal in Spotlight Search (F4 or Cmd + Space)

On Windows:

Search for command prompt or Powershell in the start menu.

On Linux:

Ctrl + Alt + T

---

User Interface

1. Menu: Provides access to the File and Help options.
2. Person List: Displays the list of tutors and tutees.
3. Response Box: Shows feedback for users from the VolunTier app.
4. Tutor Hours Chart: Displays a bar chart when the vtc command is used.
5. Command Box: The area where user commands are entered.

---

Features

Viewing help : help

Shows the command summary and a message explaining how to access the help page.

Format: help

Adding a Tutor: addTutor

Adds a Tutor to VolunTier.

Format: addTutor \n NAME \p PHONE_NUMBER \e EMAIL \a ADDRESS [\h HOURS] [\s SUBJECT]…​

Examples:

• addTutor \n Alice Pauline \p 98722342 \e alicep@example.com \a Alice street, block 123, 999888 \s math \s science
• addTutor \n John Doe \p 98765432 \e johnd@example.com \a Mingyang street, block 123, 888777 \h 6 \s english

Adding a Tutee: addTutee

Adds a tutee to VolunTier.

Format: addTutee \n NAME \p PHONE_NUMBER \e EMAIL \a ADDRESS [\h HOURS] [\s SUBJECT]…​

Adding a Lesson: addLesson

Adds a lesson in VolunTier between a Tutor and Tutee. A lesson must have a Tutor, a Tutee and a subject.

Format: addLesson TUTOR_INDEX TUTEE_INDEX \s SUBJECT

• Adds a lesson between the Tutor at the specified TUTOR_INDEX and the Tutee at the specified TUTEE_INDEX for the specified SUBJECT.
• The Tutor, Tutee, and the Lesson added must have matching subjects.

Examples:

• addLesson 1 2 \s science

Listing all persons : list

Shows a list of all persons in VolunTier.

Format: list

Editing a person : edit

Edits an existing person in VolunTier.

Format: edit INDEX [\n NAME] [\p PHONE_NUMBER] [\e EMAIL] [\a ADDRESS] [\h HOURS] [\s SUBJECT]…​

• Edits the person at the specified INDEX.
• At least one of the optional fields must be provided.
• Existing values will be updated to the input values.
• When editing subjects, the existing subjects of the person will be removed i.e adding of subjects is not cumulative.

Examples:

• edit 2 \p 91234567 \e johndoe@example.com Edits the phone number and email address of the 1st person to be 91234567 and johndoe@example.com respectively.
• edit 3 \n Betsy Crower \s Edits the name of the 2nd person to be Betsy Crower and removes all subjects linked.

Locating persons by name: find

Finds persons whose names contain any of the given keywords.

Format: find 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

Examples:

• find John returns john and John Doe
• find alex david returns Alex Yeoh, David Li

Locating persons by subject: findSubject

Finds persons who have any of the SUBJECT(s).

Format: findSubject SUBJECT [MORE_SUBJECTS]

• The search is case-insensitive. e.g., math will match Math
• The order of the keywords does not matter. e.g., math science will match science math
• Only the subject field is searched.
• Only full words will be matched e.g., mat will not match math
• Persons matching at least one keyword will be returned (i.e., OR search). e.g., math science will return persons with subjects Math, Science, Math and Science

Examples:

• findSubject English returns persons with subjects English
• findSubject math english returns persons with subjects English, Math

Deleting a person : delete

Deletes the specified person from VolunTier.

Format: delete INDEX

• Deletes the person at the specified INDEX.
• When a person is deleted, their associated lessons will be removed as well.

Examples:

• list followed by delete 2 deletes the 2nd person in VolunTier.
• find Betsy followed by delete 1 deletes the 1st person in the results of the find command.

⚠️ Warning: Deleting a person will permanently remove all lessons associated with them. Ensure you have selected the correct person before proceeding with deletion.

Deleting a lesson : deleteLesson

Deletes the specified lesson from VolunTier.

Format: deleteLesson TUTOR_INDEX TUTEE_INDEX \s SUBJECT

• Deletes the lesson between the Tutor at the specified TUTOR_INDEX and the Tutee at the specified TUTEE_INDEX for the specified SUBJECT.

Examples:

• findSubject Math followed by deleteLesson 2 5 \s Math deletes the lesson between the Tutor with index 2 and the Tutee with index 5.

Viewing a person's details : view

Displays additional details of a person that might not be shown on their card.

Format: view INDEX

• Views the details of the person at the specified INDEX.
• Details that are not shown on Person Card but can be viewed includes Hours and the person they are paired with along with the subject.

Examples:

• list followed by view 3 displays the details of the 3rd person in the address book.
• find Lisa followed by view 1 displays the details of the 1st person in the results of the find command.

Undoing a command : undo

Reverses the most recent command executed.

Format: undo

• You can only undo commands executed during the current session.

Examples:

• If you accidentally deleted a person, undo will add that person back along with their associated lessons.

Redoing a command : redo

Reapplies a command that was previously undone.

Format: redo

• Redo is only available immediately after an undo.

Examples:

• If you undo the addition of a new Tutor by mistake, redo will restore that entry.

Viewing command history : history

Provides a list of commands executed, from the most recent to the earliest.

Format: history

• History displays only commands executed during the current session.
• History displays all commands that was entered, regardless if it was successful or not.

Examples:

• If you accidentally add a Tutor as a Tutee using the addTutee command instead of addTutor, history lets you easily select and copy the previous command, saving you from retyping it.
• If you were in the middle of updating records and was distracted, history will allow you to find out where you left off last.

Viewing chart of tutors’ volunteer hours : vtc

Generates a chart displaying the total volunteering hours of all volunteer tutors.

Format: vtc

Examples:

• To see an overview of volunteer contributions, vtc will display a chart with each tutor's name and total hours logged.

Clearing all entries : clear

Clears all entries from VolunTier.

Format: clear

Importing people from CSV files : import

Allows users to import data from a CSV file and add multiple persons at once to the address book. If any rows fail the validation check or contain duplicates, they are skipped, and detailed feedback is provided to the user.

Format: import \f FILEPATH

• Use this to import your current users from your Excel spreadsheets to VolunTier.
• The .csv file to be imported must have these headings in this order: “name”, “phone”, “email”, “address”, “hours”, “role” and “subjects”.
• There should be no empty rows in your CSV file.
• For optional fields like hours and subject, leave a blank.
  For example, the following row leaves hours and subject blank: John, 91234567, john@gmail.com, “1 Jurong, 123456”, , Tutor,
• For any field that requires a comma, surround it in quotes like this: "1 Jurong, 123456".
• For more than one subject, separate it with a semicolon like this: English; Science.

Example:

• import \f ./data/new_persons.csv imports a list of people in new_persons.csv located in ./data/ into VolunTier.
• Output: 5 persons added. Rows with duplicates: [2, 4]. The following rows had data which failed some constraints: Row 3: Invalid email format. Row 5: Missing phone number.

Exiting the program : exit

Exits the program.

Format: exit

---

Saving the data

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

Editing the data file

VolunTier data are saved automatically as a JSON file [JAR file location]/data/addressbook.json. Advanced users are welcome to update data directly by editing that data file.

---

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 AddressBook home folder.

Q: Can I customize the subjects offered in VolunTier?
A: Currently, VolunTier supports only three basic subjects: Math, Science, and English. Custom subjects are not supported, but this feature may be considered in future updates.

Q: Is it possible to export my data from VolunTier?
A: VolunTier currently does not support an export feature directly. However, you can manually copy the addressbook.json file from the data folder and use it as a backup or to transfer data to another instance.

---

Known issues

1. When using multiple screens, if you move the application to a secondary screen, and later switch to using only the primary screen, the GUI will open off-screen. The remedy is to delete the preferences.json file created by the application before running the application again.
2. If you minimize the Help Window and then run the help command (or use the Help menu, or the keyboard shortcut F1) again, the original Help Window will remain minimized, and no new Help Window will appear. The remedy is to manually restore the minimized Help Window.
3. Viewing Tutor Chart when tutor's name is very long will cause layout issues and make the chart difficult to interpret. We are aware of this issue and plan to address it in future implementations to improve readability and user experience. As the average Singaporean would not have such long names, the remedy for now is to keep their names short by abbreviation.

---

Command summary