Hallper - User Guide

By: Team W16-1 Since: Aug 2018 Licence: MIT

1. Introduction
2. Quick Start
3. Command Examples
4. Features
5. FAQ
6. Command Summary
7. Glossary

1. Introduction

Hallper is a desktop application for the Junior Common Room Committee(JCRC) that allows for better and faster management of residents' contacts. More importantly, Hallper is optimized for those who prefer to work using their keyboards. If you can type fast, Hallper can get your contact management tasks done faster than most apps. Interested? Jump to Section 2, “Quick Start” to get started. Enjoy!

2. Quick Start

Ensure you have Java version 9 or later installed in your Computer.
Download the latest Hallper.jar here.
Copy the file to the folder you want to use as the home folder for your Hallper.
Double-click the file to start the app. The Hallper main window should appear in a few seconds.
Type the command in the command box and press Enter to execute it.
e.g. typing help and pressing Enter will open the User Guide window.

3. Command Examples

Here are some commands that you can try out with:

list : lists all residents
addn/John Doe p/98765432 e/johnd@example.com r/A110 s/FoS t/basketball : adds a resident named John Doe to Hallper.
delete3 : deletes the 3rd resident shown in the current list
exit : exits the app

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

4. 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 [c/CCA] can be used as n/John Doe c/soccer or as n/John Doe.
Items with … after them can be used multiple times including zero times e.g. [c/CCA]… can be used as (i.e. 0 times), c/soccer, c/soccer c/basketball etc.
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.

4.1. Updating Hallper

This section lists features related to updating residents in Hallper.

4.1.1. Adding a resident: `add`

Adds a resident to Hallper.
Format: add n/NAME p/PHONE_NUMBER e/EMAIL r/ROOM NUMBER s/SCHOOL [c/CCA]…

CCA must exist in the Budget book.

A resident can have any number of CCAs (including 0)

Examples:

add n/John Doe p/98765432 e/johnd@example.com r/C420 s/SoC c/Basketball
add n/Betsy Crowe c/Soccer e/betsycrowe@example.com p/1234567 r/B213 s/Business

4.1.2. Adding a picture to resident detail : `image`

Saves a copy of the image of resident staying in the specified room to Hallper.
Format: image r/ROOM f/FILEPATH

ROOM is not case-sensitive.
The image must be in .jpg.

Example:

image r/a123 f/C:/user/images/e0000000.jpg
Uploads the profile picture (in .jpg) of the resident living in room A123 into Hallper.

4.1.3. Clearing all residents : `clear all`

Clears all residents from Hallper.
Format: clear all

all is case-sensitive.

Example:

clear all
Clears all residents in Hallper.

4.1.4. Clearing specific residents : `clear`

Clears residents associated with specified CCAs from Hallper.
Format: clear KEYWORD…

Clears residents associated with specified KEYWORD.
KEYWORD refers to either a CCA or a ROOM.
Multiple KEYWORDS can be specified at once, in any order.

Example:

clear basketball
Clears all residents associated with CCA basketball.
clear A123
Clears all residents associated with room A123.
clear baseball C456
Clears all residents associated with CCA baseball and room C456

4.1.5. Editing a resident : `edit`

Edits an existing resident in Hallper.
Format: edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [c/CCA]…

Edits the resident at the specified INDEX. The index refers to the index number shown in the displayed resident 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 CCAs, the existing CCAs of the resident will be removed i.e adding of CCAs is not cumulative.
You can remove all the resident’s CCAs by typing c/ without specifying any CCAs after it.

Examples:

edit 1 p/91234567 e/johndoe@example.com
Edits the phone number and email address of the 1st resident to be 91234567 and johndoe@example.com respectively.
edit 2 n/Betsy Crower c/
Edits the name of the 2nd resident to be Betsy Crower and clears all existing CCAs.

4.1.6. Erasing specified ccas : `erase`

Erases all specified CCA(s) from all residents from Hallper.
Format: erase CCA…

Erases the CCA specified for all associated residents.
The CCA specified must be an existing CCA.
You can erase multiple CCAs by specifying the CCAs all at once.

Example:

erase basketball
Erases basketball from residents associated with this CCA.
erase basketball netball
Erases basketball and netball from residents associated with these CCAs.

4.1.7. Exporting residents' information: `export`

Exports file containing existing residents' information in Hallper.
Formate: export dst/PATH fn/FILENAME

The file exported will be a .xml file.

Example:

export dst/C://Users/Files fn/data.xml
Exports Hallper residents information into data.xml located at C://Users/Files.

