Student Schedule Planner - Developer Guide

This project follows oss-generic coding standards. IntelliJ’s default style is mostly compliant with ours but it uses a different import order from ours. To rectify,

Optionally, you can follow the UsingCheckstyle.adoc document to configure Intellij to check style-compliance as you write code.

After forking the repo, the documentation will still have the SE-EDU branding and refer to the ssp/scheduleplanner repo.

If you plan to develop this fork as a separate product (i.e. instead of contributing to ssp/scheduleplanner), you should do the following:

Set up Travis to perform Continuous Integration (CI) for your fork. See UsingTravis.adoc to learn how to set it up.

After setting up Travis, you can optionally set up coverage reporting for your team fork (see UsingCoveralls.adoc).

Optionally, you can set up AppVeyor as a second CI (see UsingAppVeyor.adoc).

When you are ready to start coding,

The following code snippet shows how the command is implemented:

This loop occurs after the first task is added. The tasks are created within the loop with duplicate names, priorities, venues and tags. Before adding a task, the function checks with the model if such a task already exists. If not, the task is added. If the task is a duplicate task, it is skipped and the loop proceeds until it terminates.

The following outlines an example of the command’s usage.

Step 1. The user enters the command repeat n/CS2103T Tutorial i/7 r/3 p/3 t/CS2103T t/Tutorial v/COM1

Step 2. The AddRepeatParser parses the command and isolates each of the arguments.

Step 3. The Model checks if the first task exists. If the first task does not exist in Model, it is added. If not, it is skipped.

Step 4. The execute command loops through to build each repeated task. In each loop, the date is incremented by the specified interval. Same as Step 3, a duplicate task is skipped and a task that does not exist in Model is added.

Step 5. The changes are committed and the new list is shown to the user.

The following sequence diagram shows how the add repeat operation works:

The undo/redo mechanism is facilitated by VersionedSchedulePlanner. It extends SchedulePlanner with an undo/redo history, stored internally as an SchedulePlannerStateList and currentStatePointer. Additionally, it implements the following operations:

These operations are exposed in Model interface as Model#commitSchedulePlanner(), Model#undoSchedulePlanner() and Model#redoSchedulePlanner() respectively.

Given below is an example usage scenario and how the undo/redo mechanism behaves at each step:

Step 1. The user launches the application for the first time. VersionedSchedulePlanner will be initialized with the initial schedule planner state, with currentStatePointer pointing to that single schedule planner state.

Step 2. The user executes delete 5 command. The delete command calls Model#commitSchedulePlanner(), as a result the modified state of the schedule planner is saved in schedulePlannerStateList after the delete 5 command executes, the currentStatePointer shifts to the newly inserted schedule planner state.

Step 3. The user executes add n/CS2100 Lect …​ to add a new task. The add command calls Model#commitSchedulePlanner() `, and the modified schedule planner state is saved into `schedulePlannerStateList.

Step 4. The user now decides to undo that action by executing the undo command. The undo command will call Model#undoSchedulePlanner(), which shifts the currentStatePointer to the previous index, pointing to the previous schedule planner state, and restoring the schedule planner to its previous state.

The following sequence diagram shows how the undo operation works:

The redo command does the opposite — it calls Model#redoSchedulePlanner(), which shifts the currentStatePointer to the next index, pointing to the next state, and restores the schedule planner to that state.

Step 5. The user then executes the command list. Commands that do not modify the schedule planner, such as list, will usually not call Model#commitSchedulePlanner(), Model#undoSchedulePlanner() or Model#redoSchedulePlanner(). Thus, the schedulePlannerStateList remains unchanged.

Step 6. The user executes clear, which calls Model#commitSchedulePlanner(). If the currentStatePointer is not pointing to the latest state in the schedulePlannerStateList, all states after the currentStatePointer will be purged. We designed it this way because it no longer makes sense to redo the add n/David …​ command. This is the behavior that most modern desktop applications follow.

The following activity diagram summarizes what happens when a user executes a new command:

listday/listweek utilises the same implementation used by list command:

listday further implements the following operation:

listweek further implements the following operations:

As both listday/listweek commands are similar, we will only illustrate how listweek works. Given below is an example usage scenario and how listweek mechanism behaves at each steps:

Step 1. The user entered the command listweek.

