Merge branch 'master' into update-jobapp-display

docs/DeveloperGuide.md

@@ -318,6 +318,43 @@ The following activity diagram summarizes what happens when a user executes a ne
 
 _{Explain here how the data archiving feature will be implemented}_
 
+### Apply feature
+The apply feature makes use of existing structures to function, notably the `Parser`, `Model` and `Storage`
+
+The following sequence diagram shows how job applications are added to Jobby
+
+<img src="images/apply-command/ApplyCommand.png">
+
+#### Design Considerations
+**Aspect: How to store applications**
+
+* **Actual: Applications are stored as a JSON array belonging to their respective organizations**
+  * Pros: Easy to implement
+  * Cons: Need to initialise a list of job applications from every organization every time on startup. 
+
+* **Alternative 1: Applications are stored as a JSON array separate from the contacts**
+  * Pros: Applications can be loaded immediately into Jobby without waiting for organizations to be initialised.
+  * Cons: Can have complications on other features, such as identifying which applications belong to which organizations.
+
+**Aspect: How to show applications**
+
+* **Actual: Applications are shown on a separate list**
+  * Pros: Easy to implement, less command needed to switch view from split view.
+  * Cons: Requires syncing the list with organizations, since there is no guarantee that the applications in the UI list are the same as all the ones in organizations.
+
+* **Alternative 1: Use a command to switch list view**
+  * Pros: More compact, does not require larger screen size.
+  * Cons: More difficult to implement, requires a command that directly changes the UI.
+
+**Aspect: What should the command syntax be**
+
+* **Actual: Use a separate command for adding applications**
+  * Pros: Easier to type out the command, does not require a lot of typing.
+  * Cons: More implementation effort, to implement a new command with new parser.
+* **Alternative 1: Reuse add command**
+  * Pros: Easier to implement, can make use of existing structures surrounding the add command.
+  * Cons: Overloading the add command too much.
+
 
 --------------------------------------------------------------------------------------------------------------------
 

docs/UserGuide.md

@@ -106,10 +106,6 @@ Acceptable Parameters:
 
 * `ADDRESS` can accept any value. It designates the contact’s physical address.
 
-* `STATUS` must be one of _interested, applied, pending, offered, rejected, current_ (case-insensitive, prefix-only match allowed).
-
-* `POSITION` may be any value. It designates the position you intend to apply to.
-
 * `TAG` can accept any value and may have multiple inputs.
 
 
@@ -122,7 +118,7 @@ Examples:
 
 * `add --org --name Example --url www.organization.org --tag freelance`
 
-* `add --org --name Examinations NUS --phone 65166269 --email [email protected] --url https://luminus.nus.edu.sg/ --stat pending`
+* `add --org --name Examinations NUS --phone 65166269 --email [email protected] --url https://luminus.nus.edu.sg/`
 
 
 #### Adding a recruiter contact: `add --rec`
@@ -139,6 +135,7 @@ Acceptable Parameters:
     * Specifying this sets the ID, or one unique one will be derived and generated from the name if not provided.
 
 * `ORG_ID` refers to the unique identifier which is used to uniquely identify the organization the recruiter should be tied to. It is subject to the same validation as the ID field.
+The value provided must also be the ID of an existing organization in the address book.
 
 * `NUMBER` should be a valid phone number.
 
@@ -150,7 +147,7 @@ Acceptable Parameters:
 
 
 Examples:
-* `add --rec --name John Doe --oid paypal-sg`
+* `add --rec --name John Doe --oid paypal-sg` links the recruiter `John Doe` to an organization with the id `paypal-sg`
 
 
 ### Listing all contacts: `list`
