conversation_forms 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 94c55176ce18af1c0a02a0a74eca6b2df8a8451e
-  data.tar.gz: f4749571bf260c3acd640438178652804d6804ae
+  metadata.gz: 2ca954a92fd8e55a339beff36ef74177a0cb65e4
+  data.tar.gz: 826cb88acec2e679125f16e041afc0d14691664c
 SHA512:
-  metadata.gz: df3f05bc258a7909cf06a0db5a41ed13161e8dc23a9c728182db541125026aa0ba63db955646c220f76eeec7c06a3654f2e97fdbf18a80c6e638d9a0153afee2
-  data.tar.gz: 587a70e0746623875608e5156553f203a5fca73a1f71cd43724dad1a37512536a7c7e12b243d4a1ecbdf56b71cdf35c6d24b70e882dd0677973864d14e34e759
+  metadata.gz: 801482bff23c84bcfdc95e5c6f608e99867b1b1d90ad5c8b46da44fcd75d3e6ff89050ec1c60f9842adf91590375ce5330decc7b74991219fb10ad3923bbdf55
+  data.tar.gz: 3c527b91600b0b52e85d22db1309b1577ce07a22b50f8d9a0f330a461ca3d350c610f312bb4ccfcc23fa60eca480c0dba9e207cb5c2083e3379880e9c46bedae

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    conversation_forms (1.0.1)
+    conversation_forms (2.0.0)
       autoprefixer-rails (>= 5.2.1)
       rails (~> 5.0.0, >= 5.0.0.1)
       railties

data/README.md

@@ -1,8 +1,5 @@
 # ConversationForms
