Skip to content

UserGuide.adoc

Latest commit

 

History

History
794 lines (553 loc) · 23.3 KB

UserGuide.adoc

File metadata and controls

794 lines (553 loc) · 23.3 KB
Raw

FOP Manager - User Guide

By: Team T08-4 Since: Jan 2019 Licence: MIT

1. Introduction

FOP Manager is a desktop Graphical User Interface (GUI) address book app, specifically designed for NUS Freshman Orientation Camp Organizers to manage the contact information of camp participants: both Orientation Group Leaders (OGLs) and Freshmen. It is optimized for those who prefer to work with a Command Line Interface (CLI). If you can type fast, FOP Manager can get your contact management tasks done faster than traditional GUI apps.

Interested? Hurry, jump to Quick Start to get started!

2. About User Guide

This user guide shows you how to get started with FOP Manager. It introduces you to the features of FOP Manager and provides you with examples, that you will become an expert user in no time!

Throughout this user guide, there will be various icons used, as shown below:

💡
 This is a tip. Following these suggestions will make using FOP Manager much simpler!
ℹ️
 This is a note. Read these for additional information.
⚠️
 This is a warning. Make sure to heed the warnings for FOP Manager to work smoothly!

3. Quick Start

This section serves as a tutorial for a new user to FOP Manager.

3.1. Installation

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

  2. Download the latest fop_manager.jar here.

  3. Copy the file to the folder you want to use as the home folder for FOP Manager.

  4. Double-click the file to start the app. The GUI should appear in a few seconds and will look like this:

    Ui

3.2. Introducing the Interface

UiLabelledParts

  1. Undo List: This list displays all undoable commands executed since the app was started.

  2. Redo List: This list displays all redoable commands executed since the app was started.

  3. Participant List: This panel shows a list of all the participants and their information you have stored so far.

  4. Result Box: The result box displays the result to the commands you input.

  5. Command Box: The command box is where all commands should be typed in.

3.3. Try It Out!

Now that you understand the app’s interface, you can now try keying in commands to interact with FOP Manager.

ℹ️
 Type the command in the command box and press Enter to execute it.
e.g. typing help and pressing Enter opens the help window.

Some example commands you can try:

  • list : lists all contacts

  • add_o n/John Doe s/M b/27071999 p/98765432 e/johnd@example.com m/Information Systems g/ : adds an OGL named John Doe to your contact list

  • add_h Red : adds a House named Red

  • add_g R1 Red : adds a Group named R1 to the House Red

  • delete 3 : deletes the 3rd contact shown in the current list

  • exit : exits the app

Refer to Features for details of each command.

4. Features

This section tells you about the features available in FOP Manager.

Command Format

  • Words in UPPER_CASE are parameters to be supplied by the user
    e.g. if the command states n/NAME, NAME is a parameter which can be used as 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 as many times as you want
    e.g. [t/TAG]…​ can be used as   (i.e. 0 times), t/friend, t/friend t/family etc.

4.1. Viewing help : help

Opens a window with a list of all the commands available on FOP Manager
Format: help

4.2. Add Commands

4.2.1. Adding a freshman : add_f

Adds a freshman to the Freshman list
Format: add_f n/NAME s/SEX b/BIRTHDAY p/PHONE e/EMAIL m/MAJOR g/GROUP [t/TAG]…​

  • Parameters can be accepted in any order.

  • A freshman can have any number of tags (including 0).

💡
 GROUP can be left blank i.e. g/
⚠️
 If not blank, the GROUP must exist before a freshman can be added to it

Examples:

  • add_f n/John Doe s/M b/27071999 p/98765432 e/johnd@example.com m/Information Systems g/

  • add_f n/Jane Doe s/F e/betsycrowe@example.com m/CS g/ p/1234567 t/vegetarian

4.2.2. Adding an OGL : add_o

