Documentation for v.9.2.0

Last updated: Oct 10th, 2022

About the Plugin

The main task of this plugin is to create a form to calculate window configuration, price and make an order of it.

You can create combinations of products, set their prices and sizes, define additional options.

It is possible to calculate total price online and make an order.

Plugin thumbnail

Get the plugin

Installation

Download the zip file of the plugin from the repository. After go to the admin part of your site to the Plugins - Add New page.

To open the file uploading form click the Upload Plugin button on the top.

Installation

After select the downloaded zip file in the form lower, submit it and click Activate button.

The next you might need to check is the plugin settings.

Plugin Settings

Main Settings

You choose the styles that will be included in the plugin.

  • «Full» is the self-sufficient style file. It applied all required styles to the plugin's elements.
  • «Basic» styles are fine for you if your active theme is based on the "Bootstrap 3/4/5" framework. In this case, this calculator's style will be inherited from your active theme's. Despite this, you can also add your own CSS-styling rules.
  • «None» value. doesn't include any styles at all. In this case you can create a full custom CSS-style from the plugin sources and tools or by your own approach for styling.
  • «Custom styles» include the file with your custom styles such as colors, font-size, and so on. To modify it go to the «Custom styles» sub-page.

If for some reason you need to disable some of the plugin's scripts, change «Scripts including type» setting to «Multiple files» and de-select them in the list lower.

Sometimes the server's configuration might face problems with the stored sessions. Examples are: the calculator can't go to the next steps, or the cart contents' disappear on a page refresh. In this case, tick the «Store session in the DB» option. This option works much more reliable, but, probably, a tiny slower.

If you need to migrate all created plugin data from one site to another then use the Export/Import feature for this. Click the "Export" button once to get the data-file. Then choose this file in the file input on the target site and click "Run" once to run the import process. Be sure the old site is available to get the images from there.

Remember the script downloads and uploads only images that are defined in the settings. Images from the content part will not be replaced.

To create the initial plugin's data on your site click Generate demo data button once. That will give you a starter data kit to play with.

General settings page

Custom Styles

It is possible to reconfigure the plugin's styles according to your needs. Don't forget to choose a «Custom full styles file» value of the «Styles including type» setting.

In case your styles are not shown correctly, disable the «Minify custom styles» setting. In other cases keep this setting enabled to keep the CSS-file smaller and save your customers' traffic.

There are two modes for custom styling. The «Simple mode» provides only a few main variables to change. The «Advanced mode» allows you to change a great range of variables, but it requires CSS knowledge.
All the variables of the plugin are available to be changed by using a text editor.

Sometimes the calculator's fonts look very small on specific themes. To resolve this Adjust the «Font size» option. You can use any CSS units there, like "rem", "px", "pc", and so on.

In a case of a styling-command error, you will see a message while saving. The styling file will not be saved.

In case you need to reset your styles to their initial state click the «Reset to default» button once.

Custom styles settings page

Templates Customization

Window Calculator plugin has a folder of views that are used to be shown on the front of the site. There is a possibility to customize them as you need and keep the changes while the plugin updates.

To do this select files that require customization in the views list and apply the «Copy to the active theme» action in the form above. Selected views will be copied into your active theme in the windows-calculator folder saving the sub-folders structure. Files copied to your active theme will be marked by a tick icon.

The plugin firstly searches for a specific view in the theme's folders, and if it doesn't find the view there, it gets the view from its own directory.

You can edit the copied views using the «Appearance - Them editor» page.

If you want to delete some views from your active theme choose them in the views list, select the appropriate point in the form dropdown above and apply the changes. The view will be removed from the theme and the plugin's view will be used instead.

Keep in mind plugin might have some changes in the view files while updating. So if you have customized ones some of the new features will not work or might work wrong with them. This way just copy them from the plugin and adjust to your needs once again.

Templates customization settings page

Product Settings

Basic Settings

The first step of work with the plugin data is the creating of a simple product with variations.

Each product have the following settings:

  • Thumbnail will be used on a combination canvas;
  • Name setting allows to re-name the product for the output but have a different inner post title. That might be helpful for managing a lot of products;
  • Description to be output for the product;
  • Description output type - changing showing type of the description, "tooltip" for a short description and "modal" for a long one;
  • Width/height rounding step - affects on size sliders steps with individual pricing mode;
  • Thumbnail type - changing the type of the image output.
    In a case of using of SVG images for variation thumbnails you can output them as an Inline SVG to have a possibility to control their CSS using a special options setting.
    Alternatively, you can use a simple IMG tag.
  • Show with options setting allows to show the option only then another one or a few ones are checked. This is possible to combine the rules with AND/OR conditions. Select an option in the dropdown list and set the index of one of its values in the second field. If you need make this rule chained with the next, set the "Condition" field to "AND";
  • Visually hidden makes the product invisible on the canvas, but it still will affect the price and the cart item.