4.1.8. Deleting a resident : `delete`

Deletes the specified resident from Hallper.
Format: delete INDEX

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

Examples:

list
delete 2
Deletes the 2nd resident in Hallper.
find Betsy
delete 1
Deletes the 1st resident in the results of the find command.

4.1.9. Importing residents information : `import`

Imports file containing Hallper-related information and updates Hallper accordingly.
Format: import f/FILEPATH

Allows for the mass upload of resident or CCA information.
The file to be uploaded must be a .xml file.

File format examples for importable .xml files are as shown below:

Figure 4.1.9.1: Resident information example. Multiple persons can be specified.

Figure 4.1.9.2: CCA list example. Residents are identified by their unique room number. Multiple room can be specified for multiple cca.

Figure 4.1.9.3: Budget book information example. Multiple transaction can be specified for multiple ccas.

Figure 4.1.9.4: Transaction information example. Multiple transaction can be specified.

Example:

import f/C://Users/Files/data.xml
Imports data.xml file to be read and for Hallper to be updated accordingly.

4.2. Viewing Hallper

This section lists features related to viewing all or specific residents s in Hallper.

4.2.1. Locating residents by name: `find`

Finds residents 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
residents 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 Betsy Tim John
Returns any resident having names Betsy, Tim, or John

4.2.2. Listing all residents : `list`

Shows a list of all residents in Hallper.
Format: list

Figure 4.2.2.1: Result after executing list.

4.2.3. Searching all residents under specified tag : `search`

Shows a list of all residents in the Hallper that are associated with the specified keyword.
Format: search KEYWORD [MORE_KEYWORDS]

KEYWORD can be ROOM, CCA or SCHOOL.
KEYWORD is not case-sensitive.

Examples:

Searches Hallper and lists all residents that are in basketball, staying in room A123 or studying in SoC in the resident List Panel as seen in Figure 4.2.1.1 and Figure 4.2.1.2.

Figure 4.2.3.1: Screen before running search on Hallper.

Figure 4.2.3.2: Screen after running search on Hallper.

search SoC
Searches Hallper and lists all residents that are studying in SoC.
search basketball
Searches Hallper and lists all residents that are in basketball.
search A123
Searches Hallper and lists all residents that are staying in room A123.
search basketball A123 Soc

4.2.4. Selecting a resident: `select`

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

Selects the resident and loads the profile page of the resident at the specified INDEX.
The index refers to the index number shown in the displayed resident list.
The index must be a positive integer, 1, 2, 3, …

Examples:

The screens for Hallper before and after executing the select command are shown below in Figure 4.2.4.1 and Figure 4.2.4.2 respectively:

Figure 4.2.4.1: Screen before running select on Hallper.

Figure 4.2.4.2: Screen after running select on Hallper.

list
select 2
Selects the 2nd resident in Hallper and opens his/her profile page.
find Betsy
select 1
Selects the 1st resident in the results of the find command and opens his/her profile page.

4.3. Email

This section lists features related to email in Hallper.

4.3.1. Composing an email to currently listed residents: `compose_email_list`

Composes a .eml file that can be used to send emails to currently listed residents.
Format: compose_email_list from/FROM subject/SUBJECT content/CONTENT

FROM must be a valid email address. E.g. johndoe@example.com
SUBJECT has no word limit.
CONTENT has no word limit.
  can be used in CONTENT for new line.

CONTENT is written in HTML. Users who know HTML can use it to format the CONTENT.

Example:

list

Figure 4.3.1.1: Result after executing list.

compose_email_list from/johndoe@example.com subject/Meeting this Friday content/Dear All There’s a meeting this friday. John Doe
Composes an email from johndoe@example.com to currently listed residents with subject Meeting this Friday and email body Dear All There’s a meeting this friday. John Doe and saves it as a .eml file.

Figure 4.3.1.2: Result after executing compose_email_list from/johndoe@example.com subject/Meeting this Friday content/Dear All There’s a meeting this friday. John Doe.

4.3.2. Composing an email to selected indexes: `compose_email_index`

Composes a .eml file that can be used to send emails to residents specified by index.
Format: compose_email_index from/FROM to/INDEXES subject/SUBJECT content/CONTENT

FROM must be a valid email address. E.g. johndoe@example.com
INDEXES refer to the index numbers shown in the displayed resident list.
INDEXES must be positive integers 1, 2, 3, …
SUBJECT has no word limit.
CONTENT has no word limit.
  can be used in CONTENT for new line.

CONTENT is written in HTML. Users who know HTML can use it to format the CONTENT.

