form-creator

This is a form creator for Meteor.js.

Installing

meteor add krstffr:form-creator

Example app

There is an example app in the /example/form-creator-example directory. You can also view the app here: http://form-creator.meteor.com

Still in the early stages!

This package is under development and should probably not be considered safe to use just yet.

Usage

There are two different usage scenarios for this package:

Creating a form where all the fields you define for the form are stored in a MongoDB collection.
Creating a form where you provide your own callback for the form (where you have access to all the field values and can do to them whatever you like).

Scenario 1: Where you want to store the data from a form in a MongoDB collection

When you've installed the package there'll be a FormCreator object available on the client and the server.

Start by defining an array of all the forms you want on both the client and server, then pass it to the FormCreator.setupForms( forms ) method. This will create (and validate) all the forms you've defined, and you can now get them in your HTML by using the {{> formCreatorForm 'formName' }} helper. This get's the form with the name 'formName' from the forms you passed to the setupForms() method.

But let's first look at how you define your forms. Let's first create an empty array where you store all your forms.

1// An array for storing all of our forms.
2var forms = [];

Now let's create a very basic form for storing blog posts with only two inputs: title and content.

1// Make sure we have a collection defined where we store the data
2BlogPosts = new Meteor.Collection('blogPosts');
3
4// A very simple blogPost form
5var blogPostForm = {
6
7  // name: This is the name of the form.
8  // The name is used for outputting the form in the HTML, using this helper:
9  // {{> formCreatorForm 'blogPostForm' }}
10  name: 'blogPostForm',
11
12  // description: The description is optional, and will be displayed above the form (if you want it to)
13  description: 'This is a form for creating and updating blogPosts.',
14
15  // collectionName: The name of the collection where you want to save the form data.
16  collectionName: 'BlogPosts',
17
18  // fields: An array of all the form inputs
19  fields: [{
20
21    // name: The name of the form input. This will also be the stored key in the DB.
22    name: 'title',
23
24    // fieldType: What type is this input?
25    // The valid types are: 'text', 'textarea', 'select', 'number', 'date', 'password'
26    fieldType: 'text',
27	
28    // label: This will be displayed as a <label> above the input
29    label: 'The title of the blog post',
30		
31  },
32  {
33    name: 'content',
34    fieldType: 'textarea',
35    label: 'The blog post content'
36  }],
37
38  // options: The options object contains various options for the form
39  options: {
40
41    // storeable: If false then you won't be able to save data to the DB
42    storeable: true,
43
44    // Do you also want to be able to delete documents?
45    deletable: true
46
47  }
48};

Now push the form to the forms-array and pass the forms-array to the FormCreator.setupForms( forms ); method.

1FormCreator.setupForms( forms );

And finally, let's output the form to our HTML:

{{> formCreatorForm 'blogPostForm' }}

Now you'll see your form in you HTML and you should be able to save blog posts to your DB!

More options

Creating a select input

1// Add an object like this to the form.fields array
2{
3  name: 'rating',
4
5  // fieldType: 'select'; 
6  //This will make the input a <select>
7  fieldType: 'select',
8
9  label: 'How good do you think this blog post is?',
10
11  // selectOptions: Here are the <options> for the <select>
12  // value: this is the actual value which will be stored
13  // text: this is the text the user sees in the <option>
14  selectOptions: [
15  { value: 5, text: '5/5: BRILLIANT!' },
16  { value: 4, text: '4/5: Good.' },
17  { value: 3, text: '3/5: OK' },
18  { value: 2, text: '2/5: Needs work.' },
19  { value: 1, text: '1/5: WTF is this rubbish!!?' }
20  ]
21}

Creating a required object which should be a number

1// Add an object like this to the form.fields array
2{
3  name: 'someNumber',
4  fieldType: 'number',
5  label: 'Please give us a number',
6
7  // This will make the input only accept numbers
8  valType: 'number',
9
10  // This will make the input required
11  required: true
12}

Some options for the form

1options: {
2
3  // storeable: Makes the form storable in the DB.
4  storeable: true,
5
6  // deletable: Gives the user the ability to remove documents
7  deletable: true,
8
9  // showTitle: The form will display the name of the form as a headline at the top
10  showTitle: true,
11
12  // showDescription: The form description will be shown below the title
13  showDescription: true,
14
15  // textButtonSave: Allows you to give the "Save" button to have a custom text.
16  textButtonSave: 'Publish blog post',
17
18  // textButtonUpdate: Allows you to give the "Update" button to have a custom text.
19  textButtonUpdate: 'Update blog post',
20
21  // textButtonDelete: Allows you to give the "Delete" button to have a custom text.
22  textButtonDelete: 'Remove blog post 4-ever!',
23
24  // textButtonCancel: Allows you to give the "Cancel" button to have a custom text.
25  textButtonCancel: 'I don\'t want to update this blog post',
26
27}

Updating an existing doc

If you want to update an existing document, pass the document and the formName to the FormCreator.updateDocInForm( doc, formName ); method. Maybe you have a button below every blog post which set's this up like this:

1Template.blogPost.events({
2  'click .edit-link': function ( e ) {
3    FormCreator.updateDocInForm( this, 'blogPostForm' );
4  }
5});

Now the form will show the document in the form and the Update/Delete/Cancel buttons will be displayed.

See the example app for how this could look.

Scenario 2: Where you provide your own callback

It might be wise to check out scenario 1 before trying this.

All you need to do to handle the form submissions yourself is to provide a submitCallback: fn() to the form you create. See example which will just alert(); the value of the alertThis text input.

1var formWithCustomCallback1 = {
2  name: 'customCallbackForm1',
3  description: 'A form which does not store data.',
4  fields: [{
5    name: 'alertThis',
6    fieldType: 'text',
7    label: 'Alert this!',
8    valType: 'string',
9    required: true
10  }],
11  options: {
12    storeable: false,
13    deletable: false,
14    showTitle: false,
15    showDescription: true,
16    textButtonSave: 'ALERT!',
17  },
18  submitCallback: function ( values ) {
19    // From this callback, all the values which the user has
20    // passed from the form are available in the values object.
21    // Just use the name of the input to get the value
22    return alert( values.alertThis );
23  }
24};

Of course, from within the callback you can do whatever crazy stuff you feel like, like calling methods on the server which you've defined or do whatever.