Step 2. The command word listweek invoke LogicManger to invoke SchedulePlannerParser to return a ListWeekCommand object. LogicManager then invoke ListWeekCommand#execute().

Step 3. ListWeekCommand#appendDateList(datelist, numDaysTillSunday(dateName)) will be activated. It helps to generates values for dateList and the values are sequential dates in DDMMYY format after using the result from numDaysTillSunday() method. numDaysTillSunday() will compute the number of days from current date till Sunday based on dateName, the name of the current day.

Step 4. model.updateFilteredTaskList() will update the task list with DateWeekSamePredicate as the parameter. DateWeekSamePredicate itself would take dateList in Step 3 as the parameter.

Step 5. The updated task list would be reflected on UI to be displayed to the user.

The following sequence diagram illustrates how the mechanism works:

The archiveTask mechanism is facilitated by SchedulePlanner. Schedule Planner has two lists of tasks, one is taskList for normal tasks, another is archivedTaskList for archived tasks. Normal task list is implemented using UniqueTaskList that does not allow duplicates, while archived task list is implemented using TaskList that allows duplicates.
Task list that is used to store normal tasks is implemented this way:

While task list that is used to store archived tasks does not check for duplicates:

Given below is an example usage scenario and how the archiveTask mechanism behaves. We first assume that user executes command archive 1:

The following sequence diagram illustrates how the mechanism works:

Every time when the application is launched, archived list is checked through. Tasks with deadline date earlier than 2 weeks ago are then permanently deleted from archived task list.

Given below is detailed explanation of how auto-deletion mechanism behaves:

listmonth utilises the same implementation used by the list command:

listmonth also utilises the same implementation used by the listweek command:

listmonth further implements the following operations:

Given below is an example usage scenario and how listmonth mechanism behaves at each steps:

Step 1. The user enters the command listmonth.

Step 2. The command word listmonth invokes LogicManger, which invokes SchedulePlannerParser to return a ListMonthCommand object. LogicManager then invokes ListMonthCommand#execute().

Step 3. ListMonthCommand#appendDateList(datelist, numDaysTillEndOfMonth(currentDay)) will be invoked. It generates sequential dates in DDMMYY format which are added into dateList. numDaysTillEndOfMonth(currentDay) computes the number of days from the current date till the end of the month based on currentDay. currentDay is the current date in LocalDate format.

Step 4. model.updateFilteredTaskList() updates the task list with DateWeekSamePredicate as the predicate. DateWeekSamePredicate takes dateList in Step 3 as its parameter.

Step 5. The updated task list would be reflected on UI to be displayed to the user.

The following sequence diagram illustrates how the mechanism works:

firstday mechanism is facilitated by FirstDayCommand and implements the following operations:

Given below is an example usage scenario and how firstday mechanism behaves at each steps:

Step 1. The user enter the command firstday 130818

Step 2. The command word firstday invoke LogicManager to invoke SchedulePlannerParser. SchedulePlannerParser then invoke FirstDayCommandParser#parse(130818) which will then trim the argument 130818 into trimmedArgs.

Step 3. Methods onlyOneSetArgument(trimmedArgs), Date#isValidDate(trimmedArgs) and isMonday(trimmedArgs) are used in sequential order to check if trimmedArgs is valid.

Step 4. FirstDayCommandParser return a FirstDayCommand with the validated trimmedArgs as its parameter.

Step 5. LogicManager then invoke FirstDayCommand#execute().

Step 6. FirstDayCommand#computeRangeOfWeeks(trimmedArgs) will be activated and generate the academic calendar weeks . This method will further call FirstDayCommand#addDescriptionForWeeks to add description for each of the academic calendar weeks. The academic calendar weeks will be stored in a 2D String array named rangeOfWeek.

Step 7. FirstDayCommand#saveRangeOfWeeks(rangeOfWeek) will be activated. It will create a XmlSerializableRangeOfWeek object with rangeOfWeek as its parameter to allow rangeOfWeek data to be converted into Xml format to be easily saved. Next, this method would call XmlFileStorage#saveWeekDataToFile to save XmlSerializableRangeOfWeek object data into Xml format in rangeofweek.xml

Step 8. After the data had been saved properly, should the current system date lies within the academic calendar weeks, UI would display the corresponding week description to the user.

