User Guide

Foster Family is a desktop application built for foster managers of cat and dog shelters to facilitate the administrative management of foster families.

Here are some tasks which Foster Family can help you with:

Store and update the important details of animal fosterers (people who temporarily care for an animal in their own homes).
Search for a fosterer using any detail you can remember of them.
Gain insights on the overall status of managed fosterers.

Foster Family is optimised for use via a Command Line Interface (CLI). This means that you primarily interact with it by typing commands. It also retains the benefits of a Graphical User Interface (GUI), allowing you to interact with the application (app) through graphical components. If you can type fast, Foster Family can get things done faster than traditional GUI apps.

This document is a comprehensive guide to all the commands available to you, along with step-by-step explanations and examples to help you master the features Foster Family has to offer. If you are a new user, we recommend beginning your journey with Quick Start. For those who are already acquainted, you can refer to the Table of Contents below to navigate to a section that interests you.

Table of Contents
Quick Start
Useful Notations
Technical Terms
User Interface (UI)
- The main page
- The profile page
Features
FAQ
Known Issues
Command Summary

Quick Start

Step 1. Ensure you have Java 11 or above installed in your computer. You can download it from the Oracle website.

Step 2. Download the latest FosterFamily.jar from our GitHub Page.

Step 3. Copy the file to the folder you want to use as the home folder for Foster Family.

Step 4. Open a command terminal.

Step 5. Navigate to the home folder you put the jar file in using the command
cd <path_to_home_folder>, replacing <path_to_home_folder> with your file path.

Step 6. Use the java -jar FosterFamily.jar command to run the app.

The Foster Family GUI, similar to the image below, should appear on your screen. Note that the app contains some sample data the first time you launch it.

Step 7. Type a 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 fosterers.
add n/Jerry Tan p/98765412 e/jerry123@example.com a/61 Baker Street housing/nil availability/nil animal/nil animalType/nil : Adds a fosterer named "Jerry Tan" to Foster Family.
delete 3 : Deletes the 3rd fosterer shown in the current list.
reset, followed by reset confirm : Deletes all fosterers.
exit : Exits Foster Family.

Please refer to the Features section for details of each command.

Useful Notations

These symbols highlight information you may find important.

Symbol	Meaning
	General notes about the command
	Important notes about the command
	Warnings about the command, especially when data loss or misinterpretation is likely to occur
	Tips to optimise the use of Foster Family

Technical Terms

These are some technical terms you may come across in this user guide.

Term	Definition
Command	Features of Foster Family, as well as to keywords that trigger those features
Parameter / Argument	Information to be passed to commands as inputs
Index	The number to the left of each fosterer’s name in the list shown in the main page
Field	Attributes associated with a fosterer entry in Foster Family, such as name and email, etc

User Interface (UI)

There are two different screens you will interact with in Foster Family.

The main page

This is the main view that welcomes you when you first start up Foster Family.

The profile page

ProfileExample

This is the profile view that you can use to add a fosterer, or to edit the details of an existing fosterer.

Opening the profile page

There are two ways you can use to navigate to the profile page.

Enter add to view an empty profile page to add a fosterer.
Enter either edit INDEX or view INDEX to edit or view the fosterer at index INDEX in Foster Family.

Suppose you want to open the profile page of a fosterer named Alex Yeoh who is currently at index 1.

To do so, enter view 1 as shown in the image above. You will be directed to his profile page as shown in the image below.

Navigating through fields

Entering the name, fully or partially, of the field you want to edit brings your cursor to the corresponding textbox.

In the example above, entering name, or a part of name like nam, brings the focus to the name field.

After you are done editing, press the Enter key on your keyboard to confirm your changes, and bring your cursor back to the command box.

If you wish to discard changes while editing in the textbox, press the Esc key to undo the changes and direct your cursor back to the command box.

In the example above, after changing name from “Yeoh” to “Yeo”, the Enter key was pressed.

The same process can be applied to other fields.

Saving changes

Entering save saves the changes you have made into storage.

Suppose you want to save your changes after changing the name of the fosterer.

Key in save and press Enter to save the changes.