Product settings

Product Variation

Each product must have one or more variations with the following settings:

  • Thumbnail to be used to output while variation is active;
  • Title of the the variation to output;
  • Common price is used by the common pricing type combinations;
  • Individual prices is used by the individual pricing type combinations;
    To set these prices just paste an HTML table of width, height and their prices in the editor field.
    Each new variation will has a sample of the table in the editor field.
  • Default sizes allows to define default width and height of a variation. Alternatively, the average values from the table will be taken for this.
  • Round price to sets what price will be used then product size is in between the individual prices table values. The product can have the closest upper/lower size price or change it right in the middle between the near sizes.
  • Options - you can select options just for current variation. They will be available in a special modal and only for this variation.
  • Show with options setting allows to show the product only when one or a few specific options are selected. This is possible to combine the rules with AND/OR conditions. Select an option in the dropdown list and set the index of one of its values in the second field. If you need make this rule chained with the next, set the "Condition" field to "AND".

Product variation settings

Variation Price Table

Individual pricing mode allows to define minimum and maximum product sizes and a price for each of them. At the result this will be possible to select a required width and height for each specific product of the combination.

The price of the selected product width and height will be found in the price table and used to calculate the total of the combination.

Here is an example of individual prices HTML table. The first row means the widths range and the first column is heights. The prices are in the cross of these sizes.

Product variation price table

Combination Settings

Basic Settings

Each combination have the following settings:

  • Thumbnail will be used in a combinations list;
  • Name setting allows to re-name the combination for the output but have a different inner post title. That might be helpful for managing a lot of combinations;
  • Pricing type is the most important setting. It allows to enable/disable common size controllers or individual products size controllers;
  • Description to be output for the combination;
  • Description output type - select how to show the combination's description: in a tooltip, modal or inline;
  • Attached WooCommerce product - if you want to make the possibility to order the combination using WooCommerce, you need to create a sibling WooCommerce product with the "Windows Calculator Combination" special type. This product will be added in the WooCommerce cart and have all of the combination properties. This product should have the same title and thumbnails as the combination for avoiding users confusing.

Combination settings

Individual Pricing Type

Individual pricing type have the following settings:

  • Scopes max values - allows to limit the max sum of the scope's products. Define a scope ID in the left field and max value in the right one, then the sum of these products will not be more than this value.

Individual pricing type settings

Common Pricing Type

Common pricing type have the following settings:

  • Min/max width - set minimum/maximum combination width to order (affects on size slider);
  • Mix/max height - set minimum/maximum combination height to order (affects on size slider);
  • Default width/height - set default combination width to order (affects on size slider and price calculation);
  • Width/height price multiplier - effects on price after size changing.
    Value of 100% has equaled direct dependency of the product price to width/height selected by the user.
    Increase/decrease this value is affected price multiplying between the default and current width or height.

Common pricing type settings

Canvas Settings

There are two main types of canvas: static and dynamic. The static type isn't changed visually while products size adjustment, while the dynamic type makes products have and change their visual sizes accordingly to their current size.

Decide which type you want to use before the adding of items on it.

Types support

Common pricing type supports only static canvas type while individual pricing type supports both types.

Static canvas type

Select a product or element to add it on the canvas and click the Add item button. All of these products you see on this list are taken from the Windows Calculator - Products section. Also, there is a list of helper elements to use on the canvas, such are sliders, inputs and size indicators.

Set the product position and size on the canvas by changing X/Y/Width/Height values. Also, you can use the mouse for changing this options.

Will be better to fit the canvas size for its products to shorten the white space in it.

Combination static canvas

Dynamic Canvas Type

Dynamic canvas is based on a table layput. Each cell of it might have nothing or one item within.

Use rows/cols number settings to change the table cell number. Cells might be extended right or down if there is a space to do this. Use right and down cell arrows to do this. Extended cells might be reduced back using left/up arrows.

Select a product or element to add it on the canvas and click the "plus" button of a cell - the item will be added within. All of these products you see on this list are taken from the Windows Calculator - Products section. Also, there is a list of helper elements to use on the canvas, such are sliders, inputs and size indicators.

