@amsterdam/bmi-dms-upload

DMS Upload

A document upload flow that can be implemented in any BMI React application. Documents are stored in DMS. Metadata can be added in the flow.

Installation

npm install --save @amsterdam/bmi-dms-upload

Implementation

import { AddDocumentButton } from '@amsterdam/bmi-dms-upload';

function MyComponent() {
	return (
		<AddDocumentButton<MetadataExample>
			// Dynamically construct the URL for the file upload POST
			getPostUrl={(file) => Promise.resolve('/api/example/upload')}
			// Dynamically inject headers for the file upload POST
			getHeaders={async () => {
				const headers: { [key: string]: string } = {};
				if (token) {
					headers['some-token'] = token;
				}
				return Promise.resolve(headers);
			}}
			// Do something when a file is uploaded successfully
			onFileSuccess={(file) => {
				if (typeof file.response !== 'string') throw new Error('BUG: no response provided to onFileSuccess callback');

				const response = JSON.parse(file.response);
				console.log('Optionally track successfully uploaded documents in state', response);
			}}
			// Do something when a file is being removed
			onFileRemove={(file) => {}}
			// A custom form component should be rendered here that is specifically geared towards
			// capturing the relevant metadata for the context in which this button is implemented
			metadataForm={<></>}
			// Yup can be leveraged here to validate the metadata that was captured with the form
			onMetadataValidate={async function (data: MetadataExample) {
				console.log('Validate metadata against schema', data);
				return true;
			}}
			// Dispatch actions/make async calls to persist the metadata
			// This effectively completes the wizard flow
			// If an exception were to be thrown from this callback it is gracefully handled with
			// some generic feedback to the end user
			onMetadataSubmit={async function (data: MetadataDataSubmitCallbackArg<MetadataExample>) {
				console.log('Persist metadata; the wizard has been completed and will be closed after this.');
			}}
			// Dispatch actions/make async calls to remove the uploaded files from DMS
			// (cancellation is only possible prior to metadata being persisted)
			onCancel={async function ({ metadata, file }: CancelCallbackArg<MetadataExample>) {
				console.log('Remove previously uploaded files and reset state.');
			}}
		/>
	);
}

IMPORTANT: It is expected that you have already implemented @amsterdam/asc-ui or @amsterdam/bmi-component-library. This package is built with styled-components and depends on the ThemeProvider from @amsterdam/asc-ui.

Development

To bootstrap the app in a static frontend served by webpack dev server (and a mock-api) run npm run serve. In your browser go to http://localhost:9999/. You can also use storybook for the isolated development of components using npm run start.

NPM link

The solution to working with packages for development locally is to rely on npm link. As an example, this package has @amsterdam/bmi-component-library as a dependency. To make changes in the @amsterdam/bmi-component-library package and to have these immediately reflected in your development workflow, follow these steps:

• Checkout @amsterdam/bmi-dms-upload at /path/to/repos/bmi-dms-upload
• Checkout @amsterdam/bmi-component-library at /path/to/repos/bmi-component-library
• cd /path/to/repos/bmi-component-library && npm link
• cd /path/to/repos/bmi-dms-upload && npm link @amsterdam/bmi-component-library

This will create a symlink at /path/to/repos/dms-upload/node_modules/@amsterdam/bmi-component-library which points to your clone of the @amsterdam/bmi-component-library package.

Now all you need to do is run typescript compilation in watch mode: cd /path/to/repos/bmi-component-library && npm run build:ts:es:watch

IMPORTANT: if you use NVM, it is crucial that both npm link commands are executed with the same node version.

Publish

TODO

Unit tests

npm run test

Storybook

To boot storybook, run the following command: npm run storybook. It should open your default browser at http://localhost:6006/.

React Router

This package uses react-router-dom. The v6 API is used but since the target applications that will implement this upload to DMS flow are at least partially running react-router-dom v5, we can not just install and use v6 here. Instead, the react-router-dom-v5-compat package is employed so that the v6 API can be used here, but this package remains more or less backwards compatible with applications that have not yet entirely migrated to v6 (i.e.: AIP). Only one router can exist in the component tree. For this reason it is critical that the components exported from this package are not wrapped in for example a <BrowserRouter>. It is the responsibility of the implementing party to set up a router at some (high) level in their component tree. The <Routes> (<Switch> in the v5 API) that is rendered from this package will function as a nested router from the given basePath.