conversation_forms 1.0.1 → 2.0.0
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.
- checksums.yaml +4 -4
- data/Gemfile.lock +1 -1
- data/README.md +193 -22
- data/assets/javascripts/conversation_forms.js +4 -21289
- data/assets/stylesheets/conversational_forms.css +13 -0
- data/lib/conversation_forms/engine.rb +1 -1
- data/lib/conversation_forms/version.rb +1 -1
- metadata +3 -3
- data/assets/javascripts/conversation_forms.map +0 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 2ca954a92fd8e55a339beff36ef74177a0cb65e4
|
4
|
+
data.tar.gz: 826cb88acec2e679125f16e041afc0d14691664c
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 801482bff23c84bcfdc95e5c6f608e99867b1b1d90ad5c8b46da44fcd75d3e6ff89050ec1c60f9842adf91590375ce5330decc7b74991219fb10ad3923bbdf55
|
7
|
+
data.tar.gz: 3c527b91600b0b52e85d22db1309b1577ce07a22b50f8d9a0f330a461ca3d350c610f312bb4ccfcc23fa60eca480c0dba9e207cb5c2083e3379880e9c46bedae
|
data/Gemfile.lock
CHANGED
data/README.md
CHANGED
@@ -1,8 +1,5 @@
|
|
1
1
|
# ConversationForms
|
2
|
-
|
3
|
-
|
4
|
-
## Usage
|
5
|
-
How to use my plugin.
|
2
|
+
A Rails port of [conversational-form](https://github.com/SampsonCrowley/conversational-form) inspired by [SPACE10](https://space10-community.github.io/conversational-form/)
|
6
3
|
|
7
4
|
## Installation
|
8
5
|
Add this line to your application's Gemfile:
|
@@ -21,48 +18,222 @@ Or install it yourself as:
|
|
21
18
|
$ gem install conversation_forms
|
22
19
|
```
|
23
20
|
|
24
|
-
|
25
|
-
```
|
21
|
+
require the js:
|
22
|
+
```javascript
|
26
23
|
//= require conversation_forms
|
27
24
|
```
|
28
25
|
|
26
|
+
and require the css:
|
27
|
+
```css
|
28
|
+
*= require conversation_forms
|
29
|
+
```
|
30
|
+
|
29
31
|
## Usage
|
30
32
|
|
31
33
|
on any pages that you want to use a conversation form, simply set the form's ID to `convo-form`
|
32
34
|
conversation forms will automatically detect your form's method and action
|
33
35
|
|
34
|
-
```
|
35
|
-
<form id="
|
36
|
-
<input type="text" id="test-input" name="test">
|
37
|
-
</form>
|
36
|
+
```html
|
37
|
+
<form id="my-form-element" cf-form-element ...
|
38
38
|
```
|
39
39
|
|
40
40
|
That's It!
|
41
41
|
|
42
|
-
## Advanced options (recommended)
|
43
42
|
|
44
|
-
|
43
|
+
# DOM Element attributes
|
44
|
+
|
45
|
+
### cf-questions
|
46
|
+
* to map questions directly to a tag.
|
47
|
+
* seperate by | to allow for more questions, app will shuffle.
|
48
|
+
```html
|
49
|
+
<input type="text" cf-questions="What is your name?|Please tell me your name." ..
|
50
|
+
```
|
51
|
+
|
52
|
+
### {One way value-binding} with cf-questions:
|
53
|
+
For cui-questions, add {previous-answer} to insert the value from the previous user-answer.
|
54
|
+
```html
|
55
|
+
<input type="text" cf-questions="Hello {previous-answer}" ..
|
56
|
+
```
|
57
|
+
previous input could be firstname.
|
58
|
+
|
59
|
+
```html
|
60
|
+
<input type="text" cf-questions="So you want to travel to {previous-answer}" ..
|
61
|
+
```
|
62
|
+
previous input could be a select:option list with countries.
|
63
|
+
|
64
|
+
### cf-label
|
65
|
+
* set a label to the field, [type="radio"|"checkbox"]
|
66
|
+
```html
|
67
|
+
<input type="radio" cf-label="Subscribe to newsletter" ..
|
68
|
+
```
|
69
|
+
|
70
|
+
### cf-error
|
71
|
+
* to map error messages directly to a tag.
|
72
|
+
* seperate by | to allow for more error, app will shuffle.
|
73
|
+
```html
|
74
|
+
<input type="text" cf-error="Text is wrong wrong|Input is not right" ..
|
75
|
+
```
|
76
|
+
|
77
|
+
|
78
|
+
# Validations
|
79
|
+
|
80
|
+
###
|
81
|
+
* Checks user input against the supplied regex
|
82
|
+
```html
|
83
|
+
<input type="text" pattern="^[0-9a-zA-Z-']*$" ..
|
84
|
+
```
|
85
|
+
|
86
|
+
### cf-validation-contains
|
87
|
+
* Checks if the input value is one of a pipe-separated list of values
|
88
|
+
* e.g. the following will check if the input is equal to "a", "b", "c", or "d"
|
89
|
+
```html
|
90
|
+
<input type="text" cf-validation-contains="a|b|c|d" ..
|
91
|
+
```
|
92
|
+
|
93
|
+
### cf-validation-email
|
94
|
+
* Basic email regex check to ensure the value contains only 1 "@" symbol and at lease 1 "." after the "@"
|
95
|
+
```html
|
96
|
+
<input type="text" cf-validation-email ..
|
97
|
+
```
|
98
|
+
|
99
|
+
### pattern/cf-validation-matches
|
100
|
+
* This will check user input against the supplied regex
|
101
|
+
* Using "pattern" is recommended over cf-validation-matches when possible as it is a native HTML5 attribute
|
102
|
+
```html
|
103
|
+
<input type="text" pattern="^[0-9a-zA-Z-']*$" ..
|
104
|
+
<input type="text" cf-validation-matches="^[0-9a-zA-Z-']*$" ..
|
105
|
+
```
|
106
|
+
|
107
|
+
### max/cf-validation-max
|
108
|
+
* Ensure User input is less than or equal to a maximum
|
109
|
+
* Using "max" is recommended over cf-validation-max when possible as it is a native HTML5 attribute
|
110
|
+
```html
|
111
|
+
<input type="number" max=9 ..
|
112
|
+
<input type="text" cf-validation-max=9 ..
|
113
|
+
```
|
114
|
+
|
115
|
+
### min/cf-validation-min
|
116
|
+
* Ensure User input is greater than or equal to a minimum
|
117
|
+
* Using "min" is recommended over cf-validation-min when possible as it is a native HTML5 attribute
|
118
|
+
```html
|
119
|
+
<input type="number" min=1 ..
|
120
|
+
<input type="text" cf-validation-min=1 ..
|
45
121
|
```
|
46
|
-
|
47
|
-
|
48
|
-
|
122
|
+
|
123
|
+
### required
|
124
|
+
* to require a field set the required attribute as normal
|
125
|
+
```html
|
126
|
+
<input type="text" required ..
|
127
|
+
<input type="text" required="true" ..
|
128
|
+
<input type="text" required="required" ..
|
49
129
|
```
|
50
130
|
|
51
|
-
|
131
|
+
### cf-validation-custom
|
132
|
+
* Check input against a custom Javascript function before submitting
|
133
|
+
* OBS. eval is used.
|
134
|
+
* two parameters are passed to your custom method
|
135
|
+
* value: String, the value of the input field
|
136
|
+
* tag: ITag, the actual DOM tag
|
137
|
+
```html
|
138
|
+
<input type="text" cf-validation-custom="window.validateFunction" ..
|
52
139
|
```
|
53
|
-
|
140
|
+
|
141
|
+
# Advanced Initialization
|
142
|
+
|
143
|
+
**cf-context**
|
144
|
+
If you want to have the ConversationalForm appended to a certain element (when auto-instantiating) then add attribute `cf-context` to an element, otherwise the ConversationalForm will be appended to the form's parent element.
|
145
|
+
```html
|
146
|
+
<div cf-context ...>
|
147
|
+
```
|
148
|
+
|
149
|
+
**cf-prevent-autofocus**
|
150
|
+
If you don't want to have the UserInput to auto focus.
|
151
|
+
|
152
|
+
```html
|
153
|
+
<form id="my-form-element" cf-form-element cf-prevent-autofocus>
|
54
154
|
```
|
55
|
-
instead of displaying what they submitted, it will dislay the text `[SECURITY FILTERED INPUT]`
|
56
155
|
|
57
|
-
|
156
|
+
## Customization
|
157
|
+
|
158
|
+
For more control over the output exclude the attribute `cf-form-element` from the form element and instantiate either with vanilla JS or jQuery:
|
58
159
|
|
160
|
+
### Self-instantiate with vanilla JS
|
161
|
+
|
162
|
+
```javascript
|
163
|
+
new cf.ConversationalForm({
|
164
|
+
formEl: <HTMLFormElement>,
|
165
|
+
// dictionaryData?: {}, // empty will throw error, see Dictionaty.ts for values
|
166
|
+
// dictionaryAI?: {}, // empty will throw error, see Dictionaty.ts for values
|
167
|
+
// context?: // context of where to append the ConversationalForm (see also cf-context attribute)
|
168
|
+
// tags?: tags, // pass in custom tags (when prevent the auto-instantiation of ConversationalForm)
|
169
|
+
// submitCallback?: () => void | HTMLButtonElement // custom submit callback if button[type=submit] || form.submit() is not wanted..
|
170
|
+
// userImage: "..." //base64 || image url
|
171
|
+
});
|
59
172
|
```
|
60
|
-
|
173
|
+
|
174
|
+
|
175
|
+
### Instantiate with jQuery
|
176
|
+
|
177
|
+
```javascript
|
178
|
+
$("form").conversationalForm();
|
61
179
|
```
|
62
180
|
|
63
181
|
|
64
|
-
##
|
65
|
-
|
182
|
+
## Parameters to pass the constructor of ConversationalForm: <<a name="ConversationalFormOptions"></a>ConversationalFormOptions>
|
183
|
+
* **formEl**: HTMLFormElement | string
|
184
|
+
* **context**?: HTMLElement | string
|
185
|
+
* Set the context of where the ConversationalForm will be appended to
|
186
|
+
* If not set then ConversationalForm will get appended to document.body
|
187
|
+
* **tags**?: Array<ITag>
|
188
|
+
* [cf.Tag.createTag(element), ...]
|
189
|
+
* **dictionaryData**?: object
|
190
|
+
* Possibility to overwrite the default [dictionary](https://github.com/space10-community/conversational-form/blob/master/src/scripts/cf/data/Dictionary.ts), empty will throw error, see [Dictionaty.ts](https://github.com/space10-community/conversational-form/blob/master/src/scripts/cf/data/Dictionary.ts) for values
|
191
|
+
* **dictionaryAI**?: object
|
192
|
+
* Possibility to overwrite the default [dictionary](https://github.com/space10-community/conversational-form/blob/master/src/scripts/cf/data/Dictionary.ts), empty will throw error, see [Dictionaty.ts](https://github.com/space10-community/conversational-form/blob/master/src/scripts/cf/data/Dictionary.ts) for values
|
193
|
+
* **submitCallback**?: () => void | HTMLButtonElement
|
194
|
+
* An alternative way to submit the form. Can be a Function or an HTMLButtonElement (click will be called). If not defined the component will search in the formEl after a button[type=”submit”] and call click() if not button is found final fallback will be to call submit() on formEl.
|
195
|
+
* **userImage**?: string
|
196
|
+
* Set a different userImage. "..." //base64 || image url
|
197
|
+
|
198
|
+
|
199
|
+
## Map your own tags
|
200
|
+
The Conversational Form automatically detects the accepted tags in the passed in form element.
|
201
|
+
If this is not desired then you are able to define your own **tags**, and pass them into the constructor.:
|
202
|
+
|
203
|
+
```javascript
|
204
|
+
var fields = [].slice.call(formEl.querySelectorAll("input, select, button"), 0);
|
205
|
+
for (var i = 0; i < fields.length; i++) {
|
206
|
+
var element = fields[i];
|
207
|
+
tags.push(cf.Tag.createTag(element));
|
208
|
+
}
|
209
|
+
```
|
210
|
+
|
211
|
+
Tags can then be set in the instantiation object, see [ConversationalFormOptions](#ConversationalFormOptions)
|
212
|
+
|
213
|
+
# Public API
|
214
|
+
When instantiating ConversationalForm a reference to the instance will be available in window scope.
|
215
|
+
|
216
|
+
```javascript
|
217
|
+
window.ConversationalForm
|
218
|
+
```
|
219
|
+
|
220
|
+
using this reference you are able to remove the ConversationalForm by calling:
|
221
|
+
|
222
|
+
```javascript
|
223
|
+
window.ConversationalForm.remove();
|
224
|
+
```
|
225
|
+
|
226
|
+
# Overwrite styles
|
227
|
+
You can overwrite the UI with your own styles. Please see the source [styles](https://github.com/SampsonCrowley/conversational-form/tree/master/src/styles/cf) files for more info.
|
228
|
+
|
229
|
+
|
230
|
+
# Contribute to ConversationalForm
|
231
|
+
|
232
|
+
We welcome contributions in the form of bug reports, pull requests, or thoughtful discussions in the [GitHub issue tracker](https://github.com/SampsonCrowley/conversation_forms/issues).
|
233
|
+
|
234
|
+
ConversationalForm is a concept originally by [SPACE10](https://www.space10.io/). Brought to life by [Felix Nielsen](http://twitter.com/flexmotion), [RWATGG](http://rwatgg.com). Designed by [Charlie Isslander](https://twitter.com/charlieissland).
|
235
|
+
|
236
|
+
Ported By [Sampson Crowley](https://github.com/SampsonCrowley)
|
66
237
|
|
67
238
|
## License
|
68
239
|
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
|