Revision as of 15:39, 30 November 2016

DHIS2 app for sharing graphs, maps and tables to Facebook/Twitter

Group project in INF5750 - Open Source Development.

Group members

Rune Johan Borgli (runejb@uio.no)
Matias Hermanrud Fjeld (matiashf@student.matnat.uio.no)
Pål Mathias Brandsvoll (paalmbr@uio.no)
Joakim Misund (joakimmi@student.matnat.uio.no)

Repository: https://github.uio.no/matiashf/groupname.js

Building

Run npm run-script build to create groupname.js.zip. The resulting zipfile can then be uploaded to DHIS2 under App Management.

Getting started

This webapp runs on node.js locally, and uses the DHIS2 demo server. First, you must install the correct versions of NPM and Node.js.

Ubuntu

The npm and node versions in the official Ubuntu repositories are too old for running this webapp. Install the correct versions of node and npm with the following commands:

curl -sL https://deb.nodesource.com/setup_7.x | sudo bash -
sudo apt-get install -y nodejs build-essential

OS X

which brew >/dev/null || /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew install node

Run the webapp

Install node dependencies and run the development server

npm install
npm start

Open your browser and go to http://localhost:8081/.

Other commands

To run the tests one time

npm test

To run the tests continuously on file changes (for your BDD workflow)

npm run test-watch

To generate a coverage report for the tests

npm run coverage

To check the code style for both the JS and SCSS files run

npm run lint

Troubleshooting

Make sure you have at least the following versions of node and npm.

Node version v5.6.0 or higher
npm version 3.8.0 or higher

Use the following commands to check your current versions

node -v
npm -v

Tools etc.

Frameworks... and libraries

React

React is the view part of the front-end applications, it has a component based architecture. At DHIS2 we also use JSX syntax that is generally used with React.

d2, d2-ui

d2 is the DHIS2 abstraction library that allows you to communicate with the DHIS2 api in a programatic way. d2-ui is the ui component library that is build on top of d2 to allow reuse of common components that are used within DHIS2 applications. d2-ui also contains our own application wiring code through its stores and actions.

material-ui

d2-ui makes use of material-ui for rendering more basic components like TextFields and Lists. It is therefore quite useful to look into this library too when building DHIS2 apps and making use of d2-ui.

Workflow

Webpack

Webpack is a module bundler that allows the use of plugins to do various other things. We make use of webpack for the following things:

Bundling the files up into a single file. (The primary webpack use case)
Transpiling ES2015 and React JSX code to ES5 syntax so it runs in the browser. (This is done using Babel.)
Loading Scss files. Scss is a css pre-processor that has quite some fancy features as variables, nesting of style declarations etc.
Minifying the bundled file to reduce file size
Remove duplicate dependencies

To make the development a more interactive experience we use webpack-dev-server to provide us with a development server that watches the project files and refreshes the browser when changes are detected.

npm

Npm is used as both a dependency management tool as a workflow manager through its scripts as can be seen in the package.json. It provides convenience commands to kick off various tasks. These tasks are mentioned above as npm run <command>, npm start, npm test, etc.

linting

To make sure the code is in line with the code style, we use eslint as a static style checker. To a large degree we follow the airbnb Javascript styleguide. We do however have slight modifications which are defined in our own eslint-config. (eslint-config-dhis2)

Testing

mocha, chai, sinon

Mocha is a test runner that runs the unit tests. Chai is the assertion library that is used to do assertions within those tests. It supports various styles. At DHIS2 we generally tend to go with the expect/BDD variant. Sinon is used to do mocking within the tests and to fake HTTP requests where needed. The interesting things to look at for sinon are it's spies and stubs calls and the fakeServer.

enzyme

Enzyme tool to make testing of React components easier. They provide a pretty clean api to get information from your rendered react components.

Summary of requirements

Implement listing and sharing of favorites to Facebook and Twitter as a DHIS2 webapp using javascript.

Required features:

List favorites by type (maps, charts, tables)
Share favorite to Facebook
Share favorite to Twitter

Desired features:

Show enlarged favorite
Sorting
Filtering/searching

Architecture / Tools

We will implement a DHIS2-webapp based on DHIS2 App skeleton. We will use React for code structure, D2 to communicate with the backend, and D2-ui + material-ui for the frontend. Using Webpack, we will play around with ES2016 using Babel. Also, SASS is cool!

