Form Helper

WC Vendors has a form helper class that allows the front end to be generated from defined fields. These are used on all forms provided by WC Vendors Pro. These can be custom meta or existing meta fields from third party plugins. All form fields are defined using a static call to the form helper class and parsing an array of options. All example code to make the field function will be provided including defining the field, saving the field and displaying it on a relevant form.

All front end forms support the automatic capture and storage of custom meta fields if they use a predefined prefix for the meta key relevant to the form you are wanting to customise. Unless you have a reason to define your named meta keys it is highly recommended that you use our automatic integrated code to save your new form fields.

Supported Fields 

There are several different fields supported with the form helper which makes generating form fields within our front end easier. All forms in WC Vendors Pro use this system to output the form fields on the front end. There are a few required fields to generate a field while providing optional fields that give flexibility over what is displayed.

Form Helper Fields

  • Input ( text, hidden, checkbox )
  • TextArea
  • Select
  • Select2
  • Nested select
  • Country select
  • Submit button
  • File Uploader
Don't forget

The following code definitions are just examples and you would have to change the code samples to reflect the values you require.

Input field

Form Helper class function name

WCVendors_Pro_Form_Helper::input( )

This field type is used to output a standard text field, hidden text field or a checkbox. There are only three settings required to output the input field while the optional settings give you flexibility and control over a range of different options. The following table outlines the various attributes available when creating an input field. These are defined as an array of attributes where the defined attribute is the array key and the value is the desired output.

Setting Required Description
post_id yes This is the id of the post or product you want to interact with.
id yes This is the corresponding meta key or database field
value no This is the value from the database, if it is not defined the id is used to call get_post_meta( ) internally
label no This is the label displayed on the page
class no This will set the css class, leave a space between classes to specify multiple
placeholder no This is the placeholder text that is displayed
wrapper_class no This is the class for the wrapper container
wrapper_start no This is the html code that defines the opening tags for the wrapper container
wrapper_end no This is the html code that defines the closing tags for the wrapper container
cbvalue no This is the checkbox value, required only if you have defined the type as checkbox
type no This is the field type : text (default), hidden, checkbox
show_label no This allows you to show and hide the label for the input

 Text Field

Please note

You do not have to specify the type attribute in the arguments as this is the default field type.

The following code is an example of a text input being defined, this displays the product title that you see on all our product forms. A text field is the default input type which is why you do not have to specify the type attribute for this.
Text Field Example
WCVendors_Pro_Form_Helper::input( array( 
	 	'post_id' 			=> $post_id, 
	 	'id'	 			=> 'post_title', 
	 	'label' 			=> __( 'Product Name', 'wcvendors-pro' ),
	 	'value' 			=> $product_title, 
	)
);

Hidden field

Please note

Specify the type attribute as hidden

Hidden fields are used in forms to track and store information with your form when you do not require input from the user. There are times that integrations with third party plugins will require this field type. This field type can also be used if you want to hardcode a value for your vendors, such as the price or categories.

Hidden Field Example
WCVendors_Pro_Form_Helper::input( array( 
		'post_id'		=> $post_id, 
		'type'			=> 'hidden', 
		'id' 			=> 'post_id', 
		'value'			=> $post_id
	)
);

Checkbox

Please note

Specify the type attribute as checkbox

Checkboxes are used throughout the various forms. To define a checkbox use the following definition. Due to how checkboxes are output, when the checkbox is unchecked after previously being checked, then an extra step Is needed that requires hooking into the save action of either the settings page or the product save to check if the value is not there to remove it.

Checkbox Field Example
add_action( 'wcvendors_settings_after_seller_info', 'checkbox_check' );
function checkbox_check(){
	$key = '_wcv_custom_settings_checkbox3';
	$value = get_user_meta( get_current_user_id(), $key, true );
	WCVendors_Pro_Form_Helper::input( apply_filters( $key, array(
		'id' => $key,
		'label' => __( 'Fairtrade', 'wcvendors-pro' ),
		'type' => 'checkbox',
		'desc_tip' => true,
		'value' => $value,
		'description' => __('Check this box if you are fairtrade.', 'wcvendors-pro'),
		) )
	);
}
function fairtrade( $vendor_id ) {
	if ( ! isset( $_POST[ '_wcv_custom_settings_checkbox3' ] ) ){
		delete_user_meta( $vendor_id, '_wcv_custom_settings_checkbox3' );
	}
 }
