Documentation for v.7.5.0

Last updated: Feb 15th, 2021

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

General settings page

If you active theme is based on "Bootstrap 4" framework, then the calculator will styled the same as your active theme. Otherwise, tick the "Include full styles file" option to make the calculator looks correct.

To integrate the plugin with WooCommerce plugin tick the "WooCommerce integration" setting. It will disable the order modal and send products into WooCommerce cart.

Sometimes server's configuration might have problems with storing sessions. For example, if the calculator can't loses the cart content on the page update. In this case tick "Store session in the DB" setting which works much reliable but probably a little bit slower.

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

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.

Save settings before the run

If you need WooCommerce integration and need generate those products too tick the WooCommerce integration setting and save the settings before the demo-data generation.

Product Settings

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

The possible options of a product are:

  • Name - it will be taken from the special setting or from the post title;
  • Editor field for description;
  • Width/height rounding step - affects on size sliders steps with individual pricing mode;
  • Description output type - changing showing type of the description, "tooltip" for a short description and "modal" for a long one;
  • 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.
  • Rules of showing the product in the combination only with specific options.
  • Visually hidden checkbox - just makes the product invisible on the canvas, but it still will affect the price and the cart item.

Don't forget to set product's thumbnail - it will be used while creating of combinations, alternatively the first variation thumbnail will be taken for this.

Product settings

Each product must have one or more variations with options:

  • Thumbnail;
  • Title;
  • Common price - is using by combinations with the only pair of width and height (called "Common pricing type");
  • Individual prices - is using by combinations with separately width and height of each product (called "Individual pricing type").
    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.
  • 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 - you can select with what options the variation will be available for choosing. 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 "Condition" field to "AND".

Product variation settings

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

Each combination have the following settings:

  • Thumbnail will be used in a combinations list;
  • Pricing type is the most important setting. It allows to enable/disable common size controllers or individual products size controllers;
  • Description output type - select how to show the combination's description: in a tooltip, modal or inline;
  • Attached woocommerce product - woocommerce product reflection for the shop;
  • Canvas width/height - effects on the visual part of the combination;
  • Items - products and visual elements of the canvas.

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 default and selected width or height.

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.

Work with the canvas and items

There are two main types of canvas: static and dynamic. The static type doesn't change visually while products size adjustment then the dynamic type makes products have and change their visual sizes accordingly to the 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 size 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" admin part. But the elements are built in the plugin's code.

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 the table. Each cell of it might have nothing or only 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" admin part. But the elements are built in the plugin's code.

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

Combination dynamic canvas

Item settings

Each individual 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 sizes which will be bonded to each other and change synchronously;
  • 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;
  • Hide width/height controls - if you have a product with the only row/column of prices;
  • Use combination controls - moves the control of the not only product in the "Individual pricing" mode to the canvas sliders and inputs.

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

You can hide width/height controls for specific item. The slider and the input field.

This is possible to use combination controls for an item. In this case individual priced item will not use it's own size inputs but use the inputs/sliders of the whole combination, namely placed around the all products on the canvas. But keep in mind onlt one item per combination can have this option enabled.

Canvas elements

There are a few util-items available for use on the combination canvas. They have no power over the pricing and will not be in the cart. Here they are:

  • Vertical size element allows to calculate the sum of the products by a scope ID and have a vertical view;
  • Horizontal size element allows to calculate the sum of the products by a scope ID and have a horizontal view.

WooCommerce integration

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 selected combination setting.

Be sure the "WooCommerce integration" global setting is enabled.

This product should have the same title and thumbnails as the combination for avoiding users confusing. Afterward, select this product on the combination admin page in the field called "Attached WooCommerce product" and save the changes.

Option settings

An option can have one of allowed views. Each view has specific settings, such as image size for the imaged views.

Each option must have one or more values. Here are its main options:

  • Name - it will be taken from the special setting or from the post title;
  • Type - important setting to define the option behavior;
  • Values - possible values of the option.

All option types can have a description. The editor is used for it. It can be output as a tooltip, modal or string.

Use "Show with options" setting if you need to show the options only then another one (or few options) is 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 "Condition" field to "AND".

This is possible to define with which product variations the option will be shown using the "Show with product variations" setting. Select a product from the dropdown menu and define it's variation number from zero. Add more rule lines if you need.

This is lso possible to define with which combinations the option will be shown using the "Show with combinations" setting.

You also can limit the option availability by custom rules such as current product size or price and enable/disable this setting accordingly.

Important notes

  • Options influence at the price is calculated sequenced according to their order;
  • Size based types calculated with a common product size for a common pricing type or with each product for an individual pricing type. Individual product option calculates only for this product.

Option settings page

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

Calculator settings

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

Basic

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.

Calculator basic settings

Behavior

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

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

  • To be sure the generation will work fine clean the SVG files before using 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.

There is also a possibility to add preset controls to the calculator.

Calculator behavior settings

Order

Enable order option enable/disable "order" and "add-to-cart" buttons on calculator page.

This is possible to disable the cart to not store the selections and complete the order immediately with the only 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.

To get the order info correct do not forget to add the [wincalc-order] shortcode in the Message body field.

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

The redirect after the WooCommerce order can be changed.

Calculator order settings

View

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

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.

Calculator pricing settings

Print

The Enable cart print settings allows to add the button to print the current cart items or current selection in case the cart is disabled.

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

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

Calculator print settings

Strings and labels

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

Calculator strings settings

Steps view

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

Templates Customization

If you want to customize some views of the plugin and don't lose these changes while updating the plugin create the "windows-calculator" folder in your active theme (or child theme) directory and copy into it files from the plugin's "views" directory saving the sub-directory hierarchy.

The plugin is trying to get a view from the theme at first, and if it doesn't find this view, it gets the view from the own directory.

For example, if you want to customize the cart print view copy the
%plugin_folder%/views/cart/print.php to %your_active_theme%/windows-calculator/cart/print.php.

Now you can customize this file in your theme.

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