Example:

list

Figure 4.3.2.1: Result after executing list.

compose_email_index from/johndoe@example.com to/1 3 5 subject/Meeting this Friday content/Dear All There’s a meeting this friday. John Doe
Composes an email from johndoe@example.com to residents at indexes 1, 3, and 5 with subject Meeting this Friday and email body Dear All There’s a meeting this friday. John Doe and saves it as a .eml file.

Figure 4.3.2.2: Result after executing compose_email_index from/johndoe@example.com to/1 3 5 subject/Meeting this Friday content/Dear All There’s a meeting this friday. John Doe.

4.3.3. Deleting an email : `delete_email`

Deletes an email.
Format: delete_email SUBJECT

SUBJECT is the subject of an existing email.
SUBJECT is case-sensitive.

Examples:

delete_email Meeting
Deletes the email with the subject Meeting.

image::delete_email.png[width="790"]+ Figure 4.3.3.1: Result after executing delete_email Meeting.

4.3.4. Listing all emails : `list_emails`

Displays a list of all emails in Hallper.
Format: list_emails

list emails Figure 4.3.4.1: Result after executing list_emails.

4.3.5. Viewing an email : `view_email`

Displays an email.
Format: view_email SUBJECT

SUBJECT is the subject of an existing email.
SUBJECT is case-sensitive.

Examples:

view_email Meeting on Friday
Displays the email with the subject Meeting on Friday.

Figure 4.3.5.1: Result after executing view_email Meeting on Friday.

4.4. Calendar

This section lists features related to managing the calendar in Hallper.

4.4.1. Adding all day event into calendar : `add_all_day_event`

Adds an all day event into the calendar.
Format: add_all_day_event month/MMM year/YYYY date/DD title/NAME OF EVENT

The MONTH must be specified as MMM.
The MONTH is not case-sensitive.
The YEAR must be specified as YYYY.
The DATE must be specified as DD.
The TITLE is case-sensitive.

Example:

Before executing command:

Figure 4.4.1.1: Screen before running add_all_day_event on Hallper.

add_all_day_event month/Oct year/2018 date/08 title/Hall open day
Adds an all day event titled Hall open day into the OCT-2018.ics calendar which happens on the 8th of Oct.

Figure 4.4.1.2: Screen after running add_all_day_event on Hallper.

4.4.2. Adding event into calendar : `add_event`

Adds an event with a specific time frame into the calendar.
Format: add_event month/MMM year/YYYY sdate/DD shour/HH smin/mm edate/DD ehour/HH emin/mm title/NAME OF EVENT

The MONTH must be specified as MMM.
The MONTH is not case-sensitive.
The YEAR must be specified as YYYY.
The DATE must be specified as DD.
DATE, HOUR, MINUTE must be specified as XX.
The TITLE is case-sensitive.

Example:

Before executing command:

Figure 4.4.2.1: Screen before running add_event on Hallper.

add_event month/Oct year/2018 sdate/10 shour/15 smin/30 edate/10 ehour/18 emin/00 title/Block Committee Audit
Adds an event titled Block Committee Audit into the OCT-2018.ics calendar which starts on the 10th at 1530 and ends on the 10th at 1800.

Figure 4.4.2.2: Screen after running add_event on Hallper.

4.4.3. Creating calendar : `create_calendar`

Creates a calendar file in Hallper for updating of events.
Format: create_calendar month/MMM year/YYYY

Creates a monthly calendar as a .ics file.
The MONTH must be specified as MMM.
MONTH is not case-sensitive.
The YEAR must be specified as YYYY.

Example:

create_calendar month/Feb year/2018
Creates a calendar for the month of Feb and year 2018 and saves it as a .ics file.

4.4.4. Deleting event from calendar : `delete_event`

Deletes an event from the calendar.
Format: delete_event month/MMM year/YYYY sdate/DD edate/DD title/NAME OF EVENT

An event is considered identical when it has the same start date, end date and title. Regardless of starting time and ending time.
The MONTH must be specified as MMM.
The MONTH is not case-sensitive.
The YEAR must be specified as YYYY.
The DATE must be specified as DD.
The TITLE is case-sensitive.

Example:

Before executing command:

Figure 4.4.4.1: Screen before running delete_event on Hallper.

Deleting a non-existing event (Title is case sensitive)
delete_event month/Oct year/2018 sdate/10 edate/10 title/block committee audit

Figure 4.4.4.2: Screen after running delete_event with a non-existing event in Hallper.