add_action ('wcv_pro_store_settings_saved','fairtrade');

Select

Form Helper class function name

WCVendors_Pro_Form_Helper::select( )

The select option allows you to create a simple drop down while specifying the options or the taxonomy to automatically populate from the WordPress backend.
Select Field Example
WCVendors_Pro_Form_Helper::select( array( 
	'post_id'			=> $post_id, 
	'id' 				=> '_download_type', 
	'class'				=> 'select',
	'label'	 			=> __( 'Download Type', 'wcvendors-pro' ), 
	'desc_tip' 			=> 'true', 
	'description' 		=> sprintf( __( 'Choose a download type - this controls the <a href="%s">http://schema.org</a>.', 'wcvendors-pro' ), 'http://schema.org/' ), 
	'options' 			=> array(
		''            	=> __( 'Standard Product', 'wcvendors-pro' ),
		'application' 	=> __( 'Application/Software', 'wcvendors-pro' ),
		'music'       	=> __( 'Music', 'wcvendors-pro' )
	), 	 
	// 'custom_attributes' => $custom_attributes, 
	)
);

Select2

Form Helper class function name

WCVendors_Pro_Form_Helper::select2()

 The select2 field provides an enhanced select that provides more usability and options to have multiple values selected. This can be used to define your own options such as the select example above, or hook into a defined taxonomy as per the example below. This uses the popular select2 framework to achieve this.
Select2 Field Example
WCVendors_Pro_Form_Helper::select2( array( 
		'post_id'			=> $post_id, 
		'id' 				=> 'product_cat[]', 
		'taxonomy'			=> 'product_cat', 
		'class'				=> 'category-select2',
		'show_option_none'	=> $show_option_none,
		'taxonomy_args'		=> array( 
				'hide_empty'	=> 0, 
				'orderby'		=> 'order', 					
				'exclude'		=> $exclude, 
			), 	
		'label'	 => ( $multiple ) ? __( 'Categories', 'wcvendors-pro' ) : __( 'Category', 'wcvendors-pro' ), 
		) 
);

File Uploader

Form Helper class function name

WCVendors_Pro_Form_Helper::file_uploader

New in 1.5.9

New file formats are supported in WC Vendors Pro 1.5.9 and up

The form helper provides a basic file uploader that allows you to add a single file per input to the form. This is useful if you need extra files added to a product or the store. There are several file formats supported
  • Image
  • Document
  • Audo
  • Video

The file extensions for the file formats above are determined based on what your file types your WordPress install allows.  If you do not define the file type for the second argument then the default file type is ‘image’

Image File Upload Field Example
function wcv_image_uploader( ){
	echo '<hr />';
	echo '<h3>Image Uploader</h3>';
	$value = get_user_meta( get_current_user_id(), '_wcv_custom_settings_image_example', true );
	WCVendors_Pro_Form_Helper::file_uploader( array(
		'id' 	            => '_wcv_custom_settings_image_example',
		'header_text'		=> __('Image uploader', 'wcvendors-pro' ),
		'add_text' 			=> __('Add image file', 'wcvendors-pro' ),
		'remove_text'		=> __('Remove image file', 'wcvendors-pro' ),
		'image_meta_key' 	=> '_wcv_custom_settings_image_example',
		'save_button'		=> __('Add image file', 'wcvendors-pro' ),
		'window_title'		=> __('Select an Image', 'wcvendors-pro' ),
		'value'				=> $value
		), 'image'
	);
}
Code Output example

Document File Upload Field Example
function wcv_doc_uploader( ){
	echo '<hr />';
	echo '<h3>Document Uploader</h3>';
	$value = get_user_meta( get_current_user_id(), '_wcv_custom_settings_doc_example', true );
	WCVendors_Pro_Form_Helper::file_uploader( array(
		'id' 	            => '_wcv_custom_settings_doc_example',
		'header_text'		=> __('Document uploader', 'wcvendors-pro' ),
		'add_text' 			=> __('Add document', 'wcvendors-pro' ),
		'remove_text'		=> __('Remove document', 'wcvendors-pro' ),
		'file_meta_key' 	=> '_wcv_custom_settings_doc_example',
		'save_button'		=> __('Add document', 'wcvendors-pro' ),
		'window_title'		=> __('Select a document', 'wcvendors-pro' ),
		'value'				=> $value
		), 'document'
	);
}
Code Output example

