Developer Guide

This guide will teach you how to set up your development environment, explain the basic architecture of the application, teach you how to perform some common development tasks, as well as provide contact information for the times when you require additional help.

It also provides you with the tools for you to contribute further to this project in te spirit of open source software.

We hope you enjoy working with our product!

• Git - Version control
• Eclipse - IDE
• Gradle - Build automation
• Travis, Coveralls and Codacy - Continuous integration and quality control
• GitHub - Source code hosting and issue tracking

1. Git client If you are using Linux, you should already have one installed on your command line. If you are using Windows or OS X you can use SourceTree if you are more comfortable with using a GUI.
2. JDK 1.8.0_60 or later Please use Oracle's jdk because it comes with JavaFX, which is needed for developing the application's UI.
3. Eclipse IDE
4. e(fx)clipse plugin for Eclipse Perform steps 2 onwards as listed in this page to install the plugin.
5. Buildship Gradle Integration plugin from the Eclipse Marketplace You can find Eclipse Marketplace from Eclipse's Help toolbar.

1. Click File > Import
2. Click Gradle > Gradle Project > Next > Next
3. Click Browse, then locate the project's directory
4. Click Finish

Test driven development is encouraged but not required. If possible, all of your incoming code should have 100% accompanying tests - Coveralls will fail any incoming pull request which causes coverage to fall.

Now let us explore the architecture of Uncle Jim's Discount To-do App to help you understand how it works.

The architecture diagram above explains the high-level design of the application. Here is a quick overview of each component:

• Main has only one class called MainApp. It is responsible for:

  • Bootstrapping the application at app launch by initializing the components in the correct sequence and injecting the dependencies needed for each component.
  • Shutting down the components and invoke cleanup method where necessary during shut down.

• Commons represents a collection of modules used by multiple other components

• UI: The user facing elements of tha App, representing the view layer
• Logic: The parser and command executer, representing the controller
• Model: Data manipulation and storage, representing the model and data layer

The UI, Logic and Model components each define their API in an interface of the same name and is bootstrapped at launch by MainApp.

For example, the Logic component (see the class diagram given below) defines its API in the Logic.java interface and is implemented by TodoLogic.java class.

You can see how the components interact with each other when the user issues a command by looking at the above diagram.

The diagram below shows how the EventsCenter reacts to a help command event, where the UI does not know or contain any business side logic.

The sections below will provide you with more details for each component.

3.2 UI component#

The UI component handles the interaction between the user and application. If you refer to the architecture diagram in the above sections, you will realise that the UI is responsible for passing the textual command input from the user to the Logic for execution, and displaying the outcome of the execution to the user via the GUI.

Some of the GUI view classes are shown in the UI components diagram above. You may also find the implementation for the GUI in the package seedu.todo.ui.

API : Ui.java

Referring to the diagram above, you may notice that the UI mainly consists of a MainWindow. This is where most of the interactions between the user and the application happen here. The MainWindow contains several major view elements that are discussed in greater detail below:

• CommandInputView - a text box for users to key in their commands
• CommandPreviewView - a list of suggested commands from user inputs
• CommandFeedbackView - a single line text that provides a response to their commands
• CommandErrorView - a detailed breakdown of any erroneous commands presented with a table

These view classes are represented by the CommandXView class in the UML diagram above.

The CommandController class is introduced to link the three classes together, so they can work and communicate with each other. The CommandController:

1. Obtains a user-supplied command string from the CommandInputView
2. Submits the command string to Logic for execution
3. Receives a CommandResult from Logic after the execution
4. Displays the execution outcome via the CommandResult to the CommandFeedbackView and CommandErrorView

In the meantime, the CommandPreviewView listens to any user input through an event bus ShowPreviewEvent located in the UiManager and displays the suggested commands as required.

• TodoListView - a ListView that displays a list of TaskCard
• TaskCardView - an item in the TodoListView that displays details of a specific task
• EmptyListView - a view overlapping the TodoListView which indicates that no task is displayed

Specifically, the TodoListView attaches an ObservableList of ImmutableTask from the Model and listens to any changes that are made to the ObservableList. If there are any modifications made, the TaskCard and TodoListView are updated automatically.

Also, the EmptyListView listens to the ObservableList of ImmutableTask if the list is empty. If the list is empty, the EmptyListView listens to the ObservableProperty of TaskViewFilter for the appropriate message to be displayed. You may try switching the views to see the messages yourself.

• FilterBarView - shows a list of available views users can switch to, and indicates the view that the user is currently at
• GlobalTagView - shows a global list of tags
• HelpView - shows a list of commands that users can use
• SearchStatusView - shows the information regarding a search that user has performed

All these view classes, including the MainWindow, inherit from the abstract UiPart class. You may load these view classes using the utility class UiPartLoader.