-Short description and motivation.
-
-## Usage
-How to use my plugin.
+A Rails port of [conversational-form](https://github.com/SampsonCrowley/conversational-form) inspired by [SPACE10](https://space10-community.github.io/conversational-form/)
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -21,48 +18,222 @@ Or install it yourself as:
 $ gem install conversation_forms
 ```
 
-Finally require the js:
-```bash
+require the js:
+```javascript
 //= require conversation_forms
 ```
 
+and require the css:
+```css
+*= require conversation_forms
+```
+
 ## Usage
 
 on any pages that you want to use a conversation form, simply set the form's ID to `convo-form`
 conversation forms will automatically detect your form's method and action
 
-```
-<form id="convo-form">
-  <input type="text" id="test-input" name="test">
-</form>
+```html
+<form id="my-form-element" cf-form-element ...
 ```
 
 That's It!
 
-## Advanced options (recommended)
 
-to set the question for an input, add the `data-question` attribute
+# DOM Element attributes
+
+### cf-questions
+* to map questions directly to a tag.
+* seperate by | to allow for more questions, app will shuffle.
+```html
+<input type="text" cf-questions="What is your name?|Please tell me your name." ..
+```
+
+### {One way value-binding} with cf-questions:
+For cui-questions, add {previous-answer} to insert the value from the previous user-answer.
+```html
+<input type="text" cf-questions="Hello {previous-answer}" ..
+```
+previous input could be firstname.
+
+```html
+<input type="text" cf-questions="So you want to travel to {previous-answer}" ..
+```
+previous input could be a select:option list with countries.
+
+### cf-label
+* set a label to the field, [type="radio"|"checkbox"]
+```html
+<input type="radio" cf-label="Subscribe to newsletter" ..
+```
+
+### cf-error
+* to map error messages directly to a tag.
+* seperate by | to allow for more error, app will shuffle.
+```html
+<input type="text" cf-error="Text is wrong wrong|Input is not right" ..
+```
+
+
+# Validations
+
+###
+* Checks user input against the supplied regex
+```html
+<input type="text" pattern="^[0-9a-zA-Z-']*$" ..
+```
+
+### cf-validation-contains
+* Checks if the input value is one of a pipe-separated list of values
+* e.g. the following will check if the input is equal to "a", "b", "c", or "d"
+```html
+<input type="text" cf-validation-contains="a|b|c|d" ..
+```
+
+### cf-validation-email
+* Basic email regex check to ensure the value contains only 1 "@" symbol and at lease 1 "." after the "@"
+```html
+<input type="text" cf-validation-email ..
+```
+
+### pattern/cf-validation-matches
+* This will check user input against the supplied regex
+* Using "pattern" is recommended over cf-validation-matches when possible as it is a native HTML5 attribute
+```html
+<input type="text" pattern="^[0-9a-zA-Z-']*$" ..
+<input type="text" cf-validation-matches="^[0-9a-zA-Z-']*$" ..
+```
+
+### max/cf-validation-max
+* Ensure User input is less than or equal to a maximum
+* Using "max" is recommended over cf-validation-max when possible as it is a native HTML5 attribute
+```html
+<input type="number" max=9 ..
+<input type="text" cf-validation-max=9 ..
+```
+
+### min/cf-validation-min
+* Ensure User input is greater than or equal to a minimum
+* Using "min" is recommended over cf-validation-min when possible as it is a native HTML5 attribute
+```html
+<input type="number" min=1 ..
+<input type="text" cf-validation-min=1 ..
 ```
-<input type="text" name="name" data-question="What is your name?">
-<input type="text" name="birthday" data-question="What is your birthday? (please enter DD/MM/YYYY)">
-<input type="text" name="email" data-question="Thanks! What is the best email for me to reach you at?">
+
+### required
+* to require a field set the required attribute as normal
+```html
+<input type="text" required ..
+<input type="text" required="true" ..
+<input type="text" required="required" ..
 ```
 
-obscure the display of user input to the screen, add `data-secure="true"`
+### cf-validation-custom
+* Check input against a custom Javascript function before submitting
+* OBS. eval is used.
+* two parameters are passed to your custom method
+	* value: String, the value of the input field
+	* tag: ITag, the actual DOM tag
+```html
+<input type="text" cf-validation-custom="window.validateFunction" ..
 ```
-<input type="text" name="secure-input" data-secure="true">
+
+# Advanced Initialization
+
+**cf-context**  
+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.
+```html
+<div cf-context ...>
+```
+
+**cf-prevent-autofocus**  
+If you don't want to have the UserInput to auto focus.
+
+```html
+<form id="my-form-element" cf-form-element cf-prevent-autofocus>
 ```
-instead of displaying what they submitted, it will dislay the text `[SECURITY FILTERED INPUT]`
 
-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.
+## Customization
+
+For more control over the output exclude the attribute `cf-form-element` from the form element and instantiate either with vanilla JS or jQuery:
 
+### Self-instantiate with vanilla JS
+
+```javascript
+new cf.ConversationalForm({
+	formEl: <HTMLFormElement>,
+	// dictionaryData?: {}, // empty will throw error, see Dictionaty.ts for values
+	// dictionaryAI?: {}, // empty will throw error, see Dictionaty.ts for values
+	// context?: // context of where to append the ConversationalForm (see also cf-context attribute)
+	// tags?: tags, // pass in custom tags (when prevent the auto-instantiation of ConversationalForm)
+	// submitCallback?: () => void | HTMLButtonElement // custom submit callback if button[type=submit] || form.submit() is not wanted..
+	// userImage: "..." //base64 || image url
+});
 ```
-<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)">
+
+
+### Instantiate with jQuery
+
+```javascript
+$("form").conversationalForm();
 ```
 
 
-## Contributing
-Contribution directions go here.
+## Parameters to pass the constructor of ConversationalForm: <<a name="ConversationalFormOptions"></a>ConversationalFormOptions>
+* **formEl**: HTMLFormElement | string
+* **context**?: HTMLElement | string
+	* Set the context of where the ConversationalForm will be appended to
+	* If not set then ConversationalForm will get appended to document.body
+* **tags**?: Array<ITag>
+	* [cf.Tag.createTag(element), ...]
+* **dictionaryData**?: object
+	* 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
+* **dictionaryAI**?: object
+	* 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
+* **submitCallback**?: () => void | HTMLButtonElement
+	* 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.
+* **userImage**?: string
+	* Set a different userImage. "..." //base64 || image url
+
+
+## Map your own tags
+The Conversational Form automatically detects the accepted tags in the passed in form element.
+If this is not desired then you are able to define your own **tags**, and pass them into the constructor.:
+
+```javascript
+var fields = [].slice.call(formEl.querySelectorAll("input, select, button"), 0);
+for (var i = 0; i < fields.length; i++) {
+	var element = fields[i];
+	tags.push(cf.Tag.createTag(element));
+}
+```
+
+Tags can then be set in the instantiation object, see [ConversationalFormOptions](#ConversationalFormOptions)
+
+# Public API
+When instantiating ConversationalForm a reference to the instance will be available in window scope.
+
+```javascript
+window.ConversationalForm
+```
+
+using this reference you are able to remove the ConversationalForm by calling:
+
+```javascript
+window.ConversationalForm.remove();
+```
+
+# Overwrite styles
+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.
+
+
+# Contribute to ConversationalForm
+
+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).
+
+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).
+
+Ported By [Sampson Crowley](https://github.com/SampsonCrowley)
 
 ## License
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).