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 customize. 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

Input field

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.

Text Field

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

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 when integrations with third-party plugins will require this field type. This field type can also be used if you want to hard code 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

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');

Textarea

WCVendors_Pro_Form_Helper::textarea()

The textarea field allows you to create textarea fields on various forms. The following table outlines the various attributes available when creating a text area field. These are defined as an array of attributes, where the defined attribute is the array key and the value is the desired output.

Textarea Field Example

WCVendors_Pro_Form_Helper::textarea(
					apply_filters(
						'wcv_product_description',
						array(
							'post_id'           => $post_id,
							'id'                => 'post_content',
							'label'             => __( 'Product description', 'wcvendors-pro' ),
							'value'             => $product_description,
							'placeholder'       => __( 'Please add a full description of your product here', 'wcvendors-pro' ),
							'custom_attributes' => $custom_attributes,
						)
					)
				);

Select

WCVendors_Pro_Form_Helper::select( )

The select field 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

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

WCVendors_Pro_Form_Helper::file_uploader()

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
• Audio
• Video

The file extensions for the file formats above are determined based on what 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 Field 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 the relevant prefix below then the form controller will automatically save the meta key.

Available Field Type Prefixes

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' ), 
	) 
);

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'),
		) )
	);
}

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

Taxonomy Saves

If you have defined a custom taxonomy, we support automatic saving of these. All you have to do is define the field ID with the same format as individual fields. The taxonomy name will still be what you defined when registering the taxonomy. You only need to use these prefixes for the field names on the form.

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' ), 
		)
);

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

Actions After

Example

If you know the field’s 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');