Form Configuration API

Caldera Forms has a PHP API and REST API for interacting with form configurations. This document covers programatically reading and writing form configurations and revisions. This is done via the Caldera_Forms_Forms class.

This is developer-facing documentation. It is not required for regular use to use the functions described here. The Caldera Forms shortcode is the easiest way to show a form.

How Forms Are Stored In The Database

Previous to Caldera Forms 1.5.3, forms were stored in the options table. In Caldera Forms 1.5.3 a table ‘cf_forms’ was added to store form configuration. This change was made to allow for form configuration revisions. This table has four columns:

• id – The database ID. This value is auto-incrimenting and unique.
• form_id – The form ID. This is the ID used in the UI. There can be many forms with the same ID beacuse some will be revisions.
• Type – This is either “primary” or “revision”. There should only be one “primary” form per form ID.
• Config – This is the form’s configuration. This is a stored as a serialized array.

Important Concept: Every form has 1 row in the database with the type “primary” this is the primary form and is the one that gets used. All other rows are revisions. When a form is saved, a new row is created and given the type “primary” while the old primary is given the type “revision.” Restoring a revision changes the primary form’s type to “revision” and then changes the saved revision’s type to “primary.”

Form state — active or disable — is not related to type. Form state, is saved in config and doesn’t get its own column because it’s a dumb feature that should be removed, but backwards-compat.

Migration to the new table is automatic and will happen the first time you go to the main Caldera Forms admin page after migrating, or otherwise call form configurations.

Public Methods

In this section the Caldera_Forms_Forms class is discussed. It is important to note that the Caldera_Forms_DB_Form class is the low-level API for accessing the forms table, but it should not be used directly. Always use Caldera_Forms_Forms.

get_form()

Caldera_Forms_Forms::get_form() Is used to retrieve a form’s configuration from the database and those added via filters form the file system. This returns an array with all form details. Before being returned, the form configuration is passed through the caldera_forms_get_form filter.

This method has one parameter:

• $form_id (string) – This is the form ID ‘cf…’.

Notes:

• Caldera_Forms::get_form() is a wrapper for this method. Consider that method “soft deprecated”.

get_forms()

Caldera_Forms_Forms::get_forms() Is used to retrieve all forms from the database and those added via filters form the file system.

This method has two parameters:

• $with_details (bool) – This is optional.
  • If false, the default, the returned value will be an array of form IDs.
  • If true, the returned value will be an array. The keys of the array will be form IDs and the values will be an array with basic details.
    • Basic details means what is needed to create the form list in the main Caldera Forms admin page.
• $internal_only (bool – This is optional.
  • If false, the default, filters will be used to allow loading forms from the file system.
  • If true, only forms in the database will be returned.

Notes:

• Caldera_Forms::get_forms() is a wrapper for this method. Consider that method “soft deprecated”.

save_form()

Caldera_Forms_Forms::save_form() is used to update a form’s configuration in the database.

This method has two parameters:

• $data (array) – The value to save.
• $type (string) – This is optional. If it is ‘primary’ the primary form is updated. If not a revision is saved.

Notes:

• Caldera_Forms_Admin::save_a_form() is a wrapper for this method. Consider that method “soft deprecated”.
• Caldera_Forms_Admin::save_form() is the handler for UI form save/export/delete/clone/etc. via HTTP request. Don’t use that.

create_form()

Caldera_Forms_Forms::create_form() is used to create a new form.

This method accepts one parameter:

• $newform (array) – Data used to create the new form.
  • name (string) Required if not cloning. New form name.
  • description (string) Optional.
  • Success (string) Optional.
  • form_ajax (bool) Optional. Default is true. Whether to use AJAX submissions.
  • hide_form (bool) Optional. Default is true. Whether to hide form after submission.
  • check_honey (bool) Optional. Default is true. Whether to use the anti-spam honey pot.
  • db_support (bool) Optional. Default is true. Whether to save entries in the database.
  • mailer (bool) Optional. Default is true. Whether to use the main mailer.
  • clone (string) – Optional. The ID of a pre-existing form to clone.
  • template (string) – Optional. The name of a template to use to create this form.
    • Must be a key of the array returned by the Caldera_Forms_Admin::internal_form_templates() method, which can be modified using the caldera_forms_get_form_templates

delete_form()

Caldera_Forms_Forms::delete_form() is used to delete a form by ID.

This method accepts one parameter:

• $id (string) – The form ID.

Notes:

• This method deletes the primary form and all revisions.

get_fields()

Caldera_Forms_Form::get_fields() returns all fields of a form, by default in their layout order.

This method accepts two parameters:

• $id (string) – The form ID.
• $in_order (bool) – Optional.
  • If true, the default, the fields are sorted by their layout order.
    • This option is used when you want the forms in the logic order — IE how the form looks.
    • The caldera_forms_get_field_order filter can be used to change the field order.
  • If false, the fields will be returned in the order they were added to the form.
    • This option is used when order doesn’t matter. It is slightly faster.

Note:

• This method uses the “fields” key of the form configuration.
• Fields returned here are not filtered. Caldera_Forms_Field_Util::get_field() can be used to get a field’s configuration with all the correct filters applied.

is_internal_form()

Caldera_Forms_Forms::is_internal_form() is a utility method to check by form ID if a form is “internal” IE saved in the database.

This method accepts one parameter:

• $id (string) – The form ID.

Notes:

• Hi Roy

form_state()

Caldera_Forms_Forms::form_state() is a method to toggle a form’s state between enabled and disabled.

This method accepts two parameters:

• $id (string) – The form ID.
• $enable (bool) – Optional.
  • If true, the default, the form will be enabled.
  • If false, the form will be disabled.

Notes:

• This is for the UI option to enable forms. It is not related to form type.
• This changes the value of the form config’s “form_draft” index.

entry_list_fields()

Caldera_Forms_Forms::entry_list_fields() gets the “entry list fields”. By “entry list field” we mean a field that shows in the main entry viewer table view. Fields are designated to be entry list field by checking the “Show In Entry List” option.

This method accepts two parameters:

• $form (array) – The form configuration
• $configs (bool) – Optional.
  • If true, field configuration arrays are returned.
  • If false, the default, field IDs are returned.

get_revisions()

Caldera_Forms_Forms::get_revisions() gets all form revisions by form ID.

This method accepts two parameters:

• $id (string) – The form ID.
• $simple (bool) – Optional.
  • If true, only revision ID (database row ID) is returned per form.
  • If false, the default, full form configurations are returned for each form revision.

get_revision()

Caldera_Forms_Forms::get_revision() gets one form revisions by database row ID.

This method accepts two parameters:

• $id (string) – The revision ID.