SE-AMA - 2017
This is the wiki for our project, the Sharing Editor, for the course INF5750 - Open Source Development.
Name SE-AMA explained:
- SE - Sharing Editor
- AMA - Alexander, Magnus, Andrei
- Alexander Wandrup (alexanow)
- Andrei Eismont (andreiei)
- Magnus Biong Nordin (magnubn)
Project Description Requirements
For our assignment we chose work on the Sharing Editor. The assignment states that we are to create a DHIS application that lets the user multi-selecect several metadata objects, and then lets the user edit the sharing configuration of that metadata in bulk. As of right now, sharing settings can only be applied on one object at a time.
The project lists this as a requirement:
- The purpose of this app is for the user to be able to apply read/write, read only or no access to the "public access" property of several objects at once, be it data elements, data sets, dashboards or any other sharable objection DHIS.
The primary goal of this app as we see it is then to provide the user with an intuitive and quick way to edit sharing configuration in bulk. To achieve this, we will apply many of the same principles/designs on which the DHIS app Maintenance was built upon. First, lets look at search.
- The user should be able to search on name (or other properties) for the object, be it singular or a group, dashboard or a category.
In DHIS there are several distinct sharable objects. Many of them have sub-categories. In the image below to the left you'll see a tree-like view representation of that structure. The space to the right will be greyed out and un-clickable.
The user will need to select a category - or a sub-category, if one is present, to proceed. Data element is a general term for three underlying categories: data element, data element group, and data element group set. If you chose a category with sub-categories, the tree will expand, as pictured in the image below. Once you click on a desired object - say, data elements, that area will be highlighted and the objects will be fetch from the DHIS2 server.
A list of relevant objects will then be displayed in the right box, and you can begin editing. At any point you are free to select a new category.
For search we'll be using a template not dissimilar to the one currently used by Maintenance when creating a new data element, indicator etc. For instance, all data elements will be listed in a scrollable window, as pictured above in the right box. Just like in Maintenance, you can add single elements or select multiple, or select all. Added elements will be displayed in the window next to it, which can similarly be removed, multi-select removed or emptied entirely.
Right above will be a search bar. The two windows described above will be filtered based on the search results - and, desirably, should display the number of results hidden by the filter (not implemented in the mockup above).
- The user should also be able to narrow down the search field through "other properties".
Certain objects such as data elements have specific properties that can be selected to narrow down the search field, such as selecting the domain type or value type. This feature will be implemented for objects that have additional properties. In the image above, the user has selected Category Combination, and a new pop-up comes up with a new search filter.
Listed below are functionalities listed in the assignment specification as well as our own ideas on how implement in an intuitive user experience.
- From the nested-tree menu the user will be able to select data elements, groups, data sets, programmers, dashboards and much more. A minimal requirement is to be be able to work with only a select few of the sharable objects. Ideally, there should be support for all. The images above represent the ideal outcome. This is a specification we will strive to achieve but, as of right now, we intend to take it one step at a time and just make sure we don't accidentally or purposely fall of a cliff.
- There'll also be support to edit user groups, structured in a similar fashion.
- When editing the sharing configuration for dashboards, we will need not only to alter the setting for the dashboard itself, but all of its view also, as well as all the tables or charts those views have and every element inside those charts or tables. This is considerably more work than the rest of the objects and we recon will be the primary challenge during development.
- Currently in DHIS, once the user selects a "read only" option, for instance, that setting is instantly saved. We will do it slightly different. The user has the option to select a setting: read/write, read only or no access. "Sharing Settings" can be seen in the images above. That setting will persistent until the user changes it, the save button is pressed, or a new category is selected. The search field and properties will then be reset, the right window will be emptied and the sharing setting option will return to neutral as well - this to ensure that the user doesn't forget and accidentally apply the settings from the previous configuration on the new batch of elements.
- Finally, it should be possible to both completely overwrite existing sharing settings or modify the existing sharing settings. It should therefore be possible to alter a read-only setting to write and read, despite the object marked as "read only".
For this application we'll have to do two things: get data, and then patch/put data. Thus, we need to create a front-end service that that displays the data in a fashioned manner. Before we started working on our web app, we discussed the general structure.
- We'll need to display several sharable objects that have similar but, in some cases, slightly different interfaces. Ideally there should be a generic function for this, with parameter arguments deciding when and if a slightly change is required.
- In order for us to remove and add features with easy, the app should be modular.
- While our app will have a slightly different look from regular DHIS apps, the basic functionalities such as search and selection should be in line with the rest of DHIS, particularly the Maintenance app.
DHIS is build upon React, and we therefore found React to the logical choice. DHIS apps such as Maintenance also employ the material-ui components library, which we found to be esthetically pleasing and would enable us to create a modular web app.
We'll also the following frameworks or libraries:
- d2-ui: depending on what components we require, we'll also be looking directly at source code for DHIS2, and using that to build our own app.
All software libraries used in our project are using premissive licenses, giving us a lot of freedom to redistribute our software. Our source code is either written by us or taken from OSS licensed under the BSD or MIT license. Our software will be under the BSD licenses, to comply with and follow DHIS 2's licensing.
Conditons needed for 3-Clause BSD license can be found here: [https://opensource.org/licenses/BSD-3-Clause 1]
We used components from the DHIS 2 library d2-ui, which is also under the 3-Clause BSD license.
Conditions needed for React's MIT license can be found here: [https://github.com/facebook/react/blob/master/LICENSE#L1 1]
We also used parts from Material-ui, which is also under the MIT [Ttps://github.com/mui-org/material-ui/blob/master/LICENSE license], same as React.
Lastly we also used parts of insin's react-filtered-multiselect code, which also goes under MIT.
Icons made by Those Icons from www.flaticon.com is licensed by CC 3.0 BY
Division of labour
During the initial development, we intend to work together as a group so that everyone understands how DHIS works, how React works, and how those two interact. This we feel ensures that every member of group gets the appropriate knowledge in all tools, and that any empty seat can be filled by another member should the other be indisposed.
When we have a solid foundation that we can build upon, then we can divide the tasks accordingly, depending on time and where our strengths or wishes lie.
Preliminary plan, might be object to changes.
- Wiki up and running
- Chosen assignment
- Overview of the product to be developed
- Proposed architecture of the app
- Broad timeline for development (in form of milestones)
- Link to project repository
- The app's interface up and running
- Application interacts with the DHIS2 server
- Finalize every features
- Fixing bugs and whatnot
- Completed and delivered
Note: bug fixing lasted until the day before the deadline.
What We Ended Up With
When planning our assignment we misinterpreted certain points from the project description. The pictures and specifications in the "Project Description Requirements" are therefore not wholly representative of our final product.
- We made the assumption that when editing groups or group sets, the user would be able to edit, say, the data element from a selected data element group. As we envisioned it, you'd simply edit the configuration settings for one or several groups, and all of their data elements would be updated with the same sharing settings as the group itself. We made a similar assumption about dashboards, data sets and programs. To deal with this, we added tabs. The first tab, named "edit objects", is just for editing the base object. The second tab, "edit sub-objects", is active only for a group, group sets and other objects with dependencies.
- Further, to be able to chose a specific group from a data element group, we added an additional autocomplete field. For objects with dependencies, we added two autocomplete fields. The first, for example, is to chose a dashboard, and the second to chose one of its dependencies. Once a dependency is selected, the list in rendered in the group editor.
- Originally, we envisioned sharing settings as a simple drop-down menu, where you can chose "view and edit only" and so on. However, we quickly found out that was insufficient. We need a separate dialog window to edit not only public access settings, but also add user groups. We modeled that dialog box after the existing style used by the DHIS2 Maintenance app.
- Though not in the specifications of the assignment, we felt we needed to present the user with a choice to empty existing user groups. For that, we added a checkbox, pictured in "final product". Without it, user groups would simply be added in addition to the ones already there. With our nuke option, you are able to select any number of elements from any category, check the checkbox, and then empty all user groups by simply pressing the save button.
- While we remained faithful to our design document, we felt an app closer in appearance to other DHIS2 apps such as Maintenance was perhaps more appealing. The look of the app underwear slight changes.
We felt we accomplished most of what we sought out to do. However, we do see room for improvements in a few areas, and room for feature's we would have added given more time to do so.
- Consider this scenario: you've just finished selecting the desired sharing configuration settings for a set of data elements, and you click save. The request is successful. However, unless you reload the data elements, the objects with the new configuration settings and user group settings you yourself applied to it are still there. If, in the mean time, someone has already updated those objects, you are in effect still using the old ones. When you then select to add a new user group, it won't be just that user group, but all the ones that are currently in the object from your previous configuration session. To handle this, we considered fetching the selected elements anew. In order to ensure that this works as well as it should, it would require more testing. Ultimately, we decided to abandon this in favor of improving what we already have.
- When selecting a data element group, just to pick one category group here as an example, that group's set of data element only have one field: id. To cope with this, we fetch all data elements, and then compare them against those from the select group. That is not the most elegant solution. We are aware that it is possible to fetch only a desires set of data elements using an "in" filter in the URL but, we would need to restructure a few of the methods from the api.js file.
- In the Maintenance App in DHIS2 you have types. For example, when you select a data element, you have the option to filter your search based on domain type or value type. Our app supports this. However, some categories - including data elements - have additional fields, such as "category combination" filtering, or "indicator type" filtering, to name a few. While we desired to implement this type of filtering as well, ultimately we ran out of time. It would require an additional dialog box and a search filter. The tools to implement are there but, due to unforeseen bugs in other aspects of our app, we had to limit ourself to only a selection of the type filtering available.
- At the time of building our app, we were still learning React and state. In hindsight, we should have used Redux. We use quite a bit of state to monitor when certain features should be activated and deactivates. Redux would have possibly given us cleaned code.
Link to Repository
The repository is public
- Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
- MIT License Copyright (c) 2013-present, Facebook, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.