odkformrenderer v1.1.1
odk-form-renderer-v2
Odk Form Renderer (Version 2)
The library that generates dynamic, complex react web forms using json based form definitions with minimum configuration.
About
The odk-form-renderer-v2, also can be referred as Odk Form Renderer (Version 2), is a rewrite of the odk-form-renderer-v1.
The odk-form-renderer-v2 is meant to be used as an NPM library unlike odk-form-renderer-v1, which is a stand-alone react app. Other than this crucial difference with its predecessor, the odk-form-render-v2 is written in typescript and uses redux store for shared data.
The repository is bootstrapped using the TSDX boilerplate. So the new library code can be found inside /src and a Parcel-based playground for it can be found inside /example.
Since this library is solely developed by the developers for the developers of mPower, it is hosted in odk-form-renderer-v2-lib. Anyone with the right credentials and permissions are allowed to install and use the library.
Motivation Behind Version 2
Version one provided a few challenges. To tackle those challenges in a better way, we were motivated to write this library. To name few -
We shifted from stand-alone app to library because forms from version one can be used only as iframes inside our projects. We felt it decouples the form component a bit and also limits the usage of the forms. Sometimes we are required to perform custom submit actions on submission and that becomes a challenge on version one.
We have also written the library in typescript than javascript for better maintenance and scalability.
Since the use of shared data among base components are large, the top parents were getting heavy and we have started to face some side effects. To keep things persisted, we have used a redux store in this version.
Usage
Install
The most updated and stable library can be found in odk-form-renderer-v2-lib.
Since the repository is private, prior to installation, you are required to setup an ssh connection with the mPower bitbucket server with your computer using your account. To learn more, visit how to setup an ssh key.
To install with npm
npm install git+ssh://git@bitbucket.org:mpowersocial/odk-form-renderer-v2-lib.git --saveor with yarn
yarn add git+ssh://git@bitbucket.org:mpowersocial/odk-form-renderer-v2-lib.gitUninstall
To uninstall the library using npm
npm uninstall odkformrendereror with yarn.
yarn remove odkformrendererLibrary Props
| Name | Type | Description |
|---|---|---|
| formDefinitionJson | Object | JSON format form definition that is generated after XLSX form is uploaded to the odk server. Need to be parsed as a JS object before passing as a prop. |
| userInputJson | Object | The JS object with form field names as keys and form field values as values. Useful to set default values to fields. |
| handleSubmit | Method | The method that will be called on the submit button clicked. By default, the two parameters, userInput and mediaList, will be passed.The userInput parameter will contain the latest submission data and the mediaList will contain the list of files uploaded if the form on submission does not have any required fields missing or constraint violated. If there is any such errors, the userInput will contain "Field Violated". |
| csvList | Object | The CSV options that come separate with the excel form need to be passed through this prop as a JS object. |
| defaultLanguage | String | The default language key with which the form will render. |
| languageOptions | Array\ | The number of language options, passed as JS object, that are supported by the form. |
For a detailed example, see the
constants.tsxandindex.tsxfile inside\exampledirectory.
Contributing
Setup
For contributing, we prefer
yarnovernpmsinceyarnis faster. So the next set of instructions or examples will be provided using theyarnpackage manager.You are free to use the
npmbut please consult with your current team lead or repository owner regarding the use ofnpm. If you do not intend to push thepackage.json.lockfile in the repository, you may skip the consultation.
Clone the Repository
git clone git@bitbucket.org:mpowersocial/odk-form-renderer-v2.git
SSHis always preferred overHTTPS.
Move to the root project directory.
cd [\root\to\project\directory\]Install the library dependencies
yarn Needs to be run in the root directory.
Move to the example directory present inside the root directory.
cd [\root\to\project\directory\example\]Install the example dependencies
yarnRunning Development Instance
Open the terminal and move to the library root directory
cd [\root\to\project\directory\]Start the development server for library
yarn startWhenever you edit the library codebase (inside
\srcdirectory), it will auto build a production version based on changes. Since this is a library and there is no standalone instance, you will need to run the example concurrently to see the reflection of changes.
While running the first terminal, open another terminal. Move to the example directory of the library repository.
cd [\root\to\project\directory\example\]Start the example app, using the library.
yarn startYou are required to keep both the terminals running concurrently to see any immediate reflection of your changes on the codebase. If you change any environment setup or package.json settings, like always, you will need to close the terminals and start the development instance again.
Production build
Open the terminal and move to the library root directory
cd [\root\to\project\directory\]Create a production build of the library.
yarn buildCode Quality
For linting, we have used tslint. Since developers of tslint published they will no longer update the tslint and will move to shipping the tslint with eslint, one crucial contribution will be to remove the tslint and modify the eslint config, as well as resolve the eslint issues.
Until then, you are advised to keep eslint extension in your vscode disabled (given you are using vscode and have the eslint extension enabled).