Deleting an existing event
delete_event month/Oct year/2018 sdate/10 edate/10 title/Block Committee Audit
Deletes an event titled Block Committee Audit from the OCT-2018.ics calendar which happens from the 10th of Oct to 10th of Oct.

Figure 4.4.4.3: Screen after running delete_event with an existing event in Hallper.

4.4.5. Viewing calendar : `view_calendar`

Loads the specified monthly calendar .ics file into the UI. UI by default displays the current week.
Format: view_calendar month/MMM year/YYYY

The MONTH must be specified as MMM.
MONTH is not case-sensitive.
The YEAR must be specified as YYYY.

Example:

view_calendar month/Oct year/2018
Displays view of calendar with current week as default page with the events loaded from OCT-2018.ics.

4.5. Budget and CCA

This section lists features related to CCA budget management in Hallper.

4.5.1. Adding a cca: `create`

Adds a CCA to Hallper.
Format: create n/NAME_OF_CCA budget/ALLOCATED_BUDGET

You can add in the name of the head and vice-head after you create the CCA.

undo and redo command does not apply to create.

Examples:

create n/Netball budget/500
create n/Basketball F budget/400

4.5.2. Adding a transaction: `add_trans`

Adds a transaction entry to the specified CCA in Hallper.
Format: add_trans c/NAME_OF_CCA date/DATE amount/AMOUNT remarks/REMARKS

Transaction entry can only be added one at a time.
undo and redo command does not apply to add_trans.

Examples:

add_trans c/Basketball date/31.01.2018 amount/-200 remarks/Competition Fee
Adds a transaction entry to Basketball. The date, amount and remarks of the transaction entry are 31.01.2018, -200 and Competition Fee respectively.

4.5.3. Deleting a cca : `delete_cca`

Deletes the specified CCA from Hallper.
Format: delete c/NAME_OF_CCA

The CCA specifed must exist in the Hallper.
undo and redo command does not apply to delete_cca.

Examples:

delete_cca c/netball
delete_cca c/Basketball F

4.5.4. Deleting a transaction entry : `delete_trans`

Deletes the specified transaction entry from the specified CCA from Hallper.
Format: delete_trans c/NAME_OF_CCA trans/ENTRY_NUMBER

The transaction entry number must be a positive interger (e.g. 1,2,3,4…).

The CCA specifed must exist in the Hallper.
The transaction entry number must exist for the specified CCA.
undo and redo command does not apply to delete_trans.

Examples:

delete_trans c/netball trans/1
delete_trans c/Basketball F trans/3

4.5.5. Updating a cca : `update`

Updates an existing CCA in Hallper.
Format: update c/CCA_NAME [n/NEW_CCA_NAME] [h/NAME_OF_HEAD] [vh/NAME_OF_VICE_HEAD] [budget/BUDGET] [trans/ENTRY_NUMBER] [date/DATE] [amount/AMOUNT] [remarks/REMARKS]

At least one of the optional fields must be provided.
When trans/ is included, at least one of the fields in the transaction entry must be provided. The transaction fields are date, amount and remarks.
Existing values will be updated to the input values.

The CCA specifed must exist in the Hallper.
The names of the head and vice head must exist in the Hallper.
The transaction number specified with trans/ must exist.
undo and redo command does not apply to update.

Examples:

update c/basketball n/basketball m h/Alex vh/Peter budget/700
Updates basketball to basketball m, budget to 700 and its head and vice-head to Alex and Peter respectively.
update c/Netball trans/2 date/30.05.2018 amount/-200 remarks/Purchase of Equipment
Updates the date, amount and remarks of the 2nd transaction entry of Netball with 30.05.2018, -200 and Purchase of Equipment respectively.
update c/track n/Track F h/Alice vh/June Ong budget/500 trans/1 date/28.02.2018 amount/100 remarks/Fund Raising
Updates track to Track F, its budget to 500 and its head and vice-head to Alice and June Ong respectively, and updates the date, amount and remarks of the 1st transaction entry to 28.02.2018, 100 and Fund Raising respectively.

4.5.6. Viewing all the ccas' budget : `budget`

Opens up a Budget Book in a new window.
Format: budget [c/CCA_NAME]

Figure 4.5.6.1: Budget Window with a blank screen

Figure 4.5.6.2: Budget Window showing the transaction history of Softball

budget shows the list of CCAs existing in Hallper.
If c/ is used, the new window will open up, showing the transaction information of the CCA specified.
Otherwise, the new window will open up and show a blank screen until a CCA is selected from the CCA panel.

Figure 4.5.6.3: CCA panel of the Budget Window

