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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 94c55176ce18af1c0a02a0a74eca6b2df8a8451e
4
- data.tar.gz: f4749571bf260c3acd640438178652804d6804ae
3
+ metadata.gz: 2ca954a92fd8e55a339beff36ef74177a0cb65e4
4
+ data.tar.gz: 826cb88acec2e679125f16e041afc0d14691664c
5
5
  SHA512:
6
- metadata.gz: df3f05bc258a7909cf06a0db5a41ed13161e8dc23a9c728182db541125026aa0ba63db955646c220f76eeec7c06a3654f2e97fdbf18a80c6e638d9a0153afee2
7
- data.tar.gz: 587a70e0746623875608e5156553f203a5fca73a1f71cd43724dad1a37512536a7c7e12b243d4a1ecbdf56b71cdf35c6d24b70e882dd0677973864d14e34e759
6
+ metadata.gz: 801482bff23c84bcfdc95e5c6f608e99867b1b1d90ad5c8b46da44fcd75d3e6ff89050ec1c60f9842adf91590375ce5330decc7b74991219fb10ad3923bbdf55
7
+ data.tar.gz: 3c527b91600b0b52e85d22db1309b1577ce07a22b50f8d9a0f330a461ca3d350c610f312bb4ccfcc23fa60eca480c0dba9e207cb5c2083e3379880e9c46bedae
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- conversation_forms (1.0.1)
4
+ conversation_forms (2.0.0)
5
5
  autoprefixer-rails (>= 5.2.1)
6
6
  rails (~> 5.0.0, >= 5.0.0.1)
7
7
  railties
data/README.md CHANGED
@@ -1,8 +1,5 @@
1
1
  # ConversationForms
2
- Short description and motivation.
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
- Finally require the js:
25
- ```bash
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="convo-form">
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
- to set the question for an input, add the `data-question` attribute
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
- <input type="text" name="name" data-question="What is your name?">
47
- <input type="text" name="birthday" data-question="What is your birthday? (please enter DD/MM/YYYY)">
48
- <input type="text" name="email" data-question="Thanks! What is the best email for me to reach you at?">
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
- obscure the display of user input to the screen, add `data-secure="true"`
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
- <input type="text" name="secure-input" data-secure="true">
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
- NOTE: any fields with `type="password"` or `name="password"` will automatically have the secure flag set. For security purposes, this is not an option you can override.
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
- <input type="text" id="password" name="password" data-question="Please enter the password you would to use for your account. (Don't worry, I'm a robot, no one will see it)">
173
+
174
+
175
+ ### Instantiate with jQuery
176
+
177
+ ```javascript
178
+ $("form").conversationalForm();
61
179
  ```
62
180
 
63
181
 
64
- ## Contributing
65
- Contribution directions go here.
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).