API Reference

There are two main objects that you will interact with using the Forms 2.0 API. The MktoForms2 object and the Form object. The MktoForms2 object is the top-level publicly visible namespace for Forms2 functionality and contains functions to create, load, and fetch Form objects.

MktoForms2 Methods

Method Description Parameters
.loadForm(baseUrl, munchkinId, formId [,callback]) Loads a form descriptor from Marketo servers and creates a new Form object. returns undefined

baseUrl Type: String
URL to the Marketo server instance for your subscription

munchkinId Type: String
Munchkin ID of the subscription

formId Type: String or Number
The form version id (Vid) of the form to load

callback Type: Function (optional)
A callback function to pass the constructed Form object to once it has been loaded and initialized.

.lightbox(form [,opts]) Renders a lightbox style modal dialog with the Form object in it. returns Type: Lightbox Object
A lightbox object with .show() and .hide() methods.

form Type: Form Object
An instance of a Form object that you want to have rendered in a lightbox.

opts Type: Object (optional)
An object of options passed to the lightbox object

  • onSuccess Type: Function
    A callback that will be triggered when the form is submitted.
  • closeBtn Type: Boolean default true
    Controls if a close button (X) is displayed on the lightbox dialog.
.newForm(formData [,callback]) Creates a new Form object from a Form Descriptor JS object returns undefined

formData Type: Form Descriptor Object
A form descriptor object, as created by the Marketo Forms V2 Editor

callback Type: Function
A callback function that will be called once all stylesheets and known lead information has been fetched and the Form object has been created.
This callback will be called with a single argument, a newly created instance of Form object.

.getForm(formId) Gets a previously created Form object by form identifier returns Type: Form Object

formId Type: Number or String
Form Vid Identifier.

.allForms() Fetches an array of all form objects that have been previously constructed on the page. returns Type: Array of Form Object
.getPageFields() Gets a JS object containing data from the url and referrer that may be interesting for tracking purposes. returns Type: Object
.whenReady(callback) Adds a callback that will be called exactly once for each form on the page that becomes “ready”. Readyness means that the form exists, has been initially rendered and had its initial callbacks called.

The callback is passed a single argument, a form object.

If there is already a form that is ready at the time this function is called, the passed callback will be called immediately.

returns Type: MktoForms2 Object
.onFormRender(callback) Adds a callback that will be called every time any form on the page renders. Forms are rendered when initially created, then again every time that visibility rules alter the structure of the form.

The callback will be passed a single argument, the form object of the form that was rendered.

returns Type: MktoForms2 Object
.whenRendered(callback) Like onFormRender, this adds a callback that will be called every time a form is rendered. Additionally, this will also call the callback immediately for all forms that have already been rendered.

The callback will be passed a single argument, the form object of the rendered form.

returns Type: MktoForms2 Object

Form Methods

Method Description Parameters
.render([formElem]) Renders a form object, returning a jQuery object wrapping a form element that contains the form. If passed a formElem, it will use that as the form element, otherwise it will create a new one. returns Type: jQuery Object
A jQuery wrapped form element containing the rendered form.

formElem Type: jQuery Object
A jQuery wrapped form element into which to render.

.getId() Gets the id of the form. returns Type: Number
The id of the form object that this form represents.
.getFormElem() Gets the jQuery wrapped form element of a rendered form. returns Type: jQuery Object
A jQuery wrapped form element or null if the form has not been rendered with the render() method yet.
.validate() Forces the form to validate, highlighting any errors that may exist and returning the result. Does not submit the form. returns Type: Boolean
true if all the validators on the form passed, false otherwise.
.onValidate(callback) Adds a validation callback that will be called anytime validation is triggered. returns Type: Form Object
The same form object on which the method was called, for chaining purposes.

callback Type: Function
A callback that will be triggered any time that validation occurs.
The callback will be passed one parameter, a boolean stating if the validation had succeeded.

.submit() Triggers the form’s submit event. This will start the from submit flow, performing validation, firing any onSubmit events, submitting the form, and firing any onSuccess events if form submission was successful. returns Type: Form Object
The same form object on which the method was called, for chaining purposes.
.onSubmit(callback) Adds a callback that will be called when the form is submitted. This is fired when the submission begins, before the success/failure of the request is known. returns Type: Form Object
The same form object on which the method was called, for chaining purposes.

callback Type: Function
A function that will be called when the form is submitted. This callback will be passed one argument, this Form object.

.onSuccess(callback) Adds a callback that will be called when the form has been successfully submitted but before the lead is forwarded to the follow up page. Can be used to prevent the lead from being forwarded to the follow up page after successful submission. returns Type: Form Object
The same form object on which the method was called, for chaining purposes.

callback Type: FunctionA function that will be called when the form has been successfully submitted. This callback will be passed two arguments. A JS Object containing the values that were submitted and a String url of the follow up page that the user will be forwarded to, or null or empty string if there is no configured follow up page.Special behavior: If this callback returns a false (measured using ===) then the visitor will NOT be forwarded to the follow up page and the page will NOT be reloaded. This allows the implementor to do extra processing to the follow up url, or to take action on page using JavaScript instead of leaving the page.

.submittable([canSubmit])
also available as:
.submitable([canSubmit])
Gets or sets whether the form can be submitted. If called with no arguments, it gets the value, if called with one argument it sets the value.This can be used to prevent a form from being submitted while other criteria outside of the normal form need to be fulfilled. returns Type: Boolean or Form Object.

If called with no arguments, returns a boolean indicating if the form is submittable. If called with one argument, returns this Form Object for chaining purposes.

canSubmit Type:Boolean
Sets the form to be submittable or non submittable.

.allFieldsFilled() Returns true if all the fields in the form have non-blank values set. returns Type: Boolean
True if all fields have non-blank/empty/unset/null values, false otherwise.
.setValues(vals) Sets values on one or more fields in the form. returns undefined

vals Type: Object
A JS Object. For each key/value pair in the object, the form field named key will be set to value.

.getValues() Gets all the values of all the fields in the form. returns Type: Object
A JS Object containing key/value pairs representing the names and values of the fields in the form.
.addHiddenFields(values) Adds input type=hidden fields to the form. returns undefined

values Type: Object
A JS Object containing key/value pairs representing the names and values of the hidden fields to add to the form.

.vals([values]) jQuery style .vals() setter/getter. If called with no arguments, is equivalent to calling getValues(). If called with one argument, is equivalent to calling setValues() returns undefined

values Type: Object

.showErrorMessage(msg [,elem]) Shows an error message, pointing at elem. returns Type: Form Object
This Form object, for chaining.

msg Type: String of HTML
A string containing the text of the error you want to show.

elem Type: jQuery Object
The element for the error to point to. If unset, the form’s submit button is used.