Adds an OGL to the OGL list
Format: add_o n/NAME s/SEX b/BIRTHDAY p/PHONE e/EMAIL m/MAJOR g/GROUP [t/TAG]…​

  • Parameters can be accepted in any order.

  • An OGL can have any number of tags (including 0).

💡
 GROUP can be left blank i.e. g/
⚠️
 If not blank, the GROUP must exist before an OGL can be added to it

Example:

  • add_o n/James Boe s/M b/27071999 p/13579753 e/jamesd@example.com m/CEG g/

  • add_o n/Jane Doe s/F e/betsycrowe@example.com m/CS g/ p/1234567 t/vegetarian

4.2.3. Adding other participants : add

Adds other participants involved in the camp that are neither Freshmen nor OGLs to the contact list
Format: add n/NAME s/SEX b/BIRTHDAY p/PHONE e/EMAIL m/MAJOR g/GROUP [t/TAG]…​

  • Parameters can be accepted in any order.

  • An entered participant can have any number of tags (including 0).

💡
 Leave GROUP blank i.e. g/ since there is no group allocation for this participant!

Example:

  • add n/James Boe s/M b/27071999 p/13579753 e/jamesd@example.com m/CEG g/ t/Camp Commandant

4.2.4. Adding a house : add_h

Adds a house that can contain different groups
Format: add_h HOUSENAME

ℹ️
 House names are always saved with first letter in Uppercase, the rest in lowercase
ℹ️
 House names cannot contain spaces

Example:

  • add_h blue saves a house named Blue to the house list.

4.2.5. Adding a group : add_g

Adds a group to a house
Format: add_g GROUPNAME HOUSENAME

ℹ️
 Group names are always saved in all-caps
ℹ️
 Group names cannot contain spaces
⚠️
 Groups can only be added to houses that already exist

Example:

  • add_g b1 blue saves a group named B1 in house Blue to the group list.

4.3. Edit Commands

4.3.1. Editing a participant : edit

Edits an existing participant in the contact list.
Format: edit INDEX [n/NAME] [p/PHONE] [m/MAJOR] [g/GROUP] [t/TAG] …​

  • Edits the participant currently shown at INDEX.

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

  • Existing values will be updated to the input values.

  • When editing tags, the existing tags of the participant will be removed i.e adding of tags is not cumulative.

⚠️
 INDEX must be a positive integer: 1, 2, 3, …​
💡
 To edit a particular participant by name, first find the participant by name, then edit by index
💡
 Remove all the participant’s tags by typing t/ without specifying any tags after it
💡
 Edit a participant’s GROUP after adding them, instead of choosing a group for them from the start

Examples:

  • edit 1 p/91234567 g/g1
    Edits the phone number and group of the participant at index 1 to be 91234567 and G1 respectively.

  • edit 2 n/John Koe t/
    Edits the name of the participant at index 2 to be John Koe and clears all existing tags.

4.3.2. Editing a house : edit_h

Edits a house name.
Format: edit_h OLDHOUSENAME NEWHOUSENAME

  • Edits the house named OLDHOUSENAME to NEWHOUSENAME

  • All groups under the old house name remain in the new house.

⚠️
 OLDHOUSENAME must exist in the current list of houses
⚠️
 NEWHOUSENAME must not exist in the current list of houses
💡
 House names are not case-sensitive

Example:

  • edit_h Red green
    Edits the house named Red to Green.

4.3.3. Editing a group : edit_g

Edits a group name.
Format: edit_g OLDGROUPNAME NEWGROUPNAME

  • Edits the group named OLDGROUPNAME to NEWGROUPNAME

  • The GROUP of all participants within the old group is automatically updated.

⚠️
 OLDGROUPNAME must exist in the current list of groups
⚠️
 NEWGROUPNAME must not exist in the current list of groups
ℹ️
 Group names are not case-sensitive

Example:

  • edit_g red1 red2
    Edits the group named RED1 to RED2. All participants in RED1 are now in RED2.

