diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 029f291ad10..9d5f6d4ae6b 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -6,7 +6,16 @@ # KonTActs User Guide -konTActs is a **desktop app for managing contacts, optimized for use via a Command Line Interface** (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, konTActs can get your contact management tasks done faster than traditional GUI apps. +KonTActs is a **desktop app for managing your contacts, optimized for use via a Command Line Interface** (CLI) while still having the benefits of a Graphical User Interface (GUI). + +KonTActs streamlines contact management, helping you keep track of students, professors, and fellow TAs more effectively than traditional GUI apps. + + + + + + + @@ -15,57 +24,102 @@ konTActs is a **desktop app for managing contacts, optimized for use via a Comma ## Quick start +To get started, + 1. Ensure you have Java `17` or above installed in your Computer. Refer [here](https://nus-cs2103-ay2425s1.github.io/website/admin/programmingLanguages.html) for the specific version. -1. Download the latest `.jar` file from [here](https://github.com/AY2425S1-CS2103T-T11-2/tp/releases). +2. Download the latest `.jar` file from [here](https://github.com/AY2425S1-CS2103T-T11-2/tp/releases). -1. Copy the file to the folder you want to use as the _home folder_ for your AddressBook. +3. Copy the file to the folder you want to use as the _home folder_ for KonTActs. -1. Open a command terminal, `cd` into the folder you put the jar file in, and use the `java -jar addressbook.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.
- ![Ui](images/loadingPageOfUi.png) +4. Open a command terminal, `cd` into _home folder_ you put the jar file in, and enter `java -jar KonTActs.jar` to run the application and type `view name/Alex Yeoh`.
+ A interface similar to the one below should appear in a few seconds. Note how the app contains some sample data.
+ ![quick start GUI on launch](images/quickStartLaunchScreenshot.png) -1. 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.
+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. + * `list` : Lists all contacts. - * `add n/James Ho e/jamesho@example.com telegram/@James t/friend t/colleague github/james-cool` : Adds a contact named `James Ho` to the Address Book. + * `mark name/Alex Yeoh week/0` : Marks `Alex Yeoh` attendance in KonTActs. - * `delete n/James Ho` : Deletes the contact with name `James Ho` if it is shown in the current list. + * `delete name/Bernice Yu` : Deletes `Bernice Yu` from KonTActs. - * `clear` : Deletes all contacts. + * `addGrade name/Alex Yeoh assignment/Ex01 score/9` : Assigns and adds `Ex01` with a score of 9 to `Alex Yeoh`. - * `exit` : Exits the app. + * The GUI should now look something like this.
+ ![quick start GUI after commands](images/quickStartResultScreenshot.png) -1. Refer to the [Features](#features) below for details of each command. + * `clear` : Deletes all contacts. + +6. Refer to the [Features](#features) below for details of each command.

-------------------------------------------------------------------------------------------------------------------- ## Summary of commands -| Action | Format, Examples | -|-----------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [**Add**](#adding-a-person-add) | `add n/NAME e/EMAIL telegram/TELEGRAM [t/TAG]…​ github/GITHUB`
e.g., `add n/James Ho e/jamesho@example.com telegram/@James t/friend t/colleague github/james-cool` | -| [**Clear**](#clearing-all-entries-clear) | `clear` | -| [**Delete**](#deleting-a-person-delete) | `delete n/NAME`
e.g., `delete n/James` | -| [**Edit**](#editing-a-person-edit) | `edit INDEX [n/NAME] [e/EMAIL] [telegram/TELEGRAM] [t/TAG]…​ [github/GITHUB]`
e.g.,`edit 2 n/James Lee e/jameslee@example.com` | -| [**Find**](#finding-persons-by-name-find) | `find KEYWORD [MORE_KEYWORDS]`
e.g., `find James Jake` | -| [**Filter**](#filtering-persons-by-tag-filter) | `filter t/[TAG] t/[MORE_TAG]…​`
e.g., `filter t/friends t/family` | -| [**List**](#listing-all-persons-list) | `list` | -| [**Help**](#viewing-help-help) | `help` | -| [**View**](#viewing-a-contact-s-full-details-view) | `view [n/NAME]`
e.g., `view n/John Doe` | -| [**Github**](#launching-github-repository-github) | `github n/NAME`
e.g., `github n/Harry` | -| [**Mark**](#marking-a-student-as-present-mark) | `mark n/NAME w/WEEK NUMBER`
e.g. `mark n/John Doe w/1` | -| [**Unmark**](#unmarking-a-student-as-present-unmark) | `unmark n/NAME w/WEEK NUMBER`
e.g. `unmark n/John Doe w/1` | -| [**Sort**](#sorting-the-displayed-list-sort) | `sort FIELD order/ORDER`
e.g. `sort name order/asc` | -| [**Import**](#importing-data-from-csv-file-import) | `import path/CSV FILE PATH`
e.g `import path/user/data/xxx.csv` | -| [**Export**](#exporting-data-into-csv-file-export) | `export path/DESIRED FILE DESTINATION`
e.g `export path/user/data/xxx.csv` | -| [**Command History**](#accessing-command-history-and) | ↑ and ↓ |## Features -| [**Add grade**](#adding-grades-to-a-contact-addgrade) | `addGrade n/NAME asgn/ASSIGNMENT_NAME s/SCORE`
e.g. `addGrade n/JohnDoe asgn/Ex01 s/5` | -| [**Remove grade**](#removing-grades-from-a-contact-removegrade) | `removeGrade n/NAME asgn/ASSIGNMENT_NAME`
e.g. `removeGrade n/John Doe asgn/Ex01` | - -

+| Action | Format, Examples | +|-----------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**Add**](#adding-a-person-add) | `add name/NAME email/EMAIL telegram/TELEGRAM [tag/TAG]…​ github/GITHUB`
e.g., `add name/James Ho email/jamesho@example.com telegram/@James tag/friend tag/colleague github/james-cool` | +| [**Clear**](#clearing-all-entries-clear) | `clear` | +| [**Delete**](#deleting-a-person-delete) | `delete name/NAME`
e.g., `delete name/James` | +| [**Edit**](#editing-a-person-edit) | `edit INDEX [name/NAME] [email/EMAIL] [telegram/TELEGRAM] [tag/TAG]…​ [github/GITHUB]`
e.g.,`edit 2 name/James Lee email/jameslee@example.com` | +| [**Find**](#finding-persons-by-name-find) | `find KEYWORD [MORE_KEYWORDS]`
e.g., `find James Jake` | +| [**Filter**](#filtering-persons-by-tag-filter) | `filter tag/[TAG] tag/[MORE_TAG]…​`
e.g., `filter tag/friends tag/family` | +| [**List**](#listing-all-persons-list) | `list` | +| [**Help**](#viewing-help-help) | `help` | +| [**View**](#viewing-a-contact-s-full-details-view) | `view [name/NAME]`
e.g., `view name/John Doe` | +| [**Github**](#launching-github-repository-github) | `github name/NAME`
e.g., `github name/Harry` | +| [**Mark**](#marking-a-student-as-present-mark) | `mark name/NAME week/WEEK NUMBER`
e.g. `mark name/John Doe week/1` | +| [**Unmark**](#unmarking-a-student-as-present-unmark) | `unmark name/NAME week/WEEK NUMBER`
e.g. `unmark name/John Doe week/1` | +| [**Sort**](#sorting-the-displayed-list-sort) | `sort FIELD order/ORDER`
e.g. `sort name order/asc` | +| [**Import**](#importing-data-from-csv-file-import) | `import path/CSV FILE PATH`
e.g `import path/user/data/xxx.csv` | +| [**Export**](#exporting-data-into-csv-file-export) | `export path/DESIRED FILE DESTINATION`
e.g `export path/user/data/xxx.csv` | +| [**Command History**](#accessing-command-history-and) | ↑ and ↓ |## Features +| [**Add grade**](#adding-grades-to-a-contact-addgrade) | `addGrade name/NAME assignment/ASSIGNMENT_NAME score/SCORE`
e.g. `addGrade n/JohnDoe assignment/Ex01 score/5` | +| [**Remove grade**](#removing-grades-from-a-contact-removegrade) | `removeGrade name/NAME assignment/ASSIGNMENT_NAME`
e.g. `removeGrade name/John Doe assignment/Ex01` | + +-------------------------------------------------------------------------------------------------------------------- +## Parameter shortcuts + +All parameters in KonTActs come equipped with their equivalent shortcuts. + +| Parameter | Shortcut | +|---------------|----------| +| `name/` | `n/` | +| `email/` | `e/` | +| `tag/` | `t/` | +| `assignment/` | `a/` | +| `score/` | `s/` | +| `telegram/` | `tele/` | +| `github/` | `g/` | +| `week/` | `w/` | +| `order/` | `o/` | +| `path/` | `p/` | + +-------------------------------------------------------------------------------------------------------------------- + +-------------------------------------------------------------------------------------------------------------------- +## Command shortcuts + +All commands in KonTActs come equipped with their equivalent shortcuts. + +| Command | Shortcut | +|---------------|----------| +| `mark` | `m` | +| `unmark` | `um` | +| `import` | `im` | +| `export` | `ex` | +| `find` | `fd` | +| `filter` | `f` | +| `view` | `v` | +| `addGrade` | `ag` | +| `removeGrade` | `rg` | +| `delete` | `rm` | +| `edit` | `e` | +| `GitHub` | `git` | + +-------------------------------------------------------------------------------------------------------------------- ## Features @@ -73,19 +127,19 @@ konTActs is a **desktop app for managing contacts, optimized for use via a Comma **Notes about the 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`. +* Words in `UPPER_CASE` are the parameters supplied by you.
+ e.g. `add name/NAME`, `NAME` is a parameter which can be used as `add name/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`. + e.g `name/NAME [tag/TAG]` can be used as `name/John Doe tag/friend` or as `name/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. + e.g. `[tag/TAG]…​` can be used as ` ` (i.e. 0 times), `tag/friend`, `tag/friend tag/family` etc. * Parameters can be in any order.
- e.g. if the command specifies `n/NAME telegram/TELEGRAM`, `telegram/TELEGRAM n/NAME` is also acceptable. + e.g. if the command specifies `name/NAME telegram/TELEGRAM`, `telegram/TELEGRAM name/NAME` is also acceptable. -* Extraneous parameters for commands that do not take in parameters (such as `help`, `list`, `exit` and `clear`) will be ignored.
+* Extra parameters for commands that do not take in parameters (such as `help`, `list`, `exit` and `clear`) 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 application. @@ -112,12 +166,34 @@ A compact reference guide is also provided for quick reference. -------------------------------------------------------------------------------------------------------------------- ### Adding a person: `add` -Adds a person to KonTActs. +Adds a person's contact detail to KonTActs. + + + +**Format: `add name/NAME email/EMAIL telegram/TELEGRAM [tag/TAG]…​ github/GITHUB`**
+ -**Format: `add n/NAME e/EMAIL telegram/TELEGRAM [t/TAG]…​ github/GITHUB`** +**Shortcut: `add n/NAME e/EMAIL tele/TELEGRAM [t/TAG]…​ g/GITHUB`** + + + +**Email restrictions** +Emails should be of the format `local-part@domain` and adhere to the following constraints: +1. `local-part` should only contain alphanumeric characters and `+`, `_` , `.` , `-`. +2. `local-part` may not start or end with any special characters. +3. This is followed by an `@` and then a `domain` name. The domain name is made up of domain labels separated by periods. +The `domain name` must: + - end with a domain label at least 2 characters long + - have each domain label start and end with alphanumeric characters + - have each domain label consist of alphanumeric characters, separated only by hyphens, if any. + +Eg. `t/friend t/family` + + + A person can have any number of tags (including 0) @@ -127,11 +203,18 @@ A person can have any number of tags (including 0) **Tag restrictions** * Tags must be a single word containing only alphanumeric characters (no spaces or special symbols are allowed). -* To specify multiple tags, separate each tag with a space. +* To specify multiple tags, separate each tag parameter with a space. + +Eg. `t/friend t/family` + + +**Telegram username restrictions** +* Usernames must start with an `@`, and can only contain underscores (`_`) and alphanumeric characters. + **GitHub username restrictions** @@ -179,7 +262,12 @@ Edits an existing person detail in KonTActs. -**Format: `edit INDEX [n/NAME] [e/EMAIL] [telegram/TELEGRAM] [t/TAG]…​ [github/GITHUB]`** +**Format: `edit INDEX [name/NAME] [email/EMAIL] [telegram/TELEGRAM] [tag/TAG]…​ [github/GITHUB]`** + + + + +**Shortcut: `e INDEX [n/NAME] [e/EMAIL] [tele/TELEGRAM] [t/TAG]…​ [g/GITHUB]`** @@ -213,6 +301,13 @@ Find all persons whose names contains any of the given keywords. **Format: `find KEYWORD [MORE_KEYWORDS]`** + + + +**Shortcut: `f KEYWORD [MORE_KEYWORDS]`** + + + * The search is case-insensitive. e.g `hans` will match `Hans` @@ -239,12 +334,17 @@ Finds persons whose names contain any of the given tag keywords. -**Format: `filter t/TAG [t/MORE_TAG]...`** +**Format: `filter tag/TAG [tag/MORE_TAG]...`** + + + + +**Shortcut: `f t/TAG [t/MORE_TAG]...`** -* The search is case-sensitive. e.g `friends` will not match `Friends` +* The search is case-insensitive. e.g `friends` will match `Friends` * At least one tag must be provided. * The order of the keywords does not matter. e.g. `t/friends t/family` will match `t/family t/friends` * Only the tags is searched. @@ -268,7 +368,12 @@ Deletes the specified person from the address book. -**Format: `delete n/NAME`** +**Format: `delete name/NAME`** + + + + +**Shortcut: `rm n/NAME`** @@ -294,7 +399,12 @@ Launches GitHub repository of the specified person on the browser from the addre -**Format: `github n/NAME`** +**Format: `github name/NAME`** + + + + +**Shortcut: `git n/NAME`** @@ -320,12 +430,17 @@ Opens a window at the side with the full details of the specified person from th -**Format: `view [n/NAME]`** +**Format: `view [name/NAME]`** + + + + +**Shortcut: `v [n/NAME]`** -* View the full details of the selected contact. +* View the full details of the contact you specify. * `NAME` refers to the full name of the person shown in the displayed person list. * Calling `view` without any name parameter closes any windows previously opened by `view`. @@ -347,25 +462,22 @@ Marks a student as present for a particular week. -**Format: `mark n/NAME w/[WEEK_NUMBER]`** -**Format: `mark n/NAME week/[WEEK_NUMBER]`** +**Format: `mark name/NAME week/[WEEK_NUMBER]`** + + + + +**Shortcut: `m n/NAME w/[WEEK_NUMBER]`** * Marks the particular student as present in that week. -* The full name and week number is compulsory. -* The name is case-sensitive. -* The field for `week` can be written as `week/` or `w/` -* The range of the WEEK_NUMBER is between 0 and 13, both inclusive. Rationale being there are 13 weeks per semester. +* The full name and week number is **compulsory**. +* The name is **case-sensitive**. +* The range of the WEEK_NUMBER is between 0 and 13, both inclusive. Rationale being there are 14 weeks per semester. - - -The update of the attendance will only be seen when [`view`](#viewing-a-contact-s-full-details-view) command is executed. - - - **Examples:** @@ -387,19 +499,17 @@ Unmarks a student as present for a particular week. - + -* Unmarks the particular student as present in that week. -* The full name and week number is compulsory. -* The name is case-sensitive. -* The field for `week` can be written as `week/` or `w/` -* The range of the WEEK_NUMBER is between 0 and 13, both inclusive. Rationale being there are 13 weeks per semester. +**Shortcut: `um n/NAME w/[WEEK_NUMBER]`** - - -The update of the attendance will only be seen when [`view`](#viewing-a-contact-s-full-details-view) command is executed. + +* Unmarks the particular student as present in that week. +* The full name and week number is **compulsory**. +* The name is **case-sensitive**. +* The range of the WEEK_NUMBER is between 0 and 13, both inclusive. Rationale being there are 14 weeks per semester. @@ -417,20 +527,24 @@ The update of the attendance will only be seen when [`view`](#viewing-a-contact- Sorts the displayed list based on the given field and order. - **Format: `sort FIELD order/ORDER`** **Reset Format: `sort reset`** + + +Order of contact details can be reset to default by calling `sort reset`. + + -* Current FIELD that can be sorted by: `github`, `name`, `telegram`. -* Current ORDER that is accepted: `asc`, `desc`. -* The sort order will persist between commands. +* `FIELD` that can be sorted by: `github`, `name`, `telegram`. +* `ORDER` that is accepted: `asc`, `desc`. +* The sort order persists between commands. * The sort order will reset when `sort reset` command is given. -* The sorting is case-insensitive: upper and lower case are treated as the same values. +* The sorting is **case-insensitive**: upper and lower case are treated as the same values. @@ -449,7 +563,7 @@ Sorts the displayed list based on the given field and order. ### Clearing all entries : `clear` -Clears all entries from the address book. +Clears all entries from the KonTActs. @@ -458,7 +572,7 @@ Clears all entries from the address book. -------------------------------------------------------------------------------------------------------------------- -### Importing data from CSV file `import` +### Importing data from CSV file : `import` Imports contacts based on CSV file. Importing a file will replace ALL existing contacts @@ -467,6 +581,11 @@ Imports contacts based on CSV file. Importing a file will replace ALL existing c **Format: `import path/CSV_FILE_PATH`** + + +**Shortcut: `im p/CSV_FILE_PATH`** + + * File path can be relative or absolute, but must end with .csv @@ -521,7 +640,7 @@ assignments are present for a person, separate them within the same entry using -------------------------------------------------------------------------------------------------------------------- -### Exporting data into CSV file `export` +### Exporting data into CSV file : `export` Exports contacts based on contacts and their details stored in KonTActs. @@ -530,6 +649,11 @@ Exports contacts based on contacts and their details stored in KonTActs. **Format: `export path/DESIRED_FILE_DESTINATION`** + + +**Shortcut: `ex p/DESIRED_FILE_DESTINATION`** + + * File path can be relative or absolute but must end with .csv @@ -545,7 +669,7 @@ relative path given) -------------------------------------------------------------------------------------------------------------------- -### Accessing command history ↑ and ↓ +### Accessing command history : ↑ and ↓ KonTActs automatically saves every (valid or invalid) command entered which can then be retrieved later by using the ↑ and ↓ arrow keys. @@ -573,13 +697,18 @@ KonTActs automatically saves every (valid or invalid) command entered which can -------------------------------------------------------------------------------------------------------------------- -### Adding grades to a contact `addGrade` +### Adding grades to a contact : `addGrade` + +Adds an assignment and its grades to a contact. -Add an assignment and its grades to a contact. + + +**Format: `addGrade name/NAME assignment/ASSIGNMENT_NAME score/SCORE`** + -**Format: `addGrade n/NAME asgn/ASSIGNMENT_NAME s/SCORE`** +**Shortcut: `ag n/NAME a/ASSIGNMENT_NAME s/SCORE`** @@ -626,13 +755,19 @@ Calling `addGrade` without any fields will show the list of assignments in `assi -------------------------------------------------------------------------------------------------------------------- -### Removing grades from a contact `removeGrade` +### Removing grades from a contact : `removeGrade` Removes an assignment and its grades from a contact. -**Format: `removeGrade n/NAME asgn/ASSIGNMENT_NAME`** +**Format: `removeGrade n/NAME assignment/ASSIGNMENT_NAME`** + + + + + +**Shortcut: `rg n/NAME a/ASSIGNMENT_NAME`** @@ -642,7 +777,7 @@ Removes an assignment and its grades from a contact. Assuming John Doe has `Ex01` assignment with a score of `5`. -`removeGrade n/John Doe asgn/Ex01` will remove the `Ex01` assignment from contact John Doe. +Calling `removeGrade n/John Doe asgn/Ex01` will remove the `Ex01` assignment from contact John Doe. Calling `removeGrade n/John Doe asgn/Ex01` again will throw an error since the assignment has already been removed. To add a new assignment, refer to [`addGrade`](#adding-grades-to-a-contact-addgrade) command above. @@ -664,18 +799,23 @@ Exits the program. ### Saving the data -AddressBook data are saved in the hard disk automatically after any command that changes the data. There is no need to save manually. +KonTActs data are automatically saved in the hard disk after every command that changes data. You do not need to save the data manually. + +However, it is always good practice to have a local backup :D You can do this with the [export](#exporting-data-into-csv-file-export) command. -------------------------------------------------------------------------------------------------------------------- ### Editing the data file -AddressBook data are saved automatically as a JSON file `[JAR file location]/data/kontacts.json`. Advanced users are welcome to update data directly by editing that data file. +KonTActs data are saved automatically as a JSON file `[JAR file location]/data/kontacts.json`. -If your changes to the data file makes its format invalid, AddressBook will discard all data and start with an empty data file at the next run. Hence, it is recommended to take a backup of the file before editing it.
-Furthermore, certain edits can cause the AddressBook to behave in unexpected ways (e.g., if a value entered is outside the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly. +**Recommended for more advanced and seasoned users** +- Data in the JSON file can be edited. +- If your changes to the data file results in an invalid format, KonTActs will discard all data and start with an empty data file at the next run. +- It is recommended to create a backup of the file before editing it. This can be done with the [export](#exporting-data-into-csv-file-export) command. +- Certain edits can also cause the KonTActs to behave in unexpected ways (e.g., if a value entered is outside the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly. @@ -684,11 +824,11 @@ Furthermore, certain edits can cause the AddressBook to behave in unexpected way ## 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. Alternatively, you can use the export command to export the data into a CSV file and import the CSV file into your other device. +**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 KonTActs home folder. Alternatively, you can use the [export](#exporting-data-into-csv-file-export) command to export the data into a CSV file and [import](#importing-data-from-csv-file-import) the CSV file into your other device. -------------------------------------------------------------------------------------------------------------------- -## Known issues +## 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. diff --git a/docs/images/quickStartLaunchScreenshot.png b/docs/images/quickStartLaunchScreenshot.png new file mode 100644 index 00000000000..9c69cbf6880 Binary files /dev/null and b/docs/images/quickStartLaunchScreenshot.png differ diff --git a/docs/images/quickStartResultScreenshot.png b/docs/images/quickStartResultScreenshot.png new file mode 100644 index 00000000000..ca4218d9e8d Binary files /dev/null and b/docs/images/quickStartResultScreenshot.png differ