mongoose-formulate

Mongoose Formulate

Mongoose Formulate is a package of 2 mongoose plugins that allow you to bake a programmatical CMS into your existing applications. It's intended to be used to build a framework that allows dynamic creation of form templates that in turn structure input that is stored in entries.

What is it for?

If you need a system for allowing users of your application to define custom form templates based on common input formats and a flexible way to store data submitted against those templates, Formulate is for you. Think of it as a pluggable CMS. If your looking for a full-blown CMS solution then it's not for you. There is no UI component, everything is powered programmtically and the UIs for the fieldtypes, templates and forms must be implemented by you. This is by design.

How to use it

npm install mongooose-formulate

First you need to setup the template plugin:

// install the template plugin on an existing collection, or create a generic 'templates collection'
var mongoose = require('mongoose');
var formulate = require('mongoose-formulate')
var Schema = mongoose.Schema;

// the plugin only adds additional fields to your schema, so you can add
// specific custom schema fields as you wish. Name would be an obvious one
var schema = {
	name: String
};

schema.plugin(formulate.templatePlugin);
var TemplateModel = mongoose.model('template', schema);

Next setup the entry plugin. This is where your form content will be stored. Because this is just a mongoose plugin you add it to any of your exisiting collections (giving your form content 'context') or create a generic entries collection for ultimate flexiblity.

var mongoose = require('mongoose');
var formulate = require('mongoose-formulate')
var Schema = mongoose.Schema;

var myExistingSchema = {
	name: String,
	created: Date
};

schema.plugin(formulate.entryPlugin);
var MyModel = mongoose.model('my-model', schema);

Once the two plugins are setup, you can start adding custom templates. Here is an example of a user profile template:

TemplateModel.new({
  name: 'Example Template',
	template: {
	  fieldGroups: [
		  {
			  name: 'Full Name',
				options: {
				  customOption: true
				},
				fields: [
				  {
					  fieldtype: 'text'
					}
				]
			},
		  {
			  name: 'Date of Birth',
				options: {
				  customOption: true
				},
				fields: [
				  {
					  fieldtype: 'datetime'
					}
				]
			},
		  {
			  name: 'Employment Status',
				fields: [
				  {
					  fieldtype: 'select',
						validation: {
						  enum: ['Employed', 'Self-Employed', 'Unemployed']
						}
					}
				]
			},
		]
	}
})

You could then use this resuable template to generate 'entries' via your client applications, e.g. Mobile App or Web App. Your client will need to interpret these templates (this is the part you have to write yourself) so they can display some kind of form to the end user.

The entry mimicks the schema of the template, with the addition of a value property on the fields. An entry document might be created like so:

MyModel.new({
	name: 'Custom entry name',
	content: {
	  fieldGroups: [
		  {
			  name: 'Full Name',
				options: {
				  customOption: true
				},
				fields: [
				  {
					  fieldtype: 'text',
						value: 'John Smith' // the submitted value for the field
					}
				]
			},
		  {
			  name: 'Date of Birth',
				options: {
				  customOption: true
				},
				fields: [
				  {
					  fieldtype: 'datetime',
						value: Thu Apr 24 1987 00:00:00 GMT+0000 (UTC)
					}
				]
			},
		  {
			  name: 'Employment Status',
				fields: [
				  {
					  fieldtype: 'select',
						value: 'Employed', // any value not found in enum will invalidate
						validation: {
						  enum: ['Employed', 'Self-Employed', 'Unemployed']
						}
					}
				]
			},
		]
	}
})

As you can see it is a very flexible way to store data based on freeform data (e.g. data you will not define a schema for).

Overview

There are 3 components to Formulate: Fieldtypes, Templates and Entries.

Fieldtypes

Fieldtypes are the building blocks of your templates. They are a basic from of common inputs that should be flexible enough to handle most 'form content'.

Currently Formulate has the follow fieldtypes:

• Text
• Number
• Datetime
• Select
• Relationship
• Switch

Each of the fields has validation options (which, as they stand, need improving) which allows customisation of input you store in your entries.

Templates

Templates can be thought of as a Form Builder. Imagine templates as a way to programmatically store your content structures as you would in your CMS – Heads up: Formulate handles only the logic of structuring and storing your content. There is no UI component to this package, that part is up to you!

Templates contain an Array of fieldGroups, which you can imagine as a single line of input in a traditional form entry. They have the following properties:

• Label
• Description
• Options
• Fields
  • Fieldtype
  • Validation
  • Options

Entries

Entries are where the data for a submitted template is stored. Entries mimick the schema used for the template they were based on, but there is no definite relationship between the two. E.g. Once an entry is created, it holds a copy of the template it was based on, so existing templates can be safely updated without affecting historical entries.