getodk/central-frontend

Vue.js based frontend for ODK Central

ODK Central Frontend

ODK Central is the ODK server. It manages user accounts and permissions, stores form definitions, and allows data collection clients like ODK Collect to connect to it for form download and submission upload. ODK Central Frontend provides the frontend for ODK Central using Vue.js.

This repository contains the code for the frontend of ODK Central. The central-backend repository contains the code for the backend API server. The central repository contains the Docker code for building and running a production Central stack. You can find release notes in the central repository.

The master branch of this repository reflects ongoing development for the next version of ODK Central. It may or may not be in sync with the master branch of the central-backend repository. For the latest stable version, see the release tags.

You can learn more about ODK Central by visiting the docs.

Contributing

We need your help to make ODK Central Frontend as useful as possible! Please see the Contribution Guide for detailed information on discussion forums, project policies, code guidelines, and an overview of the software architecture.

Setting up your development environment

Follow these steps to set up your development environment:

• Install Node.js 20.
• Install dependencies by running npm install.
• Install NGINX.
• Set up ODK Central Backend.
  • You will need to create a user using an ODK Central Backend command line script.
  • You will probably also want to promote that user to a sitewide administrator.

Running in development

Follow these instructions to run ODK Central Frontend in development. For deploying to production, see the next section.

First, run ODK Central Backend.

Next, build ODK Central Frontend files for development by running npm run dev. The files will be outputted to dist/. As you update the source code, the files will be automatically rebuilt. npm run dev will also start NGINX, which will serve the files. NGINX effectively places ODK Central Frontend and ODK Central Backend at the same origin, avoiding cross-origin requests.

ODK Central Frontend will be available on port 8989.

ODK Central Frontend communicates with ODK Central Backend in part using a session cookie. The cookie is Secure, but will be sent over HTTP on localhost. ODK Central Frontend also interacts with data collection clients and with services:

• To upload an XLSForm, run pyxform-http. ODK Central Frontend communicates with pyxform-http through ODK Central Backend.
• You can use ODK Collect to scan an app user QR code, download a form, and submit data. One option to do so is to use ngrok. ODK Central Frontend is available on port 8989, so you can run ngrok http 8989 to expose a temporary HTTPS URL that you can use. Within ODK Central Backend, you will also need to set the default.env.domain property in config/default.json to the HTTPS URL, then restart ODK Central Backend if it is already running.
• Enketo is a web form engine used to show form previews and allow for web-based data entry. Please see our instructions for optionally setting up an Enketo server for use in development (it is already included in the production ODK Central stack).

Deploying to production

To build ODK Central Frontend files for production with minification, run npm run build. The files will be outputted to dist/. For more details on this command, see the documentation for Vue CLI.

Note that this repository's main.nginx.conf is for development only.

For more information on deploying to production, see the central repository.

central-frontend's Issues

Messaging for when fetching data takes a while

Right now Super Adventure doesn't indicate to the end user that it is in the process of fetching data (for example, the list of forms or submissions). How about we add messaging for when that fetching takes a while?

Add login

• Add login page.
• When navigating to a route, check the session.
• Send session information with requests.

Modals should not be dismissable while an action is happening

If the spinner is spinning for a long time, accidentally clicking on eg the grey background makes the whole dialog go away. This is scary!

Consider removing blurring

Update dashboard

What should go in the dashboard?

Add details to documentation links

Right now documentation links all navigate to the ODK documentation home. This issue is to make the links more specific.

Add basic user management

Create/read/list/update users.

IcoMoon license/copyright information

IcoMoon generates a CSS file, as well as a JSON file that stores our icon selection and IcoMoon preferences. The two files do not include license or copyright information. We have not modified the JSON file, and other than changing paths, we have not modified the CSS file.

According to https://icomoon.io/app-features.html, the CSS file is MIT licensed. However, I found that page from Google, and it looks possibly outdated.

Based on the above, I have a few questions:

• Should we add license/copyright information about IcoMoon anywhere?
• If we do add license/copyright information, where is the best place to put it? At the top of the file? In our repository's NOTICE file? Both?
• If we do add license information, and if MIT is the correct license, should we add the entire MIT license or just mention that the file is MIT licensed?

Update user reset password success message

@clint-tseng suggests for UserResetPassword:

can we update that message to also indicate that the present password has been successfully revoked?

v-for key with jQuery-managed elements

I think in some cases, we cannot reuse a jQuery-managed element, but unless we use the right v-for key, Vue may try to do so.

As part of this, check the approach for the field key list.

Add license

Add license based on the conversation here.

Switch from PhantomJS to Headless Chrome?

Removing jQuery listeners and data

I'm not sure we're removing all jQuery listeners and data as part of the Vue component destroy process. (Or at other times when we remove jQuery-managed elements, for example, removing elements in a data table before fetching fresh data.) One case: I think we might not be removing listeners and data from the popovers on the field key list page.

Use something like zxcvbn to indicate password strength

Currently, when a user sets or resets their password, we do not restrict their password in any way. We also do not indicate the strength of their password.

At the least, we wish to indicate to the user the strength of their password. We're thinking we could use zxcvbn or a library like it to do so.

We may also wish to add password restrictions rather than just warnings, such that the user cannot choose a password that fails to satisfy certain restrictions. I think we would consider at least a restriction on password length ("the password must be at least X characters"). If we add such a restriction, we may need to update Backend as well.

Add tests for forms

I'm skipping these for now.

Add readme

Use more recent versions of dependencies from vueify

Among the dev dependencies that the vueify template introduced, there are several that now have a new major version. I think we should consider bumping these to the latest version after checking whether doing so would break anything.