The UI component uses JavaFX UI framework. The layout of these UI parts are defined in matching .fxml files that are in the src/main/resources/view folder. For example, the layout of the CommandInputView is specified in CommandInputView.fxml

Other than through CommandResult and ObservableList, you may also invoke changes to the GUI outside the scope of UI components by raising an event. UiManager will then call specific view elements to update the GUI accordingly. For example, you may show the HelpView by raising a ShowHelpPanel via the EventsCentre.

3.3 Logic component#

API : Logic.java

You can think of the logic component as the glue sitting between the UI and the data model, or as the controller in the traditional MVC pattern. All subcomponents in logic are stateless, which reduces complexity and makes it easier to reason about. Our application uses the thin controller/fat model design pattern, and therefore we delegate as much of the data manipulation and state handling to the model. Logic consists of three separate subcomponents, each of which also defines their API using interfaces or abstract classes:

• Parser - turns user input into command and arguments
• Dispatcher - maps parser results to commands
• Command - validates arguments and execute command

When the Logic component is instantiated, each of these subcomponents is injected via dependency injection. This allows them to be tested more easily as the dependencies can be replaced with stub implementations.

The flow of a command being executed is:

1. Logic parses the user input into a ParseResult object
2. The ParseResult is sent to the dispatcher which instantiates a new Command object representing the command the user called
3. Logic binds the model and arguments to the Command object and executes it
4. The command execution can affect the Model (e.g. adding a person), and/or raise events.

Given above is the Sequence Diagram for interactions within the Logic component for the execute("delete 1") API call. See the implementation section below for the implementation details of the logic component.

3.4 Model component#

API : Model.java

The model component represents the application's state and data layer. It is implemented by TodoModel, which is a composite of of the individual data models for the application, as well as higher level information about the state of the application itself, such as the current view and the undo/redo stack. Model has two subcomponents:

• TodoList - represents the todolist tasks
• UserPrefs - represents saved user preferences

Each individual data model handles their own CRUD operations, with the Model acting as a simplified and uniform interface for external components to work with. Each of the data model holds an injectable Storage object that exposes a simple interface for reading and writing to the appropriate storage mechanism.

To avoid tight coupling with the command classes, the model exposes only a small set of generic functions. The UI component binds to the model through a set of getters, such as getObservableList, which expose JavaFX Property objects that the UI can listen to for changes.

The model ensure safety by exposing as much of its internal state as possible as immutable objects using interfaces such as ImmutableTask.

The storage component represents the persistence layer of the data. It is implemented by TodoListStorage which holds and contains ImmutableTodoList. Similarly, JsonUserPrefsStorage stores the user preferences.

Both classes implement FixedStorage, which exposes methods to read and save data from storage. Users can choose to move their storage file, hence MovableStorage is exposed to allow them to do so. User preferences cannot be exported.

• UnmodifiableObservableList: Used by the UI component to listen to changes to the data through the Observer pattern.
• Events: Used by components to marshal information around and inform other components that things have happened. (i.e. a form of Event Driven design)
• LogsCenter: Used by many classes to write log messages to the App's log file.

• TimeUtil: Used by Ui to display time that is readable and user friendly.
• XmlUtil: Used by storage to save and read .xml files.

• IllegalValueException: Used by Logic and Model internally to signal that a single value is invalid
• ValidationException : Used by Logic and Model classes to signal that the command or model parsed is invalid.

See the Logic component architecture section for the high level overview of the Logic component.

The parser tokenizes the user input by whitespace characters then splits it into three parts:

• Command string - the first word of the user input
• Positional argument string - everything from the command to the first flag
• Named argument Map<String, String> - a map of flags to values

For example, the command add The Milk /d tomorrow 3pm /p will produce

command: "add"
positional: "The Milk" 
named: 
  d: "tomorrow 3pm"
  p: "" # Empty String

This is then passed on to the dispatcher.

If you need to do additional argument validation, you can also override the validateArgument command, which is run after all arguments have been set.

The generic type T represents the return type of the command argument. To implement a new argument type, extend the abstract base class Argument, then implement the setValue function. Remember to call the super class's setValue function so that the required argument check works.

• The logging level can be controlled using the logLevel setting in the configuration file (See Configuration)
• The Logger for a class can be obtained using LogsCenter.getLogger(Class) which will log messages according to the specified logging level
• Currently log messages are output through: Console and to a log file.
• The logs roll over at 5MB such that every log file is smaller than 5MB. Five log files are kept, after which the oldest will be deleted.

To use the logger in your code, simply include

private static final Logger logger = LogsCenter.getLogger(<YOUR CLASS>.class);

at the top of your class, and replace <YOUR CLASS> with the class the logger is used in.

We have two types of tests:

1. GUI Tests - These are System Tests that test the entire App by simulating user actions on the GUI. These are in the guitests package.