The effect of a save depends on the command you used to enter the profile page.

If this was an edit command, your changes to the fosterer will be saved.
If this was an add command, the new fosterer with the inputted details will be added, and you will be redirected back to the main page.

Exiting the profile page

Entering exit closes the profile page and directs you back to the main page. Foster Family will warn you if you attempt to exit without saving your changes.

1. Changes are saved

Suppose you have already saved your changes.

Exit command saved after

Key in exit and press Enter to close the profile page.

Exit command saved after

2. Changes are not saved

Suppose you entered exit without saving your latest changes.

Exit command not saved warning

If you press the Enter key again, you will discard your changes and be redirected back to the main page.

If you press the Esc key, the exit is cancelled, and you can continue working on your changes in the profile page.

Exit command not saved cancel

The image above is the result of pressing the Esc key after the warning.

To learn more about adding a new fosterer through the profile page, refer to the section Adding a fosterer through the profile page: add.
To learn more about editing a fosterer through the profile page, refer to the section Editing a fosterer’s detail through the profile page: edit.

Features

Notes about the command format:

Words in UPPER_CASE are parameters to be supplied by you.
e.g. in 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/urgent or 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. zero times), t/urgent, t/urgent t/experienced 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.
Extraneous parameters for commands that do not take in parameters (such as help, exit, undo, sort and reset) will be ignored.
e.g. if the command specifies help 123, it will be interpreted as help.
If you are using a PDF version of this document, be careful when copying and pasting commands that span multiple lines, as space characters surrounding line-breaks may be omitted when copied over to the app.
If the command you entered has an invalid format, our app will provide specific error messages to guide you to rectify the issue.

Viewing help for commands : `help`

Opens a pop-up window, providing you with the link to our User Guide for help.

Format: help

Help

Adding a fosterer through the main page: `add`

Adds a fosterer to your address book, done through the main page.

Format: add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS housing/HOUSING_TYPE availability/AVAILABILITY animal/ANIMAL_NAME animalType/TYPE_OF_ANIMAL [t/TAG]…

Parameters:

Parameter	About	Example
`NAME`	Name of the fosterer	`Alice Tan`, `Harry Yeo`
`PHONE_NUMBER`	Phone number of the fosterer	`93456778`, `89067547`
`EMAIL`	Email of the fosterer	`thomas718@gmail.com`, `kate@yahoo.com.sg`
`ADDRESS`	Address of the fosterer	`Orchard road, Blk 8, #13-04`
`HOUSING_TYPE`	- Housing type of the fosterer - Case-sensitive - Can only take the values shown in the example column	`HDB`, `Condo`, `Landed`, `nil`
`AVAILABILITY`	- Availability of the fosterer - Case-sensitive - Can only take the values shown in the example column	`NotAvailable`, `Available`, `nil`
`ANIMAL_NAME`	Name of the animal fostered	`Fluffball`, `nil`
`TYPE_OF_ANIMAL`	- Type of animal which the fosterer is currently fostering, or prefer to foster - Case-sensitive - Can only take the values shown in the example column	`current.Dog`, `current.Cat`, `able.Dog`, `able.Cat`, `nil`
`TAG`	Tag to be associated with the fosterer	`experienced`, `urgent`

Tip:

A person can have any number of tags (including 0).
nil can be indicated for HOUSING_TYPE, AVAILABILITY, ANIMAL_NAME and TYPE_OF_ANIMAL if that specific information is not currently available.

Valid cases:

No.	Scenario	`AVAILABILITY`	`TYPE_OF_ANIMAL`	`ANIMAL_NAME`
1	Not fostering, insufficient info collected	`nil`	`nil`	`nil`
2	Not fostering, insufficient info collected	`Available`	`nil`	`nil`
3	Not fostering, preference indicated	`Available`	`able.Dog/Cat`	`nil`
4	Not fostering (e.g. overseas, currently not able to foster)	`NotAvailable`	`nil`	`nil`
5	Fostering: ALL information must be present	`NotAvailable`	`current.Dog/Cat`	NOT `nil`

For invalid cases, error messages will be shown when you enter the invalid commands. For example: Add

Important:

You cannot add duplicate fosterers. This is detected using the fosterer’s name.
e.g. "Anne Tay" is the same person as "anne tay" and "anne (multiple spaces) tay".

Examples:

add n/Jerry Tan p/98765412 e/jerry123@example.com a/Baker street, block 5, #27-01 housing/HDB availability/NotAvailable animal/Dexter animalType/current.Cat t/Urgent
- adds a fosterer named Jerry Tan with the following details:
add n/Pete Tay p/98765411 e/pete@example.com a/Happy street, block 5, #27-01 housing/Condo availability/Available animal/nil animalType/able.Cat
- adds a fosterer named Pete Tay with the following details:

In the case where duplicate field descriptions or values for HOUSING_TYPE, AVAILABILITY, ANIMAL_NAME and TYPE_OF_ANIMAL are given, the last one will be chosen:

add n/Jerry Tan p/98765412 e/jerry123@example.com a/Baker street, block 5, #27-01 housing/HDB housing/Condo availability/Available availability/NotAvailable animal/Dexter animal/Happy animalType/able.Dog animalType/current.Cat t/Urgent
- adds a fosterer named Jerry Tan, who lives in a Condo and is fostering a cat named Happy.

Adding a fosterer through the profile page: `add`

Redirects you to an empty profile page with all the fields set to nil. In the profile page, you can key in the fosterer’s details and save the information to add the fosterer to your address book.

Format: add

Notes about the command:

The restrictions imposed on what makes a valid fosterer, as explained in the section Adding a fosterer through the main page: add, still applies in this alternative way of adding a fosterer.

Here is the profile page you will see after entering add:

To learn more about the profile page, please refer to the section User Interface: The profile page.

Listing fosterers: `list` (Alias: `find`)

Lists fosterers in your address book that match a particular description or search, or all fosterers if the search is blank.

Format: list *KEYWORDS

Alias: find

Notes about the command:

The keywords are case-insensitive.
The order of the keywords does not matter. e.g. Hans Bo will match Bo Hans.
All fields are searched (including tags).
Your keywords can overlap. e.g. samm my will match Sammy.
Fosterers must match all keywords (i.e. AND search).
e.g. Hans Bo will return Hansbo Grahm, but not Hans Duo.
You can use double quotes " for exact, case-sensitive, word-level match.
e.g. "Tom" matches “Tom”, but not “Tommy”.
Symbols between keywords or sections will combine them according to the function of the symbol.

Symbol / Operator	Description	Precedence
`&`	Logical AND	lowest
`/`	Logical OR	low
’ ’ (space)	Logical AND	high
`(` and `)`	Parentheses for grouping	highest

e.g. a & b / c d is the same as a & (b / (c & d)).

Important:

For most fields, your keywords can match as parts of words.
e.g. john will match Johnny.

However, for the Housing and Availability fields, as well as for tags, your keywords must match the entire field.
e.g. available will not match NotAvailable.

Examples:

list
- lists all fosterers in your address book.

list john doe
- lists fosterers that match “John Doe”, “Doe John”, “Johnny Doe”, and “Mary” who lives on “John Doe Street”.

find john john doe
- is redundant and gives the same result as find john doe.

list "John" / zam & doe
- lists fosterers which match “John Doe” and “Doe Shazam”, but not “John Grahm”.

Viewing a fosterer’s detail: `view`

Redirects you to the profile page of the fosterer at the specified index of your currently displayed list.

Format: view INDEX

Parameters:

Parameter	About	Example
`INDEX`	- Index of a fosterer displayed in the list obtained from a `list`/`find` command - Index must be a positive integer	`1`, `2`, `3`

Important:

Only the save and exit commands are available to you in the profile page.

To learn more about profile page, please refer to the section User Interface: The profile page.

Examples:

list followed by view 2
- views the profile of the 2nd fosterer in your address book.

Editing a fosterer’s details through the main page: `edit`

Edits the details of the fosterer at the specified index in your currently displayed list, done through the main page.

Format: edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [housing/HOUSING_TYPE] [availability/AVAILABILITY] [animal/ANIMAL_NAME] [animalType/TYPE_OF_ANIMAL] [t/TAG…]

