TravelPal - Developer Guide

The Page UiPart, as contained by MainWindow, is the key component that reflects the differences in the data displayed across different pages of the application.

Each class extending Page is able to implement its various components and root JavaFX node types separately, allowing for much flexibility in terms of the different user interfaces of the pages.

Due to its flexibility, the Page abstract class is mainly only responsible for :

Editing of trip/day/event can be accessed from TripsPage/DaysPage/EventsPage respectively. The execution of commands in the each page is facilitated by TripManagerParser/DayViewParser/EventViewParser which extends from the PageParser. This class serves as the abstraction for all parsers related to each Page.

The operations are exposed to the Model interface through the Model#getPageStatus() method that returns the PageStatus containing the all information regarding the current state of application. This includes the descriptors (explained in Step 1 below) which stores all information about the edit.

Given below is an example usage scenario and how the program behaves at each step.

Step 1. When the user launches the application. The PageStatus is initialized under along with other Model components. PageStatus at launch does not contain any EditTripDescriptor/EditDayDescriptor/EditEventDescriptor responsible for storing information for the edit.

Step 2. The user currently on the TripsPage/DaysPage/EventsPage is displayed a list of Trip/Day/Event respectively. The user executes the edit command EDIT1 using the OneBasedIndex on the list to edit it.This executes the EnterEditTripFieldCommand/EnterEditDayFieldCommand/EnterEditEventFieldCommand that initializes a new descriptor within PageStatus before switching over to the EditTripPage/EditDayPage/EditEventPage containing to perform the editing.

Step 3. The user is now on the edit page displaying a list of fields that the user can edit in the Trip/Day/Event. Commands on each page differs based on the fields they contain.

When user executes the command edit n/EditedName on the DaysPage. The command creates a new descriptor from the contents of the original, replacing the fields only if they are edited. The new descriptor is then assigned to PageStatus replacing the original EditDayDescriptor. The result of the edit is then displayed to the user.

Step 4. The user has completed editing the Trip/Day/Event and executes done/cancel to confirm/discard the edit. The execution of the two cases are as follows:

Below is a sequence diagram illustrating the execution of the command "edit ds/10/10/2019" on Days Page:

After executing the parsers above, the last parser instantiates and recursively returns the command (e.g. commandEditDayFieldCommand) up to the LogicManager. LogicManager then executes the command as the sequence diagram below:

The execution of the command is explained above (refer to Section 3.1.1, “Aspect: Logic”).

The UI for to edit fields are associated with the EditTripPage/EditDayPage/EditEventPage respectively.

The execution of the edit command involves the Model, Logic and Ui components of the application. Listed here are the packages used in the execution of the edit commands that are found in the figure above:

The class at large in the diagram above is the EditTripPage of the 3 pages explained. It extends from the Page class and is associated with the following:

The contents of the fields are updated by the execution of the commands above. When the user edits any of the FormItems, the commands are executed which will cause the EditTripPage/EditDayPage/EditEventPage#fillPage() to execute again. fillPage retrieves the updated fields from PageStatus and displays them as the values in the FormItems.

The logic of editing a field and committing it to memory is a simple process of validating each field. If any field fails to meet the specifications, the Trip/Day/Event will not be created/edited. Below is an example execution of validating the edit:

When designing this feature, there were several challenges involved while working with the existing code base especially to adhere to strict Object Orientated Programming Principles. Below are two such design challenges that and how they were resolved:

Deletion of Trip/Day/Event is facilitated by PageStatus. PageStatus stores the current state of execution of the user program. Upon initial startup of the program Model is initialized with PageStatus with the PageType set to enum PageType#TRIP_MANAGER. This indicates the current page displayed to the user. PageStatus is initialized with empty references to the Trip/Day/Event the user executes an action for.

Step 1. When the user launches the application. PageStatus is initialized along with other Model components with empty references.

Step 2. The user enters the DaysPage/EventsPage using the goto command. This instantiates a new PageStatus object from the the existing PageStatus with a modified Day/Trip, providing the context for subsequent actions. Below is an example execution of the command:

Step 3. The user is now on the TripManager/DaysPage/EventsPage, the user can execute the delete command in accordance to the display ordered index on any of the aforementioned pages.

When the command delete <index> is executed, DeleteTripCommand/DeleteDayCommand/DeleteEventCommand is executed. This command accesses Trip/Day reference in PageStatus assigned by the previous step. (Note: deleting Trips do not require PageStatus, it being directly accessible to Model using TripList accessors).