4.4. List Commands

4.4.1. Listing all the participants : list

Shows a list of all the participants involved in the camp in your contact list.
Format: list

4.4.2. Listing all freshmen : list_f

Shows a list of all the freshmen in the freshmen list.
Format: list_f

4.4.3. Listing all OGLs : list_o

Shows a list of all the OGLs in the OGL list.
Format: list_o

4.4.4. Listing all group participants : list_g

Shows a list of all the participants in a group.
Format: list_g GROUPNAME

ℹ️
 Group names are not case-sensitive
💡
 list_g empty lists participants with an empty group field
⚠️
 OLDGROUPNAME must exist in the current list of groups

Examples:

  • list_g g1 lists all participants in Group G1 if G1 exists.

  • list_g empty lists all participants not in any group yet.

4.5. View Commands

4.5.1. Viewing all houses : view_h

Views the list of all houses added so far.
Format: view_h

Example:

  • Houses Orange and Blue have been added.
    view_h returns [Orange, Blue].

4.5.2. Viewing all groups : view_g

Views the list of all groups added so far, along with the house they belong to.
Format: view_g

Example:

  • Groups R1 and R2 have been added under the house Red.
    view_g returns [(R1, Red), (R2, Red)].

4.6. Delete Commands

4.6.1. Deleting a participant : delete

Deletes the specified participant from your contact list.
Format: delete INDEX

  • Deletes the participant at the specified INDEX.

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

⚠️
 The index must be a positive integer: 1, 2, 3, …​

Examples:

  • list has just been entered.
    delete 2 deletes the participant at index 2.

  • find Betsy has just been entered.
    delete 1 deletes the participant at index 2 in the results of the find command.

4.6.2. Deleting a group : delete_g

Deletes the specified group from the list of groups.
Format: delete_g GROUPNAME

  • Deletes the group matching the specified GROUPNAME.

  • GROUPNAME must exist in the list of groups.

⚠️
 The group must contain no participants before it can be deleted
ℹ️
 Group names are not case-sensitive

Examples:

  • Group G1 has just been added under house Green.
    delete_g G1 removes the group G1 from the list of groups.

  • list_g y1 shows only one participant in Group Y1.
    edit 1 g/ removes the participant from the group.
    delete_g Y1 removes the group Y1 from the list of groups.

4.6.3. Deleting a house : delete_h

Deletes the specified house from the list of houses.
Format: delete_h HOUSENAME

  • Deletes the house matching the specified HOUSENAME.

  • HOUSENAME must exist in the list of hosues.

⚠️
 The house must contain no groups before it can be deleted.
ℹ️
 House names are not case-sensitive

Examples:

  • A house named Blue has just been added.
    delete_h blue deletes the house Blue.

  • view_g shows only 1 group R1 in the house Red.
    Group R1 is deleted by first removing its participants from the group, then entering delete_g R1.
    delete_h RED deletes the house Red.

4.7. Displaying the camp size: size

Displays the total number of participants, the number of OGLs and freshmen, and the number of houses and groups in the command result box.
Format: size

4.8. Finding participants by name: find

Finds participants 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. John Poe will match Poe John

  • Only name is searched.

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

  • Participants 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 Goe

  • find Betsy Tim John returns any participant having names Betsy, Tim, or John

4.9. Selecting a participant : select

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

  • Selects the participant at the specified INDEX.

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

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

Examples:

  • list has just been entered.
    select 2 selects the participant at index 2 in your contact list.

  • find Betsy has just been entered.
    select 1 selects the participant at index 1 in the results of the find command.

4.10. 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.11. Undoing previous command : undo

Restores your contact list to the state before the previous undoable command was executed.
Format: undo

ℹ️
 Undoable commands are commands that modify your contact list’s content (add, delete, edit and clear).
💡
 Undoable commands are shown in the undo list.