2. Non-GUI Tests - These are tests not involving the GUI. They include,

   1. Unit tests - targeting the lowest level methods/classes.
      e.g. seedu.todo.commons.UrlUtilTest
   2. Integration tests - that are checking the integration of multiple code units (those code units are assumed to be working).
      e.g. seedu.todo.model.TodoModelTest
   3. Hybrids of unit and integration tests. These tests are checking multiple code units as well as how the are connected together.
      e.g. seedu.todo.logic.BaseCommandTest

• guitests - the actual test script that contains sequences of user actions
• guitests.guihandles - view handles that provide direct access to the contents of the displayed view elements

The GuiHandle class allows you to search for your view elements by their id, and you may retrieve the contents of the view element just like how you do so for any JavaFX view nodes.

You may view sample codes from handles such as TaskCardViewHandle and CommandErrorViewHandle in the guitests.guihandles package.

All our GUI JUnit tests are inherited from TodoListGuiTest. The TodoListGuiTest class provides useful methods based on the TestFX library that makes automation easier. You may refer to the TestFX documentation for more details.

See UsingGradle.md to learn how to run tests in headless mode.

We use Gradle for build automation. Gradle handles project dependencies, build tasks and testing. If you have configured Eclipse by importing the project as shown in the setting up section Gradle should already be properly configured and can be executing from within Eclipse to build, test and package the project from the Run menu.

See the appendix Using Gradle for all of the details and Gradle commands.

1. Update the Version number in MainApp.java
2. Generate a JAR file using Gradle
3. Tag the repo with the version number. e.g. v0.1
4. Crete a new release using GitHub and upload the JAR file you created
5. Update README to link to the new release

To add a new dependency, look for instructions on the project's documentation for Gradle configuration required. For most projects it will look something like this:

// https://mvnrepository.com/artifact/org.mockito/mockito-all
compile group: 'org.mockito', name: 'mockito-all', version: '2.0.2-beta'

This should be copied into the dependencies section of the build.gradle file. If you wish to, you can split the version string out so that the shorter compile property can be used instead, but this is not strictly necessary.

project.ext {
    // ... other variables 
    mockitoVersion = '8.40.11'
}

dependencies {
    // .. other dependencies
    compile "org.mockito:mockito-all:mockitoVersion"
}

After that rerun the Gradle build command and make sure the file has been edited properly, then right click on the project folder in Eclipse, select Gradle > Refresh Gradle Project. You should now be able to use the package in your code. Remember to inform all other team members to refresh their Gradle Project when the commit is merged back into master.

1. Make sure you have Python 3.5+ installed. Run python3 --version to check that it is installed correctly.
2. Install the dependencies - pip3 install markdown pygments beautifulsoup4
3. Run the script from the project root - python3 docs/build/converter.py

For example,

public class YourCommand extends BaseCommand {
    // TODO: Define additional parameters here
    private Argument<Integer> index = new IntArgument("index").required();

    @Override
    protected Parameter[] getArguments() {
        // TODO: List all command argument objects inside this array
        return new Parameter[]{ index };
    }
}

is produced by

``` java
public class YourCommand extends BaseCommand {
    // TODO: Define additional parameters here
    private Argument<Integer> index = new IntArgument("index").required();

    @Override
    protected Parameter[] getArguments() {
        // TODO: List all command argument objects inside this array
        return new Parameter[]{ index };
    }
}
```

The syntax for this the block above is

!!! warning
    This is an example of an admonition block

warning is the style of the box, and also used by default as the title. To add a custom title, add the title after the style in quotation marks.

!!! warning "This is a block with a custom title"
    This is an example of an admonition block

The following styles are available

<img src="..." alt="...">

<figcaption>
  The sequence of function calls resulting from the user input 
  <code>execute 1</code>
</figcaption>

The document processor will automatically wrap the <figcaption> and the preceding element in a <figure> element and automatically add a count to it, producing the following code:

<figure>
  <img src="..." alt="...">

  <figcaption>
    <strong>Figure 2.</strong>
    The sequence of function calls resulting from the user input 
    <code>execute 1</code>
  </figcaption>
</figure>

Note that Markdown is not processed inside HTML, so you must use HTML to write any additional inline markup you need inside the caption.

1. User types out an event with start time, end time and location
2. TodoApp adds event with specified fields and saves it to disk

Use case ends.

Extensions

1a. The task has no title

1a1. TodoApp shows an error message
Use case resumes at step 1

1b. The task's date field is empty

1b1. TodoApp creates a task with no start and end date
Use case resumes at step 2

1c. The task has a start time later than end time

1c1. TodoApp assumes the dates are inverted
Use case resumes at step 2

1d. The event's timing overlaps with an existing event's timing

1d1. TodoApp displays a warning to the user that he has another event at the same time
Use case resumes at step 2

