PhraseForm.js

What’s the point?

Let’s face it: forms are stuffy. Nobody brags about filling out a form at the DMV, and generally speaking, the experience on basically any web site that needs information from you is equally… exciting.

PhraseForm is an attempt to make things more interesting and personal for your user. Instead of giving them a traditional form, put your input into the context of a sentence or question that they can then complete. It’s a little bit like a Mad Libs game.

Of course, nothing is stopping you from simply writing up some HTML that places some words around your inputs, so what is the point of a javascript plugin that does it for you?

Good question! The point of this plugin — indeed, the point of most javascript — is to add a dynamic, interactive element to these natural language forms. This plugin handles the messiness of dynamically adding, removing and grouping your form inputs based on your user’s needs at any given point in time.

What’s the catch?

Well, for now at least, the forms you’ll end up with aren’t going to be the most accessible. No labels for your inputs, and all that jazz. I’m working hard to figure out a way to make these dynamic forms every bit as accessible as the boring ones we’ve been using for years, but it’ll be a while before I settle on a solution I’m happy with.

Oh, and this plugin uses jQuery, so you’ll need to include it if you plan to use this. At this point, there are no plans to develop this plugin using straight javascript, or another library. Sorry.

How do I turn my form into a phrase form?

Build your form

You can do this using the utilities in the plugin’s build namespace, but it’s probably a good idea to have a static form to fall back on for those noscript nutjobs, anyhow.

  <form id="petShop" method="POST" action="#">
    <input id="pet" type="text" />
    <input id="size" type="text" />
    <input id="color" type="text" />
  </form>

Build your NaturalForm object

This part’s easy, of course. Just create a PhraseForm object. You can pass in a jQuery object, like so:

  var search = new PhraseForm($('#petShop'));

Or you can create an empty object and attach your form later, like so:

  var search = new PhraseForm();
  search.make.from($('#petShop'));

At this point, all of your inputs will disappear. Don’t panic! Just read through to the next step.

Note: For you diehard script-fu masters that refuse to work with HTML directly, you can use the plugin to generate your whole form, using make.new, build.input and/or build.inputs:

  var search = new PhraseForm();
  
  var myForm = search.make.new({
    method : 'POST',
    action : '#',
    id : 'petShop'
  });
  
  search.build.input({ id : 'pet' }); //Build a single input
  search.build.inputs([               //Build multiple inputs (passed as an array of hashes)
    { id : 'size' },
    { id : 'color' }
  ]);
  
  $('body').append(myForm);

Honestly, though, unless your site is just way too dynamic, there’s not any real benefit to doing things this way.

Build your contexts

You can build contexts for individual inputs with build.context, or make a batch of contexts with build.contexts.

  search.build.context('pet', 'I want to buy a pet %input.');
  search.build.contexts({
    'size' : 'It needs to be %input or it won\'t fit in the house.',
    'color' : 'I\'ve always been partial to the color %input.' 
  });

The format for a context? A string containing any text you want, with the delimiter %input wherever you want your input to show up in the phrase.

Re-build your form

Now, any inputs you want your user to see, you just add back to the form. Functions that manipulate the items in your phrase form are located in the act namespace.

  search.act.add('pet');
  search.act.add('color');

Build your groups

You’ve probably noticed two things: First, that adding fields one by one is a little inconvenient, and second, that the language turns out a little stiff when you have a bunch of contexts strung together. The solution? Groups.

With groups, you can associate several inputs together, and even add a custom group context which will contextualize the inputs in a more fluid manner.

  search.build.group('spottedPet', ['pet', 'color']);

At this point, you can add both the ‘pet’ and ‘color’ inputs to the form with the contexts we already gave them, with search.act.add('spottedPet');. Or, even better, we can create a group context for the two inputs:

  search.build.context('spottedPet', 'I am looking for a pet %input, preferably with %input stripes.');

Note: The inputs will be inserted into the context in the order they were listed in the group definition. Now, when we add our input group to the form, we get a much cleaner contextualization that wraps both inputs together.

Remove your inputs

The form wouldn’t be very dynamic if you couldn’t remove inputs as well as add them. The command is simple:

  search.act.remove('pet');

Get results

One of the goals of this plugin is to make things readable and helpful for the developer, as well. The get namespace offers a few utilities to make parsing your phrase form a breeze.

Need to retrieve the current value of an input or group of inputs? There’s a utility for that:

  search.get.value('pet');        //This will return a single string value
  search.get.value('spottedPet'); //This will return an array of string values

Need to get the end result of your contextualized query string with the user’s input values inserted, to display or log somewhere? There’s a utility for that, too:

  search.get.query();       //This will return a string for all currently added inputs
  search.get.query('size'); //This will return a string for the specified input

What’s coming next?

1. Creation of form by name, rather than jQuery object
2. Better accessibility features
3. Support for non-‘text’ inputs
4. A better example file
5. Aliasing of input ids