Parameters:

Parameter	About	Example
`INDEX`	- The index of a fosterer displayed in the list obtained from a `list`/`find` command - Index must be a positive integer	`1`, `2`, `3`
`NAME`	Updated name of the fosterer	`Alice Tan`, `Harry Yeo`
`PHONE_NUMBER`	Updated Phone number of the fosterer	`93456778`, `89067547`
`EMAIL`	Updated email of the fosterer	`thomas718@gmail.com`, `kate@yahoo.com.sg`
`ADDRESS`	Updated address of the fosterer	`Orchard road, Blk 8, #13-04`
`HOUSING_TYPE`	- Updated housing type of the fosterer - Case-sensitive - Can only take the values shown in the example column	`HDB`, `Condo`, `Landed`, `nil`
`AVAILABILITY`	- Updated availability of the fosterer - Case-sensitive - Can only take the values shown in the example column	`NotAvailable`, `Available`, `nil`
`ANIMAL_NAME`	Updated name of animal fostered	`Fluffball`, `nil`
`TYPE_OF_ANIMAL`	- Updated type of animal which the fosterer is currently fostering, or prefer to foster - Case-sensitive - Can only take the values shown in the example column	`current.Dog`, `current.Cat`, `able.Dog`, `able.Cat`, `nil`
`TAG`	Tag to be associated with the fosterer	`experienced`, `urgent`

Tip:

The index of the fosterer has to be provided. However, the number of parameters to be edited can vary from zero to all fields.

Important:

If the parameters are not provided, edit INDEX operates the same way as view INDEX, leading you to the profile page of the person at index INDEX in the address book.
If you run the same edit command multiple times consecutively (resulting in no visible change after the first run), the undo command will not be able to revert the data back to the original state.
This is because undo can only undo the last command, even if the command made no visible changes.

Examples:

find or list followed by edit 3 n/John
- edits the name of the 3rd fosterer in your address book to “John”.

find or list followed by edit 1 p/12345678 animal/Bobby
- edits the phone number and animal name of the 1st fosterer in your address book to “12345678” and “Bobby” respectively.

find or list followed by edit 2
- opens the profile page of the 2nd fosterer in your address book, since parameters are not provided.

Caution:

Edit for tags in the main page overwrites existing tags.
e.g. If the first fosterer has 2 tags : experienced and reliable, entering edit 1 t/goodWithCats will mean fosterer 1 will lose the experienced and reliable tags.

This is not a problem when editing using the profile page.

Editing a fosterer’s details through the profile page: `edit`

Edits the details of the fosterer at the specified index in your address book, by redirecting you to the profile page.

Format: edit INDEX

Parameters:

Parameter	About	Example
`INDEX`	- The index of a fosterer displayed in the list obtained from a `list`/`find` command - Index must be a positive integer	`1`, `2`, `3`

Notes about the command:

Apart from the details added by the add command, we also provide an optional notes feature in the profile page for more flexibility.

notes example

You can use this to include additional details such as:
- Health condition of the animal
- Foster period of the animal
- Identifiable physical traits of the animal

If you have at least one fosterer in your address book, here is an example of a profile page you will see after entering view 1 or edit 1:

To learn more about the profile page, please refer to the section User Interface: The profile page.

Saving changes in a fosterer’s details: `save`

Saves changes to details of the fosterer which you have made in the profile page.

Important:

This command only works in the profile page, which you can navigate to by executing the view command.

Format: save

Notes about the command:

Entering save in the profile of a new fosterer saves the new fosterer and exits the profile page.
Entering save in the profile of an already existing fosterer saves the changes but does not exit the profile page, allowing you to edit more details if needed.

Deleting a fosterer : `delete`

Deletes the fosterer at the specified index of your currently displayed list.

Format: delete INDEX [INDEX...]

Caution:

The index of a fosterer is not fixed. It is relative to the current list of fosterers you are handling.

Parameters:

Parameter	About	Example
`INDEX`	- The index of a fosterer displayed in the list obtained from a `list`/`find` command - At least one index must be provided - Index must be a positive integer	`1`, `2`, `3`

