Difference between revisions of "MFL"

From mn/ifi/inf5750
Jump to: navigation, search
 
(34 intermediate revisions by 4 users not shown)
Line 10: Line 10:
 
== Product description ==
 
== Product description ==
  
MFL is a DHIS2 application for searching, browsing and proposing changes to organisation units, as requested by the [[Master Facility List]] assignment. Our understanding of the assignment is reflected by the following user stories:
+
MFL is a DHIS2 application for searching, browsing and proposing changes to organisation units, as requested by the [[Master Facility List]] assignment.
  
 
====User stories====
 
====User stories====
 +
Our understanding of the assignment is reflected by the following user stories:
 
*As a user I want to find specific organization units
 
*As a user I want to find specific organization units
 
**As a user I want to search for organization units by name
 
**As a user I want to search for organization units by name
Line 20: Line 21:
 
* As a user I want to see detailed information on a particular organization unit
 
* As a user I want to see detailed information on a particular organization unit
 
** As a user I want to see all attributes of a particular organization unit
 
** As a user I want to see all attributes of a particular organization unit
** As a user I want to see the GIS coordinates of a particular organization unit
+
** As a user I want to see the location of a particular organization unit
 
** As a user I want to see which organization unit groups a particular organization belongs to
 
** As a user I want to see which organization unit groups a particular organization belongs to
 
** As a user I want to see what data sets are assigned to a particular facility
 
** As a user I want to see what data sets are assigned to a particular facility
Line 33: Line 34:
  
 
==== Mockups ====
 
==== Mockups ====
https://app.moqups.com/nicoleke@student.matnat.uio.no/FGj4VwY2Xd/view
+
Our initial UI/UX approach is reflected by the following mockups:
 +
 
 +