Audio File Upload Example Example
function wcv_audio_uploader( ){
	echo '<hr />';
	echo '<h3>Audio Uploader</h3>';
	$value = get_user_meta( get_current_user_id(), '_wcv_custom_settings_audio_example', true );
	WCVendors_Pro_Form_Helper::file_uploader( array(
		'id' 	            => '_wcv_custom_settings_audio_example',
		'header_text'		=> __('Audio uploader', 'wcvendors-pro' ),
		'add_text' 			=> __('Add audio', 'wcvendors-pro' ),
		'remove_text'		=> __('Remove audio', 'wcvendors-pro' ),
		'file_meta_key' 	=> '_wcv_custom_settings_audio_example',
		'save_button'		=> __('Add audio', 'wcvendors-pro' ),
		'window_title'		=> __('Select audio', 'wcvendors-pro' ),
		'value'				=> $value
		), 'audio'
	);
}
Code Output example
Video File Upload Field Example
function wcv_video_uploader( ){
	echo '<hr />';
	echo '<h3>Video Uploader</h3>';
	$value = get_user_meta( get_current_user_id(), '_wcv_custom_settings_video_example', true );
	WCVendors_Pro_Form_Helper::file_uploader( array(
		'id' 	            => '_wcv_custom_settings_video_example',
		'header_text'		=> __('Video uploader', 'wcvendors-pro' ),
		'add_text' 			=> __('Add video', 'wcvendors-pro' ),
		'remove_text'		=> __('Remove video', 'wcvendors-pro' ),
		'file_meta_key' 	=> '_wcv_custom_settings_video_example',
		'save_button'		=> __('Add video', 'wcvendors-pro' ),
		'window_title'		=> __('Select video', 'wcvendors-pro' ),
		'value'				=> $value
		), 'video'
	);
}
Code Output example

Automatic Field Saves

To take advantage of our automatic field save feature you will need to define your custom meta keys with our predefined prefixes. All prefixes that start with an ‘_’ are hidden from the edit form in the WordPress dashboard. If you need the field to be displayed on the backend for admins to edit then leave the underscore off the prefix.

What does this mean? It means that if you define your form field and start the id with relevant prefix below then the form controller will automatically save meta key.

Available Field Type Prefixes

Form Name  Prefix Name Example
Product _wcv_custom_product_ _wcv_custom_product_ingredients
Product wcv_custom_product_ wcv_custom_product_delivery_time
Settings & Signup _wcv_custom_settings_ _wcv_custom_settings_bankname
Settings & Signup wcv_custom_settings_ wcv_custom_settings_bankname
Coupon _wcv_coupon_post_meta_ _wcv_coupon_post_meta_newfield

Product Field Automatic Save Example

WCVendors_Pro_Form_Helper::input( array(  
		'post_id'			=> $object_id, 
		'id' 				=> '_wcv_custom_product_ingredients', 
		'label' 			=> __( 'Ingredients', 'wcvendors-pro' ), 
		'placeholder' 		=> __( 'Ingredients', 'wcvendors-pro' ), 
		'desc_tip' 			=> 'true', 
		'description' 		=> __( 'The product ingredients', 'wcvendors-pro' ), 
	) 
);
Please Note

This works for any field type that isn’t a multi select.

Settings & Signup Form Field Automatic Save Example 
add_action( 'wcvendors_settings_after_seller_info', 'checkbox_check' );
function checkbox_check(){
	$key = '_wcv_custom_settings_checkbox3';
	$value = get_user_meta( get_current_user_id(), $key, true );
	WCVendors_Pro_Form_Helper::input( apply_filters( $key, array(
		'id' => $key,
		'label' => __( 'Fairtrade', 'wcvendors-pro' ),
		'type' => 'checkbox',
		'desc_tip' => true,
		'value' => $value,
		'description' => __('Check this box if you are fairtrade.', 'wcvendors-pro'),
		) )
	);
}
Taxonomy Saves

If you have defined a custom taxonomy we also support automatic save of these. All you have to do is define the field id with the same format as individual fields.

Form Name  Prefix Name Example
Product _wcv_custom_taxonomy_ _wcv_custom_taxonomy_subjects
Product wcv_custom_taxonomy_ wcv_custom_taxonomy_subjects
Product Taxonomy Automatic Save Example

The following is an example of a custom-defined taxonomy.

 WCVendors_Pro_Form_helper::select2( array(
		'post_id'			=> $object_id,
		'id'				=> '_wcv_custom_taxonomy_subjects[]',
		'class'				=> 'select2',
                'custom_tax'                    => true, 
		'label'				=> __('Subjects', 'wcvendors-pro'),
		'show_option_none'	=> __('Select Subject(s)', 'wcvendors-pro'),
		'taxonomy'			=>	'subjects', 
		'taxonomy_args'		=> array( 
								'hide_empty'	=> 0, 
							),
		'custom_attributes'	=> array( 'multiple' => 'multiple' ), 
		)
);
Please Note

The taxonomy name will still be what you defined when registering the taxonomy. You only need to use these prefix for the field names on the form.

Actions

Every form input has a _before_ and _after_ action that allows you to hook into the form before or after the element is rendered. All form types defined above provide this access. The field id is appended to the end of the actions so that you can target specific fields defined.

Actions Before

Field  Action
input do_action( ‘wcv_form_input_before_’. $field[ ‘id’ ], $field );
 select do_action( ‘wcv_form_select_before_’. $field[ ‘id’ ], $field );
select2  do_action( ‘wcv_form_select2_before_’. $field[ ‘id’ ], $field );
nested_select do_action( ‘wcv_form_nested_select_before_’. $field[ ‘id’ ], $field );
textarea do_action( ‘wcv_form_textarea_before_’. $field[ ‘id’ ], $field );
product_media_uploader do_action( ‘wcv_form_product_media_uploader_before_product_media_uploader’, $post_id );
file_uploader do_action( ‘wcv_form_file_uploader_before_’. $field[ ‘id’ ], $field );
submit do_action( ‘wcv_form_submit_before_’. $field[ ‘id’ ], $field );
country_select2 do_action( ‘wcv_form_country_select2_before_’. $field[ ‘id’ ], $field );
wcv_terms_checklist do_action( ‘wcv_form_wcv_terms_checklist_before_’. $field[ ‘id’ ], $field );
custom_field do_action( ‘wcv_form_custom_field_before_’. $field[ ‘id’ ], $field );

Actions After

Field Action
input do_action( ‘wcv_form_input_after_’. $field[ ‘id’ ], $field );
 select do_action( ‘wcv_form_select_after_’. $field[ ‘id’ ], $field ); &nbsp;
select2  do_action( ‘wcv_form_select2_after_’. $field[ ‘id’ ], $field );
nested_select do_action( ‘wcv_form_nested_select_after_’. $field[ ‘id’ ], $field );
textarea do_action( ‘wcv_form_textarea_after_’. $field[ ‘id’ ], $field );
product_media_uploader do_action( ‘wcv_form_product_media_uploader_after_product_media_uploader’, $post_id );
file_uploader do_action( ‘wcv_form_file_uploader_after_’. $field[ ‘id’ ], $field ); =
submit do_action( ‘wcv_form_submit_after_’. $field[ ‘id’ ], $field );
country_select2 do_action( ‘wcv_form_country_select2_after_’. $field[ ‘id’ ], $field );
wcv_terms_checklist do_action( ‘wcv_form_wcv_terms_checklist_after_’. $field[ ‘id’ ], $field );
custom_field do_action( ‘wcv_form_custom_field_after_’. $field[ ‘id’ ], $field );


Example

If you know the fields ID then you can hook into the action. For example the Post Title field id is post_title therefore the before and after actions would be the following. You would then define the information to output before or after with the functions parsed.add_action( ‘wcv_form_input_before_post_title’, ‘add_field_before_post_title’ ); 

add_action( 'wcv_form_input_before_post_title', 'add_field_before_post_title' ); 
add_action( 'wcv_form_input_after_post_title', 'add_field_after_post_title');

actions

Updated on November 10, 2020

Was this article helpful?