Step 9. When user launch the application,MainApp will create a FirstDayCommand object named fdc to utilise the methods fdc#createDefaultFileIfNotExist, fdc#createDefaultFileIfUnableConvert, fdc#createDefaultFileIfDiffSize, fdc#createDefaultFileIfNull and fdc#createDefaultFileIfInvalidDateOrRange.

If it is the first time the user launches the application or if user deleted rangeofweek.xml or invalidated data in rangeofweek.xml, the application will record the log message and create a default rangeofweek.xml.

The following code snippet shows that with the extra layer of data verification and rectification, the user do not need to worry when they accidentally invalidated the storage file.

Step 10. MainApp will create a Config object named as updateConfig and then calls the method updateConfig.setAppTitle(fdc.computeAppTitle()). fdc.computeAppTitle() would create a 2D String Array called retrieveData for storing academic semester dates to operate FirstDayCommand#retrieveRangeOfWeeks(retrieveData) to retrieve saved data.

It then check if system date is within the retrieveData by using FirstDayCommand#isWithinDateRange(x,y) where x and y stands for the first academic and last academic day respectively. If it is within, it then generate the corresponding application title by using FirstDayCommand#retrieveWeekDescription(retrieveData). Else it uses the default application title. It would then return the result into updateConfig.setAppTitle() to update the application title.

Step 11. MainApp then calls ConfigUtil#saveConfig(updateConfig, configFilePathUsed) to save the updated configuration into the path configFilePathUsed where config.json is.

Step 12. MainApp would then retrieve the application title from config.json and display on UI.

The following sequence diagrams illustrates how the mechanism works:

Since filter and filterstrict are implemented in similar fashion, we will simply refer to filter.

The filter mechanism utilises FilterCommandParser to parse the user command into separate tags by invoking the method FilterCommandParser.parse(args), where args are the tags to be filtered. e.g tag1 tag2 will be parsed into tag1 and tag2.

Given below is an example usage scenario and how the filter mechanism behaves at each step:

Step 1. The user executes the command filter tutorial CS2100

Step 2. The 'filter' command invokes FilterCommandParser, which parses the argument tutorial CS2100 into separate words tutorial and CS2100, and are stored in an array in the predicate TagsContainsKeywordsPredicate.

Step 3. FilterCommandParser then returns a FilterCommand , which contains TagsContainsKeywordsPredicate, a predicate which tests for the tags 'tutorial' and 'CS2100'. FilterCommand.execute() calls model .updateFilteredTaskList(TagsContainsKeywordsPredicate), which returns an updated list of tasks containing any of the tags input by the user.

The following sequence diagram summarizes what happens when a user executes a new filter command:

Given below is a code snippet of the ListOverdueCommand.

The ListOverdueCommand calls the method updateFilteredTaskList with a new OverduePredicate which has the current date as the parameter.

The test function within OverduePredicate class compares the current system date with the date of the task. If the task’s date is after the current time, the function returns false, and vice versa.

Model contains a UniqueTaskList called tasks.

Given below is an example usage scenario and how the list overdue mechanism behaves at each step:

Step 1. The user executes the command listoverdue.

Step 2. model.updateFilteredTaskList() will update the task list with OverduePredicate as the parameter OverduePredicate itself takes the current system date in the yyMMdd format.

Step 3. The updated task list would be reflected on the UI to be displayed to the user.

Model contains two UniqueTaskLists - tasks and archivedTasks - each containing the tasks and archived tasks respectively.

Given below is an example usage scenario and how the list archived mechanism behaves at each step:

Step 1. The user executes the command listarchived.

Step 2. The listarchived command raises a new ChangeViewEvent that signals a change to archived view.

Step 3. MainWindow responds to the ChangeViewEvent with MainWindow#handleChangeViewEvent().

Step 4. MainWindow calls Logic#getFilteredArchivedTaskList(). It then creates a new TaskListPanel instance with Tasks in that list.

Step 5. MainWindow places the new TaskListPanel in the TaskListPanelPlaceHolder. The archived tasks are now displayed.

The following sequence diagram shows how the list archive operation works:

Sorting feature does not require any user input command. Whenever the tasks are listed, they are always listed according to deadline date, then priority. Our application offers 3 priority levels from 1 to 3, 3 is the highest priority and 1 is the lowest.