While developing we will set up DHIS2-live locally (alternatively depend on [DHIS2-play](https://play.dhis2.org/)).

Milestones / Time Schedule

Milestone 1: 28/10 - Implementation plan
Milestone 2: 6/11 - Implement core features
Milestone 3: 13/11 - Optional features and polish
Milestone 4: 27/11 - Final delivery
Milestone 5: 7-9/12 - Group Presentation

Potential problems

Will we need image conversion for Twitter?
Should we make a responsive page?

How we are dividing tasks within the group

Coming ~1/11.

Screenshots and screen flows

Screenshot of Maps

Sreenshot of Charts

Screenshot of Table

Sreenshot of Event Charts

.

What we tried that did not work

Use the d2-library. It worked fine for maps, but not for charts. In the list-function an assertion was not passed, therefor nothing was returned. We spent 2 days on trying to fix it, but the complexity made us decide to use a selfmade solution.

Have the maps overlay google maps. DHIS has a map-plugin, but it can only be used by apps uploaded to DHIS. We tried to use the google api directly, and got it working with one map. We did not find any way to have several maps on the same page. After failing to create the map-support ourselves we found some npm-libraries, none of which worked.

Documented learning during project

Web development is tricky :D

Suggested improvements to the API

It's beautiful. Love it unconditionally. <3

@@ Line 1: / Line 1: @@
+= DHIS2 app for sharing graphs, maps and tables to Facebook/Twitter =
+Group project in INF5750 - Open Source Development.
 == Group members ==
 * Rune Johan Borgli (runejb@uio.no)
@@ Line 7: / Line 11: @@
 Repository: https://github.uio.no/matiashf/groupname.js
-==How to run:==
+= Building =
+Run <code>npm run-script build</code> to create <code>groupname.js.zip</code>. The resulting zipfile can then be uploaded to DHIS2 under ''App Management''.
-*DHIS2 app for sharing graphs, maps and tables to Facebook/Twitter
+== Getting started ==
+This webapp runs on node.js locally, and uses the DHIS2 demo server. First, you must install the correct versions of NPM and Node.js.
-Group project in INF5750 - Open Source Development.
+=== Ubuntu ===
+The npm and node versions in the official Ubuntu repositories are too old for running this webapp. Install the correct versions of node and npm with the following commands:
+ curl -sL <nowiki>https://deb.nodesource.com/setup_7.x</nowiki> | sudo bash -
+ sudo apt-get install -y nodejs build-essential
-*Building
+=== OS X ===
+ which brew >/dev/null || /usr/bin/ruby -e "$(curl -fsSL <nowiki>https://raw.githubusercontent.com/Homebrew/install/master/install</nowiki>)"
-Run `npm run-script build` to create `groupname.js.zip`. The resulting
+ brew install node
-zipfile can then be uploaded to DHIS2 under *App Management*.
-*Getting started
-This webapp runs on node.js locally, and uses the [DHIS2 demo server](https://play.dhis2.org/demo/). First, you must install the correct versions of NPM and Node.js.
-*Ubuntu
-The npm and node versions in the official Ubuntu repositories are too
-old for running this webapp. Install the correct versions of node and
-npm with the following commands:
-```sh
-curl -sL https://deb.nodesource.com/setup_7.x | sudo bash -
-sudo apt-get install -y nodejs build-essential
-```
-*OS X
-```sh
-which brew >/dev/null || /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-brew install node
-```
-*Run the webapp
+== Run the webapp ==
 Install node dependencies and run the development server
+ npm install
+ npm start
+Open your browser and go to <code><nowiki>http://localhost:8081/</nowiki></code>.
-```sh
+== Other commands ==
-npm install
-npm start
-```
-Open your browser and go to `http://localhost:8081/`.
-*Other commands
 To run the tests one time
-```sh
+ npm test
-npm test
-```
 To run the tests continuously on file changes (for your BDD workflow)
-```sh
+ npm run test-watch
-npm run test-watch
-```
 To generate a coverage report for the tests
-```sh
+ npm run coverage
-npm run coverage
-```
 To check the code style for both the JS and SCSS files run
-```sh
+ npm run lint
-npm run lint
-```
-*Troubleshooting
+== Troubleshooting ==
+Make sure you have at least the following versions of <code>node</code> and <code>npm</code>.
-Make sure you have at least the following versions of `node` and `npm`.
+* Node version v5.6.0 or higher
+* npm version 3.8.0 or higher
-+ Node version v5.6.0 or higher
+Use the following commands to check your current versions
-+ npm version 3.8.0 or higher
+ node -v
+ npm -v
-Use the following commands to check your current versions
+= Tools etc. =
-```sh
-node -v
-npm -v
-```
-*Tools etc.
+== Frameworks... and libraries ==
-* Frameworks... and libraries
+=== React ===
-* React
+React is the ''view'' part of the front-end applications, it has a component based architecture. At DHIS2 we also use JSX syntax that is generally used with React.
-[React](https://facebook.github.io/react/) is the _view_ part of the front-end applications, it has a component based architecture. At DHIS2 we also use JSX syntax that is generally used with React.
-*d2, d2-ui
+=== d2, d2-ui ===
-[d2](https://github.com/dhis2/d2) is the DHIS2 abstraction library that allows you to communicate with the DHIS2 api in a programatic way. [d2-ui](https://github.com/dhis2/d2-ui) is the ui component library that is build on top of d2 to allow reuse of common components that are used within DHIS2 applications. d2-ui also contains our own application wiring code through its _stores_ and _actions_.
+d2 is the DHIS2 abstraction library that allows you to communicate with the DHIS2 api in a programatic way. d2-ui is the ui component library that is build on top of d2 to allow reuse of common components that are used within DHIS2 applications. d2-ui also contains our own application wiring code through its ''stores'' and ''actions''.
-* material-ui
+=== material-ui ===
-d2-ui makes use of [material-ui](http://www.material-ui.com) for rendering more basic components like TextFields and Lists. It is therefore quite useful to look into this library too when building DHIS2 apps and making use of d2-ui.
+d2-ui makes use of material-ui for rendering more basic components like TextFields and Lists. It is therefore quite useful to look into this library too when building DHIS2 apps and making use of d2-ui.
-* Workflow
+== Workflow ==
-* Webpack
+=== Webpack ===
 Webpack is a module bundler that allows the use of plugins to do various other things. We make use of webpack for the following things:
-+ Bundling the files up into a single file. (The primary webpack use case)
+* Bundling the files up into a single file. (The primary webpack use case)
-+ Transpiling ES2015 and React JSX code to ES5 syntax so it runs in the browser. (This is done using [Babel](http://babeljs.io).)
+* Transpiling ES2015 and React JSX code to ES5 syntax so it runs in the browser. (This is done using Babel.)
-+ Loading [Scss](http://sass-lang.com) files. Scss is a css pre-processor that has quite some fancy features as variables, nesting of style declarations etc.
+* Loading Scss files. Scss is a css pre-processor that has quite some fancy features as variables, nesting of style declarations etc.
-+ Minifying the bundled file to reduce file size
+* Minifying the bundled file to reduce file size
-+ Remove duplicate dependencies
+* Remove duplicate dependencies
+To make the development a more interactive experience we use <code>webpack-dev-server</code> to provide us with a development server that watches the project files and refreshes the browser when changes are detected.
-To make the development a more interactive experience we use `webpack-dev-server` to provide us with a development server that watches the project files and refreshes the browser when changes are detected.
+=== npm ===
+Npm is used as both a dependency management tool as a ''workflow manager'' through its <code>scripts</code> as can be seen in the package.json. It provides convenience commands to kick off various tasks. These tasks are mentioned above as <code>npm run <command></code>, <code>npm start</code>, <code>npm test</code>, etc.
-* npm
+=== linting ===
-[Npm](https://www.npmjs.com) is used as both a dependency management tool as a _workflow manager_ through its `scripts` as can be seen in the [package.json](https://github.com/dhis2/app-skeleton/blob/master/package.json#L6-L14). It provides convenience commands to kick off various tasks. These tasks are mentioned above as `npm run <command>`, `npm start`, `npm test`, etc.
+To make sure the code is in line with the code style, we use eslint as a static style checker. To a large degree we follow the airbnb Javascript styleguide. We do however have slight modifications which are defined in our own eslint-config. (eslint-config-dhis2)
-* linting
+== Testing ==
-To make sure the code is in line with the code style, we use [eslint](http://eslint.org) as a static style checker. To a large degree we follow the [airbnb Javascript styleguide](https://github.com/airbnb/javascript). We do however have slight modifications which are defined in our own eslint-config. ([eslint-config-dhis2](https://github.com/dhis2/eslint-config-dhis2/blob/master/.eslintrc))
-* Testing
+=== mocha, chai, sinon ===
+Mocha is a test runner that runs the unit tests. Chai is the assertion library that is used to do assertions within those tests. It supports various styles. At DHIS2 we generally tend to go with the expect/BDD variant. Sinon is used to do mocking within the tests and to fake HTTP requests where needed. The interesting things to look at for sinon are it's spies and stubs calls and the fakeServer.
-* mocha, chai, sinon
+=== enzyme ===
-[Mocha](https://mochajs.org) is a test runner that runs the unit tests. [Chai](http://chaijs.com) is the assertion library that is used to do assertions within those tests. It supports various styles. At DHIS2 we generally tend to go with the [expect/BDD](http://chaijs.com/api/bdd/) variant. [Sinon](http://sinonjs.org) is used to do mocking within the tests and to fake HTTP requests where needed. The interesting things to look at for sinon are it's [spies](http://sinonjs.org/docs/#spies) and [stubs](http://sinonjs.org/docs/#stubs) calls and the [fakeServer](http://sinonjs.org/docs/#fakeServer).
+Enzyme tool to make testing of React components easier. They provide a pretty clean api to get information from your rendered react components.
-* enzyme
-[Enzyme](https://github.com/airbnb/enzyme) tool to make testing of React components easier. They provide a pretty clean api to get information from your rendered react components.
 == Summary of requirements ==
 Implement listing and sharing of favorites to Facebook and Twitter as a DHIS2 webapp using javascript.

Difference between revisions of "Groupname.js"