Scaffold

The Scaffold module is the heart of all our editing pages, and allows us to render user-friendly HTML forms from JSON schemas with very little effort.

Behind the scenes, Scaffold essentially provides a wrapper and Adapt-specific API for Backbone Forms, which itself is a flexible, customisable form framework for Backbone.js applications.

With Scaffold, you get the following:

• Fieldsets
• Custom views
• Custom fields
• Custom templates
• Custom validators

Scaffold also manages overlays opened during editing forms and pulls down new schemas when plugins are configured.

API

Quick navigation:

• buildForm
  • Building a form
  • Committing and saving the form
  • Updating schema models
• addCustomField
• addCustomValidator
• addCustomTemplate
• getCurrentModel

Origin.scaffold

A global Scaffold object is accessible throughout the lifespan of the application, and can be accessed from the Origin object.

The following functions are members of this global object.

buildForm(options:Object)

Builds a form object which can be used to append and commit the Backbone Form object.

Building a form

// using all defaults
var myForm = Origin.scaffold.buildForm({ model: contentObjectModel });

To use a different schemaType than the model's _type attribute, pass a schemaType attribute to the function:

var myForm = Origin.scaffold.buildForm({ model: contentObjectModel, schemaType: 'menuSchema' });

Committing and saving the form

To save a form, call commit() on the form object returned by Origin.scaffold.buildForm. The commit function returns a list of errors (if there are any):

var errors = myForm.commit();

if (errors) return console.error('There are errors');

Updating schema models

Schema models are cached in a collection on app initialize for speed. If you ever need to update the schema models, use the event scaffold:updateSchemas:

Origin.trigger('scaffold:updateSchemas', function() {
    // Callback function is called when new schemas have been fetched
}, this); 

addCustomField(fieldName:String, view:Backbone.View, overwrite:Boolean)

To add a custom field, pass in the fieldName and the Backbone view. This creates a custom view which can be used by specifying its type in a schema. The overwrite parameter specifies that Scaffold should overwrite any existing views using this name.

Tip: When building a custom view it's advised to follow this template: Backbone Forms Custom Editor.

Origin.scaffold.addCustomField('Asset:image', ScaffoldAssetView);

// Schema property
"inputType": "Asset:image"

addCustomValidator(name, validatorMethod)

Validators are used to ensure that a value for an input is within expected parameters.

To add a custom validator, pass in the name of the validator and the function you would like to use to validate the form input field.

Scaffold and Backbone Forms use an array of validators, so it's possible to have multiple validators for one input field.

Origin.scaffold.addCustomValidator('titleLength', function(value, formValues) {
  if (value.length < 3) {
    return {
        type: 'title',
        message: 'Titles must be at least 3 characters long'
    };
  };
});

// Schema property
"validators": ["titleLength"]

addCustomTemplate(templateName:String, template, overwrite:Boolean)

Sometimes you might want to use a different template without a new view. This is useful when using HTML input types such as password or number.

Origin.scaffold.addCustomTemplate('inputPassword', Handlebars.templates['inputPassword']);

// Schema property
"template": "inputPassword" 

getCurrentModel

Use this method to return the current model being edited in Backbone Forms.

var currentModel = Origin.scaffold.getCurrentModel();
console.log(currentModel.get('_parentId'));