Turning web forms into conversations. Conversational Form is an open-source concept by SPACE10 to easily turn any form element on a web page into a conversational form interface. It features conversational replacement of all input elements, reusable variables from previous questions and complete customization and control over the styling.
Below you will find guides to inlcude the ConversationalForm into a page containing a form or try a quick demo
Include ConversationalForm in your page
<script type="text/javascript" src="https://cf-4053.kxcdn.com/conversational-form/0.9.6/conversational-form.min.js" crossorigin></script>ConversationalForm will automatically look through the DOM for a form element with the attibute cf-form, and auto-instantiate.
<form id="my-form-element" cf-form ...>That's it! Your form is now conversational 👍
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 body element.
<div cf-context ...>cf-prevent-autofocus
If you don't want to have the UserTextInput to auto focus.
<form id="my-form-element" cf-form cf-prevent-autofocus>cf-no-animation
Add this to `
<form id="my-form-element" cf-form cf-no-animation>For more control over the output exclude the attribute cf-form from the form element and instantiate either with vanilla JS or jQuery:
Only parameter formEl is mandatory for the object you pass to the constructor.
new cf.ConversationalForm({
// HTMLFormElement
formEl/*: HTMLFormElement;*/
});new cf.ConversationalForm({
// HTMLFormElement
formEl,/*: HTMLFormElement;*/
// context (HTMLElement) of where to append the ConversationalForm (see also cf-context attribute)
context,/*?: HTMLElement;*/
// pass in custom tags (when prevent the auto-instantiation of ConversationalForm)
tags,/*?: Array<ITag>;*/
// overwrite the default user Dictionary items
dictionaryData,/*?: Object;*/
// overwrite the default robot Dictionary items
dictionaryRobot,/*?: Object;*/
//base64 || image url // overwrite user image, without overwritting the user dictionary
userImage,/*?: string;*/
// base64 || image url // overwrite robot image, without overwritting the robot dictionary
robotImage,/*?: string;*/
// custom submit callback if button[type=submit] || form.submit() is not wanted..
submitCallback,/*?: () => void | HTMLButtonElement;*/
// can be set to false to allow for loading and packaging of Conversational Form styles within a larger project.
loadExternalStyleSheet,/*?: boolean;*/
// start the form in your own time, {cf-instance}.start(), exclude cf-form from form tag, see examples: manual-start.html
preventAutoAppend,/*?: boolean;*/
// start the form in your own time, {cf-instance}.start(), exclude cf-form from form tag, see examples: manual-start.html
preventAutoStart,/*?: boolean;*/
// prevents the initial auto focus set on the UserInput
preventAutoFocus,/*?: boolean;*/
// optional horizontal scroll accerlation value, 0-1
scrollAccerlation,/*?: number;*/
// allow for a global validation method, asyncronous, so a value can be validated through a server, call success || error
flowStepCallback,/*?: (dto: FlowDTO, success: () => void, error: () => void) => void;*/
// optional event dispatcher, has to be an instance of cf.EventDispatcher, see Wiki pages (Events)
eventDispatcher,/*?: cf.EventDispatcher;*/
// optional, set microphone input, future, add other custom inputs, ex. VR, see voice (1, 2) examples in docs folder
microphoneInput,/*?:IUserInput;*/
// optional, hide UserInputField when radio, checkbox, select input is active
hideUserInputOnNoneTextInput,/*?: boolean*/
// optional, parameters for the User Interface of Conversational Form, set here to show thinking dots or not, set delay time in-between robot responses
userInterfaceOptions,/*?:cf.UserInterfaceOptions*/
});Please see ConversationalFormOptions for available options
$("form").conversationalForm({
});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.:
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
pattern attribute will automatically be used if set in tag.:
<input type="text" pattern="^hello" cf-questions="Your answer needs to include 'hello'" ..- to map questions directly to a tag.
- seperate with || to allow for more questions, app will shuffle.
<input type="text" cf-questions="What is your name?||Please tell me your name." ..- seperate with && to allow for chained questions.
<input type="text" cf-questions="Hello?&&Please tell me your name." ..- tag specific, set the placeholder text on the UserTextInput field
<input type="text" cf-input-placeholder="Should include http" ..For cui-questions, add {previous-answer} to insert the value from the previous user-answer, you are also able to reference the input ID.
using the {previous-answer} mapping:
<input type="text" cf-questions="What is your firstname?">
<input type="text" cf-questions="Hello {previous-answer}, what is your lastname?">Using the ID attribute, this will loop through all submitted tags and map:
<input type="text" cf-questions="What is your first name?" id="firstname">
<input type="text" cf-questions="What is your last name?" id="lastname">
<input type="text" cf-questions="Hi {firstname} {lastname}, please tell me your email?">previous input could be a select:option list with countries.
<input type="text" cf-questions="So you want to travel to {previous-answer}">- set a label to the field, [type="radio"|"checkbox"]
<input type="radio" cf-label="Subscribe to newsletter" ..- Javascript validate a before submitting
- OBS. eval is used.
- Asyncronous, so a value can be validated through a server
- three parameters is passed to the method
- dto: FlowDTO
- success: () => void //callback
- error: (optionalErrorMessage?: string) => void //callback
<input type="text" cf-validation="window.validateFunction" ..- to map error messages directly to a tag.
- seperate by | to allow for more error, app will shuffle.
<input type="text" cf-error="Text is wrong wrong|Input is not right" ..When instantiating ConversationalForm a reference to the instance will be available in window scope.
window.ConversationalFormBe aware that if you create mutiple Conversational Forms within one page then the reference will be overwritten with latest created.
Use windo.ConversationalForm[form["cf-create-id"]]?` or just manually instantiate the form and user the returned instance.
Add tags to the form, see examples/formless.html for how this can be achived.
window.ConversationalForm.addTags(tagsData/*: Array<DataTag>*/, addAfterCurrentStep/*: boolean = true*/, atIndex/*: number = -1*/);Sets focus on Conversational Form'
window.ConversationalForm.focus();add a robot reponse, this you would usually do at the end of a process.
window.ConversationalForm.addRobotChatResponse("You have reached the end of the form!");See example of end-message here
add a robot reponse, this you would usually do at the end of a process.
window.ConversationalForm.addUserChatResponse("Hello from user.");See example of end-message here
remove the ConversationalForm by calling:
window.ConversationalForm.remove();get the FormData object of mapped form element, pass in true to get a serialized object back (JSON).
window.ConversationalForm.getFormData(serialized);remap registered tags and start flow from {index} possible to ignore existing tags, to allow for the flow to just "happen"
window.ConversationalForm.remapTagsAndStartFrom(index, setCurrentTagValue, ignoreExistingTags);$ bower install conversational-form --save
$ npm install conversational-form --save
import cf from 'conversational-form';
var cfInstance = cf.startTheConversation({
formEl: document.getElementById("form")
});You can overwrite the UI with your own styles. Please see how the docs site is overwritting the styles here.
We welcome contributions in the form of bug reports, pull requests, or thoughtful discussions in the GitHub issue tracker.
ConversationalForm is a concept by SPACE10. Brought to life by Felix Nielsen. Designed by Charlie Isslander.
$ cd gulp-tasks
$ npm install
Install local gulp from project root
$ npm install gulp
$ cd src/scripts
$ typings install
watch task, watches .styl, .ts, .jpg, .png, .gif, compiles to /build
# compiles (same as build) and watches files
$ gulp
# compiles build files, to run locally, runs docs, examples, conversational form scripts and styles and finally runs through Karma tests.
$ gulp dist
please see Unit testing below for more info.
Previous versions. These versions are also available through bower, npm and Github tags.
<!-- v0.9.5 -->
<script type="text/javascript" src="https://cf-4053.kxcdn.com/conversational-form/0.9.5/conversational-form.min.js" crossorigin></script><!-- v0.9.4 -->
<script type="text/javascript" src="https://cf-4053.kxcdn.com/conversational-form/0.9.4/conversational-form.min.js" crossorigin></script><!-- v0.9.3 -->
<script type="text/javascript" src="https://conversational-form-093-0iznjsw.stackpathdns.com/conversational-form.min.js" crossorigin></script><!-- v0.9.2 -->
<script type="text/javascript" src="https://conversational-form-092-0iznjsw.stackpathdns.com/conversational-form.min.js" crossorigin></script><!-- v0.9.1 -->
<script type="text/javascript" src="https://conversational-form-091-0iznjsw.stackpathdns.com/conversational-form.min.js" crossorigin></script><!-- v0.9.0 -->
<script type="text/javascript" src="https://conversational-form-0iznjsw.stackpathdns.com/conversational-form.min.js" crossorigin></script>We are using Travis and Karma to run tests.
$ karma start
this will run through the tests defined in .tests`, after starting karma, you can access http://localhost:9876 to view and modify the tests-cases.
You can view some examples here and find many more code-wise here.
Lowest common denominator of browser testing:
| Chrome | Firefox | IE | Opera | Safari | iOS | Android |
|---|---|---|---|---|---|---|
| 40+ ✔ | 40+ ✔ | 10+ ✔ | 46+ ✔ | 9.1+ ✔ | 9.1+ ✔ | 4.4+ ✔ |
If you have a project that uses Conversational Form, feel free to make a PR to add it to this list:
- ...