This is also possible to change the horizontal/vertical alignment of each cell using the special fields.

As the canvas is dynamic its "height" setting might be ignored on the for combination output.

Combination dynamic canvas

Canvas Item Settings

Order setting of any element on the canvas affects on the items overlapping and cart item data order.

Each individual pricing type canvas product have a settings modal with the following:

  • Group for width/height - these settings allows to define an ID of group of item values which will be bonded to each other to synchronously;
  • Reflect group for width/height - these settings allows to define an ID of group of item values which will be equal to each other while the changing;
  • Inversely group for width/height - these settings allows to define an ID of group of item values which will be reduced/increased while changing the value of one of them;
  • Scope for width/height - these settings allows to mark item sizes by an ID. The sum of the same scope values will be used for slave elements with the same Calculate width/height from a scope setting value;
  • Calculate width/height from a scope - an ID of a scope to calculate the sum of values from this scope products;
  • Enable width/height input/slider - this is possible to on/off each specific sizing element for the product;
  • Use combination controls - product will not use its own size inputs, but use the inputs/sliders of the whole combination, namely placed around all of the items on the canvas. Keep in mind only one item per combination can have this option enabled;
  • Display in cart - control item present in the cart item properties;
  • Name - control element name in the cart item properties;
  • Min/max/default value - define element's values range and the default value;
  • Value step - element's value change step property;
  • Visually hidden makes the product invisible on the canvas, but it still will affect the price and the cart item.

Scope and group settings cross-fire

Scope and group settings have a global IDs scope. That's an advantage but might be a reason of configuration mistakes. Don't forget to use different IDs for settings you don't want to be intersected.

Canvas Elements

There are a few util-items available for use on the combination canvas:

  • Vertical/horizontal size element allows to calculate and output the sum of the products by a scope ID;
  • Vertical/horizontal slider element allows to output a size slider with a defined range and value;
  • Vertical/horizontal input element allows to output an input field with a defined range and value, and also with scope/group settings for using.

Option Settings

Basic Settings

Each option have the following settings:

  • Name setting allows to re-name the option for the output but have a different inner post title. That might be helpful for managing a lot of options;
  • Type is an important setting to define the option controls;
  • Values setting controls what values will be available to select for the option;
  • Description to be output for the option;
  • Description output type - select how to show the option's description: in a tooltip, modal or inline;
  • Show with options setting allows to show the option only then another one or a few options are selected. This is possible to combine the rules with AND/OR conditions. Select an option in the dropdown list and set the index of one of its values in the second field. If you need make this rule chained with the next, set the "Condition" field to "AND";
  • Show with product variations setting allows to define with which product variations the option will be shown. Select a product from the dropdown menu and define it's variation number from zero. Add more rule lines if you need;
  • Show with combinations setting allows to define with which combinations the option will be shown;
  • Availability rules setting controls the option availability by custom rules, such as current product size or price to enable/disable this option accordingly.

Important notes

  • Options influence at the price is calculated sequenced according to their order;
  • Size based types are calculated using the common product size for the common pricing type, and using the each product size for an individual pricing type.
    Individual product options are calculated only for their parent product;
  • Then you're using option categories for a calculator these options might be ordered not as you wanted to have them. To solve it easily use any 3rd-party plugin the posts sorting, for example, Simple Custom Post Order.

Option settings page

Option Item Settings

According to the selected option type there might be different set of settings available for each option value item. The constant are:

  • Name - option item label;
  • Value - numeric value or formula to apply while the option item is selected;
  • Common pricing multipliers affect controls will individual product options be calculated before or after the common pricing modification.
  • Type setting allows to select the option calculation behavior. See more details about;
  • Available with options setting allows to make the item available only then another option or a few options are selected. This is possible to combine the rules with AND/OR conditions. Select an option in the dropdown list and set the index of one of its values in the second field. If you need make this rule chained with the next, set the "Condition" field to "AND";
  • Available with product variations setting allows to define with which product variations the item will be available. Select a product from the dropdown menu and define it's variation number from zero. Add more rule lines if you need;
  • Available with combinations setting allows to define with which combinations the item will be available;
  • Availability rules setting controls the item availability by custom rules, such as current product size or price to enable/disable this item accordingly.
  • Display in cart - control item present in the cart item properties;

