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 Returns
.loadForm(baseUrl, munchkinId, formId, callback) Loads a form descriptor from Marketo servers and creates a new Form object.
Name Type Description
baseUrl String URL to the Marketo server instance for your subscription
munchkinId String Munchkin ID of the subscription
formId String or Number The form version id (Vid) of the form to load
callback (optional) Function A callback function to pass the constructed Form object to once it has been loaded and initialized.
undefined
.lightbox(form, opts) Renders a lightbox style modal dialog with the Form object in it.
Name  Type Description
form Form Object An instance of a Form object that you want to have rendered in a lightbox.
opts (optional) Object An object of options passed to the lightbox object
  • onSuccess
Function A callback that will be triggered when the form is submitted.
  • closeBtn
Boolean default true Controls if a close button (X) is displayed on the lightbox dialog.
A lightbox object with .show() and .hide() methods.
.newForm(formData, callback) Creates a new Form object from a Form Descriptor JS object.

Adds a callback function that will be called once all stylesheets and known lead information has been fetched and the Form object has been created.

Name Type Description
formData Form Descriptor Object A form descriptor object, as created by the Marketo Forms V2 Editor
callback (optional) Function This callback will be called with a single argument, a newly created instance of Form object.
undefined
.getForm(formId) Gets a previously created Form object by form identifier
Name Type Description
formId Number or String Form Vid Identifier.
Form Object
.allForms() Fetches an array of all form objects that have been previously constructed on the page. n/a Array of Form Object
.getPageFields() Gets a JS object containing data from the url and referrer that may be interesting for tracking purposes. n/a 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.

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

Name Type Description
callback Function

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

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.
Name Type Description
callback Function  The callback will be passed a single argument, the form object of the form that was rendered.
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.
Name Type Description
callback Function  The callback will be passed a single argument, the form object of the rendered form.
MktoForms2 Object

Form Methods

Method Description Parameters Returns
.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.
Name  Type Description
formElem (optional) jQuery Object A jQuery wrapped form element into which to render.
Type Description
jQuery Object A jQuery wrapped form element containing the rendered form.
.getId() Gets the id of the form. n/a
Type Description
Number The id of the form object that this form represents
.getFormElem() Gets the jQuery wrapped form element of a rendered form. n/a
Type Description
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. n/a
Type Description
Boolean Returns 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.
Name Type Description
callback 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.
Type Description
Form Object The same form object on which the method was called, for chaining purposes.
.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. n/a
Type Description
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.
Name Type Description
callback Function A function that will be called when the form is submitted. This callback will be passed one argument, this Form object.
Type Description
Form Object  The same form object on which the method was called, for chaining purposes.
.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.
Name Type Description
 callback  Function A 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.

Type Description
 Form Object The same form object on which the method was called, for chaining purposes.
.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.
Name Type Description
 canSubmit (optional)  Boolean Sets the form to be submittable or non submittable.
Type Description
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.
.allFieldsFilled() Returns true if all the fields in the form have non-blank values set. n/a
Type Description
 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.
Name Type Description
 vals  Object A JS Object. For each key/value pair in the object, the form field named key will be set to value.
 undefined
.getValues() Gets all the values of all the fields in the form. n/a
Type Description
 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.
Name Type Description
 values  Object A JS Object containing key/value pairs representing the names and values of the hidden fields to add to the form.
 undefined
.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()
Name Type Description
 values (optional)  Object


  undefined
.showErrorMessage(msg, elem) Shows an error message, pointing at elem.
Name Type Description
 msg String of HTML A string containing the text of the error you want to show.
elem (optional) jQuery Object The element for the error to point to. If unset, the form’s submit button is used.
Type Description
 Form Object  This Form object, for chaining.