=== Unit Converter & Sizing Calculator for Product Pages ===  
Contributors: dreamwell  
Tags: unit converter, sizing calculator, quantity calculator, product returns, product specification  
Requires at least: 5.8  
Tested up to: 6.9  
Requires PHP: 7.4  
Stable tag: 1.3.0  
License: GPLv2 or later  
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Reduce Product Returns with Unit Aware Specs & Buying Calculators that help customers buy the right size & quantity from the beginning.

== Description ==

Enhance your product pages with inline unit conversion and interactive unit-aware sizing calculators powered by CalcsLive. Makes it easier for customers to choose the right size and quantity before checkout. Help **Reduce support inquiries and product returns**. 

**Free:** a) Unit converter shortcodes that let visitors toggle between metric and imperial units in your product specifications—no account required; b) Calculator embedding: 2 pages on 1 domain for Free tier.

**Pro:** Embed powerful sizing and quantity calculators from [CalcsLive](https://www.calcslive.com) that guide customers to the right product configuration.

= Perfect For =

* **E-commerce stores** – AC sizing, concrete quantity, flooring coverage, paint calculators
* **Technical products** – Specifications with live unit conversion (mm ↔ inches, kg ↔ lbs)
* **Building materials** – "How many bags do I need?" calculators
* **Industrial equipment** – Belt sizing, cylinder selection, capacity calculators

= Key Features =

* **570+ Units, 67 Categories** – Full [CalcsLive unit library](https://calcslive.com/help/units-reference): length, mass, temperature, pressure, force, flow rate, and more
* **Unit Converter Shortcodes** – Free, no API key needed: `[calcslive_qty value=25 unit="mm"]`
* **Calculator Embed** – Embed full calculators: `[calcslive id="YOUR_ID"]`
* **Gutenberg Block** – Visual editor with live preview
* **Responsive** – Works on desktop, tablet, and mobile
* **Lightweight** – Scripts load only on pages that use them
* **Reduce Returns Preventively** – Helps customers choose right before purchase, and businesses reduce returns and all associated hassles, contrary to conventional **reactive** solutions

= Works With =

Shortcodes and the Gutenberg block work inside any WordPress editor or plugin that renders standard shortcodes:

* **WooCommerce product tabs** – Add unit-aware specs or calculators to any tab using plugins like [Custom Product Tabs for WooCommerce](https://wordpress.org/plugins/woo-custom-product-tabs-lite/) or YITH WooCommerce Tab Manager
* **Elementor** – Drop a Shortcode widget onto any product or landing page
* **Divi** – Use a Code or Text module with the shortcode
* **WPBakery / Classic Editor** – Paste shortcodes directly into any text area
* **Any shortcode-aware plugin** – If it renders `[shortcodes]`, CalcsLive shortcodes work inside it

= Buying Calculations: Reduce Returns, Increase Confidence =

Technical products often require customers to determine **the right size** and **the right quantity** before purchase. Without guidance, they guess—leading to returns, exchanges, and frustration.

**Buying Calculations** solve this by embedding pre-purchase calculators directly on product pages:

* **Sizing calculators** – Help customers choose correct dimensions, capacity, or fit
* **Quantity calculators** – Calculate how many bags, sheets, or units are needed

= Create Calculators Without Coding =

Traditional product calculators require custom development. CalcsLive changes this:

* Create calculation logic using familiar technical data
* Turn it into an interactive, unit-aware calculator
* Embed on WordPress with a simple shortcode

**From days of development to under one hour**—no coding required.

Product teams, engineers, or office staff can create and deploy calculators themselves, shifting calculator creation from a development task to a content task.

= How It Works =

**For unit converters (free, no account):**
1. Add to any page:  
  - Single quantity:
    - `[calcslive_qty value=25.4 unit="mm"]`, value input without quote  
    - `[calcslive_qty value='25.4' unit="mm"]`, value input with ' '  
    - `[calcslive_qty value="25.4" unit="mm"]`, value input with " "   
  - Quantity pair:
    - `[calcslive_qty_pair values="10x20" unit="cm"]` for 2D dimensions, or 
    - `[calcslive_qty_pair values="(10, 20)" unit="cm"]` for coordinates/range
  - Quantity triplet:
    - `[calcslive_qty_triplet values="10x20x30" unit="cm"]` for 3D dimensions, or 
    - `[calcslive_qty_triplet values="(10, 20, 30)" unit="cm"]` for 3D coordinates
2. Visitors click to convert between compatible units

**For embedded calculators:**
1. Create your calculator on [CalcsLive](https://www.calcslive.com)
2. Get your embed API key and article ID
3. Add `[calcslive id="YOUR_ID"]` to your product page
4. Customers use the calculator interactively

= Free Tier =

Start free with CalcsLive:
* 2 embedded calculators
* 1 domain
* Full calculator functionality
* Unit converter shortcodes (unlimited, no account needed)

[Get started free](https://www.calcslive.com/auth/register)

= Third-Party Service =

This plugin relies on the **CalcsLive** external service to display interactive calculations. When an embed is rendered, your visitor's browser loads content directly from CalcsLive via an iframe.

**What is sent:**

* Your embed API key and domain (included in the iframe URL)
* The article ID you specify in the shortcode or block

**No visitor data** (such as IP addresses, cookies, or personal information) is collected or sent to CalcsLive by this plugin. The iframe loads in the visitor's browser like any standard embedded content.

* CalcsLive website: [calcslive.com](https://www.calcslive.com)
* Terms of Service: [calcslive.com/terms](https://www.calcslive.com/terms)
* Privacy Policy: [calcslive.com/privacy](https://www.calcslive.com/privacy)

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/calcslive-article-embed/`, or install directly through the WordPress plugins screen.
2. Activate the plugin through the 'Plugins' screen in WordPress.

That's it for unit converters — no account or API key needed. For embedded calculators, see the Quick Start below.

== Quick Start ==

Unit-Aware Specs and Product Buying Calculators are two independent features. Use either one, or both.

= A: Unit-Aware Specs (Free, No Account) =

Use unit converter shortcodes anywhere shortcode insertion is supported — product descriptions, pages, posts, WooCommerce tabs, page builders:

`[calcslive_qty value="25.4" unit="mm"]` — single quantity
`[calcslive_qty_pair values="10x20" unit="cm"]` — 2D dimensions or coordinates
`[calcslive_qty_triplet values="10x20x30" unit="cm"]` — 3D dimensions or coordinates

Visitors click the unit dropdown to convert between compatible units. No API key. No external service. Fully client-side.

= B: Embed Buying Calculators (Requires CalcsLive Account) =

1. Create your calculator at [calcslive.com](https://www.calcslive.com) — no coding required
2. Get your embed API key (Settings → CalcsLive in WordPress) and your article ID
3. Embed anywhere with: `[calcslive id="YOUR_ARTICLE_ID"]` or use the CalcsLive Gutenberg block

Customers interact with the calculator live on your product page — inputs update in real-time.

= Unit Converter Shortcodes =

No API key needed. These shortcodes render interactive values that visitors can click to convert between units:

**Single value:**  
`[calcslive_qty value=25.4 unit="mm"]` (value input without quote)  
`[calcslive_qty value='25.4' unit="mm"]` (value input with ' ')  
`[calcslive_qty value="25.4" unit="mm"]` (value input with " ")  

**Value pair — 2D dimensions:**  
`[calcslive_qty_pair values="10x20" unit="cm"]`

**Value pair — 2D coordinates or range:**  
`[calcslive_qty_pair values="(10, 20)" unit="cm"]`

**Value triplet — 3D dimensions (L x W x H):**  
`[calcslive_qty_triplet values="10x20x30" unit="cm"]`

**Value triplet — 3D coordinates:**  
`[calcslive_qty_triplet values="(10, 20, 30)" unit="cm"]`

**Optional attributes:**

* `dp` - Decimal places (default: 2)
* `show_unit_arrow` - Show/hide unit dropdown arrow (default: true)

= Getting Your API Key =

1. Sign up or log in at [CalcsLive](https://www.calcslive.com)
2. Go to Account → API & Integration Settings
3. Create a new API key with service type "Website Embedding"
4. Add your WordPress domain to the allowed domains
5. Copy the API key to your WordPress settings

== Frequently Asked Questions ==

= Where do I get an API key? =

You can get an API key from your CalcsLive account at [calcslive.com/account/api-keys](https://www.calcslive.com/account/api-keys). You need to create an embed-type API key and add your WordPress domain.

= How do I find my article ID? =

The article ID is the short code at the end of your CalcsLive article URL. For example, in `https://www.calcslive.com/view/3M7EJLZQ2-4N5`, the article ID is `3M7EJLZQ2-4N5`.

= Can I embed multiple calculators on one page? =

Yes! Each article can contain multiple calculations with different namespaces. You can also embed multiple articles on the same page using multiple shortcodes.

= Does this work with page builders like Elementor? =

Yes. Both the calculator embed and the unit converter shortcodes work in any page builder that renders standard WordPress shortcodes:

* **Elementor** – Add a Shortcode widget and paste in `[calcslive id="..."]` or `[calcslive_qty ...]`
* **Divi** – Use a Code module or Text module
* **WPBakery** – Use the Classic Editor shortcode field or a Raw HTML element
* **Beaver Builder, Bricks, Oxygen** – Use any HTML or shortcode module

= Does this work inside WooCommerce product tabs? =

Yes. Any plugin that adds custom tabs to WooCommerce product pages (and renders shortcodes in their content area) is compatible. Tested with [Custom Product Tabs for WooCommerce](https://wordpress.org/plugins/woo-custom-product-tabs-lite/):

1. Install and activate Custom Product Tabs for WooCommerce
2. Edit a product → scroll to the Custom Tab section
3. Add a tab title (e.g., "Sizing Calculator" or "Specifications")
4. In the tab content area, paste your shortcode: `[calcslive id="YOUR_ID"]` or `[calcslive_qty value="25.4" unit="mm"]`
5. Save the product — the tab and its content appear on the frontend

This also works with YITH WooCommerce Tab Manager and similar tab plugins that support shortcode content.

= Is this free? =

The WordPress plugin is free and open source. CalcsLive offers a free tier with 2 embed pages, or you can upgrade for more pages and domains.

= Can customers enter their own values? =

Yes! The embedded article is fully interactive. Customers can change input values and units, and the calculations update in real-time.

= Do the unit converter shortcodes need an API key? =

No. The `[calcslive_qty]`, `[calcslive_qty_pair]`, and `[calcslive_qty_triplet]` shortcodes work entirely client-side with no external service. They use the bundled [physical-quantity](https://www.npmjs.com/package/physical-quantity) web component library.

= Where is the source code for the bundled JavaScript? =

The `pq.umd.js` file is built from the [physical-quantity](https://www.npmjs.com/package/physical-quantity) npm package (MIT licensed). The source is human-readable and includes version metadata in a banner comment.

= What units are supported? =

570+ units across 67 categories — the same full library used by CalcsLive. Covers length, mass, temperature, pressure, force, flow rate, energy, electrical, and many more. See the full [Units Reference](https://calcslive.com/help/units-reference). Visitors click the unit dropdown to convert between compatible units (e.g., mm ↔ inches, kg ↔ lbs, °C ↔ °F).

== Screenshots ==

1. AC Sizing Calculator embedded on a portable air conditioner product page - helps customers choose the right BTU capacity
2. Concrete Mix Calculator on a product page - customers calculate exactly how many bags they need
3. Belt Selection Calculator integrated with Gates A36 product - technical specifications with interactive sizing

== Demo Site ==

= Unit Converter Shortcodes in Action =

https://www.youtube.com/shorts/Cg2H7P_D3fo

= Live Product Page Examples =

See live examples at [cl.donwen.com](https://cl.donwen.com):

* [Portable Air Conditioner](https://cl.donwen.com/product/portable-air-conditioner/) - AC sizing calculator
* [Concrete Mix](https://cl.donwen.com/product/concrete-mix/) - Quantity calculator
* [Gates A36 Belt](https://cl.donwen.com/product/gates-a36/) - Belt selection tool
* [Air Cylinder](https://cl.donwen.com/product/mcm-m-series-round-body-air-cylinder/) - Air Cylinder Sizing Calculator

== Changelog ==

= 1.3.0 =
* Migrated to the new public-safe Embed Token format (`cle_xxx`) — these tokens are designed to be safely embedded in public pages
* Legacy `embed_xxx` tokens continue to work until 2026-08-31; replace yours with a `cle_` token from Account → API Keys before then
* Renamed "API Key" → "Embed Token" in settings UI to reflect the new token format
* Added "Test Connection" button — validates your token server-side and shows plan tier and configured allowed domains

= 1.2.0 =
* Updated bundled physical-quantity library to v1.3.0 — now shares the full CalcsLive unit library with 570+ units across 67 categories (see [Units Reference](https://calcslive.com/help/units-reference))

= 1.1.5 =
* Updated bundled physical-quantity library to v1.2.0
* `uc-qty-pair` now correctly supports x-format (`values="10x20"`) and tuple format (`values="(10, 20)"`)
* Updated shortcode examples in docs to use the two canonical formats

= 1.1.4 =
* Added shortcode examples for qty, pair, and triplet in readme

= 1.1.3 =
* Renamed plugin for better discoverability in WordPress directory
* Improved readme with clearer feature descriptions and use cases

= 1.1.2 =
* Added unit converter shortcodes: `[calcslive_qty]`, `[calcslive_qty_pair]`, `[calcslive_qty_triplet]`

= 1.1.1 =
* Bundled physical-quantity web component library (v1.1.92)
* PQ script loads only on pages using PQ shortcodes

= 1.0.1 =
* Updated tested WordPress version to 6.9
* Added third-party service disclosure for WP.org compliance
* Added languages directory for i18n support

= 1.0.0 =
* Initial release
* Shortcode support: `[calcslive id="..." width="..." height="..."]`
* Gutenberg block with live preview
* Settings page for API key and default dimensions
* Responsive iframe embedding

== Upgrade Notice ==

= 1.1.4 =
Added shortcode examples in readme. No functional changes.

= 1.0.0 =
Initial release with calculator embed and Gutenberg block support.