Tip:

You can delete multiple fosterers at once.

Each index needs to be separated by a white space.
Any duplicates and extra white spaces will be ignored.

Examples:

list followed by delete 2
- deletes the 2nd fosterer in your address book.

find Jerry or list Jerry, followed by delete 1
- deletes the 1st fosterer in the result list of your find / list query

list followed by delete 1 3 7
- deletes the 1st, 3rd and 7th fosterers in your address book.
In the example above, Alex, Bernice and Charlotte are the fosterers deleted.

list followed by delete 3 3 3 3
- deletes the 3rd fosterer in your address book.

Sorting fosterers: `sort`

Sorts your list of fosterers alphabetically by name, where uppercase letters come before lowercase letters (i.e. "annie tan" will be sorted behind "Jerry Tan").

Format: sort

Sort

Important:

Repeated sort commands will not result in additional changes to the address book, and undo will not be able to revert the data back to its original state.
This is because undo can only revert the last command, even if the command made no changes to the address book.

Viewing statistics of available fosterers : `stats avail`

Helps you calculate statistics about fosterers who are available to foster, and the animals they can foster. Percentages are calculated to 2 decimal places.

Format: stats avail

Notes about the command:

All statistic commands are calculated based on the list currently displayed in your address book.
In the example below, find available was first entered, resulting in a list of 2 available fosterers.
stats avail was then entered, and we see the resulting statistic reporting all listed fosterers as available.

Stats

Therefore, remember to use the find or list commands to get the list you want your statistics to be calculated from first, before using the statistic commands.

Examples:

list followed by stats avail
- calculates statistics of available fosterers, taking into account all fosterers in your address book.
In the example above, you have 6 fosterers in your address book, and 3 of them are available to foster.
find cat followed by stats avail
- calculates statistics of available fosterers, only taking into account fosterers who are either currently fostering a cat or are able to foster a cat.

Viewing statistics of current fosterers : `stats current`

Helps you calculate statistics about fosterers who are currently fostering, and the type of animals they are fostering. Percentages are calculated to 2 decimal places.

Format: stats current

Examples:

list followed by stats current
- calculates statistics of current fosterers, taking into account all fosterers in your address book.
In the example above, you have 6 fosterers in your address book, and 2 of them are currently fostering.
find dog followed by stats current
- calculates statistics of current fosterers, only taking into account fosterers who are either currently fostering a dog, or are able to foster a dog.

Viewing statistics of housing types: `stats housing`

Helps you calculate statistics about the various housing types of fosterers. Percentages are calculated to 2 decimal places.

Format: stats housing

Examples:

list followed by stats housing
- calculates housing statistics, taking into account all fosterers in your address book.
In the example above, out of the 6 fosterers in your address book, 3 live in HDBs, 1 live in a Condo, and 2 live in Landed properties.
find available followed by stats housing
- calculates housing statistics, only taking into account fosterers who are available.

Undoing the previous command : `undo`

Undoes your previous command, given that the previous command successfully executed is either add, delete, edit, sort or a successful execution of the reset command.

Format: undo

Notes about the command:

The undo command can only be executed once at a time, and it will undo your last successful command. When the undo command is executed consecutively more than once, an error message will be shown:

Clearing all entries : `reset`, followed by `reset confirm`

Clears all your fosterer entries from the address book.

Format: reset, followed by reset confirm

Notes about the command:

Upon entering reset, a confirmation message will be shown for the user to verify if he/she really wants to clear all the fosterer entries.
- User is prompted to enter reset confirm to confirm and execute the deletion of all fosterers.
- In the case where the user wishes to cancel the reset, he/she just has to proceed to type any other valid command in the command box.

Exiting Foster Family : `exit`

Exits the app.

Format: exit

Notes about the command:

On the profile page, entering exit leads you back to the main page, instead of exiting the app.

Please refer to User Interface: The profile page: Exiting the profile page for more information.

Saving data

In the main page, your Foster Family data is saved in the hard disk automatically after any command that changes the data, so no manual saving is needed. However, edits made in the profile page have to be saved via the save command. Else, changes will be discarded once you exit out of that fosterer’s profile page.