Dependency name	Version we're using	Latest version
babelify	7.3.0	8.0.0
browserify	13.3.0	16.2.2
cross-env	2.0.1	5.2.0
envify	3.4.1	4.1.0
uglify-js	2.8.29	3.4.9

AccountClaim: no need to replace space with +

Suggestion: Use standard HTML5 APIs

For example, Fetch API is broadly supported since last year: http://caniuse.com/#feat=fetch
(this would replace Axios)

Add unit tests

Vue.js seems to have some testing tools. Can we utilize those?

Add file-level copyright notices and license information

We'll continue doing this once we decide on the app's name.

Add version number / commit SHA on every page

Actions invoked downpage trigger offscreen status message

If you have eg a lot of user accounts and reset a password way down the page, you never see the happy message because it's at the top of the page. I think this isn't a big deal for v1 but we should keep an eye on it.

It may be another catalyst to stop having many alert widgets all trying to do the same thing within pageflow and instead have them float above the entire page somewhere fixed.

Hide field key QR code popover upon window resize

Otherwise, I think the popover would end up positioned incorrectly? I think this is mentioned in the Bootstrap documentation.

Improve error messages

Right now if a request fails, we basically say, "Something went wrong." We should use the details that Jubilant sends back: either the Jubilant problem message or the problem code.

Add router

We want a router so that folks can go back in their browser history and so that they can add individual pages of Super Adventure to their bookmarks. Investigate the Vue.js router:

https://router.vuejs.org/en/

Update contributing guide

Switch from babel-preset-es2015 to babel-preset-env

npm install warns:

npm WARN deprecated [email protected]: 🙌 Thanks for using Babel: we recommend using babel-preset-env now: please read babeljs.io/env to update!

Show display name, not email, in navbar

Right now the display name is just the email, so this isn't a big issue, but we should make the change at some point.

Newly invoked action modals retain old error messages.

1. Perform an action in a modal that triggers an error (eg reset password but the server isn't there).
2. Error appears at top of modal. Do not dismiss it.
3. Perform the action successfully.
4. Modal disappears and happy message is shown on the parent page.
5. Attempt to perform a new action with the same modal (eg resetting a different user's password).
6. Error is confusingly already present.

First pass at standard form and button things

See the release criteria.

Automatically refresh form and submission lists

As the user views the form and submission lists, we should automatically refresh the lists in the background.

We should think about messaging in case the list initially renders successfully, but then subsequent requests fail or take a long time.

Replace loading message with spinner

For this issue, replace each loading message with a spinner throughout Frontend. Once that is done, remove the VisibilityDelay component. If as part of this, you have replaced <loading> with <spinner>, go ahead and remove the Loading component.

Ideally, the spinner used to replace the loading message will be larger than the spinner used in other places. However, it's also fine if it's the same size. Try applying a transform: scale(2.0) (use a Spinner prop to toggle this). However, if that breaks the spinner, don't worry about it — we can just have it be the same size.

The spinner used to replace the loading message should be centered. If the entire page or PageBody is blank, and only the spinner is shown, the spinner should be shown further down the page than the loading message currently is.

One tricky part of this is that some v-if directives may need to become v-show (or vice versa).

Style tweaks

Style tweaks to consider:

Navbar

• After clicking the user's email address and hovering over Log out, only part of the background is gray.
• Dropdown menus seem slightly misaligned with the edge of the buttons that open them (in navbar and other places).
• After collapsing the navbar and clicking the user's email address, the background color of Log out is gray.

Other

• In buttons, the icon could probably be a few more pixels away from the button text.

Standard date formatting

As part of this, add tests of any table data that includes a date.

Deployment weight too heavy

The final JS bundle is 3.0MB, which is absolutely gargantuan. The bootstrap CSS is 112KB, which is more palatable but still seems highly excessive for a bunch of CSS. We should aim to bring these down by orders of magnitude by release.

Menus right at the bottom of the screen clip awkwardly

The cheap solution since all our menus are short right now is just to pad out the bottom of tables.

Add support for Jubilant user endpoints

Dependencies: replace ^ with ~

Two digits after the ~ is a good default in order to catch security updates. (But do a quick check of whether the package seems to be using semantic versioning.)

Add button to refresh submissions list

• Button should contain just a refresh icon. Once you click it, a spinner overlays the icon.
• Button should be in line with the table header.
• If the refresh fails, the page should show an alert.

Account for axios errors without a response

In some cases, axios errors might not have a response property. We should update our error handling to account for that case. axios has an example:

https://github.com/axios/axios#handling-errors

Research ESLint plugin for Vue.js

Right now Super Adventure uses eslint-plugin-html (this is how the Vue.js Browserify project template configured it), but it looks like there is an official ESLint plugin for Vue.js. The documentation for eslint-plugin-html says that the two are incompatible. Should we switch from eslint-plugin-html to eslint-plugin-vue?

Set up CircleCI

Blocked by #7.

Add remaining icons

• New form modal: next to "choose one".
• Submissions download button
• Form list: chevron next to form name.
• Field key list: QR code icon next to "See code".
  • Update toggleFieldKeyListPopovers() to account for icon.

Add linting

Mock-up?

Just wanted to check, do we have mock-ups that we could use for Jubilant?

Testing: replace Jasmine with Mocha

Session expiration

Right now Adventure doesn't monitor whether the session is expired.

Set up nginx

We need something like this as a more permanent solution for CORS.

Replace moment with Luxon?

@clint-tseng writes in #24:

i have been a happy moment user for many many years now, but they have a new one http://moment.github.io/luxon/ that seems cleaner, lighter, and better (immutable, for one). take a look?