Soilstack UI Updates
This issues describes several distinct pieces of work:
- Updates to the User Profile page
- Updates to the Super Admin page
- Updates / Finishing of the Landing page
- Creation of Group pages
They could all be their own issues, and it's probably good to try to keep them on separate branches for easier review and updating of the database
branch that we'll work off of. All of this work requires the same introductory information below under Working in the current state of the codebase
, so I'll just keep it all in one issue instead of duplicating that information.
Working in the current state of the codebase
Local Development Setup
- instructions for getting started with soil api are in the README of soil-api on the
database
branch - instructions for getting started with soil client are in the README of soil-client on the
database
branch (same branch name in soil-client and soil-api repo)
Organization of work
- All work should be done on branches off of the
database
branch. Merge requests should target thedatabase
branch.
Setting up some test data (relevant to Groups pages and Super Admin page)
- You may want to set up some test data while developing, like some groups and memberships before starting on the ui work.
- With the api running, navigate to the
/api-docs
route to view the api reference for the endpoints you'll use to create some data. Endpoints of interest are:POST /groups
andPOST /groups/:id/memberships
. - There are two approaches to creating some test data that I can think of:
Via API Requests
- Before api tokens backend mr is merged, you can use the commented out
resolveAuthToken
middleware that allows you be any user you want by specifying an auth header likeAuthorization: email@example.com
.- once you've setup the data you need via api requests, swap the resolveAuthToken middleware back to the real one to be able to login via UI.
- Once the api tokens backend mr is merged to the database branch, you can create an api token for yourself via api call (using the alternate
resolveAuthToken
middleware), then use an auth header likeAuthorization: apikey your-long-alpha-numeric-api-token-here
for subsequent requests, instead of needing to the use the alternateresolveAuthToken
middleware. - Once the api tokens frontend mr is merged to database branch, you can create an api token for yourself via the ui, and then use the api token to make requests. You won't need the alternate
resolveAuthToken
middleware at all.
Via the UI as you build it
- Another approach would be to try to do the ui work in an order that allows you to use it as you go, without needing to make api requests outside the ui. The advantage to this would be that you can rely on the auth header that is automatically passed by the frontend when you are logged in, and not have to fiddle with the
resolveAuthToken
stuff. - An order that might work: (1) create group (2) create membership, (3) view groups, memberships, etc.
Super Admin Page
-
We need to update this page to have a Groups tab with a Groups table, similar to the other two tabs (Show info, actions, and have ability to search). Data can be fetched from GET /groups. -
The main thing we need to accomplish is to provide the ability to delete a group. (DELETE /groups/:id) - Deleting a group will delete all descendant groups, and all memberships to the group and its descendant groups. We should display a confirmation dialog with a clear warning stating this. (
ConfirmDialog
component can be used). Maybe we can display the specific descendant groups that will also be deleted.
- Deleting a group will delete all descendant groups, and all memberships to the group and its descendant groups. We should display a confirmation dialog with a clear warning stating this. (
- The super admin UI is for our use only, and so does not need to be particularly pretty. I expect it will be much easier to list all of the groups in the table without regard to the group tree structure. That's totally fine, unless we come up with a relatively low effort way to display it better.
Groups Pages
- The purpose of these pages is to allow users to
- create groups
- add and remove users from groups.
- view the members of a group
- view the parent group and subgroups of a group
- allow super admins to delete groups -> @cryinbockritz this sounds redundant to Super Admin Page - do we really need that in both places? -> @manuel-ch You are correct. We do not want the ability to delete groups outside of the super admin page.
-
Add a link to the Groups page to the left nav. -
Groups List Page (route: /groups) - list all of the root level groups a user has access to (GET /groups).
- a root level group for a given user is just a user without a parent group that the user has access to. It's not necessarily a root group in the database.
- button to create a group (POST /groups)
- button opens a form where you optionally choose a parent group, and always enter a group name. If you don't choose a parent group, the group will be created at the root. -> solved this by adding the button in the parent group (and setting parent behind the scenes) instead of making the user choose the parent group explicitly). This seems to be a little more intuitive to me.
- list all of the root level groups a user has access to (GET /groups).
- Group Details Page (route: /groups/:id)
-
show group name (data from GET /groups) -
show group path -
show group path ideally with a "breadcrumb" trail with links to ancestor groups) (data from GET /groups), ex: Show Group A -> SubGroup A1 -> SubSubGroup A2
when viewing SubSubGroup A2. -
list group members (GET /groups/:id/memberships) -
display their email -
button to remove member (DELETE /groups/:id/memberships/:id)
-
-
list subgroups (data from GET /groups) - link to Group Details Page for each subgroup
-
button to add a member (POST /groups/:id/memberships) - specify email address of member to be added
-
- Potential Issues
- The schema of the GET /groups response has not changed as part of the switch from surveystack to a database. Most of the frontend code that works with that groups data should continue to work without changes. However, there may be some assumptions in the frontend that all groups are descendents of a root group (since in surveystack, all soilstack groups were within a 'soilstack root group'). Lookout for this. Our short term options will be to either (1) update the frontend to not assume a single root group or (2) have the api prefix all groups to "pretend" there is a root group for now.
Looking at some of the group tree handling code in
src/store/modules/group/utils.ts
, it looks like this may not be an issue. Anyway, keep a lookout just in case.
- The schema of the GET /groups response has not changed as part of the switch from surveystack to a database. Most of the frontend code that works with that groups data should continue to work without changes. However, there may be some assumptions in the frontend that all groups are descendents of a root group (since in surveystack, all soilstack groups were within a 'soilstack root group'). Lookout for this. Our short term options will be to either (1) update the frontend to not assume a single root group or (2) have the api prefix all groups to "pretend" there is a root group for now.
Looking at some of the group tree handling code in
Profile Page
-
The purpose of this page is to allow the user to manage their account. -
The user icon link in the app header should take the user to the profile page (already set up). -
link to keycloak account management page (using keycloak client) - keycloak client documentation can be found here: https://www.keycloak.org/docs/latest/securing_apps/index.html#javascript-adapter-reference
-
link to update password (using keycloak client) -
show api tokens belonging to the user - this issue ( https://gitlab.com/our-sci/software/soil-client/-/issues/99 ) covers the work of displaying, creating, and deleting api tokens in the frontend. It is being worked by Martin. Once that work is complete, we should delete the placeholder api tokens page and move its contents to the User Profile page.
-
Optionally, display some of the information the keycloak client exposes about logged in users on the page. The only thing I can think of would be their email address. This is not required but may be useful in filling out the layout of the page. We have to be careful about which information we use, as it may not be available for every Keycloak user depending on how Keycloak is configured and how the user is configured. We can safely rely on email address being present though. -
beautify page layout
Landing Page
-
❗ fix issue when starting installed pwa, await keycloakReady in router/index.ts never returns -
The purpose of the page is to provide a place for non authenticated usersnon installed users to land. This is generally a fine thing to have, but in particular it is required because we need to have a landing page on our domain so that users showing up to the app for the first time are able to add it to their homescreen.- If we didn't have our own landing page, we'd probably end up using the Keycloak login page instead, but that would not allow users to add the app to their homescreen as the keycloak login page will live on a separate sub domain.
-
When the app is installed to the homescreen, do not show the landing page, instead redirect the user to the keycloak login page if they are not authenticated. -
Do not show left nav menu -
Do not show Profile link - We should either:
- continue to display the question mark icon link to the help docs
-
Or, if we decide to not show the app header on this page (which would remove the left nav and profile link, which we want), display a link to the help docs somewhere else on the page.
-
Display logo prominently. - logo assets can be found here: https://drive.google.com/drive/folders/1Nxo8HGKM5omBYrCqNbwBmn3Y5exjb9pU?usp=sharing
-
Optionally, display the paragraph of copy from the top of the new website. It may help to fill out the page a bit and the info could be nice to have. This isn't required, though; whatever looks good. -
Have a call to action that let's users know to add the app to their homescreen, and (2) login or register. (login dialog shows up directly after install, to reduce a click) -
register link (using keycloak client) - the keycloak client documentation can be found here: https://www.keycloak.org/docs/latest/securing_apps/index.html#javascript-adapter-reference
- add registration to the keycloak login screen by enabling that feature in keycloak client config
-
login link (using keycloak client) -
When authenticated - redirect to /fields page (I think this is already setup, but we should confirm this behavior works and remains)
- For users returning to the app from a keycloak flow (login or register), a redirectUri is passed into the keycloak call. (see
keycloak.login()
for example). - For users that arrive another way, perhaps because they bookmarked the landing page, redirect them to /fields if they are already authenticated. This is handled by the loginRequiredGuard in the router.
- For users returning to the app from a keycloak flow (login or register), a redirectUri is passed into the keycloak call. (see
- redirect to /fields page (I think this is already setup, but we should confirm this behavior works and remains)
-
beautify page layout
Edited by Manuel H.