Editing data file

Your Foster Family data is saved automatically as a JSON file with the file path
[JAR file location]/data/addressbook.json.
A JSON file stores fosterer details as key value pairs, making it more readable than a regular text file.

In the example above, the “name” key is paired with a value “Alex Yeoh” for the first fosterer in your address book.
We strongly advise you to update the data file directly only if you are an advanced user.
Otherwise, we highly recommend you to perform edits using our user-friendly interface instead.

Caution:

If your changes to the data file makes its format invalid, Foster Family will discard all data and start with an empty data file at the next run. Hence, it is recommended to make a backup of the file before editing it.

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 Foster Family home folder.

Q: How do I know which version of Java I am using / have installed on my computer?
A: Open a command terminal, type java -version and press Enter. The Java version in use will be displayed as a response message.

Known Issues

If you are using multiple screens and you move the app to a secondary screen, a part of the GUI may appear “off-screen” if you later choose to switch back to your primary screen.
To resolve this, you can delete the preferences.json file that was created, before running the app again. This file is located in the same home folder as your jar file.

Command Summary

Action	Format	Examples
Help	`help`	-
Add from main page	`add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS housing/HOUSING_TYPE availability/AVAILABILITY animal/ANIMAL_NAME animalType/TYPE_OF_ANIMAL [t/TAG]…`	`add n/Jerry Tan p/98765412 e/jerry123@example.com a/Baker street, block 5, #27-01 housing/HDB availability/NotAvailable animal/Dexter animalType/current.Cat t/Urgent`
Add from profile page	`add`	-
List or Find	`list`, `find`	`list`, `find`, `list available`, `find available`
View Profile	`view INDEX`	`view 1`
Save updated fosterer details	`save`	-
Edit from main page	`edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [housing/HOUSING_TYPE] [availability/AVAILABILITY] [animal/ANIMAL_NAME] [animalType/TYPE_OF_ANIMAL] [t/TAG…]`	`edit 2 n/James Lee e/jameslee@example.com`
Edit from profile page	`edit INDEX`	`edit 1`
Delete	`delete INDEX [INDEX...]`	`delete 1 2 3`
Sort	`sort`	-
View Available Fosterer Statistics	`stats avail`	-
View Current Fosterer Statistics	`stats current`	-
View Housing Statistics	`stats housing`	-
Undo	`undo`	-
Clear all data entries	`reset`, followed by `reset confirm`	-
Exit from app / profile page	`exit`	-

Table of Contents

Quick Start

Useful Notations

Technical Terms

User Interface (UI)

The main page

The profile page

Opening the profile page

Navigating through fields

Saving changes

Exiting the profile page

Features

Viewing help for commands : help

Adding a fosterer through the main page: add

Adding a fosterer through the profile page: add

Listing fosterers: list (Alias: find)

Viewing a fosterer’s detail: view

Editing a fosterer’s details through the main page: edit

Editing a fosterer’s details through the profile page: edit

Saving changes in a fosterer’s details: save

Deleting a fosterer : delete

Sorting fosterers: sort

Viewing statistics of available fosterers : stats avail

Viewing statistics of current fosterers : stats current

Viewing statistics of housing types: stats housing

Undoing the previous command : undo

Clearing all entries : reset, followed by reset confirm

Exiting Foster Family : exit

Saving data

Editing data file

FAQ

Known Issues

Command Summary

Viewing help for commands : `help`

Adding a fosterer through the main page: `add`

Adding a fosterer through the profile page: `add`

Listing fosterers: `list` (Alias: `find`)

Viewing a fosterer’s detail: `view`

Editing a fosterer’s details through the main page: `edit`

Editing a fosterer’s details through the profile page: `edit`

Saving changes in a fosterer’s details: `save`

Deleting a fosterer : `delete`

Sorting fosterers: `sort`

Viewing statistics of available fosterers : `stats avail`

Viewing statistics of current fosterers : `stats current`

Viewing statistics of housing types: `stats housing`

Undoing the previous command : `undo`

Clearing all entries : `reset`, followed by `reset confirm`

Exiting Foster Family : `exit`