Assume there are two tasks in a task list, task A and task B. Given below is the scenario when task list is retrieved from schedule planner using any kind of list command and how the sorting mechanism behanves.

Given below is a sequence diagram of the sorting feature.

Each category has a unique name, and contains a list of tags. The list of tags is implemented using UniqueTagList, which does not allow duplicates, in other words, tags with same name. Given below is a snippet of implementation of UniqueTagList:

Given below is a snippet of implementation of category:

Schedule Planner contains a list of cateogry list, implemented using UniqueCategoryList. UniqueCategoryList is a list used to save categories which does not allow duplicates. Any two categories with same name are considered identical. Given below is a snippet its implementation:

Given below is an example usage scenario and how the category mechanism behaves at each step:

Step 1. User enters command addcat c/Game list to add a category named Game list.

When user is adding tasks using unspecified tags (tags that have never been added to any category), the tags will be automatically added to default category Others.

Step 2. User enters command addtag c/Game list t/Zelda to add tag Zelda into category Game list.

Given below is the sequence diagram of add tag command.

Step 3. User enters command editcat c/Game list c/Reading list to rename category from Game list to Reading list.

Given below is the sequence diagram of edit category command:

Step 4. User enters command removecat c/Reading list to remove the category named Reading list. Let us call this category categoryReadingList.

Given below is the sequence diagram of remove category command:

Besides adding tag, renaming (editing) and removing, we support clearing category as well. Clear category command clears the tags list of selected category. Mechanism of clearing category is very similar to renaming (editing) category. Model#clearCategory() calls VersionedSchedulePlanner#clearCategory(), which then initialize a new empty category with name "Modules". Below is a code snippet of VersionedSchedulePlanner#clearCategory():

Below is a code snippet of #UniqueCategoryList#setCategory()` used here, which is slightly different from what is used in editing category:

We omit the sequence diagram here because of its similarity to edit category command.

Every time any category or tag is changed in the Student Schedule Planner, it raises a SchedulePlannerChangedEvent. The UI will then handle that event and update the side bar panel with the new version of categories and tags.

Given below is an example usage scenario and how the schedule planner behaves at each step:

Step 1. The user executes command addtag c/Modules t/CS2100.

Step 2. The addtag command updates the model with the new tag and raises a new SchedulePlannerChangedEvent.

Step 3. SidebarPanel responds to the SchedulePlannerChangedEvent with SidebarPanel#handleSchedulePlannerChangedEvent().

Step 4. The Accordion containing all the categories and tags is cleared.

Step 5. The Accordion is filled with the new list of updated categories and tags.

Step 6. The user executes command tags c/Modules.

Step 7. The ShowTagsCommand raises a new ShowTagsRequestEvent("Modules").

Step 8. SidebarPanel responds to the ShowTagsRequestEvent with SidebarPanel#handleShowTagsRequestEvent().

Step 9. The TitledPane with the matching name "Modules" is expanded to display all the tags listed under the Modules category.

Below is a code snippet showing how the SidebarPanel handles a ShowTagsRequestEvent:

Whenever the user makes a change in the schedule planner, for example add, delete, or archive a task, it raises a new SchedulePlannerChangedEvent. UI part ProgressBarPanel will handle this event and update the values for both today and this week’s progress bars.

Given below is an example usage scenario and how the progress bar mechanism behaves at each step:

Step 1. User archives a Task due today.

Step 2. A new SchedulePlannerChangedEvent is raised.

Step 3. ProgressBarPanel handles the event with ProgressBarPanel#handleSchedulePlannerChangedEvent().

Step 4. The taskList is retrieved by SchedulePlannerChangedEvent#data.getTaskList(). The archivedTaskList is retrieved by SchedulePlannerChangedEvent#data.getArchivedTaskList().

Step 5. ProgressBarPanel#updateProgressBars(taskList, archivedTaskList) is called.

Step 6. After filtering through each lists with the DateSamePredicate, their sizes are calculated.

Step 7. The number of completed tasks for today is the size of the filtered archived list, while the total number of tasks for today is the size of both the filtered archived list and the filtered task list.

Step 8. The fraction is calculated from completed / total. Then the progress bar for today is set to that fraction.

Step 9. The same is done for this week’s progress bar but the lists are filtered with DateWeekSamePredicate.

The following sequence diagram shows how the progress bar mechanism works: