Developer Hooks

GravityWP List Number Format has JavaScript hooks and PHP filters for developers who want to change how number columns are cleaned, calculated and initialized. You do not need them to use the add-on; all settings are in the Gravity Forms form editor.

The JavaScript hooks use the Gravity Forms hooks API: add filters with gform.addFilter() and actions with gform.addAction(). Add your code in a script that loads on the page with the form, after the Gravity Forms scripts.

JavaScript filters

gf_list_col_number_clean_value

Changes the value of a number column after List Number Format cleaned and rounded it, and before it is written back in the column’s number format. It runs when the value of a number column input changes, for example when a visitor leaves the input, but not for empty values, 0 or dropdown columns.

gform.addFilter( 'gf_list_col_number_clean_value', function ( cleanValue, formId, fieldId, fieldData ) {
	return cleanValue;
} );

Parameter	Description
cleanValue	The value as a number, with a point as decimal separator and rounding applied.
formId	The form ID.
fieldId	The List Field ID.
fieldData	The settings of the column, such as list_col_num_format (decimal_dot, decimal_comma or currency), list_col_number_rounding (-1 for no rounding), list_col_number_rounding_direction, decimal_separator and thousand_separator.

Example: never allow negative values in List Field 4 of form 12.

gform.addFilter( 'gf_list_col_number_clean_value', function ( cleanValue, formId, fieldId, fieldData ) {
	if ( parseInt( formId, 10 ) === 12 && parseInt( fieldId, 10 ) === 4 && cleanValue < 0 ) {
		return 0;
	}
	return cleanValue;
} );

gf_list_col_calculation_formula

Changes the formula of a calculated column, or the Min or Max of a column with a range (a fixed value or a range formula), before the merge tags are replaced. After this filter, the Gravity Forms gform_calculation_formula filter runs on the result.

gform.addFilter( 'gf_list_col_calculation_formula', function ( formula, formulaField, formId ) {
	return formula;
} );

Parameter	Description
formula	The formula, for example {Order Items:1.2} * {Order Items:1.3}.
formulaField	An object with field_id (the List Field ID) and formula.
formId	The form ID.

gf_list_col_merge_tag_value_pre_calculation

Changes the value of a merge tag in the formula of a calculated column or a calculated range. It runs for each merge tag that has no value from Gravity Forms (an empty value or 0). List Number Format uses this filter itself to replace List column merge tags with the value of that column in the current row.

gform.addFilter( 'gf_list_col_merge_tag_value_pre_calculation', function ( value, mergeTag, isVisible, formulaField, formId, destinationField ) {
	return value;
} );

Parameter	Description
value	The value of the merge tag.
mergeTag	The merge tag match: mergeTag[0] is the merge tag, mergeTag[1] the input ID (for example 1.2), mergeTag[2] the column part (for example .2).
isVisible	false when the field is hidden by conditional logic.
formulaField	An object with field_id (the List Field ID) and formula.
formId	The form ID.
destinationField	The jQuery object of the input that gets the result. Use destinationField.parents( '.gfield_list_group' ) to get the row.

JavaScript actions

gwp_lnf_post_init

Runs after List Number Format has initialized the number columns of a form: when the form is loaded, and again when List Fields are initialized again, for example after GP Populate Anything populated them.

gform.addAction( 'gwp_lnf_post_init', function ( formId, fieldIds ) {
	// Your code.
} );

Parameter	Description
formId	The form ID.
fieldIds	The IDs of the List Fields that were initialized, or null when all List Fields of the form were initialized.

gf_list_col_post_calculation_events

Runs for each merge tag in the formula of a calculated column, in each row, after List Number Format has bound the events that start the calculation. Use it to start the calculation on other events.

gform.addAction( 'gf_list_col_post_calculation_events', function ( mergeTag, formulaField, formId ) {
	// Bind your own events.
} );

Parameter	Description
mergeTag	The merge tag match, as in gf_list_col_merge_tag_value_pre_calculation.
formulaField	An object with field_id (the List Field ID) and formula.
formId	The form ID.

gf_list_col_min_range_calculation_events and gf_list_col_max_range_calculation_events

Run for each merge tag in the Min Formula (gf_list_col_min_range_calculation_events) or Max Formula (gf_list_col_max_range_calculation_events) of a column with Enable Range Calculation, after List Number Format has bound the events that check the range. Use them to check the range on other events.

gform.addAction( 'gf_list_col_min_range_calculation_events', function ( mergeTag, formulaField, formId ) {
	// Bind your own events.
} );

gform.addAction( 'gf_list_col_max_range_calculation_events', function ( mergeTag, formulaField, formId ) {
	// Bind your own events.
} );

The parameters are the same as for gf_list_col_post_calculation_events; formulaField.formula is the Min Formula or the Max Formula.

Initialize List Fields again

When your code replaces the markup of a List Field after the form was loaded, call the init function to apply the number format settings, total row and calculations again:

window.GWPListNumberFormat.gf_list_col_number_format_init( formId, fieldIds );

Parameter	Description
formId	The form ID.
fieldIds	Optional. An array of List Field IDs to initialize, for example [ 4, 7 ]. Leave it out or pass null to initialize all List Fields with number format settings in the form.

List Number Format calls this function itself after GP Populate Anything populates a List Field. After the function has run, the gwp_lnf_post_init action fires.

PHP filters

gf_list_col_num_default_format

Sets one number format for all number columns, in all forms. Return decimal_dot (9,999.99), decimal_comma (9.999,99) or currency. Return an empty string (the default) to use the format set per column.

add_filter( 'gf_list_col_num_default_format', function ( $format ) {
	return 'decimal_comma';
} );

gf_list_col_num_default_rounding

Sets one rounding for all number columns, in all forms. Return 'norounding' or a number of decimals from '1' to '5'. Return an empty string (the default) to use the rounding set per column.

add_filter( 'gf_list_col_num_default_rounding', function ( $rounding ) {
	return '2';
} );

Both PHP filters change the settings that List Number Format passes to the form in the browser. They do not change the settings saved in the form, which are used for validation on submit and for column totals in entries.

Frequently Asked Questions