Here are the settings available for specific option types only:

  • Influence on setting allows to modify combination price or other options value, instead of the formula-based ones;
  • Influenced combinations - use this setting to option item influence only specific combinations. Keep empty to influence all combinations;
  • Influenced options - use this setting to option item influence only specific options. Keep empty to influence all options;
  • Multiplication behavior setting controls the approach of the multiplication option type. It can be multiplied with the value already changed by other options or the pure one;
  • Count settings are available for the checkbox option type and output the quantity input field near the item. Count value influence the option item price result;
  • Show price setting outputs the item value near its label;
  • Checked setting allows to pre-select specific option item;
  • Thumbnail setting is available for the image-based option types to output an appropriate image for the option item;
  • Texture settings allow to add a texture above the combination or products while the option item is selected;
  • Reduce products widths/heights settings allows to reduce maximum product sizes by a defined value while the option is selected;
  • Apply CSS setting adds defined CSS rules to the page with the calculator while the option item is selected.

Option item settings

Types of Pricing

Addition

Simple adds the price value to the combination price.

Example: value 15 + combination price $100 = $115

Area size based addition

Gets multiplication of the value with combination width and height and adds it to the combination price.

Example: value 0.01 * 50cm of width * 40cm of height + combination price $100 = $120

Perimeter size based addition

Gets multiplication of the value with two combination widths plus two heights and adds it to the combination price.

Example: value 0.1 * (50cm of width + 40cm of height) * 2 + combination price $100 = $118

Width based addition

Gets multiplication of the value with combination width and adds it to the combination price.

Example: value 0.1 * 50cm of width + combination price $100 = $105

Height based addition

Gets multiplication of the value with combination height and adds it to the combination price.

Example: value 0.1 * 40cm of height + combination price $100 = $104

Multiplication

Gets combination price and multiply it with price value.

Example: value 1.2 * combination price $100 = $120

Area size based multiplication

Gets multiplication of the value with combination width and height and multiply it to the combination price.

Example: value 0.01 * 50cm of width * 40cm of height * combination price $100 = $2000

Perimeter size based multiplication

Gets multiplication of the value with two combination widths plus two heights and adds it to the combination price.

Example: value 0.1 * (50cm of width + 40cm of height) * 2 * combination price $100 = $1800

Width based multiplication

Gets multiplication of the value with combination width and adds it to the combination price.

Example: value 0.1 * 50cm of width * combination price $100 = $500

Height based multiplication

Gets multiplication of the value with combination height and adds it to the combination price.

Example: value 0.1 * 40cm of height * combination price $100 = $400

Custom formula

Calculate the formula result using the current combination price, option value, its count, and products total width and height.

Available variables are: [price], [value], [total_width], [total_height], [count]

Important: don't forget to use the [price] variable to modify the current combination price.

Example: [price] + ([value] * [total_width] / 2)

Calculator Settings

After all previous steps done, you can create a calculator post.

Basic Settings

First of all, select the combinations for use in this calculator and set their order. Also, you can select combination categories to show them accordingly in the calculator.

There are two ways to output the options: show them in one section or as blocks of few options. Use the options source setting to change the appropriate way. For the first way select and sort specific options, but for the second way do the same with the option categories. Use any free posts sorting plugin to change the order of the options within each category.

There are a few built-in layouts for use. The steps layout has another setting called steps instead of the options selector. There you can define steps and their order in the calculator. Three steps are built-in: combinations, combinations categories, and the canvas. The other steps are the options categories.

Save state to URL setting will allocate the current URL arguments according the current calculator options and values. After page refresh all settings will be applied again.

Generate cart item thumbnails setting replacing the cart item's thumbnails with the active canvas image.

SVG image notes

To have the best products presentation use the default SVG files from the plugin as a basement.

They are organized to be well rubber-scaled with the dynamic canvas type and to generate the cart item thumbnail correctly.

You can modify them for your needs and required style or keep as they are.

If you're going to use own SVG images then keep im mind:

  • To be sure the generation will work fine clean, the SVG files with any cleaning tool, like SVGOMG
  • Don't forget to define SVG width and height attributes for correct image generation
  • Add preserveAspectRatio="none" attribute to SVG image to make it rubber scaling

If you have really many of different combinations and it slowdown the performance then check the Load combinations via AJAX option.

Calculator basic settings

Order Settings

Enable order setting allows to get orders using a Contact Form or WooCommerce plugin.

By default product cart is enabled. However, this is possible to disable it to not store the selections and complete the order immediately with the current calculator selection.

