Form Fields adds text, number, select, radio, checkbox, date and file-upload fields to a configurator. Its hooks cover how field values are formatted for the cart and order, where uploaded files are stored and who may download them, and the frontend field views.
See the hook reference index for how to register PHP and JavaScript callbacks.
PHP filters
| Hook | Arguments | Purpose |
|---|---|---|
mkl_pc/form_builder/date_format | 'd/m/Y' | Date format used when a date field is displayed |
mkl_pc/form_builder/value_arrow | $arrow, $layer, $meta, $value | The separator between a field's label and its value |
mkl_pc/get_temp_upload_dir_name | $path | Directory holding uploads before the order exists |
mkl_pc/get_final_upload_dir_name | $path, $order | Directory files are moved to once the order is placed |
mkl_pc/user_can_download_attached_file | $can_download | Who may download a customer's uploaded file |
PHP actions
| Hook | Arguments | Purpose |
|---|---|---|
PC.fe.form_builder.select.option.label | (none) | Template hook inside a select <option> |
tmpl-mkl-pc-form-builder--select | (none) | Admin template hook, select field options list |
tmpl-mkl-pc-form-builder--select-option | (none) | Admin template hook, one select option row |
JavaScript actions
| Hook | Arguments | Purpose |
|---|---|---|
PC.fe.configurator.choice-item-form.init | view | A form field view was initialised |
PC.fe.configurator.choice-item-form.render | view | A form field view finished rendering |
PC.fe.form.item.change | model, event | The customer changed a field's value |
JavaScript filters
| Hook | Arguments | Purpose |
|---|---|---|
PC.fe.save_data.parse_choices.added_form_choice | data, choice | Field data about to be saved with the configuration |
PC.form.select.get_default_option | option | The blank option added in the admin select builder |
mkl_pc/user_can_download_attached_file
Guards the download endpoint for files a customer uploaded. The default is
current_user_can( 'manage_woocommerce' ) — shop managers and administrators. The check runs
before any request parameters are read, and failing it calls wp_die().
add_filter( 'mkl_pc/user_can_download_attached_file', function ( $can_download ) { return $can_download || current_user_can( 'edit_shop_orders' );} );This filter receives no order or file context, so it can only widen or narrow the capability
check globally. Be careful: returning true unconditionally exposes every customer's uploads to
anyone with the URL.
mkl_pc/get_temp_upload_dir_name and mkl_pc/get_final_upload_dir_name
Uploads land in a temporary directory while the customer is still configuring, then move into a
per-order directory when the order is placed. Both paths are relative to the uploads basedir.
// Group order uploads by year and month.add_filter( 'mkl_pc/get_final_upload_dir_name', function ( $path, $order ) { return 'woocommerce_uploads/configurator-order-uploads/' . $order->get_date_created()->date( 'Y/m' ) . '/order-' . $order->get_id();}, 10, 2 );Defaults are woocommerce_uploads/mkl-pc-temp-user-images and
woocommerce_uploads/configurator-order-uploads/order-{id}. Keep both under
woocommerce_uploads so WooCommerce's own protection rules apply, and remember that changing the
final directory does not move files that are already there.
mkl_pc/form_builder/value_arrow
Between a field's label and its value the add-on prints an arrow — → normally, x for a
quantity field. This filter receives the whole wrapped separator plus the layer, the meta array
being built, and the value.
add_filter( 'mkl_pc/form_builder/value_arrow', function ( $arrow, $layer, $meta, $value ) { return ': ';}, 10, 4 );Return an empty string to run label and value together.
mkl_pc/form_builder/date_format
The PHP date format a date field's stored value is rendered with, wherever it is displayed —
cart, order, emails. Defaults to d/m/Y.
add_filter( 'mkl_pc/form_builder/date_format', function () { return get_option( 'date_format' );} );Using the site's own Settings → General date format, as above, is usually what a merchant expects.
PC.fe.form.item.change
Fires whenever a field's value changes — text input, select, radio, checkbox or quantity. The model has already been updated when it fires.
wp.hooks.addAction( 'PC.fe.form.item.change', 'my-plugin/ff', function ( model, event ) { if ( 'engraving' === model.get( 'name' ) ) { updateMyLivePreview( model.get( 'field_value' ) ); }} );Text fields fire this on every keystroke, so debounce anything expensive. The add-on fires the
core PC.fe.choice.change from the same place.
PC.fe.save_data.parse_choices.added_form_choice
The last chance to change what a field contributes to the saved configuration, immediately before it is pushed into the payload sent to the cart.
wp.hooks.addFilter( 'PC.fe.save_data.parse_choices.added_form_choice', 'my-plugin/ff', function ( data, choice ) { data.my_extra = choice.get( 'field_value' ).toUpperCase(); return data; });For select and radio fields, data.field_label has already been resolved from the selected
index by the time this runs.
PC.fe.configurator.choice-item-form.init and .render
The Backbone view lifecycle for a single field. init fires before the element exists; render
fires once the markup is in place, which is where you attach third-party widgets such as a date
picker or an input mask.
wp.hooks.addAction( 'PC.fe.configurator.choice-item-form.render', 'my-plugin/ff', function ( view ) { if ( 'date' === view.model.get( 'text_field_type' ) ) { myDatePicker( view.$( 'input' ).get( 0 ) ); } });render can fire more than once for the same view — clean up any previous instance first.
PC.form.select.get_default_option
Internal. Arguments and firing order can change in any release.
Filters the blank option appended when a shop manager adds a row to a select field in the admin select builder. Rarely useful outside the plugin.
Core hooks it also fires
PC.fe.choice.init, PC.fe.choice.change, PC.fe.configurator.choice_data and
PC.choices.canSelectChoice — see the
Product Configurator JavaScript hooks.