@@ -239,20 +236,6 @@ Jobby data are saved automatically as a JSON file `[JAR file location]/data/jobb
 If your changes to the data file makes its format invalid, Jobby 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.
 </div>
 
-### Applying to an organization: `Apply`
-
-Format: `add index/ id <additional parameters and values...>`
-
-
-App a contact to the address book of the given class type: Organization or Recruiter.
-
-Applying to a Organization by indicating it with the organization's index in the address book or the organization's unique id.
-
-This can be done by supplying the organization's `index` or `id` as the preamble.
-
-Details specifically will be explained the next sections.
-
-
 #### Applying to an Organization: `apply`
 
 Format: `apply INDEX/ID --title TITLE [--desc DESCRIPTION] [--by DEADLINE: DD-MM-YYYY] [--stage APPLICATION STAGE: resume | online assessment | interview] [--stat STATUS: pending | offered | accepted | turned down]`
@@ -305,24 +288,52 @@ Examples:
 * `edit --application 1 --stat rejected`
 * `edit --application 1 --stage interview`
 
-### Sort `sort`
+### Sorting contacts/job applications: `sort`
 Sorts contacts or applications by the specified flag.
 
 Format: `sort --FLAG_TO_SORT`
 
-* Currently only the following sorting functions are supported:
-  * For contacts:
-    * `--addr`
-    * `--email`
-    * `--name`
-    * `--id`
-    * `--phone`
-    * `--url`
-  * For job applications
-    * `--stale`: Sorts by last updated applications
+The following sorting flags are supported:
+* For contacts:
+  * `--address`
+  * `--email`
+  * `--name`
+  * `--id`
+  * `--phone`
+  * `--url`
+* For job applications:
+  * `--deadline`: Sorts by application deadline
+  * `--stage`: Sorts by application stage
+  * `--stale`: Sorts by last updated applications
+  * `--status`: Sorts by application status
+  * `--title`: Sorts by job title
+* To reset the sorting arrangement:
+  * `--none`
+
+Supplying `--ascending` or `--descending` sorts the contacts or applications in the specified order. 
+If not specified, the default order is used:
+* Chronological (for deadlines)
+* According to the stage/status order (for application stages and statuses)
+* Alphabetical (for the rest)
+Neither order flag may be supplied if `-none` is the specified sorting flag.
 
+Examples:
+* `sort --name`
+* `sort --deadline --descending`
+* `sort --title --ascending`
+* `sort --none`
 
+### Reminding about deadlines: `remind`
+Reminds the user of upcoming deadlines for job applications.
 
+Format: `remind --earliest/--latest`
+
+Specifying `--earliest` will list the application deadlines in order of urgency, from earliest to latest.
+Specifying `--latest` will list the application deadlines in order of reverse urgency, from latest to earliest.
+
+Examples:
+* `remind --earliest`
+* `remind --latest`
 --------------------------------------------------------------------------------------------------------------------
 
 ## FAQ
@@ -342,7 +353,7 @@ Format: `sort --FLAG_TO_SORT`
 
  Action               | Format, Examples                                                                                                                                                                                                                                                                            
 ----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- **Add Organization** | `add --org --name <NAME> [--id ID] [--phone NUMBER] [--email EMAIL] [--url URL] [--addr ADDRESS] [--stat STATUS] [--pos POSITION] [--tag TAG]...`<br> e.g., `add --org --name NUS --phone 0123456789 --email [email protected] --url https://www.nus.edu.sg/ --stat pending --pos Research` 
+ **Add Organization** | `add --org --name <NAME> [--id ID] [--phone NUMBER] [--email EMAIL] [--url URL] [--addr ADDRESS] [--tag TAG]...`<br> e.g., `add --org --name NUS --phone 0123456789 --email [email protected] --url https://www.nus.edu.sg/` 
  **Add Recruiter**    | `add --rec --name <NAME> [--id ID] [--oid ORG_ID] [--phone NUMBER] [--email EMAIL] [--url URL] [--addr ADDRESS] [--tag TAG]...`<br> e.g., `add --rec --name John Doe --oid paypal-sg`                                                                                                       
  **Clear**            | `clear`                                                                                                                                                                                                                                                                                     
  **Delete**           | `delete INDEX [--recursive]` or <br> `delete --id ID [--recursive]` <br> e.g., `delete 3`, `delete --id 55tg`                                                                                                                                                                               

docs/diagrams/ModelClassDiagram.puml

@@ -22,6 +22,9 @@ Class Url
 Class Phone
 Class Tag
 
+Class JobApplicationList
+Class JobApplication
+
 Class I #FFFFFF
 }
 
@@ -47,6 +50,9 @@ Contact *--> Url
 Contact *--> Address
 Contact *--> "*" Tag
 
+ModelManager *-down-> "1" JobApplicationList
+JobApplicationList -down-> "*" JobApplication
+
 Contact -[hidden]up--> I
 UniqueContactList -[hidden]right-> I
 

docs/diagrams/StorageClassDiagram.puml

@@ -19,6 +19,7 @@ Class "<<interface>>\nAddressBookStorage" as AddressBookStorage
 Class JsonAddressBookStorage
 Class JsonSerializableAddressBook
 Class JsonAdaptedContact
+Class JsonAdaptedApplication
 Class JsonAdaptedTag
 }
 