Examples:

  • delete 1 has just been entered.
    undo reverses the delete 1 command

  • Only select 1 has been entered.
    undo fails as there are no undoable commands executed previously.

  • delete 1 and clear have been entered.
    undo reverses the clear command.
    undo reverses the delete 1 command.

4.12. Redoing previously undone command : redo

Reverses the most recent undo command.
Format: redo

💡
 Redoable commands are shown in the redo list.

Examples:

  • delete 1 has just been entered.
    undo reverses the delete 1 command.
    redo reapplies the delete 1 command.

  • Only delete 1 has been entered.
    redo fails as there are no undo commands executed previously.

  • delete 1 and clear have just been entered.
    undo reverses the clear command.
    undo reverses the delete 1 command.
    redo reapplies the delete 1 command.
    redo reapplies the clear command.

4.13. Randomizing groupings : randomize

Randomize group allocation of all registered participants.
Format: randomize

ℹ️
 Command will only work under the following conditions:
- At least 2 groups created
- Number of OGLs must be more than number of groups
- At least 2 participants registered

Examples:

  • randomize
    Successful Output:

randomize success

  • randomize.
    Error Output:

randomize fail

4.14. Show camp participants' statistic: stat

Show the camp participants' statistic base on age, major and sex in the form of pie charts

Format: stat

⚠️
 This command will not work if there are no participant inside the application.

Examples:

  • add_o n/John Doe s/M b/27071999 p/98765432 e/johnd@example.com m/Information System g/

  • add_o n/Joh Doe s/F b/27071998 p/98765432 e/johnd@example.com m/ceg g/

  • add_o n/John s/M b/27071995 p/98765432 e/johnd@example.com m/Information System g/

  • add_o n/Doe s/M b/27071999 p/98765432 e/johnd@example.com m/cs g/
    Add some sample data to the application

  • stat
    The output is shown below:

StatCommandExample

4.15. Save statistic pie charts to images: save_c

Save the pie charts generated by the stat command to image files

Format: save_c [FILE NAME]

⚠️
 This command will not work if there are no participant inside the application.
💡
 This command only save the most recently generated charts. Use the stat command before this command to avoid outdated or empty charts.

Examples:

  • stat

  • save_c For NUS
    Save the charts to image files with the name "For NUS"

4.16. Export Commands

4.16.1. Exporting the whole contact list : export

Exports all entries from your contact list to Excel Spreadsheet.
Format: export

  • Excel Spreadsheet name is FOP_MANAGER_LIST.xls.

  • Excel Spreadsheet will be saved in the current User Directory.

Entering the export commands will result in an Excel Spreadsheet in the current User Directory. As shown below.

ExportImage

The Excel Spreadsheet will look like this:

ExportResult
⚠️
 Save and close the Excel file before exporting.

There are other export commands to produce a spreadsheet for Freshmen and OGL lists as shown in the next two sections.
The name of the file will change accordingly, however, the location is the same.

4.16.2. Exporting only the Freshmen in the contact list : export_f

Exports all the Freshmen entries from your contact list to Excel Spreadsheet.
Format: export_f

  • Excel Spreadsheet name is FOP_MANAGER_FRESHMEN_LIST.xls.

  • Excel Spreadsheet will be saved in the current User Directory.

⚠️
 Save and close the Excel file before exporting.

4.16.3. Exporting only the OGLs in the contact list : export_o

Exports all the OGL entries from your contact list to Excel Spreadsheet.
Format: export_o

  • Excel Spreadsheet name is FOP_MANAGER_OGL_LIST.xls.

  • Excel Spreadsheet will be saved in the current User Directory.

⚠️
 Save and close the Excel file before exporting.

4.17. Importing contact list : import

Imports contact list from an Excel Spreadsheet into the FOP Manager.
Format: import

  • The Excel Spreadsheet should have the headings in the order NAME, SEX, BIRTHDAY, PHONE, EMAIL, MAJOR, GROUP and then TAG.

  • Entries in the NAME, SEX, BIRTHDAY, PHONE, EMAIL, MAJOR and TAG columns have to be non-null.

  • Only the non-duplicate contacts are added.

  • If we want to edit the contacts found in the FOP Manager via excel, we should clear the FOP Manager and then import.

