@bigbinary/neeto-form-frontend 1.2.7 → 1.2.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +48 -316
- package/dist/index.cjs.js +131 -121
- package/dist/index.cjs.js.map +1 -1
- package/dist/index.js +133 -123
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,257 +1,30 @@
|
|
|
1
1
|
# neeto-form-nano
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The `neeto-form-nano` allows us to build forms within neeto applications. This nano exports `@bigbinary/neeto-form-frontend` NPM package and `neeto-form-engine` Rails engine.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
# Contents
|
|
6
|
+
1. [Development with Host Application](#development-with-host-application)
|
|
7
|
+
- [Engine](#engine)
|
|
8
|
+
- [Frontend package](#frontend-package)
|
|
9
|
+
- [Installation](#installation-1)
|
|
10
|
+
- [Usage](#usage)
|
|
11
|
+
2. [Instructions for Publishing](#instructions-for-publishing)
|
|
6
12
|
|
|
7
|
-
|
|
13
|
+
# Development with Host Application
|
|
8
14
|
|
|
9
|
-
##
|
|
10
|
-
|
|
11
|
-
neetoFormFrontend is the library that manages forms across neeto products.
|
|
12
|
-
|
|
13
|
-
### Installation
|
|
14
|
-
|
|
15
|
-
```zsh
|
|
16
|
-
yarn add @bigbinary/neeto-form-frontend
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
**neetoFormEngine-frontend** has a few peer dependencies that are required for
|
|
20
|
-
the proper functioning of the package. Install all the peer dependencies using
|
|
21
|
-
the below command:
|
|
22
|
-
|
|
23
|
-
```zsh
|
|
24
|
-
yarn add @bigbinary/neetoui @bigbinary/neeto-icons ramda@^0.28.0 classnames@^2.3.1 formik@2.2.9 @bigbinary/neeto-commons-frontend
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
Import stylesheet from the following location:
|
|
28
|
-
|
|
29
|
-
```scss
|
|
30
|
-
@import "@bigbinary/neeto-form-frontend/dist/main.css";
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
This package relies on the host project's tailwind configuration. So add
|
|
34
|
-
neeto-form-frontend to your project's tailwind.config.js file:
|
|
35
|
-
|
|
36
|
-
```js
|
|
37
|
-
module.exports = {
|
|
38
|
-
purge: {
|
|
39
|
-
content: [
|
|
40
|
-
// ... other content directories
|
|
41
|
-
"./node_modules/@bigbinary/neeto-form-frontend/**/*.js",
|
|
42
|
-
],
|
|
43
|
-
},
|
|
44
|
-
// ... other tailwind config options
|
|
45
|
-
};
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
### Components
|
|
49
|
-
|
|
50
|
-
`BuildForm` component is used to render a form builder.
|
|
51
|
-
|
|
52
|
-
```js
|
|
53
|
-
import { BuildForm } from "@bigbinary/neeto-form-frontend";
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
| prop | type | description |
|
|
57
|
-
| ------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
-
| `id` | `string` | Form id |
|
|
59
|
-
| `onUpdate` | `function` | Callback for form update |
|
|
60
|
-
| `buildRequestArgs` | `object` | Arguments for build request |
|
|
61
|
-
| `showAddQuestionDivider` | `boolean` | To show add question divider |
|
|
62
|
-
| `nonRemovableFields` | `string[]` | Field kinds that cant be deleted from a form. Accepts array of kinds: `name`, `email`, `phone`, `rating`, `checkbox`, `dropdown` |
|
|
63
|
-
| `submitButtonProps` | `object` | Props for submit button |
|
|
64
|
-
| `cancelButtonProps` | `object` | Props for cancel button |
|
|
65
|
-
| `requiredFields` | `string[]` | Fields that are required. Provided fields will be treated as required by default in the External form, the checkbox for toggling `required` will be hidden for the fields. Accepts array of kinds: `name`, `email`, `phone`, `rating`, `checkbox`, `dropdown` |
|
|
66
|
-
| `questionKinds` | `object[]` | To override default question kinds |
|
|
67
|
-
| `isKindAlreadyActive` | `function` | To override the logic for equality checking of question kinds. The function will receive `activeQuestions` and `kind` as arguments |
|
|
68
|
-
| `getActiveKindDetails` | `function` | To override the logic for extracting the details of the specified item. The function will receive `allQuestionKinds` and `item` as arguments and returns `kind`, `label`, `FieldComponent`, `FieldIcon` and `isSingular` props for the specified `item` |
|
|
69
|
-
| `showLoader` | `boolean` | To specify whether we need to show a page loader while loading questions. If specified as `true` a page loader will be displayed otherwise placeholder data will be shown while loading questions. The default value will be `false` |
|
|
70
|
-
| `kindUniqueOn` | `string[]` | To specify the prop used for uniquely identifying each question kind. Accepts the path of the prop as a `string[]`. The default value will be `["type"]` |
|
|
71
|
-
| `isFieldRequired` | `(item: Item) => boolean;` | To specify whether a question is required or not. The function will receive `item` as an argument and returns a boolean value. Fields that return `true` will be treated as required by default in the External form |
|
|
72
|
-
| `isFieldLabelDisabled` | `(item: Item) => boolean;` | To specify whether a question label input is disabled or not. The function will receive `item` as an argument and returns a boolean value. |
|
|
73
|
-
| `isQuestionDeletable` | `(item: Item) => boolean;` | To specify whether a question is deletable or not. The function will receive `item` as an argument and returns a boolean value. Fields that return `true` cannot be removed from a form. |
|
|
74
|
-
| `allowAdditionalGuests` | `boolean` | To specify whether we need to allow additional guests input field in the form. If specified as `true` a checkbox will be displayed in the form to allow additional guests. The default value will be `false`. (neetoCal specific) |
|
|
75
|
-
| `disabledAddButtonTooltipProps` | `object` | To specify the custom tooltip for disabled button when there are no more questions to add. By default the tooltip will be `No more question fields to add` |
|
|
76
|
-
|
|
77
|
-
`ExternalForm` component is used to render a form.
|
|
78
|
-
|
|
79
|
-
```js
|
|
80
|
-
import { ExternalForm } from "@bigbinary/neeto-form-frontend";
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
| prop | type | description |
|
|
84
|
-
| --------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
85
|
-
| `formId` | `string` | Form id |
|
|
86
|
-
| `customSubmitHandler` | `function` | Custom submit handler to be called instead of internal submit handlers |
|
|
87
|
-
| `onBeforeSubmit` | `(responses, formikValues) => updatedResponses` | Callback for before form submit, if the form responses needs to be updated, return the updated responses from this callback. The updated responses will be sent to the server. If the callback doesn't return anythong or returns a falsy value, the form will submit with the original responses. |
|
|
88
|
-
| `onCreateSuccess` | `function` | Callback for form creation success |
|
|
89
|
-
| `showTitle` | `boolean` | To show form title |
|
|
90
|
-
| `submitRequestArgs` | `object` | Arguments for form submit request payload |
|
|
91
|
-
| `footer` | `React.Component` | To render a Footer Component |
|
|
92
|
-
| `submitButtonProps` | `object` | Props for submit button |
|
|
93
|
-
| `cancelButtonProps` | `object` | Props for cancel button |
|
|
94
|
-
| `resetButtonProps` | `object` | Props for reset button |
|
|
95
|
-
| `showPrefixIcons` | `boolean` | To show prefix icons in input fields |
|
|
96
|
-
| `displayThankYou` | `boolean` | To show thank you message after form submit |
|
|
97
|
-
| `className` | `string` | To apply custom class to the form wrapper |
|
|
98
|
-
| `submissionId` | `string` | To set submission id for updating the form |
|
|
99
|
-
| `preview` | `boolean` | To show form in preview mode |
|
|
100
|
-
| `preserveValues` | `boolean` | To preserve form values in localStorage |
|
|
101
|
-
| `formTitle` | `string` | To set form title |
|
|
102
|
-
| `titleProps` | `object` | To set props for form title |
|
|
103
|
-
| `clearValuesOnSubmit` | `boolean` | To clear local storage values on submit |
|
|
104
|
-
| `clearValuesOnReset` | `boolean` | To clear local storage values on reset |
|
|
105
|
-
| `formDomProps` | `object` | To set props for form element |
|
|
106
|
-
| `initialValues` | `object` | To set initial values for form |
|
|
107
|
-
| `editorProps` | `object` | To set neetoEditor props for `rich_text` input field |
|
|
108
|
-
| `onChange` | `function` | Callback for form field values change |
|
|
109
|
-
| `customValidator` | `(question) => Yup.Schema or null` | Custom validator for form fields, it should return an yup validation schema based on the question proeprties. To make use of the default validation for a question type, return `null` |
|
|
110
|
-
|
|
111
|
-
`Submission` component is used to render a form result.
|
|
112
|
-
|
|
113
|
-
```js
|
|
114
|
-
import { Submission } from "@bigbinary/neeto-form-frontend";
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
| prop | type | description |
|
|
118
|
-
| -------------------- | -------- | --------------------------------------- |
|
|
119
|
-
| `formId` | `string` | Form id |
|
|
120
|
-
| `submissionId` | `string` | Submission id |
|
|
121
|
-
| `className` | `string` | To apply custom class component wrapper |
|
|
122
|
-
| `questionLabelProps` | `object` | To override props for question label |
|
|
123
|
-
| `answerProps` | `object` | To override props for answer text |
|
|
124
|
-
|
|
125
|
-
`Fields` component provides access to all the components used in building forms.
|
|
126
|
-
|
|
127
|
-
```js
|
|
128
|
-
import { Fields } from "@bigbinary/neeto-form-frontend";
|
|
129
|
-
|
|
130
|
-
const {
|
|
131
|
-
Email,
|
|
132
|
-
Dropdown,
|
|
133
|
-
ShortText,
|
|
134
|
-
LongText,
|
|
135
|
-
MultipleChoice,
|
|
136
|
-
SingleChoice,
|
|
137
|
-
Phone,
|
|
138
|
-
Rating,
|
|
139
|
-
Terms,
|
|
140
|
-
StarRating,
|
|
141
|
-
} = Fields;
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
Following components are currently available:
|
|
145
|
-
|
|
146
|
-
- `Email`
|
|
147
|
-
- `Dropdown`
|
|
148
|
-
- `ShortText`
|
|
149
|
-
- `LongText`
|
|
150
|
-
- `MultipleChoice`
|
|
151
|
-
- `SingleChoice`
|
|
152
|
-
- `Phone`
|
|
153
|
-
- `Rating`
|
|
154
|
-
- `Terms`
|
|
155
|
-
- `StarRating`
|
|
156
|
-
- `Additional guests (neetoCal specific)`
|
|
157
|
-
- `Condition`
|
|
158
|
-
- `Integer`
|
|
159
|
-
- `Decimal`
|
|
160
|
-
|
|
161
|
-
### Hooks
|
|
162
|
-
|
|
163
|
-
`useBuildFormState` hook is used to get the form state.
|
|
164
|
-
|
|
165
|
-
```js
|
|
166
|
-
import { useBuildFormState, BuildForm } from "@bigbinary/neeto-form-frontend";
|
|
167
|
-
|
|
168
|
-
const FormBuilder = () => {
|
|
169
|
-
const {
|
|
170
|
-
values,
|
|
171
|
-
dirty,
|
|
172
|
-
isSubmitting,
|
|
173
|
-
isValid,
|
|
174
|
-
submitForm,
|
|
175
|
-
resetForm,
|
|
176
|
-
errors,
|
|
177
|
-
} = useBuildFormState();
|
|
178
|
-
|
|
179
|
-
return <BuildForm />;
|
|
180
|
-
};
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
`useFormSubmission` hook is used to fetch the form submission data.
|
|
184
|
-
|
|
185
|
-
```js
|
|
186
|
-
import { useFormSubmission } from "@bigbinary/neeto-form-frontend";
|
|
187
|
-
|
|
188
|
-
const Component = () => {
|
|
189
|
-
const { submission, isLoading } = useFormSubmission({
|
|
190
|
-
formId: "form-id",
|
|
191
|
-
submissionId: "submission-id",
|
|
192
|
-
});
|
|
193
|
-
|
|
194
|
-
return <></>;
|
|
195
|
-
};
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
`useForms` hook is used to fetch all the forms.
|
|
199
|
-
|
|
200
|
-
`useForm` hook is used to fetch all details of a form.
|
|
201
|
-
|
|
202
|
-
`useCreateForm` hooks is used to create a form.
|
|
203
|
-
|
|
204
|
-
`useUpdateForm` hooks is used to update a form.
|
|
205
|
-
|
|
206
|
-
`useDeleteForm` hooks is used to delete a form.
|
|
207
|
-
|
|
208
|
-
The usage is as follows.
|
|
209
|
-
|
|
210
|
-
```js
|
|
211
|
-
import {
|
|
212
|
-
useForm,
|
|
213
|
-
useForm,
|
|
214
|
-
useCreateForm,
|
|
215
|
-
useUpdateForm,
|
|
216
|
-
useDeleteForm,
|
|
217
|
-
} from "@bigbinary/neeto-form-frontend";
|
|
218
|
-
|
|
219
|
-
const Component = () => {
|
|
220
|
-
const { data: forms, isLoading } = useForms();
|
|
221
|
-
const { data: form, isLoading } = useForm({ formId: "form-id" });
|
|
222
|
-
|
|
223
|
-
const { mutate: createForm, isLoading } = useCreateForm();
|
|
224
|
-
createForm(payload);
|
|
225
|
-
|
|
226
|
-
const { mutate: updateForm, isLoading } = useUpdateForm();
|
|
227
|
-
updateForm({ id: "form-id", values: payload });
|
|
228
|
-
|
|
229
|
-
const { mutate: deleteForm, isLoading } = useDeleteForm();
|
|
230
|
-
deleteForm("form-id");
|
|
231
|
-
|
|
232
|
-
return <></>;
|
|
233
|
-
};
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
_`useCreate`, `useUpdate` & `useDelete` uses react-query's useMutation hook
|
|
237
|
-
under the hood._
|
|
238
|
-
|
|
239
|
-
_`useForm` & `useForms` uses react-query's useQuery hook under the hood._
|
|
240
|
-
|
|
241
|
-
_We can pass in extra options supported by react-query to these hooks. We can
|
|
242
|
-
also destructure all react-query supported props from the response._
|
|
243
|
-
|
|
244
|
-
## neetoFormEngine
|
|
245
|
-
|
|
246
|
-
neetoForm engine adds features to build form and attach it to any model. It will
|
|
247
|
-
store submissions as well.
|
|
15
|
+
## Engine
|
|
16
|
+
The engine adds setup for form on backend and allows us to attach forms to any model. It also stores submissions.
|
|
248
17
|
|
|
249
18
|
### Installation
|
|
250
19
|
|
|
251
20
|
1. Add this line to your application's Gemfile:
|
|
252
21
|
|
|
253
22
|
```ruby
|
|
254
|
-
|
|
23
|
+
source "NEETO_GEM_SERVER_URL" do
|
|
24
|
+
# ...existing gems
|
|
25
|
+
|
|
26
|
+
gem 'neeto-form-engine'
|
|
27
|
+
end
|
|
255
28
|
```
|
|
256
29
|
|
|
257
30
|
2. And then execute:
|
|
@@ -263,116 +36,75 @@ store submissions as well.
|
|
|
263
36
|
3. Install the migrations
|
|
264
37
|
|
|
265
38
|
```shell
|
|
266
|
-
|
|
39
|
+
bundle exec rails neeto_form_engine:install:migrations
|
|
267
40
|
```
|
|
268
41
|
|
|
269
42
|
4. Run the migrations
|
|
270
43
|
|
|
271
44
|
```shell
|
|
272
|
-
|
|
45
|
+
bundle exec rails db:migrate
|
|
273
46
|
```
|
|
274
47
|
|
|
275
|
-
5.
|
|
276
|
-
`owner_class` information
|
|
48
|
+
5. Add this line to your application's `config/routes.rb` file (replace `at` to your desired route):
|
|
277
49
|
|
|
278
50
|
```ruby
|
|
279
|
-
NeetoFormEngine
|
|
51
|
+
mount NeetoFormEngine::Engine, at: "/neeto_form_engine"
|
|
280
52
|
```
|
|
281
53
|
|
|
282
|
-
6.
|
|
54
|
+
6. Create file `neeto_form_engine.rb` under `config/initializers` to provide the `owner_class` information
|
|
283
55
|
|
|
284
56
|
```ruby
|
|
285
|
-
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
7. Configure models to add below association to scope submission records
|
|
289
|
-
(optional)
|
|
290
|
-
|
|
291
|
-
```ruby
|
|
292
|
-
has_one :submission, class_name: "::NeetoFormEngine::Submission", as: :record
|
|
57
|
+
NeetoFormEngine.owner_class = "Organization"
|
|
293
58
|
```
|
|
294
59
|
|
|
295
|
-
|
|
60
|
+
7. Configure models to add below association to the provided owner class
|
|
296
61
|
|
|
297
62
|
```ruby
|
|
298
|
-
|
|
63
|
+
has_many :forms, class_name: "::NeetoFormEngine::Form", as: :owner
|
|
299
64
|
```
|
|
300
65
|
|
|
301
|
-
|
|
302
|
-
your desired route):
|
|
66
|
+
8. Configure models to add below association to scope submission records (optional)
|
|
303
67
|
|
|
304
68
|
```ruby
|
|
305
|
-
|
|
69
|
+
has_one :submission, class_name: "::NeetoFormEngine::Submission", as: :record
|
|
306
70
|
```
|
|
307
71
|
|
|
308
|
-
|
|
309
|
-
step 3) to manage your forms.
|
|
310
|
-
|
|
311
|
-
### Development
|
|
312
|
-
|
|
313
|
-
1. Add this line to your application's Gemfile (replace the path to the local
|
|
314
|
-
copy of neetoForm' engine):
|
|
72
|
+
9. Configure model to add below association to attach form (optional)
|
|
315
73
|
|
|
316
74
|
```ruby
|
|
317
|
-
|
|
318
|
-
```
|
|
319
|
-
|
|
320
|
-
2. And then execute:
|
|
321
|
-
|
|
322
|
-
```shell
|
|
323
|
-
bundle install
|
|
324
|
-
```
|
|
325
|
-
|
|
326
|
-
3. Install the migrations
|
|
327
|
-
|
|
328
|
-
```shell
|
|
329
|
-
bin/rails neeto_form:install:migrations
|
|
330
|
-
```
|
|
331
|
-
|
|
332
|
-
4. Run the migrations
|
|
333
|
-
|
|
334
|
-
```shell
|
|
335
|
-
rake db:migrate
|
|
75
|
+
has_one :form, class_name: "::NeetoFormEngine::Form", as: :attachable
|
|
336
76
|
```
|
|
337
77
|
|
|
338
|
-
|
|
339
|
-
|
|
78
|
+
## Frontend package
|
|
79
|
+
The frontend package allows us to create forms across neeto products.
|
|
340
80
|
|
|
341
|
-
|
|
342
|
-
NeetoFormEngine.owner_class = "Organization"
|
|
343
|
-
```
|
|
344
|
-
|
|
345
|
-
6. Configure models to add below association to the provided owner class
|
|
81
|
+
### Installation
|
|
346
82
|
|
|
347
|
-
|
|
348
|
-
|
|
83
|
+
1. Install the NPM package
|
|
84
|
+
```zsh
|
|
85
|
+
yarn add @bigbinary/neeto-form-frontend
|
|
349
86
|
```
|
|
350
87
|
|
|
351
|
-
|
|
352
|
-
|
|
88
|
+
2. The frontend package has a few peer dependencies that are required for
|
|
89
|
+
the proper functioning of the package. Install all the peer dependencies using
|
|
90
|
+
the below command:
|
|
353
91
|
|
|
354
|
-
```
|
|
355
|
-
|
|
92
|
+
```zsh
|
|
93
|
+
yarn add @bigbinary/neetoui @bigbinary/neeto-icons ramda@^0.28.0 classnames@^2.3.1 formik@2.2.9 @bigbinary/neeto-commons-frontend
|
|
356
94
|
```
|
|
357
95
|
|
|
358
|
-
|
|
96
|
+
3. Import stylesheet from the following location:
|
|
359
97
|
|
|
360
|
-
```
|
|
361
|
-
|
|
98
|
+
```scss
|
|
99
|
+
@import "@bigbinary/neeto-form-frontend/dist/main.css";
|
|
362
100
|
```
|
|
363
101
|
|
|
364
|
-
|
|
365
|
-
your desired route):
|
|
366
|
-
|
|
367
|
-
```ruby
|
|
368
|
-
mount NeetoFormEngine::Engine, at: "/form"
|
|
369
|
-
```
|
|
102
|
+
### Usage
|
|
370
103
|
|
|
371
|
-
|
|
104
|
+
You can learn more about the usage here:
|
|
105
|
+
1. [Components](./docs/frontend/components.md)
|
|
106
|
+
2. [Hooks](./docs/frontend/hooks.md)
|
|
372
107
|
|
|
373
|
-
|
|
374
|
-
NEETO_FORM_DEVELOPMENT=true
|
|
375
|
-
```
|
|
108
|
+
# Instructions for Publishing
|
|
376
109
|
|
|
377
|
-
|
|
378
|
-
step 3) to manage your forms.
|
|
110
|
+
Consult the [building and releasing packages](https://neeto-engineering.neetokb.com/articles/building-and-releasing-packages) guide for details on how to publish.
|