If you are going to get the orders through email, then select one of the existing Contact Form 7 forms in the Order contact form setting.

This is possible to clear cart then the contact form is sent or keep it.

To get the order info as a string add the [wincalc-cart] shortcode in the Message body field.

If there is no attached PDF file in the email then add the [wcpw-cart-pdf] shortcode in the File attachments field.

WooCommerce order redirect setting leads the customer to the cart, checkout or whatever page after the WooCommerce add to cart action.

Calculator order settings

View Settings

There are a lot of view settings for the most calculator's parts. There are no limitations and you can combine them as you want to have the appropriate view.

Calculator view settings

Pricing Settings

Calculate online option enables/disables any amount values and cart on a calculator's page.

Define the required price currency and format using the special settings.

If you need to add some tax to the total sum, then set tax value size in percents.

Also, you can change some text strings and price format.

Calculator pricing settings

Cart PDF Settings

Enable cart PDF settings to have a special button in the cart section to open the PDF file in the new tab. It will show all current cart content if it's enabled or only current selection if the cart is off.

Lower you can find the most page parts settings to adjust.

Moreover, you can pass extra CSS to the pdf file using the special setting.

If that's not enough then try to customize the view of the print page.

Calculator print settings

Controls settings

All calculator buttons can have different classes for their styling. As the main plugin styles are based on the Bootstrap 5 framework you can use any from the available styling classes of buttons.

Also, there are a few classes to control buttons text and icons appearing:

  • hide-text - hides text of the button but keeps it for screen readers;
  • hide-text-on-mobile - hides text of the button on small screens but keeps it for screen readers;
  • icon-left - define on which side of the button the icon should appear;
  • icon-right - define on which side of the button the icon should appear;
  • show-icon - always shows a pre-defined button icon. Requires icon-left/right class for work;
  • show-icon-on-mobile - shows a pre-defined button icon on small screens. Requires icon-left/right class for work;

There is also a possibility to add preset controls to the calculator. This setting will output two buttons to save the current calculator selection to a file and load it from this file.

Controls settings

Strings and Labels Settings

This is possible to change all static text parts of the calculator output.

Calculator strings settings

Steps Layout Settings

There are a few options only for the steps layout.

Calculator steps-view settings

WooCommerce Product Settings

This is possible to create a WooCommerce product of a special type with an attached windows calculator within.

This is necessary to select a calculator and a combination which will be used for showing instead of the default WooCommerce product content. Doesn't matter which combinations/categories are selected for this calculator - there will be only the selected combination. Also, the calculator's own cart will be disabled. All other calculator settings will be used as they are.

To make this product purchasable define the regular price of the product. As windows calculator products mostly have variable amount, so the price will be output with a "From" prefix.

WooCommerce product settings

PHP Tricks and Utils

Modify products and options prices dynamically

In case you need to modify the stored prices according to some situation, e.g. according to currencies exchange, you can use a couple of filters for this. This extra code changes all product prices and any additional type options.

The price has doubled in the lower example. Change the return of the getWinCalcPriceModifier function according to your needs.

<?php
function getWinCalcPriceModifier()
{
    return 2;
}

add_filter('wincalc_product_variations', function ($variations, $id) {
    static $cache = [];

    if (isset($cache[$id])) {
        return $cache[$id];
    }

    $modifier = getWinCalcPriceModifier();

    if ($modifier == 1) {
        return $variations;
    }

    foreach ($variations as &$variation) {
        $variation['price'] = round($variation['price'] * $modifier, 2);

        foreach ($variation['prices'] as &$price) {
            $price['value'] = round($price['value'] * $modifier, 2);
        }

        unset($price);
    }

    unset($variation);

	$cache[$id] = $variations;

    return $variations;
}, 10, 2);

add_filter('wincalc_option', function ($option, $id) {
	static $cache = [];

    if (isset($cache[$id])) {
        return $cache[$id];
    }

    $modifier = getWinCalcPriceModifier();
    $handledTypes = [
        'addition',
        'area-size-based-addition',
        'perimeter-based-addition',
        'width-based-addition',
        'height-based-addition'
    ];

    if ($modifier == 1) {
        return $option;
    }

    foreach ($option['values'] as &$value) {
        if ($value['influence_on'] == 'combinations_price' && in_array($value['type'], $handledTypes)) {
            $value['price'] = round($value['price'] * $modifier, 2);
        }

        unset($value);
    }

	$cache[$id] = $option;

    return $option;
}, 10, 2);