PROJECT: NUS Hangs

Overview

NUS Hangs is a desktop Schedule Manager application. It has a GUI but most of the user interactions happen using a CLI (Command Line Interface). It is a Java application written by developers of F11-4, to target small/mid-size interest/sttudy groups in NUS.

Summary of contributions

  • Major enhancement:

  • Minor enhancement: allow timetable to be viewed without internet.

  • Code contributed: [Functional and Test code]

  • Other contributions:

    • Project management:

      • Managed releases v1.1 - v1.4 (4 releases) on GitHub

    • Enhancements to existing features:

      • allow timetable to be viewed without internet.

      • Wrote additional tests for existing features to increase coverage to >4% (Pull requests #130, #140, #148)

    • Documentation:

      • Edit the Developer Guide to include implementation of timetable: #121

    • Community:

      • Help Team by suggesting methods:

{you can add/remove categories in the list above}

Contributions to the User Guide

Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

Timetable(Wen Kai)

Adding a timetable: add_timetable

Short form/Alias: at

User to download timetable template first before using download_timetable INDEX and change csv at the location.
Reload page by clicking on another person and then click on the person again
Or right click on timetable and select the reload page option(Not working).

Format: add_timetable INDEX [fl/FILE_LOCATION]

  • Existing values will be updated to the input values.

  • timings are start time of the event. Eg. if timetable shows 0800, it means the event is from 0800 to 0900.

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

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

  • Time zone used is Singapore (GMT+8)

Example (user does not provide a file path):

  • add_timetable 1

  • add_timetable will add timetable from the given csv file from the person specified by the INDEX from file location if file location is present. If not, NUSHangs will throw an error message if the file cannot be found from the given (typed) file path

  • Will not be able to add if timetable is not present in the stored location of person specified by INDEX

Example (user provides a file path):

  • add_timetable 1 fl/C:\Users\timetable\timetable.csv

  • WINDOWS:

    • add_timetable fl/C:\Users\timetable\timetable.csv (absolute pathing)

    • add_timetable fl/timetable.csv (relative pathing: when the csv file is in the same directory as the jar file).

  • MAC:

    • add_timetable 1 fl//FILEPATH (absolute pathing: note the double slashes)

    • add_timetable 1 fl/timetable.csv (relative pathing).

  • add_timetable will add timetable from the given csv file.

  • the first row and first column should be left alone.

  • the top left corner entry can be edited (the blank space at the top of Monday in the first column).

  • can only edit in given rows and columns of the timetable.

  • any invalid timetable will be ignored.

  • example of correctly formatted timetable is given below

add timetable fl

Editing a timetable: edit_timetable

Short form/Alias: et

Edits a timetable timeslot of the timetable from the person specified by the INDEX.
Format: edit_timetable INDEX day/DAY timing/TIMING [m/DETAILS]

  • timings are in 24h format from 0800 to 2300.

  • timings are start time of the event. Eg. if timetable shows 0800, it means the event is from 0800 to 0900.

  • Existing values will be overwritten by the input details.

  • days are days of a week in full name(case insensitive) from Monday to Friday.

  • edit the timetable at the specified INDEX.

  • can only edit 1 hour timeslot at a time.

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

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

  • Time zone used is Singapore (GMT+8)

  • DETAILS cannot be empty.

  • If no DETAILS is inputted, the value will be deleted at the timeslot

Example:

  • edit_timetable 1 day/wednesday timing/0900 m/do cs2103

Example(User clear event at timeslot):

  • edit_timetable 1 day/wednesday timing/0900

Download timetable : download_timetable

Short form/Alias: dlt

Download a timetable from the person specified by the INDEX to the stored folder from the person specified by the INDEX as a csv file.
Format: `download_timetable INDEX `

  • Download the timetable at the specified INDEX.

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

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

  • Will not download if there is a file with same filename in the folder as the filename of the timetable from the person specified by the INDEX.

  • Will not download if there is no such folder to download the timetable csv file given by the file location from the person specified by the INDEX.

Examples:

  • download_timetable 1

Deleting a timetable : delete_timetable

Short form/Alias: dt

delete csv file of the timetable from stored location from the person specified by the INDEX and adds a default timetable to the person specified by the INDEX.Resets the timetable of the person to the default timetable if there is no timetable in the stored location from the person specified by the INDEX.
Format: delete_timetable INDEX

  • Deletes the timetable at the specified INDEX.

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

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

Examples:

  • list_timetable
    delete_timetable 2
    Deletes the 2nd timetable in NUS Hangs.

  • find Betsy
    delete_timetable 1
    Deletes the 1st timetable in the results of the find command.

Contributions to the Developer Guide

Given below are sections I contributed to the Developer Guide. They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

Timetable Feature

As shown in the diagram below, timetable and person classes are associated. A person contains 1 timetable.

timetableclassdiagram

Reason for implementation

The objective of the add_timetable feature is to to add data entries of a timetable into NUS Hangs. But it is hard to visualise the adding of the entries so we allowed user to add directly all the entries from a csv file. For edit_timetable , it is for User who just want to edit entries without going to find the timetable. For download_timetable, it is to allow the user to share their timetable to their friends.

How to implement

For add_timetable , we create a timetable class in person first, then we create a timetableData class with method to create a String [][] Matrix from the data from the csv file. Then we create a timetableString to which contains information on the entries about the timetable and store it in the xml file of the person in the addressbook.

Current Implementation

The current timetable commands are:

  • add_timetable — adds a timetable from the csv file to the person.

  • delete_timetable — delete a timetable from the person and creates a default timetable in person. It will also find the timetable csv file of the person and deletes it.

  • edit_timetable — edit a timetable timeslot in the person

  • download_timetable — downloads a timetable into a csv file into a stored folder location from the person.

These operations are handled by the logic component and uses the person in model to do the execution.

Given below is an activity diagram.

timetableworkflow

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

Step 1: The user launches the application for the first time. The NUS Hangs will initialise the person with the timetable with the details which was stored using Storage.

Step 2: user finds a timetable of first person in the stored location which is called test7.csv. Using this command, User does not need to type in the timetable name. As shown in the diagram below its easy to see what event the person has.

addTimetable step 2

Step 3: The user executes add_timetable 1 to add the timetable of first person in stored folder to NUS hangs. A new timetable will be created containing the data of the timetable of first person in stored folder. The timetable of first person will be replaced by this new timetable.

The timetable is then added to storage as a String which contains all of the data. This is to allow the app to save time in storage.

The following sequence diagram shows how add_timetable works.

addtimetablediagram

Design Considerations

  • Alternative 1 : adds the timetable via a csv file.

    • Pros: Easier for user to visualise and edit his timetable

    • Cons: Hard to implement. No choice other than to edit his timetable from the stored folder defined.

  • Alternative 2 (current choice) : adds the timetable via a csv file from other locations.

    • Pros: Easier for user to visualise and edit his timetable and allows user a choice on where to edit his timetable.

    • Cons: Hard to implement, and user has to know how to get file location of a file.

  • Alternative 3: adds the timetable edit by editing the xml file of the person.

    • Pros: Easier to implement

    • Cons: User must know how to edit via the xml file of the person, and harder for User to visualise.

Aspect: Data structure to support the add_timetable commands

  • Alternative 1 (current choice): Use a String [][] Matrix to store entries of the timetable.

    • Pros: Easy for new Computer Science student undergraduates to understand, who are likely to be the new incoming developers of our project. Better intuition to access entries of the matrix (matrix[i][j]) Which makes edit_timetable easier to implement.

    • Cons: Slower Time efficiency because using 2 for loops to fill the Matrix with the data. Unable to use functions in ArrayList.

  • Alternative 2: Use ArrayList<ArrayList<String>>

    • Pros: Faster Time efficiency because using 1 for loops to fill the Matrix with the data. Able to use functions in ArrayList

    • Cons: Harder for new Computer Science student undergraduates to understand, who are likely to be the new incoming developers of our project. Less intuition to access entries of the matrix (matrix.get(i).get(j)).

{Optionally, you may include other projects in your portfolio.}