The CCA specifed must exist in the Hallper.

Examples:

budget
Opens up the Budget Window.
budget c/Softball
Opens up the Budget Window, showing the transaction history of Softball.

4.6. Miscellaneous

This section lists miscellaneous commands for navigating Hallper.

4.6.1. Exiting the program : `exit`

Exits the program.
Format: exit

4.6.2. 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.

4.6.3. 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)

4.6.4. Saving the data

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

4.6.5. Undoing previous command : `undo`

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

Undoable commands: Commands that modify Hallper’s residents (add, delete, edit and clear).

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)

Add : add n/NAME p/PHONE_NUMBER e/EMAIL b/BLOCK r/ROOM NUMBER s/SCHOOL [c/CCA]…
e.g. add n/James Ho p/22224444 e/jamesho@example.com b/C r/420 s/School of Computing c/Basketball
Clear : clear KEYWORD [MORE_KEYWORDS]
e.g. clear basketball A123
Clear all : clear all
Delete : delete INDEX
e.g. delete 3
Edit : edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [c/CCA]…
e.g. edit 2 n/James Lee e/jameslee@example.com
Erase : erase CCA
e.g. erase basketball
Export : export dst/PATH fn/FILENAME
Import : import f/FILEPATH
Image : image r/ROOM f/FILEPATH

6.2. Viewing Hallper

Find : find KEYWORD [MORE_KEYWORDS]
e.g. find James Jake
List : list
Search : search KEYWORD [MORE_KEYWORDS]
e.g. search basketball A123
Select : select INDEX
e.g. select 1

6.3. Email

Compose Email (Index) : compose_email_index from/FROM to/INDEXES subject/SUBJECT content/CONTENT
e.g. compose_email_index from/johndoe@example.com to/1 3 5 subject/Meeting this Friday content/Hey there’s a meeting this friday.
Compose Email (List) : compose_email_list from/FROM subject/SUBJECT content/CONTENT
e.g. compose_email_list from/johndoe@example.com subject/Meeting this Friday content/Hey there’s a meeting this friday.
List Emails : list_emails
View Email : view_email SUBJECT
e.g. view_email Meeting this Friday

6.4. Calendar

Add All Day Event : add_all_day_event month/MMM year/YYYY date/DD title/NAME OF EVENT
e.g. add_all_day_event month/Oct year/2018 date/08 title/Hall open day
Add Event : add_event month/MMM year/YYYY sdate/DD shour/HH smin/mm edate/DD ehour/HH emin/mm title/NAME OF EVENT
e.g. add_event month/Oct year/2018 sdate/10 shour/15 smin/30 edate/10 ehour/18 emin/00 title/Block Committee Audit
Create Calendar : create_calendar month/MMM year/YYYY
e.g. create_calendar month/Oct year/2018
Delete Event : delete_event month/MMM year/YYYY sdate/DD edate/DD title/NAME OF EVENT
e.g. delete_event month/Oct year/2018 sdate/10 edate/10 title/Block Committee Audit
View Calendar : view_calendar month/MMM year/YYYY
e.g. view_calendar month/Oct year/2018

6.5. Budget and CCA

Add CCA : create n/CCA bud/BUDGET
e.g. create n/Basketball budget/500
Add Transaction : add_trans c/NAME_OF_CCA date/DATE amount/AMOUNT remarks/REMARKS
e.g. add_trans c/Basketball date/31.01.2018 amount/-200 remarks/Competition Fee
Delete CCA : delete_cca c/CCA
e.g. delete_cca c/basketball
Delete Transaction : delete_trans c/NAME_OF_CCA trans/ENTRY_NUMBER
e.g. delete_trans c/netball trans/1
Update CCA Details : update c/CCA_NAME [n/NEW_CCA_NAME] [h/NAME_OF_HEAD] [vh/NAME_OF_VICE_HEAD] [budget/BUDGET] [trans/ENTRY_NUMBER] [date/DATE] [amount/AMOUNT] [remarks/REMARKS]
e.g. update c/track n/Track F h/Alice vh/June Ong budget/500 trans/1 date/28.02.2018 amount/100 remarks/Fund Raising
View CCAs' budget : budget [c/CCA_NAME]
e.g. budget c/basketball

6.6. Miscellaneous

Exit : exit
Help : help
History : history e.g. view 2
Redo : redo
Undo : undo

7. Glossary

CCA: Co-Curricular Activity that residents can join within their respective halls.
JCRC: Junior Common Room Committee in charge of administrative duties within their respective halls.