v 1.1.3

modo.FormContainer

Use this container to create edit forms for your data.

You can add different editing controls to it (eg. Textfields, ToggleButtons, Dropdowns... basically everything with a get() and set() method) and assign each control to a specific value of a object or Backbone Model. When you pass a object or Backbone Model to the FormContainer, each value is provided to the connected element. If autosave is enabled, all data from all elements is automatically assigned back to the original object/model structure upon changes.

You can also use the Modo FormContainer to collect and transfer data to your server by either a AJAX request, or a standard form submission.

Constructor

modo.FormContainer(params)modo.FormContainer

The following list of parameters can be used in the params object, passed to the constructor. Parameters in [brackets] are optional.

PropertyDescription

[autosave]

Set this to true, if you want to get automatic backward databinding between form elements and a Backbone Model. Optional. Default = false.

[autosync]

Set this to true, if you want a connected BackboneJS Model to automatically send changes to the server.

[csrf]

When you are working with CSRF tokens (and you should!), you can pass the token here. When you do AJAX or form submission communication to your server, a value named csrf_token will be automatically sent along.

[prepare]

Prepare functions are used to convert data from the data source to the specified element. Example:

function(dataValue){
  return convertedValue;
}

Pass an key/value object here, where the keys match the keys of the Backbone Model or JavaScript Object you want to change and the values contain converter functions.

[clean]

Clean Functions are used to convert data from the specified element to the data source. Example:

function(elementValue){
  return convertedValue;
}

Note: If the function returns undefined, then nothing will be assigned to the data source (original will be kept).

[finalPrepare]

This function is called, AFTER all prepare functions for the specified elements have been run.
The complete prepared dataset can be manipulated and extended before its finally distributed to the single elements.
May be necessary to feed multiple multiple control elements from one data value.

[finalClean]

This function is called, AFTER all clean functions for the data source have been run.
The complete prepared data set can be manipulated, before its copied to the originally passed object / Backbone Model.
May be necessary to set one data value from multiple control elements, or remove temporary data fields.

[defaultData]

The blank data object will be used as form data when the set() function is called with no data.
Useful for setting default values for new data objects.

[layout]

Define here, if contained elements should be layed out in Block (modo.Container.NORMAL) or Inline-Block (modo.Container.INLINE) mode, by default. Default: modo.Container.NORMAL

[className]

A string with custom CSS classes to apply to the generated DOM element

[dataAttributes]

A object with attributes to assign to the generated DOM element. Omit the "data-" part. So for example {count: 1} becomes data-count="1" on the DOM element.

[el]

The jQuery enhanced DOM element to be generated. If nothing is set, a standard DIV container will be created. If you want to use a different DOM element, pass a jQuery generated DOM element to this parameter.

[showEffect]

The default show effect for the element. See associated property description. Default: null

[hideEffect]

The default hide effect for the element. See associated property description. Default: null

Properties

dirtyBool

This flag will be set to true when one of the contained, keyed set/get enabled elements fire a change event. It will be set back to false, after a set() or save() call. Note: This will never switch to false in a autosave enabled FormContainer!

defaultDataObject

The blank data object will be used as form data when the set() function is called with no data. Useful for setting default values for new data objects.

Inherited Properties from modo.Container

Methods

add(...)this

Use this function to add one or more modo / jQuery / DOM elements to the container. Will trigger the Backbone Event "add". Either pass:

  • Modo elements directly
  • DOM/jQuery elements directly
  • Modo elements encapsulated in a object to add them with keys. Example: {mykey: someModoElement}

remove(key, [force=false])this

This will remove the element with the given key from the container.

You cannot remove elements nested inside a modo.FormSlot container by default. Pass force = true to remove the parent FormSlot container of the given element as well. Be careful, this might remove other elements with different keys that are also stored in that FormSlot!

removeAll()this

Will remove all elements from that FormContainer.

set(data)this

Will pass a new dataset into the container and will populate all children with a set() function and a given key with its matching data. When you omit the data property, the form will be reset to the defaultData you have pre-defined.

reset([options])this

Same as calling set() without a parameter, but may be easier to remember.

get()object

Will return a getJSON()-like formatted object with all current values from all elements with a get() method and a populated key.

getElements()array

Returns an array of all added elements.

save()this

Writes all changed data back to the given dataset.

send(options)this

This method can be used to transport your collected data via HTTP. Submit the parameter ajax = true to have it sent with an AJAX request (and the result returned in a callback), or set ajax = false to submit the data like a traditional <form>-tag (triggers page load).

Available Options
ParameterDescription

target

The URL which should receive the data.

[method]

HTTP method to be used. default = POST

[ajax]

Should the data be sent through a AJAX call, or with traditional form submission? default = true

[callback]

A function to be called after the data has been sent. Will receive an argument with the response string.

focus()this

Will try and set the input focus to the first element.

Inherited Methods from modo.Element

add(element, ..., [options])this

Use this function to add one or more modo / jQuery / DOM elements to the container. Will trigger the Backbone Event "add", unless {silent: true} is passed as option object.

remove(element, ..., [options])this

This will remove one or more elements from the container. Either pass a modo element here, to get it removed from the container, or pass a jQuery selector to remove a DOM element.

Inherited Methods from modo.Element

setFlexible([value])this

Pass either true or false to this value to make the element stretch inside a modo.FlexContainer element.

show(options)this

Make the connected DOM object visible and trigger the Backbone Event "show".

You can control the way the element is shown by passing an object of options.

Example:

element.show({
    effect: 'slideDown',
    effectArgs: ['fast']
});

hide()this

Make the connected DOM object invisible and trigger the Backbone Event "hide".

You can control the hide effect the same way as with the show() method.

addClass(classname, doPrefix)this

Will add another class name to the DOM element. The class name will be automatically prefixed (i.e. with mdo-) if doPrefix = true (default).

removeClass(classname, doPrefix)this

Will remove a class name from the DOM element. The class name will be automatically prefixed.

addClassTemporary(classname, timeout, doPrefix)this

Helps with adding a classname temporarily to the object. Just call this method and after the specified amount of time, the added class(es) will be removed.


Note: All modoJS Objects are extended with all methods of the Backbone.Events class.


Events

change

Triggered, wenn the forms dataset has been changed through a call to set().

save

Triggered after the save() method has been called.

Inherited Events from modo.Container

add

Triggered, when a child has been added through add()

Event ParameterDescription

childElement

Can be either a modo element, a jQuery enhanced DOM object, or a DOM object

remove

Triggered, when a child has been removed through remove()

CSS Classes

mdo-formcontainer

Will be added to this element.

Inherited CSS Classes from modo.Container

mdo-container

Applied to the modo element.

mdo-container-layout-normal

Applied when horizontal container layout is configured.

mdo-container-layout-inline

Applied when vertical container layout is configured.

Inherited CSS Classes from modo.Element

mdo-element

Basic class that will be applied to every element that extends modo.Element.

mdo-flexible

Will be applied to every modo element where setFlexible(true) has been called upon.

comments powered by Disqus