The Day/Trip reference contains the list of Events/Days in memory respectively (DayList/EventList). DayList#remove/EventList#remove are methods in the respective list classes used to delete the day/event. These are executed, modifying the in memory TravelPal and Trip/Event/Day is removed.

The UI of expense manager mainly consists of two Page: ExpensesPage and EditExpensePage.

ExpensePage is the component in charge of displaying expense and budget information. It has a list of ExpenseCard, a component that contains individual expense details. ExpensePage extends PageWithSidebar as it contains navigation bar that helps user to navigate between different features.

In ExpensePage, user can toggle between Days View and List View. In Days View, a list of DailyExpensesPanel is used to group ExpenseCard according to date.

EditExpensePage is the main page for creating and editing of expense. Both ExpensesPage and EditExpensePage have access to Model and Logic of the application, for handling of stored data and parsing commands.

From ExpensePage, user can navigate to Currency feature of application through CLI or GUI.

The main Page for displaying and creating currency is CurrencyPage. The page contains a list of CurrencyCard for displaying individual currency details. Two types of CurrencyCard: SelectedCurrencyCard and UnelectedCurrencyCard are used to indicate the currency in use. Upon launching of the application, a default CustomisedCurrency — Singapore Dollars is automatically added to the CurrencyList, which is not deletable. Thus, there will always be at least one CurrencyCard in CurrencyPage.

CurrencyPage also contains text fields for input of new currency information. It has a PresetSymbols instance which contains a group of ToggleButton which updates the symbol in MainWindow. CurrencyPage have access to Model and Logic of the application, for handling of stored data and parsing commands.

From ExpensePage, user can navigate to Expense Manager feature of application through CLI or GUI.

The executions of add / delete of CustomisedCurrency is similar to those of Trip / Day / Event / Expense. More details can be found in the previous sections: Section 3.1, “[Itinerary] Edit trip/day/event feature”

The UI of Booking Manager mainly consists of two Page: BookingsPage and EditBookingsPage.

BookingsPage is the component in charge of displaying all the information of the booking: name, contact details and associated expenditure.

It has a list of BookingCard, a component that contains individual booking details. BookingsPage extends PageWithSidebar as it contains navigation bar that helps user to navigate between different main features.

EditBookingsPage is the main page for creating and editing of booking. Both BookingsPage and EditBookingsPage have access to Model and Logic of the application, for handling of stored data and parsing commands.

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

These operations are exposed in the Model interface as Model#commitAddressBook(), Model#undoAddressBook() and Model#redoAddressBook() 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. The VersionedAddressBook will be initialized with the initial address book state, and the currentStatePointer pointing to that single address book state.

Step 2. The user executes delete 5 command to delete the 5th person in the address book. The delete command calls Model#commitAddressBook(), causing the modified state of the address book after the delete 5 command executes to be saved in the addressBookStateList, and the currentStatePointer is shifted to the newly inserted address book state.

Step 3. The user executes add n/David …​ to add a new person. The add command also calls Model#commitAddressBook(), causing another modified address book state to be saved into the addressBookStateList.

Step 4. The user now decides that adding the person was a mistake, and decides to undo that action by executing the undo command. The undo command will call Model#undoAddressBook(), which will shift the currentStatePointer once to the left, pointing it to the previous address book state, and restores the address book to that state.

The following sequence diagram shows how the undo operation works:

The redo command does the opposite — it calls Model#redoAddressBook(), which shifts the currentStatePointer once to the right, pointing to the previously undone state, and restores the address book to that state.

Step 5. The user then decides to execute the command list. Commands that do not modify the address book, such as list, will usually not call Model#commitAddressBook(), Model#undoAddressBook() or Model#redoAddressBook(). Thus, the addressBookStateList remains unchanged.

Step 6. The user executes clear, which calls Model#commitAddressBook(). Since the currentStatePointer is not pointing at the end of the addressBookStateList, all address book 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:

The main UiPart component that displays photos is the DiaryGallery. It abides by the Page implementation (see Section 2.2.1, “Page API”), and is thus contained within, in one of DiaryPage’s placeholders.

The main JavaFX component responsible for displaying the photos is a ListView<DiaryPhoto> component. The ListView obtains its data from the PhotoList of the DiaryGallery, which is automatically observed by the ListView.

Hence, changes in the PhotoList, such as the addition of a DiaryPhoto are immediately communicated to the user interface.

The ListView uses a simple custom cell factory, which sets the ListCells of the ListView to use DiaryGalleryCards as its graphic. DiaryGalleryCards are in turn generated in the cell factory using the ListCell’s index and a DiaryPhoto instance.