1. User enters a task while specifying a deadline for the task.
2. TodoApp creates new todo item with deadline specified and saves it to disk

Use case ends.

Extensions

1a. The task has no title

1a1. TodoApp shows an error message
Use case resumes at step 1

1b. The task's date field is empty

1b1. TodoApp creates a task with no deadline
Use case ends

1. User enters a task with a recurring time period
2. TodoApp creates a new recurring todo item with the specified time period
3. At the start of the specified time period (eg. every week, month) TodoApp creates a copy of the original task for the user

Use case ends.

Extensions

2a. The given recurring time period is invalid

2a1. TodoApp shows an error message
Use case resumes at step 1

1. User requests to see a list of uncompleted tasks.
2. TodoApp shows a list of uncompleted tasks.
3. User marks complete a specific task in the list.
4. TodoApp marks the task as complete by striking through the task and saving its new state to disk

Use case ends.

Extensions

1a. User uses another method to list tasks (e.g. search)

1a1. TodoApp shows the list of tasks requested
Use case resumes at step 2

2a. The list is empty

1a1. TodoApp informs the user the list is empty
Use case ends

3a. The given index is invalid

3a1. TodoApp shows an error message
Use case resumes at step 2

3b. The given index is a task which has already been completed

3b1. TodoApp informs the user the task has already been completed Use case ends

1. User requests to delete a specific task from the list
2. TodoApp deletes the person

Use case ends.

Extensions

1a. The given index is invalid

1a1. TodoApp shows an error message
Use case resumes at step 1

1. User requests to view specific tab
2. TodoApp shows a list of tasks under specific tab

Use case ends.

Extensions

1a. User enters invalid view (eg. a view that doesn't exist )

1a1. TodoApp shows an error message
Use case ends

1. User searches for task with specific tag or fragmented title
2. TodoApp returns a list of tasks matching search fragment

Use case ends.

Extensions

1a. User enters an invalid tag/search fragment

1a1. TodoApp returns an empty list
Use case ends

Extensions

2a. List returned is empty

Use case ends

3a. User enters invalid task index

3a1. TodoApp shows error message indicating invalid index
Use case resumes at Step 2

3b. User enters invalid arguments to edit fields

3b1. TodoApp shows error message indicating invalid fields
Use case resumes at Step 2

1. User searches for specific task to pin using the find command
2. TodoApp returns a list of tasks matching the search query
3. User selects a specific task to pin
4. TodoApp pins selected task and updates the storage file on disk

Use case ends.

Extensions

2a. List returned by TodoApp is empty

Use case ends

3a. Selected task is already pinned

3a1. TodoApp unpins selected task Use case ends

3b. User provides an invalid index

3b1. TodoApp shows an error message
Use case resumes at Step 3

Extensions

2a1. The user calls the undo command without having made any changes

2a1. TodoApp shows an error message
Use case ends

1. work on any mainstream OS as long as it has Java 8 or higher installed.
2. use a command line interface as the primary input mode
3. have a customizable colour scheme.
4. be able to hold up to 100 todos, events and deadlines.
5. come with automated unit tests.
6. have competitive performance with commands being executed within 5 seconds of typing into the CLI
7. be open source.

Very flexible and easy to use, but hard to organise tasks on them. Also, data can only be saved locally.

Online/Cloud Based Todo lists

Apps such as Google Calendar, Asana and Trello offer a wide range of effective features that help manage your To-do lists. However, most of them require heavy mouse usage and the constant context switching might break user concentration. Our target audience are users who prefer not use the mouse at all, and that makes some of these applications almost unusable. Also, it is hard to sync without a constant internet connection.

• Running tests
• Managing library dependencies
• Analyzing code for style compliance
• Packaging code for release

The gradle configuration for this project is defined in the build script build.gradle.

• On Windows :gradlew <task1> <task2> ... e.g. gradlew clean allTests
• On Mac/Linux: ./gradlew <task1> <task2>... e.g. ./gradlew clean allTests

To force Gradle to create the JAR file even if the current one is up-to-date, you can 'clean' first.
e.g. ./gradlew clean shadowJar

guiTests - Runs all tests in the guitests package

nonGuiTests - Runs all non-GUI tests in the seedu.address package

headless - Sets the test mode as headless. The mode is effective for that Gradle run only so it should be combined with other test tasks.

Here are some examples:

• ./gradlew headless allTests -- Runs all tests in headless mode
• ./gradlew clean nonGuiTests -- Cleans the project and runs non-GUI tests

compileJava - Checks whether the project has the required dependencies to compile and run the main program, and download any missing dependencies before compiling the classes.

See build.gradle > allprojects > dependencies > compile for the list of dependencies required.

compileTestJava - Checks whether the project has the required dependencies to perform testing, and download any missing dependencies before compiling the test classes.

See build.gradle > allprojects > dependencies > testCompile for the list of dependencies required.