iGrad - Developer Guide

Section by: Nathanael Seen

The Credits class maintains 2 integers; creditsRequired and creditsFulfilled, for storing both the total number of course credits (MCs) required for graduation, and also the number credits the user has fulfilled thus far, respectively.

Also, it some public validation methods (isValidCreditsFulfilled() and isValidCreditsFulfilled()) which is used in the constructor for constructing a 'valid' Credits object.

The following constraints defines a 'valid' Credits object:

Note that creditsFulfilled can be more than or equals to creditsRequired, as it is possible that a student 'over-fulfills' the graduation requirements in her course.

The following are some noteworthy details on the Credits class/object:

Section by: Teri

Semesters stores the total semesters and remaining semesters that a user has in the course.

The following are some noteworthy details on the Semesters class/object:

In this section, we describe how computeCredits(requirement: Requirement[]) works to recompute the latest Credits.

As previously mentioned, this method is invoked everytime there is a possible change in the total course Credits.

This might be caused through the following commands:

Now, we have specified the possible scenarios where computeCredits(…​) might have to be invoked to update Credits of CourseInfo, however we have not described how it actually works.

As from our previous discussion, we note that creditsFulfilled and creditsRequired is computed through summing up the creditsFulfilled and creditsRequired for the individual Requirements.

More formally, the interactions between the various classes, for the computation to be performed are as such:

Similar to Section 3.1.1.3, “Compute Credits”, Cap has to be updated frequently, each time module information in coursebook changes, and the computeCap(…​) method facilitates the recomputation of the updated Cap.

The diagram below describes the interactions between the various classes, as the computation is performed:

We note that from above, CourseInfo does most of the interfacing with other classes, and the rest of the classes don’t interact with each another.

In summary, the following steps are performed as computeCap(…​) is invoked:

(For each Module in the moduleList):

Users can edit their course info, which are Name and Semesters by using the course edit command.

Here is how the courseInfo class updates when name and semesters of course is edited.

When a user edits a course, the user has to specify the prefix n/ for Name or s/ prefix for Semesters.

Then the application proceeds to do the following steps:

Users can get an automatic calculation of their desired C.A.P. by using the course achieve command and entering their desired Cap.

The computation of C.A.P. is done through computeEstimatedCap in courseInfo which uses Semesters and Cap of courseInfo.

When a user wants to calculate achievable C.A.P., the user has to specify the prefix c/ for Cap. Then the application proceeds to do the following steps:

The below is a detailed description of what happens inside the Model:

Invalid and Unachievable C.A.P.

It is possible that a calculated Cap to achieve is not a valid Cap. In such situations, an exception is thrown within the computeEstimatedCap command and it is caught in the CourseAchieveCommand. User will be given feedback that the desired C.A.P. is not achievable.

The figure below illustrates this:

Therefore, there are three types of result displayed to User:

The "automatic" addition of modules allows users to add up to 10 modules at once with all non-optional values filled in. This is done by making a HTTP GET request to the NUSMods API and fetching the module data given in a JSON format.

The automatic filling in of module details on addition of a new module is facilitated by NusModsRequester. It creates a new instance of GetRequestManager which it relies on to make a request to the NUSMods API. Upon receiving a response, it creates an instance of JsonParsedModule.

JsonParsedModule parses the JSON object given in the response of the initial request and stores the following values:

The created JsonParsedModule object is then converted into a Module object, which is subsequently added to the courseBook via the method addModule of the ModelManager.

Figure 22, “Module Add Auto Sequence Diagram” illustrates this:

Most of the design considerations arose as a result of having to make a network request.

A secondary module addition feature

As with all network requests, this feature might not work as intended in certain circumstances. Possible cases are:

In such situations, it becomes difficult or impossible to carry out the addition of modules using this command. Therefore, this feature was built on top of the primary module add feature, ensuring that the user could still manage to add modules even when faced with the issues as listed above.

The use case for this situation is as follows:

System: iGrad

Use case: UCM1 - Add module via NUSMods

Actor: User, NUSMods

MSS:

Use case ends.

Extensions:

5a. NUSMods does not respond with the requested data.

5a1. User adds module manually

Messages for individual modules

As this feature allows a user to add modules by batches, it is possible that one or more modules in the batch are invalid or require warning messages. In order to facilitate this, the processing of the list of modules and the generation of error and warning messages were done in parallel. This was because if the list of modules was processed first, modules with issues would be filtered out without notice, leading to a confusing user experience.

Improving the user experience [PROPOSED]

Due to network latency - the Round Trip Time taken from when a request is made to when a response is received - the user might experience a situation where it appears that the application has stopped working.

