The Submission class is initialized once for each loaded submission. It acts as a model for individual submissions.
Methods
clone()
This method is available to server-side scripts.
Returns an unsaved local copy of the submission. The clone is based on the current state of the submission, and will have any unsaved changes that the submission has.
var clone = submission.clone();
clone.submit();
display()
Returns a string indicating the format that the submission is displayed in. It can have the values "page", or "modal". A return value of page indicates that the submission's form is displayed in full-page format, in the body of the page. A return value of modal indicates that the submission was dynamically loaded with a modal. The submission.modal object will be undefined unless the display type is modal.
if (submission.display() == "modal") {
submission.modal.show();
}
destroy()
This method is available to server-side scripts.
Sends a request to the server deleting the submission. Returns a jQuery Deferred object. This method is the reverse of restore. Because Forms has submission-based version control, there is no permanent deletion of forms. Users and scripts with permission can restore a deleted submission at any time. Deleting a submission hides it from all tables and reports.
submission.destroy().done(function() {
// Destroyed successfully
}).fail(function(response) {
console.log(response.error) // "permission_denied"
});
destroyed()
This method is available to server-side scripts.
Returns a boolean value indicating whether the submission is currently deleted. This does not make a request to the server, and indicates the status at the time the submission was loaded. Using the destroy or restore methods will update this value.
if (submission.destroyed()) {
modal("You can't edit this!");
}
draft()
This method is available to server-side scripts.
Returns a boolean indicating whether the submission was loaded from a draft.
submission.draft()
element
Returns the jQuery DOM element containing the submission.
submission.element
fields
This method is available to server-side scripts.
The fields object contains API methods for accessing and controlling fields. For more information see Field Management.
submission.fields
submission.fields.first()
submission.fields.field_name.value("New Value")
modal
The modal object is a standard Modal object, and contains methods for controlling the modal that a submission is displayed in. Note that not all submissions are displayed in modals, and that this object will be undefined if this is the case. See display for more information.
if (submission.modal != undefined) {
submission.modal.show()
}
permalink()
This method is available to server-side scripts.
Returns the submission's permalink, a globally-unique alphanumeric ID. If the submission is unsaved, it will be undefined. Note that we do not guarantee that the formats of permalinks will not change for newly created submissions, and you shouldn't depend on the length of them. At the time of writing, permalinks are 10-character uppercase alphanumeric strings.
submission.permalink()
persisted()
This method is available to server-side scripts.
Returns a boolean indicating whether the submission has been saved to the server. This method is equivalent to checking if the submission's permalink is undefined.
submission.persisted()
redirect(url = undefined)
If a URL string is passed to the optional url parameter, the user will be redirected to that url when the form is submitted. By default, redirection will only fire for full-page submissions (see display for more information), since many modals can be open at a time. Calling this method with no parameter will redirect the user to the redirection url immediately, and can be called in an after_submit callback to force redirection for modal submissions.
submission.redirect("https://www.sonadier.com/")
submission.after_submit(function() {
submission.redirect()
})
refresh()
Recalculates the scripts used to format and style the submission's form element. This is done automatically and shouldn't be neccessary, but may resolve layout glitches triggered by custom scripts.
submission.refresh()
remove()
Removes the submission's element and modules, losing any unsaved changes. This will not delete the submission from the database.
submission.remove()
restore()
This method is available to server-side scripts.
Sends a request to the server restoring the submission. Returns a jQuery Deferred object. This method is the reverse of destroy. Because Forms has submission-based version control, there is no permanent deletion of forms. Users and scripts with permission can restore a deleted submission at any time. Deleting a submission hides it from all tables and reports.
submission.restore().done(function() {
// Restored successfully
}).fail(function(response) {
console.log(response.error) // "permission_denied"
});
submit()
This method is available to server-side scripts.
Submits the submission to the server after running any callbacks.
submission.submit()
values()
This method is available to server-side scripts.
Returns an object containing key-value pairs for the submission's field names and current values. The object's keys are snake_case versions of the human-readable field names, exactly the same as the Field Management object. The key is the field's variable name, a snake_case version of the original field name.
console.log(submission.values()) // { field_name: "The value of Field Name", another_field: "Another Value" }
Callbacks
after_create(method)
This method is available to server-side scripts.
Runs a passed method after the submission is created. This will only run the first time the submission is submitted.
submission.after_create(function() {
console.log("submission was created")
})
after_submit(method)
This method is available to server-side scripts.
Runs a passed method after the submission is submitted. This will run for both initial submission creation and for any updates.
submission.after_submit(function() {
console.log("submission was submitted")
})
after_update(method)
This method is available to server-side scripts.
Runs a passed method after the submission is updated. This will not run the first time the submission is submitted, but will run for any subsequent updates.
submission.after_update(function() {
console.log("submission was updated")
})
before_create(method)
This method is available to server-side scripts.
Runs a passed method before the submission is created. This will only run the first time the submission is submitted. The before_create method runs before the submission's data has been sent to the server, and can contain deferred objects that will block submission until resolution. This method should not be used to validate the submission, as it cannot stop the submission process. To validate a submission, use the validate method.
submission.before_create(function() {
console.log("submission was created")
})
before_submit(method)
This method is available to server-side scripts.
Runs a passed method before the submission is submitted. This will run both for initial submission creation and for any updates. The before_submit method runs before the submission's data has been sent to the server, and can contain deferred objects that will block submission until resolution. This method should not be used to validate the submission, as it cannot stop the submission process. To validate a submission, use the validate method.
submission.before_submit(function() {
console.log("submission was submitted")
})
before_update(method)
This method is available to server-side scripts.
Runs a passed method before the submission is updated. This will not run the first time the submission is submitted, but will run for any subsequent updates. The before_update method runs before the submission's data has been sent to the server, and can contain deferred objects that will block submission until resolution. This method should not be used to validate the submission, as it cannot stop the submission process. To validate a submission, use the validate method.
submission.before_update(function() {
console.log("submission was updated")
})
failed_create(method)
This method is available to server-side scripts.
Runs a passed method when creating the submission fails. This will only run if the submission has not been saved to the server.
submission.failed_create(function() {
console.log("submission could not be created")
})
failed_submit(method)
This method is available to server-side scripts.
Runs a passed method when submitting the submission fails. This will run both for initial submission creation failure and for any subsequent failures when editing the submission.
submission.failed_submit(function() {
console.log("submission could not be submitted")
})
failed_update(method)
This method is available to server-side scripts.
Runs a passed method when updating the submission fails. This will not run if the initial submission creation fails, but will run if editing a saved submission fails.
submission.failed_update(function() {
console.log("submission could not be updated")
})
validate(method)
This method is available to server-side scripts.
Runs a passed method to validate the submission before submission. If the method returns false, or adds any errors to fields with the Error object, submission will be cancelled and any errors will be shown. Be careful with returning false, since it will not display any indication to the user. Any errors added will be automatically displayed in the form element. All of the following methods will prevent the submission from submitting.
var user_is_project_manager = function() {
if (submission.fields.project_manager.value() != current_user.username) {
submission.fields.project_manager.error("You are not the project manager.")
}
}
submission.validate(user_is_project_manager)
submission.validate(function() {
if (submission.fields.status.value() != "Completed") {
submission.fields.status.errors.add("You must mark this as complete.")
}
})
submission.validate(function() {
modal("Please try again later.")
return false
})
In addition to the frontend "validate" callback, you can also write server-side Validations. Server-side validations use the same general API as client-side scripts, but cannot be bypassed by advanced users disabling scripting.