⚠️
 Spreadsheet name has to be FOP_MANAGER_LIST.xls and it has to be located at the current User Directory.
The values entered under each respective columns, have to follow the format of the the add command.
The TAG column cannot be empty. If you want it to be empty, put a white space.
Save and close the Excel file before importing.

4.18. Clearing all entries : clear

Clears all entries from your contact list.
Format: clear

4.19. Exiting the program : exit

Exits the program.
Format: exit

4.20. Saving the data

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

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

Participants data will be auto-encrypted when the app closes, so that data files cannot be accessed when the app is not running.
Participant data will be decrypted when the app starts up.

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 FOP Manager folder.

6. Command Summary

Congratulations, you are now ready to start your journey with FOP Manager!

Below is a summary of all commands available in FOP Manager:

Command Purpose Example Reference

help

Views help

help

Viewing help

add_f

Adds a freshman

add_f n/NAME s/SEX b/BIRTHDAY p/PHONE e/EMAIL m/MAJOR g/GROUP [t/TAG]…​

Adding a freshman

add_o

Adds an OGL

add_o n/NAME s/SEX b/BIRTHDAY p/PHONE e/EMAIL m/MAJOR g/GROUP [t/TAG]…​

Adding an OGL

add

Adds a participant

add n/NAME s/SEX b/BIRTHDAY p/PHONE e/EMAIL m/MAJOR g/GROUP [t/TAG]…​

Adding a participant

add_h

Adds a house

add_h HOUSENAME

Adding a house

add_g

Adds a group

add_g GROUPNAME HOUSENAME

Adding a group

edit

Edits participant at INDEX

edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [m/MAJOR] [g/GROUP] [t/TAG]…​

Editing a Participant

edit_h

Edits an existing house’s name

edit_h OLDHOUSENAME NEWHOUSENAME

Editing a house

edit_g

Edits an existing group’s name

edit_g OLDGROUPNAME NEWGROUPNAME

Editing a group

list

Lists all participants in contact list

list

Listing all participants

list_f

Lists all freshmen in contact list

list_f

Listing all freshmen

list_o

Lists all OGLs in contact list

list_o

Listing all OGLs

list_g

Lists all participants in a particular group

list_g GROUPNAME

Listing all group participants

view_h

Views all houses in house list

view_h

Viewing all houses

view_g

Views all groups in group list

view_g

Viewing all groups

delete

Deletes participant at INDEX

delete INDEX

Deleting a participant

delete_g

Deletes a group

delete_g GROUPNAME

Deleting a group

delete_h

Deletes a house

delete_h HOUSENAME

Deleting a participant

size

Displays the number of participants, OGLs, freshmen, houses and groups

size

Displaying camp size

find

Finds participants by name

find KEYWORD [MORE_KEYWORDS]

Finding participants by name

select

Selects participant at INDEX

select INDEX

Selecting a participant

history

Lists all previously entered commands

history

Listing entered comamnds

undo

Undoes previous command

undo

Undoing previous command

redo

Redoes previously undone command

redo

Redoing previously undone command

randomize

Randomizes group allocation

randomize

Randomizing groupings

stat

Show participants statistic

stat

Show camp participants' statistic

save_c

Save charts to images

save_c [FILE NAME]

Save statistic pie charts to images

export

Exports contact list

export

Exporting whole contact list

export_f

Exports freshmen contact list

export_f

Exporting freshmen contact list

export_o

Exports OGL contact list

export_o

Exporting OGL contact list

import

Imports contacts

import

Importing contact list from Excel Spreadsheet

clear

Clears contact list

clear

Clearing all entries

exit

Exits program

exit

Exiting the program