DiaryGalleryCards display the information as supplied by the DiaryPhoto model using a series of Labels and one ImageView. Additionally, the index of the card as ordered in the DiaryGallery is also displayed, but not stored in the model.

The logic for photo manager plays to the same PageParser structure of parsing commands, that is, DiaryParser returns either AddPhotoParser, DeletePhotoParser when the appropriate command word is parsed, which in turn returns instances of AddPhotoCommand and DeletePhotoCommand respectively.

The main model abstraction holding the data of an entry is the DiaryEntry class.

It stores three key fields, namely:
1. An Index denoting the day the entry is for
2. A String written by the user in the domain specific language (see Section 3.9.2.1, “Entry text parsing”) required by the user interface.
3. A PhotoList storing the photos of the entry, as described in Section 3.8.1, “Aspect: Models”.

The DiaryEntry models are contained within a DiaryEntryList, which enforces the uniqueness of the Index (denoting the day index) of each DiaryEntry, and supports common list operations.

As one of the desired specifications of our application was to allow the user commands, and edits made directly to the edit box to be non final until the done command is executed, a separate buffer model, EditDiaryEntryDescriptor, was needed to store the edit information.

This buffer model stores the same PhotoList and Index as the initial DiaryEntry it is constructed from, but the diary text references a different String, that is, the buffered diary text String.

Multiple UiPart components come into play in displaying the diary entry. However, Page implementation (see Page Api) is still followed, and all components are thus contained within, in one of DiaryPage’s placeholders.

The DiaryEntryDisplay is the component responsible for displaying the content of the DiaryEntry model. Internally, it uses a JavaFX ListView<CharSequence> with a custom cell factory that returns DiaryTextLineCell (as detailed in Section 3.9.2.1.3, “Graphic of ListView cells in DiaryEntryDisplay”). DiaryTextLineCells in turn uses the DiaryLine UiPart as its graphic.

Numerous design decisions and comprimised had to be made due to the desired specifications of text editing and displaying.
Specifically, the following had to be achieved :

An overall trip inventory list is the inventory list of all the items the user needs for the trip.

Each trip only has one overall trip inventory list.

An event inventory list is the inventory list of all the items the user needs for the event.

Each trip can have mutiple event inventory lists.

Therefore, in a trip, all the events inventory lists are subsets of one overall trip inventory list.

The Overall Trip Inventory List (with Model InventoryList) is displayed in the TableView<Inventory> of the InventoryPage, as seen in the object diagram:

The TableView has 3 columns. The first column numbers the items. The second column displays the item’s name. And the thrid column displays whether the item’s isDone property is true or false (through a checkbox).

Both the first and the second column’s cellValueFactory were set to new PropertyValueFactory(STRING) with String STRING. However, the third column was set to CheckBoxTableCell.forTableColumn(BOOLEAN) with Boolean BOOLEAN.

The Event Inventory List (with Model Event) is displayed in the ListView<Inventory> of the EventPage, as seen in the object diagram:

The ListView uses the CSS styling of resources/view/Inventory/InventoryListViewTheme.css' by calling `listView.getStylesheets().add(CSS_FILE_PATH) with the File Path CSS_FILE_PATH)

Furthermore, the reason why ListView and ListCell are in package Ui.itinerary is because EventPage is in itinerary Ui.itinerary. Similarly, Event is in package Model.itinerary

From the sequence diagram, it can be observed that only if InventoryViewParser and AddInventoryParser returns a Command, will the Command be executed. This ensures the AddCommand is only executed when intended.

Moreover, as seen from the sequence diagram, whenever the AddInventoryCommand is executed, it will always return the InventoryView that corresponds to the Trip that the user is correctly on - ensuring that there is only one Overall Trip Inventory List.

Furthermore, the InventoryList calls its own internal function of add to add an item to its list - which loops through the entire list to make sure that the item to be added does not already exist - otherwise it does not add it . Therefore, this also allows all the items in InventoryList to be unique.

Currently, both the Event Inventory List and the Overall Trip Inventory List utilise a common Inventory class to store inventory items.

However, an inventory item in the Event Inventory List does not need to keep count of the eventInstances attribute. Although, the current solution of setting eventInstances to -1 allows both classes to share the Inventory class, it might not be scalable and there may lead to bugs in the future.

Therefore, in a future update, it would be rational to remove make the Inventory class an abstract class with just a Name attribute. And have 2 different classes extend it for the 2 different use cases.