@@ -39,5 +40,6 @@ JsonAddressBookStorage .up.|> AddressBookStorage
 JsonAddressBookStorage ..> JsonSerializableAddressBook
 JsonSerializableAddressBook --> "*" JsonAdaptedContact
 JsonAdaptedContact --> "*" JsonAdaptedTag
+JsonAdaptedContact --> "*" JsonAdaptedApplication
 
 @enduml

docs/diagrams/UiClassDiagram.puml

@@ -13,8 +13,11 @@ Class HelpWindow
 Class ResultDisplay
 Class ContactListPanel
 Class ContactCard
+Class ApplicationListPanel
+Class ApplicationCard
 Class StatusBarFooter
 Class CommandBox
+Class AutoCompleteTextField
 }
 
 package Model <<Rectangle>> {
@@ -33,25 +36,33 @@ UiManager -down-> "1" MainWindow
 MainWindow *-down->  "1" CommandBox
 MainWindow *-down-> "1" ResultDisplay
 MainWindow *-down-> "1" ContactListPanel
+MainWindow *-down-> "1" ApplicationListPanel
 MainWindow *-down-> "1" StatusBarFooter
 MainWindow --> "0..1" HelpWindow
 
 ContactListPanel -down-> "*" ContactCard
+ApplicationListPanel -down-> "*" ApplicationCard
+CommandBox -down-> "0..1" AutoCompleteTextField
 
-MainWindow -left-|> UiPart
+MainWindow --|> UiPart
 
 ResultDisplay --|> UiPart
 CommandBox --|> UiPart
 ContactListPanel --|> UiPart
 ContactCard --|> UiPart
 StatusBarFooter --|> UiPart
 HelpWindow --|> UiPart
+AutoCompleteTextField --|> UiPart
+ApplicationListPanel --|> UiPart
+ApplicationCard --|> UiPart
 
 ContactCard ..> Model
+ApplicationCard ..> Model
 UiManager -right-> Logic
 MainWindow -left-> Logic
 
 ContactListPanel -[hidden]left- HelpWindow
+ApplicationListPanel -[hidden]left- ContactListPanel
 HelpWindow -[hidden]left- CommandBox
 CommandBox -[hidden]left- ResultDisplay
 ResultDisplay -[hidden]left- StatusBarFooter

docs/diagrams/apply-command/ApplyCommand.puml

@@ -0,0 +1,70 @@
+@startuml
+!include style.puml
+skinparam ArrowFontStyle plain
+
+box Logic LOGIC_COLOR_T1
+participant ":LogicManager" as LogicManager LOGIC_COLOR
+participant ":AppParser" as AddressBookParser LOGIC_COLOR
+participant ":ApplyCommandParser" as ApplyCommandParser LOGIC_COLOR
+participant ":ApplyCommand" as ApplyCommand LOGIC_COLOR
+participant ":CommandResult" as CommandResult LOGIC_COLOR
+end box
+
+box Model MODEL_COLOR_T1
+participant ":Model" as Model MODEL_COLOR
+end box
+
+[-> LogicManager : execute("apply 1 --title SWE")
+activate LogicManager
+
+LogicManager -> AddressBookParser : parseCommand("apply 1 --title SWE")
+activate AddressBookParser
+
+create ApplyCommandParser
+AddressBookParser -> ApplyCommandParser
+activate ApplyCommandParser
+
+ApplyCommandParser --> AddressBookParser
+deactivate ApplyCommandParser
+
+AddressBookParser -> ApplyCommandParser : parse(" --title SWE")
+activate ApplyCommandParser
+
+create ApplyCommand
+ApplyCommandParser -> ApplyCommand
+activate ApplyCommand
+
+ApplyCommand --> ApplyCommandParser :
+deactivate ApplyCommand
+
+ApplyCommandParser --> AddressBookParser :
+deactivate ApplyCommandParser
+'Hidden arrow to position the destroy marker below the end of the activation bar.
+ApplyCommandParser -[hidden]-> AddressBookParser
+destroy ApplyCommandParser
+
+AddressBookParser --> LogicManager :
+deactivate AddressBookParser
+
+LogicManager -> ApplyCommand : execute()
+activate ApplyCommand
+
+ApplyCommand -> Model : addJobApplication()
+activate Model
+
+Model --> ApplyCommand
+deactivate Model
+
+create CommandResult
+ApplyCommand -> CommandResult
+activate CommandResult
+
+CommandResult --> ApplyCommand
+deactivate CommandResult
+
+ApplyCommand --> LogicManager : result
+deactivate ApplyCommand
+
+[<--LogicManager
+deactivate LogicManager
+@enduml