[https://app.moqups.com/nicoleke@student.matnat.uio.no/FGj4VwY2Xd/view MFL on Moqups.com]
 +
 
 +
==== Screenshots ====
 +
The screenshot shows the starting page of our application. In the sidebar filters for organization units can be set, the results are immediately visible.
 +
[[File:MainPage_MFL.png|538x538px|Screenshot of MFL Application]]
 +
 
 +
 
 +
The application can be found in DHIS2 under [https://inf5750.dhis2.org/demo/api/apps/Master-Facility-List/index.html#/ MasterFacilityList-Application]
  
 
== Architecture ==
 
== Architecture ==
MFL will be developed as a Single-Page Application (SPA) using Facebook's React framework. React was chosen for its ubiquitousness as well as for consistency with existing DHIS2 applications.
+
MFL is designed as a client/server application where the DHIS2 server is responsible for data storage and data access logic, whereas the client is responsible for application logic and presentation logic.
 +
 
 +
=== Client architecture ===
 +
Starting off, we really wanted to make something consistent with existing DHIS2 apps. Therefore, we looked into DHIS2 libraries such as [https://github.com/dhis2/app-skeleton dhis2/app-skeleton] and [https://github.com/dhis2/d2-ui dhis2/d2-ui]. Unfortunately, we found the documentation for some of these libraries to be lacking. So rather than using these libraries, we identified and chose some of their core underlying frameworks, most notably React, Redux and material-ui. These are also hugely popular frameworks that all of the group members were eager to learn more about.
 +
 
 +
[[File:Client architecture.png|thumb|538x538px|The client architecture of MFL]]
 +
The client is therefore developed as a Single-Page Application (SPA) using Facebook's '''React''' view framework and the '''Redux architecture'''.
 +
 
 +
At its core is a '''normalized Redux store''' that serves as a single source of truth for the application state. This state is changed by emitting actions (objects describing what happened). When actions involves API interactions, they will wait for a response before dispatching the relevant action(s).
 +
 
 +
The normalization of data in the Redux store greatly simplifies handling of the nested JSON objects returned from the DHIS2 API, as it avoid data duplication and allows different parts of the app to easily reuse data fetched by other parts.
 +
 
 +
Using React, the view part of the app has a component-based architecture. In MFL, these are divided between '''connected components''' (containers) and '''presentational components'''.
 +
 
 +
The '''connected components''' are focused on ''how things work''; they subscribe to the Redux state through its selector functions, dispatch Redux actions and pass relevant data and callback functions as props to (one or more) child components. The container components maps more or less to the different screens of the application.
  
Using React implies, among other things, a component-based UI and uni-directional data-flow.
+
The '''presentational components''' are concerned with ''how things look'' (markup and style). They are not aware of Redux, but read data and callback functions solely from passed props. This makes them reusable in different context.
  
== Timeline for development ==
+
This separation of concern makes the application easy to reason about and makes it easy for contributors to work on different parts of the app simultaneously.
  
 
== Licensing ==
 
== Licensing ==
 +
We chose to use the MIT license for our application. This license is permissive, the wording of the licenses is very simple and easy to understand.
 +
We had to check that the MIT license didn’t violate any licenses used by any framework or libraries that we use in our code. We used a license checker to check if there was any conflict.
 +
After running license-checker, this is what we got:
 +
 +
├─ MIT: 826
 +
 +
├─ ISC: 63
 +
 +
├─ BSD-3-Clause: 61
 +
 +
├─ Apache-2.0: 19
 +
 +
├─ BSD-2-Clause: 18
 +
 +
├─ BSD*: 12
 +
 +
├─ MIT*: 4
 +
 +
├─ BSD: 3
 +
 +
├─ CC-BY-4.0: 2
 +
 +
├─ Apache License, Version 2.0: 2
 +
 +
├─ Unlicense: 2
 +
 +
├─ BSD-3-Clause OR MIT: 1
 +
 +
├─ Public Domain: 1
 +
 +
├─ UNLICENSED: 1
 +
 +
├─ (WTFPL OR MIT): 1
 +
 +
├─ (BSD-2-Clause OR MIT OR Apache-2.0): 1
 +
 +
├─ WTFPL: 1
 +
 +
├─ Custom: http://example.com/base.js: 1
 +
 +
├─ (MIT AND CC-BY-3.0): 1
 +
 +
├─ LGPL-2.1+: 1
 +
 +
├─ (GPL-2.0 OR MIT): 1
 +
 +
├─ Apache*: 1
 +
 +
└─ AFLv2.1,BSD: 1
 +
 +
 +
Most of these licenses are permissive as the MIT license, Apache 2.0, BSD, CC-BY, ISC, AFL, WTFPL. The LGPL license was use in a library so we do not violate this license by our MIT. And the GPL or MIT license is a dual license so we can chose which one that should apply.
  
 
== Division of labour ==
 
== Division of labour ==
 +
* Aanund Nordskog
 +
** Search results, admin view, queries
 +
* Nicole Keppler (nicoleke@student.matnat.uio.no)
 +
** Detail view of organisation unit
 +
* Saliha Sajid (salihasa@student.matnat.uio.no)
 +
** Sidebar and Filtering
 +
* Henrik Halvorsen Hortemo (henrihho@ifi.uio.no)
 +
** API queries and state management (Redux)
  
 
== External links ==
 
== External links ==
 
[https://github.uio.no/salihasa/INF5750Project MFL on GitHub]
 
[https://github.uio.no/salihasa/INF5750Project MFL on GitHub]
 +
 +
[https://app.moqups.com/nicoleke@student.matnat.uio.no/FGj4VwY2Xd/view MFL on Moqups.com]

Latest revision as of 08:55, 6 December 2017

Group members

Aanund Nordskog (aanundjn@ifi.uio.no)

Nicole Keppler (nicoleke@student.matnat.uio.no)

Saliha Sajid (salihasa@student.matnat.uio.no)

Henrik Halvorsen Hortemo (henrihho@ifi.uio.no)

Product description

MFL is a DHIS2 application for searching, browsing and proposing changes to organisation units, as requested by the Master Facility List assignment.

User stories

Our understanding of the assignment is reflected by the following user stories:

  • As a user I want to find specific organization units
    • As a user I want to search for organization units by name
    • As a user I want to filter my search results by unit group membership
    • As a user I want to filter my search results by ancestor relationships
    • As a user I want to filter my search results by which data sets are assigned to the organization units
  • As a user I want to see detailed information on a particular organization unit
    • As a user I want to see all attributes of a particular organization unit
    • As a user I want to see the location of a particular organization unit
    • As a user I want to see which organization unit groups a particular organization belongs to
    • As a user I want to see what data sets are assigned to a particular facility
    • As a user I want to see data element and/or indicator values for the particular organisation unit for the current/last year
  • As an administrator I want to select what data elements and/or indicators to display
  • As a user I want to propose changes to organization units
    • As a user I want to propose changes to organization unit attributes
    • As an administrator I want to review submitted proposals
    • As an administrator I want to mark proposals as resolved/invalid

Mockups

Our initial UI/UX approach is reflected by the following mockups:

MFL on Moqups.com

Screenshots

The screenshot shows the starting page of our application. In the sidebar filters for organization units can be set, the results are immediately visible. Screenshot of MFL Application


The application can be found in DHIS2 under MasterFacilityList-Application

Architecture

MFL is designed as a client/server application where the DHIS2 server is responsible for data storage and data access logic, whereas the client is responsible for application logic and presentation logic.

Client architecture

Starting off, we really wanted to make something consistent with existing DHIS2 apps. Therefore, we looked into DHIS2 libraries such as dhis2/app-skeleton and dhis2/d2-ui. Unfortunately, we found the documentation for some of these libraries to be lacking. So rather than using these libraries, we identified and chose some of their core underlying frameworks, most notably React, Redux and material-ui. These are also hugely popular frameworks that all of the group members were eager to learn more about.

The client architecture of MFL

The client is therefore developed as a Single-Page Application (SPA) using Facebook's React view framework and the Redux architecture.

At its core is a normalized Redux store that serves as a single source of truth for the application state. This state is changed by emitting actions (objects describing what happened). When actions involves API interactions, they will wait for a response before dispatching the relevant action(s).

The normalization of data in the Redux store greatly simplifies handling of the nested JSON objects returned from the DHIS2 API, as it avoid data duplication and allows different parts of the app to easily reuse data fetched by other parts.

Using React, the view part of the app has a component-based architecture. In MFL, these are divided between connected components (containers) and presentational components.

The connected components are focused on how things work; they subscribe to the Redux state through its selector functions, dispatch Redux actions and pass relevant data and callback functions as props to (one or more) child components. The container components maps more or less to the different screens of the application.

The presentational components are concerned with how things look (markup and style). They are not aware of Redux, but read data and callback functions solely from passed props. This makes them reusable in different context.

This separation of concern makes the application easy to reason about and makes it easy for contributors to work on different parts of the app simultaneously.

Licensing

We chose to use the MIT license for our application. This license is permissive, the wording of the licenses is very simple and easy to understand. We had to check that the MIT license didn’t violate any licenses used by any framework or libraries that we use in our code. We used a license checker to check if there was any conflict. After running license-checker, this is what we got:

├─ MIT: 826

├─ ISC: 63

├─ BSD-3-Clause: 61

├─ Apache-2.0: 19

├─ BSD-2-Clause: 18

├─ BSD*: 12

├─ MIT*: 4

├─ BSD: 3

├─ CC-BY-4.0: 2

├─ Apache License, Version 2.0: 2

├─ Unlicense: 2

├─ BSD-3-Clause OR MIT: 1

├─ Public Domain: 1

├─ UNLICENSED: 1

├─ (WTFPL OR MIT): 1

├─ (BSD-2-Clause OR MIT OR Apache-2.0): 1

├─ WTFPL: 1

├─ Custom: http://example.com/base.js: 1

├─ (MIT AND CC-BY-3.0): 1

├─ LGPL-2.1+: 1

├─ (GPL-2.0 OR MIT): 1

├─ Apache*: 1

└─ AFLv2.1,BSD: 1


Most of these licenses are permissive as the MIT license, Apache 2.0, BSD, CC-BY, ISC, AFL, WTFPL. The LGPL license was use in a library so we do not violate this license by our MIT. And the GPL or MIT license is a dual license so we can chose which one that should apply.

Division of labour

  • Aanund Nordskog
    • Search results, admin view, queries
  • Nicole Keppler (nicoleke@student.matnat.uio.no)
    • Detail view of organisation unit
  • Saliha Sajid (salihasa@student.matnat.uio.no)
    • Sidebar and Filtering
  • Henrik Halvorsen Hortemo (henrihho@ifi.uio.no)
    • API queries and state management (Redux)

External links

MFL on GitHub

MFL on Moqups.com