$ninja_forms_processing

Type: Global Variable
Accepted Parameters: N/A.

Return: Used to interact with user-submitted values and form settings.

This global variable is available to functions attached to Ninja Forms processing hooks (ninja_forms_before_pre_process, ninja_forms_pre_process, ninja_forms_process, ninja_forms_post_process.).

It is the main tool for interacting with both user submitted values and stored form data. Developers should use this instead of simply trying to access $_POST or $_REQUEST data. It has already been sanitized, and values can be modified for use in other hooked functions.

Example:

This is an exhaustive list of the methods available to developers using the $ninja_forms_processing global variable to interact with user and form data:

Accessing and modifying general processing variables:

  • $ninja_forms_processing->get_user_ID() – Used to retrieve the User ID if the user was logged in.
  • $ninja_forms_processing->get_action() – Used to retrieve the action currently being performed. (‘submit’, ‘save’, ‘edit_sub’).
  • $ninja_forms_processing->set_action(‘action’) – Used to set the action currently being performed. (‘submit’, ‘save’, ‘edit_sub’).

Accessing and modifying user submitted values:

  • $ninja_forms_processing->get_all_fields() – Returns an array of all the user submitted fields in the form of array(‘field_ID’ => ‘user value’).
  • $ninja_forms_processing->get_field_value(‘field_ID’) – Used to access the submitted data by field_ID.
  • $ninja_forms_processing->update_field_value(‘field_ID’, ‘new_value’) – Used to change the value submitted by the user. If the field does not exist, it will be created.
  • $ninja_forms_processing->remove_field_value(‘field_ID’) – Used to delete values submitted by the user.
  • $ninja_forms_processing->get_field_settings(‘field_ID’) – Used to get all of the back-end data related to the field (type, label, required, show_help, etc.).
  • $ninja_forms_processing->update_field_settings(‘field_ID’, $data) – Used to temporarily update the back-end data related to the field. This is NOT permanent and will only affect the current form processing.

Accessing and modifying extra values. (These are fields that begin with an _ and aren’t Ninja Forms Fields )

  • $ninja_forms_processing->get_all_extras() – Returns an array of all extra form inputs.
  • $ninja_forms_processing->get_extra_value(‘name’) – Used to access the value of an extra field.
  • $ninja_forms_processing->update_extra_value(‘name’, ‘new_value’) – Used to update an extra value.
  • $ninja_forms_processing->remove_extra_value(‘name’) – Used to delete the extra value from the processing variable.

Accessing and modifying form settings for the form being processed. (Please note that the changes made with these methods only affect the current process and DO NOT permanently change these settings):

  • $ninja_forms_processing->get_form_ID() – Used to retrieve the form ID of the form being processed.
  • $ninja_forms_processing->get_all_form_settings() – Used to get all of the settings of the form currently being processed.
  • $ninja_forms_processing->get_form_setting(‘setting_ID’) – Used to retrieve a form setting from the form currently being processed.
  • $ninja_forms_processing->update_form_setting(‘setting_ID’, ‘new_value’) – Used to change the value of a form setting using its unique ID. If the setting does not exist, it will be created.
  • $ninja_forms_processing->remove_form_setting(‘setting_ID’) – Used to remove a form setting by its unique ID.

Error reporting.

Please note two things:

  1. Errors set will prevent Ninja Forms from moving on to the next processing hook.
  2. Errors may be set at ANY priority. The default for required fields is priority 13. If you check the errors before they are added, nothing will be returned.
  • $ninja_forms_processing->get_all_errors() – Used to get an array of all error messages in the format: array(‘unique_id’ => array(‘error_msg’ => ‘Error Message’, ‘display_location’ => ‘Display Location’)). An empty array is returned if no errors are found.
  • $ninja_forms_processing->get_error(‘unique_id’) – Used to get a specific error message by its unique ID.
  • $ninja_forms_processing->get_errors_by_location(‘location’) – Used to retrieve an array of error messages with a given display location.
  • $ninja_forms_processing->add_error(‘unique_ID’, ‘Error Message’, ‘display_location’) – Used to add an error message. The optional ‘display_location’ tells the display page where to show this error.
    Possible examples include a valid field_ID or ‘general’. If this value is not included, the latter will be assumed and will place this error at the beginning of the form.
  • $ninja_forms_processing->remove_error(‘unique_ID’) – Used to remove an error message.
  • $ninja_forms_processing->remove_all_errors() – Used to remove all currently set error messages.

Success reporting:

  • $ninja_forms_processing->get_all_success_msgs() – Used to get an array of all success messages in the format: array(‘unique_ID’ => ‘Success Message’).
  • $ninja_forms_processing->get_success_msg(‘unique_ID’) – Used to get a specific success message.
  • $ninja_forms_processing->add_success_msg(‘unique_ID’, ‘Success Message’) – Used to add a success message.
  • $ninja_forms_processing->remove_success_msg(‘unique_ID’) – Used to remove a success message.

Calculation Methods:

  • $ninja_forms_processing->get_calc( name or id, return array ) – Used to get the value of the specified calculation field. Unless bool(false) is sent, returns an array including all of the fields that contributed to the value.
  • $ninja_forms_processing->get_calc_fields(calc_id) – Used to get an array of the fields that contributed to the calculation. This array includes a field_id and calculation value.
  • $ninja_forms_processing->get_calc_total( return array ) – Used to get the final value of the “Payment Total” if it exists. Unless bool(false) is sent, returns an array including all of the fields that contributed to the value and are marked with calc_option.
  • $ninja_forms_processing->get_calc_sub_total( return array ) – Used to get the value of the “Payment Subtotal” if it exists. Unless bool(false) is sent, returns an array including all of the fields that contributed to the value and are marked with calc_option.
  • $ninja_forms_processing->get_calc_tax_rate() – Used to get the value of the “Tax” field if it exists.
  • $ninja_forms_processing->get_calc_tax_total() – Used to get the total amount of tax if the tax field is set.

User Information Methods:

  • $ninja_forms_processing->get_user_info() – Used to get an array of the user’s information. Requires that the appropriate “User Information” fields be used.

Please note – when using this within a custom function, be sure to declare the global variable after opening the function.

This class that creates this variable can be found in ninja-forms/includes/display/processing/class-ninja-forms-processing.php.