Skip to content

Latest commit

 

History

History
267 lines (214 loc) · 12.1 KB

README.md

File metadata and controls

267 lines (214 loc) · 12.1 KB

akvo-react-form-editor

Survey Editor for generating Akvo React Form survey definition. View Demo

Build Status Repo Size GitHub release NPM JavaScript Style Guide GitHub license Documentation Status

Install

Using NPM

npm install --save akvo-react-form-editor

Using Yarn

yarn add akvo-react-form-editor

Supported Question Type

Type Value
Input Text input
Input Number number
Cascade Select cascade
TextArea text
Date date
Option option
Multiple Option multiple_option
Tree Select tree
Geolocation geo
Table (Multiple Question) table
Autofield (fn string) autofield

Usage

import React from 'react';
import 'akvo-react-form-editor/dist/index.css'; /* REQUIRED */
import WebformEditor from 'akvo-react-form-editor';

const Example = () => {
  const onSave = (values) => {
    console.log(values)
  }

  render() {
    return <WebformEditor initialValue={{}} onSave={onSave} />;
  }
}

API

WebformEditor

Props Description Type Default
onSave Trigger after save button click function(values) -
limitQuestionType Support to limit question type available Array[QuestionType] | undefined -
defaultQuestion Support to set custom default new question type, name and required status Object{defaultQuestion} | undefined -
initialValue Set value by Form initialization (Required as empty object) Object{initialValue} | {} -
settingCascadeURL Value for Select Option on cascade question type Array[settingCascadeURL] | undefined -
settingHintURL Value for Hint / Validate question setting Object{settingHintURL} | undefined -
customParams Custom Parameters Object{customParams} | undefined

Properties

Default Question (optional)

Default question should be defined as object.

Props Description Type
type Use one of QuestionType as default new question type number | input | text | option | multiple_option | cascade | tree | geo
name Set default new question title / name String
required Set new question required true/false by default Boolean

Example:

<WebformEditor
  defaultQuestion={{
    type: 'text',
    name: 'New Question Title',
    required: true,
  }}
/>

Setting Cascade URL

Setting cascade URL should be defined as array of object. This value was used to fill Select Option value for cascade question type.

Props Description Type
id Unique id as option value Integer
name Shown as option label String
endpoint Cascade API String
initial Initial Parameter Integer | String | undefined
list Object name of array res.data?.[list] | res.data | String | undefined | false

Example:

<WebformEditor
  settingCascadeURL={[
    {
      id: 1,
      name: 'Province',
      endpoint:
        'http://tech-consultancy.akvo.org/akvo-flow-web-api/cascade/seap/cascade-296940912-v1.sqlite',
      initial: 0,
      list: false,
    },
  ]}
/>

Setting Hint URL

Setting Hint URL should be defined as array of object. This value was used to fill Select Option value for hint setting in a question.

Example:

<WebformEditor
  settingHintURL={{
    questionTypes: ['number'],
    settings: [
      {
        id: 1,
        name: 'JMP Explorer API',
        endpoint: 'https://jmp-explorer.akvotest.org/api/hint',
        path: [
          {
            label: 'Maximum',
            value: 'max',
          },
          {
            label: 'Minimum',
            value: 'min',
          },
          {
            label: 'Average',
            value: 'mean',
          },
          {
            label: 'Quantile 1',
            value: 'q1',
          },
          {
            label: 'Quantile 2',
            value: 'q2',
          },
          {
            label: 'Quantile 3',
            value: 'q3',
          },
        ],
      },
    ],
  }}
/>

Setting Hint URL Object

Props Description Type
questionTypes Value to limit hint setting for a certain question Array[QuestionType] | undefined
settings Value for hint options Array[Settings Parameters]

Settings Parameters

Props Description Type
id Unique id as option value Integer
name Shown as option label String
endpoint Hint API String
path Hint of object path provided by API which containt the value will be shown as a hint/validation Array[Path Parameters]

Path Parameters

Props Description Type
label Label for the path options String
value Value for the path options String

Initial Value (optional)

Webform initial value use the same format as Akvo React Form form structure. This value was used to load a form into Akvo React Form Editor to update that form definition.

Example: Initial Value Example

akvo-react-form antd

Custom Params

Custom parameters are key-value pairs that we can implement in the Webform Editor.

Example:

<WebformEditor
  customParams={{
    label: 'Set Custom Parameter',
    params: [
      {
        name: 'params_name_a',
        label: 'Single Option Param',
        type: 'option',
        multiple: false,
        options: [
          { label: 'Option 1', value: 'SO1' },
          { label: 'Option 2', value: 'SO2' },
        ],
      },
      {
        name: 'params_name_b',
        label: 'Multiple Option Param',
        type: 'option',
        multiple: true,
        options: [
          { label: 'Multiple Option 1', value: 'MO1' },
          { label: 'Multiple Option 2', value: 'MO2' },
        ],
      },
      {
        name: 'params_name_c',
        label: 'Input Param',
        type: 'input',
      },
    ],
  }}
/>

Custom Parameters Setting

Props Description Type
label Label for the custom params tab String | undefined
params List of custom parameters Array[Custom Parameters]

Custom Parameters

Props Description Type
name Parameter name String
label Parameter label String | undefined
type Field Type option | input | number
multiple Whether multiple or not Boolean
options Parameter Options Array[Option Parameters] | undefined

Option Parameters

Props Description Type
label Label for the params options String | undefined
value Value for the params options String

License

AGPL-3.0 © akvo