# WooCommerce Extra Product Options

Create extra options on your products!

- epo.themecomplete.com

Thank you for purchasing our plugin. If you have any questions that are beyond the scope of this help file, please visit the support forum here. Thanks so much!

# Overview

Extra Product Options allows you to create extra fields on your WooCommerce products locally on the edit product page or globally. The current version supports checkboxes, radio buttons, select boxes, textareas, input boxes, upload, date, range picker and color picker. The options you create show up above the add to cart form.

### Minimum requirements

- PHP 5.6
- WordPress 5
- WooCommerce 3
- JavaScript / jQuery

### Credits

- Font Awesome v5.12.0

  http://fontawesome.io License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License)

- Spectrum Colorpicker v1.8.0

  Author: Brian Grinstead. (https://github.com/bgrins/spectrum/) Licensed under the MIT license

- nouislider v13.1.5

  (http://refreshless.com/nouislider/) License: http://www.wtfpl.net/about/

- Lazy Load XT v1.1.0

  Lazy Load XT is licensed under the MIT license

- jQuery Mask Plugin v1.14.15

  (Created by Igor Escobar https://github.com/igorescobar/jQuery-Mask-Plugin) Licensed under the MIT license

- jQuery Validation Plugin v1.19.0

  Copyright (c) 2014 JΓΆrn Zaefferer http://jqueryvalidation.org/ Licensed under the MIT license

- Owl Carousel 2 v2.3.4

  Copyright 2013-2018 David Deutsch http://owlcarousel2.github.io/OwlCarousel2/ Licensed under SEE LICENSE

- jQuery

  Copyright 2014 The jQuery Foundation. jQuery License

# Installation

There are two primary methods for installing any WordPress plugin.

### Install with a zip file

1. From your WordPress dashboard, choose `Plugins > Add New`
2. Select `Upload` from the set of links at the top of the page (the second link)
3. From here, browse for the zip file included in your plugin purchase titled woocommerce-tm-extra-product-options.zip and click the `Install Now` button
4. Once installation is complete, click `Activate Plugin` to activate it and enable its features.

### Install by FTP Manager

If you are have no previous web experience and have no idea what an FTP Manager is, then this option is not for you.

1. Access your host through the FTP manager
2. Access the plugins directory of your WordPress install `/(WordPress directory)/wp-content/plugins/`

   If WordPress is installed on the root folder the directory is `/wp-content/plugins/`

3. Find the directory titled woocommerce-tm-extra-product-options and upload it and all files within to the directory from the previous step.
4. From your WordPress dashboard, choose `Plugins > Installed Plugins`
5. Locate the newly added plugin and click on the `Activate` link to enable its features.

# Quick Start Guide

Adding extra options to your products is really easy. Below we describe the required steps for creating your fields.

## Basic plugin usage

The basic usage of the plugin assigns option fields to a specific product.

### Step 1

Add or edit a WooCommerce product.

### Step 2

Make sure your product type is either Simple, Variable, Composite, Bookable or Subscription product.

### Step 3

Locate the sub-section Extra Product Options in the product data panel and click it. You should now be presented with the plugin interface. If you haven't created extra options before for that product you will see the Builder mode.

Note that the Normal mode previously used in the plugin is depreacated and unsupported. It will eventually be removed from the plugin.

#### Builder mode

This is the preferable way of creating options.

On this mode you are presented with with Form Builder that you will use to create your options. Click the Add section button to create a section where the options must placed in. Click the Add element button (cross button) located on the section to select the option field type.

For better understanding of the Form Builder see the section Form Fields Builder.

## Advanced plugin usage

This method uses the Form Builder to create options that can be set to all of the products, products that belong to specific categories or alternatively to specific products.

### Step 1

From the WordPress dashboard choose `Products > Global Extra Product Options`.

### Step 2

Click the Add Global Form button at the top of the screen.

### Step 3

Add title and description for your reference only, so that you can distinguish the different forms.

### Step 4

Select the Product Categories that you want your form to be applied on. Choose no categories to apply the form to all products (even to products that don't belong to any category). Clicking the Disable categories checkbox will make the plugin disregard selected categories. You can assign specific products to the form by selecting them on the Products meta box.

### Step 5

Add your fields on the Form Fields Builder.

For information on the form settings see the section Global Extra Product Options. For help creating a field on the Form Fields Builder see the section Form Fields Builder

## Panel settings

Clicking the settings tab while on the product panel you can override some global settings.

Include additional Global forms

This list contains all of the global forms and checking one will include it on the global. The forms you choose will be displayed alongside with the forms that the product already has. This setting will also override the next one.

Exclude from Global Extra Product Options

This will exclude any global forms assigned to this product except those defined in the previous setting.

Override global display

This overrides the global display setting for the display of the fields on the front-end for the current product only. The default value is `Use global setting` which uses whatever you have chosen on the global settings (see below). `Always show` will always show the fields assigned to the current product and `Show only with action hook` will only show the fields for the current product by using action hooks (see below).

Override Final total box

This will override the global totals box display for this product. The default value is `Use global setting` which uses whatever you have chosen on the global settings (see below).

Override enabled roles for this product

This will override which roles can see the options for this product.

Override disabled roles for this product

This will override which roles cannot see the options for this product. This setting has priority over the enabled roles one.

## Global Extra Product Options

Global Extra Product Options are applied to all products, products belonging to a specific category or categories or specific products. To gain access to Global Extra Product Options interface from the WordPress dashboard choose `Products > Global Extra Product Options`.

Any existing Global Extra Product Options created are displayed in the familiar WordPress table view.

To add a new Global Product Options form click the `Add Global Form` button. This will bring you to the add screen.

Title and Description

These are for your reference only and are not currently being used anywhere in the front-end.

Priority

This is used to determine in which order multiple forms that apply to a specific product are being displayed in the front-end.

Please note that, the "Priority" is not used to determine if your form will show up before or after the local (per-product) prices. This is done in the form editor.

Product Categories

They are used to limit the display of your current global product option form on the products that belong to the selected categories. Selecting no categories means that the form will be applied to ALL products.

Disable Categories

Checking this will disable the categories.

Search for a product

This where you type the individual products to assign the product to.

# Form Fields Builder

The Form Fields Builder is where you actually create your options. It operates as a regular form builder. The concept behind the builder is that you create sections and inside the sections you put the fields.

## Sections

MOVE

Click and drag to re-order the section.

MINUS

Decreases the size of the section.

PLUS

Increases the size of the section.

DUPLICATE

Duplicates the section (including all its fields).

EDIT

Shows this section's settings

DELETE

Deletes the section and all its fields.

CHANGE WIDTH

Drag to change the section width.

ADD ELEMENT

Click to add a new element to that section.

### Adding a section

Click the `Add section` button. This will add a new section to the form.

### Section settings

To gain access to the section settings click the edit button at the section's toolbar. Doing this will open a pop up where you can edit the settings for that section.

Section style

Determines the style of that section on the front-end.

Section placement

Determines where this section will appear compare to local (per-product) options. You can place it before or after the local options.

If you have multiple sections, the priority of the section determines the display order either before or after local options.

Section type

Determines if the section will be a pop up (the section's title will be used as a the link title to open the pop up) or a wizard slider.

Section class name

This will add a custom class name to the section. You can use this to style the section.

## Fields

DRAG HANDLE

Click and drag to re-order the field.

MINUS

Decreases the size of the field.

PLUS

Increases the size of the field.

DUPLICATE

Duplicates the field.

EDIT

Shows this field's settings

DELETE

Deletes the field.

### Adding a field

Clicking the cross button will display a pop up of the available elements. If you have more than one sections and you want your element to appear on a specific section you can instead drag the item placeholder to the desired section.

### Field settings

To gain access to the field settings click the edit button at the field's toolbar. Doing this will open a pop up where you can edit the settings for that field.

Please remember that currently you cannot change a field's type after you have placed it inside a section.

Depending on the field you choose you can edit different settings.

#### Label options for all fields

Label type

Here you can choose the type of the field's title.

Label

Here you enter the title of the field.

Label color

This changes the default color for the title.

Subtitle

Here you can enter a subtitle for the field's title.

Subtitle Subtitle position

This changes the displayed location of the subtitle.

Subtitle color

This changes the color for the subtitle.

Divider type

Here you can choose to show a divider between the field title and the actual field.

#### General options

Required

Choose whether the user must fill out this field or not.

Price

Here you enter the price for the field.

Text before Price

Text entered here will be displayed before the price. Leave the setting blank for no text.

Text after Price

Text entered here will be displayed after the price. Leave the setting blank for no text.

Set to Fee

This makes the option to be a fee added to the cart line item.

Price type

Here you can choose how the price is calculated. Depending on the field there various types you can choose.

Fixed amount

This is an flat increase or decrease added to the product price.

Percent of the original price

This is a percentage increase or decrease of the initial product price.

Percent of the original price + options

This is a percentage increase or decrease of the initial product price plus all of the other options that are not of this type or the "Fixed amount + options" type.

Fixed amount + options

This is a fixed increase or decrease of the initial product price plus all of the other options that are not of this type or the "Percent of the original price + options" type.

Current value

This will add a price the current value of the field.

Price per Interval

This will multiply field's value by the Price you set and will deduct the minimum price. This price type is exclusive to the range picker element.

Step * price or Quantity

This will multiply field's value by the Price you set.

Price per row

This will multiply the field's text rows by the Price you set. This price type is exclusive to the textarea element.

Price per char

This will multiply the field's number of characters by the Price you set.

This price type has several variations like Price per char (no spaces), Price per char (no first char), Price per char (no n-th char), Price per char (no n-th char and no spaces), Percent of the original price per char, Percent of the original price per char (no first char), Percent of the original price per char (no n-th char), Percent of the original price per char (no n-th char and no spaces)

Price per word

This will multiply the field's number of words by the Price you set.

This price type has several variations like Price per word, Price per word (no n-th char), Percent of the original price per word, Percent of the original price per word (no n-th char)

Math formula

This will set the price of the field based on a mathematical formula.

Hide price

Choose whether to hide the price on the front-end or not. This just hides the price. It doesn't disable it. If you want your field to not have a price leave the price field blank.

##### Checkboxes specific settings

Limit selection

Enter a number above 0 to limit the checkbox selection or leave blank for default behavior.

Exact selection

Enter a number above 0 to have the user select the exact number of checkboxes or leave blank for default behavior.

Minimum selection

Enter a number above 0 to have the user select at least that number of checkboxes or leave blank for default behavior.

Use image replacements

This lets you display images in place of the checkbox.

Changes product image

This will let you change the product image with a custom one.

Enable Swatch mode

This will show the option label on a tooltip when Use image replacements is active.

Items per row

Use this setting to make a grid display. Enter how many items per row for the grid or leave blank for normal display.

Populate options

Here you add the labels and their prices for the field choices.

Mass add

To mass add option use the following format:

    Option 1 | 10
    Option 2 | 20

and press the Populate button. Please note that this method only adds options, it doesn't replace existing ones.

##### Radio button specific settings

Use image replacements

This lets you display images in place of the radio button.

Changes product image

This will let you change the product image with a custom one.

Enable Swatch mode

This will show the option label on a tooltip when Use image replacements is active.

Items per row

Use this setting to make a grid display. Enter how many items per row for the grid or leave blank for normal display.

Use URL replacements

This will enable you to redirect to a url when a radio option is clicked.

Populate options

Here you add the labels and their prices for the field choices.

Mass add

To mass add option use the following format:

    Option 1 | 10
    Option 2 | 20

and press the Populate button. Please note that this method only adds options, it doesn't replace existing ones.

##### Select boxes specific settings

Changes product image

This will let you change the product image with a custom one.

Use URL replacements

This will enable you to redirect to a url when a radio option is clicked.

Placeholder

This will add an option to the select box that will act as a placeholder. Use this to instruct the user to select something.

Populate options

Here you add the labels and their prices for the field choices.

Mass add

To mass add option use the following format:

    Option 1 | 10
    Option 2 | 20

and press the Populate button. Please note that this method only adds options, it doesn't replace existing ones.

##### Text area and Text field specific settings

Placeholder

Here you may enter a placeholder for the field.

Maximum characters

Enter a value to limit the maximum characters the user can enter.

#### Conditional logic

With Conditional Logic you can apply rules to your fields in order to control their display. Not all fields can be used as rules to the logic. Only fields that have a way of showing a value are valid. An example of a field that cannot be used as a logic rule is the upload field. All fields though can have logic applied on them.

ACTION

This controls the display of the field if the conditions are met. You can either hide or show the field.

CONDITION

This controls how the logic is applied. You can either select to have the applied when ALL rules are me or when ANY of the rules are met.

FIELD NAME

This is the field that you want to check its value.

OPERATOR

This determines how the field's value is evaluated.

VALUE

This describes the value of the field you want to check. When the FIELD NAME is a select box, checkbox, radio button or a customized variation you will see the list of the available values. If it's a text field or a textarea you will need to type the value to check.

# Math Formula

The math formula price type can be use to set the price of an option based on a mathematical formula.

This formula can be based on other options and mathematical operations that are supported by both PHP and JavaScript languages.

These include functions like: "ceil", "floor", "abs", "exp", "sqrt", "sin", "cos", "tan", "pi", "asin", "acos", "atan", "int", "cosh", "acosh", "ln", "^", "tanh", "atanh", "Mod", "sinh", "asinh", "e", "log", "Sigma", "Pi", "pow"

You can use the normal mathematical operators like -, +, /, *

## Global variables

Below are the predefined global variables you can use.

{quantity}

Product quantity

{product_price}

Original product price

## Variables for the current element

Below are the predefined variables for the current element.

{this.value}

The value of this element

{this.value.length}

The value length of this element

{this.count}

The number of options the user has selected

{this.count.quantity}

The total quantity of this element

{this.quantity}

The quantity of this element

## Variables for other options

To target other element you will need to know the element id or you can jsut click on the buttons that represent the element.

You will find a selector to choose between the Price of element, the Value of element, the Quantity of element and the Selected options of element

The format where you enter to target other elements is:

{field.ID.TYPE}

where ID is the element id and TYPE is which of the above element charatcteriks we want to target.

# Settings

You can find the settings of the plugin under the `Extra Product Options` tab in the main WooCommerce settings.

## General

Enable for roles

Here you can choose the roles which the plugin will be displayed for.

Final total box

Here you can set when the total box is being displayed.

Enable Final total box for all products

This will enable Final total box even when product has no extra options.

Strip html from emails

This will strip html code such as image tags from the field values whenever an email is sent.

Disable lazy load images

This will disable the lazy load image feature. Disable this if you are mostly dealing with mobile sites.

Enable plugin for WooCommerce shortcodes

Activating this setting will show the fields when using native WooCommerce shortcodes. Enabling this will load the plugin files to all of your pages.

## Display

Display

This controls how your fields are displayed on the front-end.

Normal

This is the normal setting that displays the fields automatically

Show using action hooks

Setting this means that you have to manually write the code to your theme or plugin to display the fields and the placement settings will not work.

If you use Composite Products extension you must leave this setting to "Normal" otherwise the extra options cannot be displayed on the composite product bundles.

##### Action hooks

`woocommerce_tm_epo`

This displays both the fields and the extra total options box on the frontend

`woocommerce_tm_epo_fields`

This displays only the fields

`woocommerce_tm_epo_totals`

This displays only the extra options box on the frontend

##### Example usage

        function my_custom_function(){
            do_action("woocommerce_tm_epo");
        }

        add_action( 'woocommerce_before_add_to_cart_button','my_custom_function');

Extra Options placement

Here you can select where you want the extra options to appear.

Totals box placement

Here you can select where you want the Totals box to appear.

Floating Totals box

This will enable a floating box to display your totals box.

Force Select Options

This is a setting for shop and archive pages. This changes the add to cart button to display select options when the product has extra product options. Enabling this will remove the Ajax functionality.

Remove Free price label

The will remove the Free price label when product has extra options.

Hide uploaded file path

This hides the uploaded file path from users.

Show quantity selector only for elements with a value

Self-explanatory. The quantity selector refers to the quantity of the created options and not the native product quantity.

Hide add-to-cart button until an option is chosen

Enabling this will show the add to cart button only when at least one option is filled.

Auto hide price if zero

This hides the displayed price of an option if it is zero.

Use translated values when possible on admin Order

Please note that if the options on the Order change or get deleted you will get wrong results by enabling this!

## Cart

Clear cart button

Enables or disables a clear cart button.

Cart Field Display

Select how to display the fields in the cart. You can choose the normal display or in a pop up.

Hide extra options in cart

This will hide or show the extra fields from the cart.

Hide extra options prices in cart

This will hide or show the extra fields price from the cart.

Prevent negative priced products

This will prevent the product being added to the cart if its calculated price is less than zero.

## Strings

Final total text

This changes the Final total text of the totals box. Leave blank for default.

Options total text

This changes the Options total text of the totals box. Leave blank for default.

Free Price text replacement

Enter here a replacement text for the Free price label when product has extra option.

Reset Options text replacement

Enter here a replacement text for the Reset options text when using custom variations.

Edit Options text replacement

Enter here a replacement text for the Edit options text on the cart.

Additional Options text replacement

Enter here a replacement text for the Additional options text when using the pop up setting on the cart.

Close button text replacement

Enter here a replacement text for the Close button text when using the pop up setting on the cart.

## Style

Enable checkbox and radio styles

This enables or disables extra styling for checkboxes and radio buttons.

Style

Here you can select the extra styling type.

Select item border type

Here you can select the style for the selected border when using image replacements or swatches.

## Global

Enable validation

This enables the validation features.

Input decimal separator

Determine the decimal separator for user inputs.

Displayed decimal separator

This changes the decimal separator on currency prices.

Radio button undo button

This globally changes the undo button for all radio buttons.

Required state indicator

This changes the default * displayed when an option is required.

Required state indicator position

This changes the position of the indicator.

Include tax string suffix on totals box

This will include the tax string as a suffix on the totals box.

Datepicker theme

This changes the theme of the datepicker globally.

Datepicker size

This changes the size of the datepicker globally.

Datepicker position

This changes the position of the datepicker globally.

## License

On this section you will activate the plugin to enable access to the support forum and access to the automatic update feature.

#### Activation

You cannot activate the plugin on localhost. Be sure that you are activating for an actual online site

#### Deactivation

Be sure to deactivate the license if you are moving servers or changing sites. You can only activate once per domain.

# Loading outside WooCommerce

It is possible to use the provided action hooks outside of WooCommerce product screen. A typical scenario is when you develop a custom plugin or theme and you want to use the fields you have created.

## Required steps

### 1. Load the required javascript files.

To correctly do this make sure that somewhere in the code, preferably before the header is rendered place the following code.

    function tm_epo_js_loader(){
      do_action( 'woocommerce_tm_epo_enqueue_scripts');
    }
    add_action( 'wp_enqueue_scripts', 'tm_epo_js_loader' );

### 2. Displaying the fields.

This step requires that somehow you know the id of your WooCommerce product. Make sure you put the action somewhere after the 'init' hook if you want the fields to be displayed, like inside a template file.

Now it is time to display your fields. Find out where on your code you want to display them and use one of the provided action hooks. For example:

    if (isset($post) && is_object($post) && ($post instanceof WP_Post )){
        do_action("woocommerce_tm_epo",$product_id);
    }

# Translation with WPML

To get started, you will need WPML and add-on Plugins i.e. the core WPML Multilingual CMS which is always required and the String translations add-on.

Guide for installing & activating WPML is available on the WPML getting started guide.

#### WooCommerce Multilingual

Please note that while WooCommerce Multilingual is not conflicting with the plugin you cannot use it to translate the extra options.

##### Product Translation Interface

It is essential to use the "Go to the native WooCommerce product editing screen" on "Product Translation Interface" setting else you will not be able to translate the options inside a product.

## Translating global forms

### 1. Go to to the "Global Extra Product Options" list interface.

Here you can see all the translation of global form just right to the form's name. If a translation is not present you will see a cross (+) link to add the translation to the corresponding language else you will see the edit (pencil) icon indicating that a translation is already created.

### 2. Click the cross (+) link of the language you want to add.

### 3. Go to the form editor to edit the strings.

Please note that in this interface not all builder elements are activated. Only translatable strings are enabled.

#### Missing translations

If a translation is not created for a language then when viewing the product in that language the global form of the default language is used (or the language of the initial created form).

## Translating extra options in products

### 1. Make sure the product in the original language has a builder you want to translate.

Translated products use the form builder of the original created product.

### 3. Translate the product first.

You can use the the WooCommerce Multilingual to do the translation but for the next step you must set the "Product Translation Interface" to "Go to the native WooCommerce product editing screen".

### 4. Go to the form editor to edit the strings.

After you have translated the product edit it again and the builder will be available. Please note that in this interface not all builder elements are activated. Only translatable strings are enabled.

#### Missing translations

If a translation is not created for a language then when viewing the product in that language the strings of the default language is used (or the language of the initial created product).