For a large batch of modules, the application might also display a not responding label in the toolbar. In order to improve the user experience, it is ideal that a loader be displayed when waiting for the response from the server. However, due to time constraints, this was not implemented.

Getting the latest data [DEPRECATED]

Past iterations of this feature made a maximum of two requests for one module. The first request would attempt to get the module for the current academic year, whilst the second request attempted to get the module for the previous academic year, in the event the module for the current academic year was not available.

This process is illustrated in Figure 25, “Previous implementation of Module Add Auto”. However, it was decided that the benefits of making a maximum of one request outweighed that of getting the latest module information and thus, currently only one request is made.

The average number of modules a student has for a 4 year program in NUS is 40. The application window, however, can display a maximum of 9 modules for a 17" screen and considerably less for smaller displays. As a result, it is imperative that users have a way to filter modules so that only what is required is displayed.

The filtering of modules is done by calling the execute function of ModuleFilterCommand.ModuleFilterCommand takes in optional parameters Semester, Credits, Grade and an operator, which could be AND or OR. The ModuleFilterCommand then calls updateFilteredModuleList on the Model such that the Model updates the filteredList based on the predicates provided. The ModuleFilterCommand then calls getFilteredModuleList() to check if the filter was applied successfully.

The matching is done by the functions checkSemesterMatch(Module m), checkCreditsMatch(Module m) and checkGradeMatch(Module m). Unlike the other two functions, checkCreditsMatch(Module m) does not check if the actual credits for a module is present since the credits field in a module is compulsory.

The AND operator specifies that the provided parameters be chained with the logical and operator.

The OR operator specifies that provided parameters be chained with the logical or operator.

When the filter command is issued, the Model updates the module list based on the predicate given. Figure 26, “Module Filter Sequence Diagram” illustrates this sequence of events:

Resetting the state

When this command is issued, the modules that do not match the predicate given will disappear from the module list. It is thus necessary to allow the user to issue a new command in order to view all the modules again.

Whilst creating a new command such as module reset was proposed, it was decided that a new command would only serve to make the user experience more complicated than it should be.

Therefore, an allowance was made for module filter to reset the state when receiving no parameters, a divergence from the way other functions handled the situation of empty parameters.

Figure 27, “Module Filter Activity Diagram” illustrates this clearly:

The filteredList of modules therefore takes three general states (see Figure 28, “Module Filter State Diagram”):

Displaying Filter State [PROPOSED]

An issue with the filtering of modules is that when the current state is not obvious, the user might lose track of what the module list is filtering on. To solve this problem, it would be an improvement to display the current state prominently to the user.

This feature enables students to mark a module which they have completed with a certain grade. Once a module is marked 'done', it would be counted to graduation requirements.

Trivial as it might seem, there are actually quite a number of coursebook data which needs to be updated when a module is marked 'done'.

This includes the Module itself, the various Requirements in the UniqueRequirementList, and the CourseInfo.

The following diagram illustrates this:

As from the above, there are two possible scenarios; either a Module belongs to at least one Requirement or that it does not belong to any Requirement.

In the latter case, calls to methods which update CourseInfo would be immediately invoked, bypassing the updating of the Requirement(s).

The requirement add command adds a Requirement to the Course. The Credits information held by the Course is updated to reflect the total modular credits required to complete the course.

When a user enters a requirement add command, the parameters specified by the user, i.e. the requirement title and the requirement credits required to fulfill the Requirement, are passed to the LogicManager, CourseBookParser and subsequently into the RequirementAddCommandParser where the parameters are extracted and parsed into Title and Credits objects.

The RequirementCode is generated at this stage by using the first letter of every word in the title parameter passed in, upper-cased. For example, if the title provided is "Computer Science Foundation", the RequirementCode generated would be CSF. Similarly, if the title provided is "3Computer Science 4Foundation", the RequirementCode generated would still be CSF because non-alphabets in the title are ignored.

The parsed Title, Credits and the generated RequirementCode are used to create a RequirementAddCommand object, which is later executed by the LogicManager, as shown in the Requirement Add Sequence Diagram below.

When the command is executed by the LogicManager, the new Requirement is created and stored in the CourseBook through the Model.

This feature allows Module(s) to be assigned or mapped under a Requirement.

We note that as like the module done command, a few pieces of information in the coursebook would have to be updated.

The command-parsing-execute mechanism is largely similar to requirement add the above, however, we would like to focus more on the activities (such as validations, etc) that happens at the Model side.

The following diagram details this:

Hence as per the diagram, we observe that modules are assigned to a Requirement on the following two conditions: