=== CalcsLive Article Embed === Contributors: dreamwell Tags: calculator, embed, iframe, unit conversion, calcslive Requires at least: 5.8 Tested up to: 6.9 Requires PHP: 7.4 Stable tag: 1.1.2 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html Embed interactive CalcsLive articles and unit-aware physical quantities into your WordPress site. == Description == **CalcsLive Article Embed** allows you to embed interactive calculation articles from [CalcsLive](https://www.calcslive.com) and display unit-aware physical quantities with live unit conversion on your WordPress website. = What is CalcsLive? = CalcsLive is a platform for creating, sharing, and embedding unit-aware calculations. Articles can contain multiple calculations with automatic unit conversions, making them perfect for: * **E-commerce product pages** - Help customers calculate requirements (AC sizing, concrete needs, etc.) * **Technical documentation** - Add interactive examples to engineering content * **Educational content** - Let students explore calculations with real-time results * **Product specification pages** - Embed sizing tools and configuration calculators = Key Features = * **Article Embed Shortcode** - Embed with `[calcslive id="YOUR_ID"]` * **Physical Quantity Shortcodes** - Display values with live unit conversion: `[calcslive_qty value="25" unit="mm"]` * **Gutenberg Block** - Visual block editor with live preview for article embeds * **Responsive Design** - Works on all screen sizes * **Secure Embedding** - API key authentication with domain restrictions * **Lightweight** - PQ script loads only on pages that use PQ shortcodes = How It Works = 1. Create your calculation article on CalcsLive 2. Make the article public 3. Get your embed API key from CalcsLive 4. Use the shortcode or block to embed on your WordPress site 5. Your visitors can use the calculator interactively = Free Tier Available = CalcsLive offers a free tier that includes: * 2 embed pages * 1 domain * Full calculator functionality [Get started for free at CalcsLive](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. 3. Go to Settings → CalcsLive to configure your API key. 4. Use the `[calcslive]` shortcode or the CalcsLive Article block in the editor. 5. Use `[calcslive_qty]` shortcodes for inline physical quantities (no API key needed). = Physical Quantity Shortcodes = No API key needed. These shortcodes render interactive unit-aware values that visitors can convert between units: **Single value:** `[calcslive_qty value=25.4 unit="mm"]` **Value pair (e.g., dimensions):** `[calcslive_qty_pair values="10,20" unit="cm"]` **Value triplet (e.g., L x W x H):** `[calcslive_qty_triplet values="1,2,3" unit="m"]` **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, you can use the shortcode `[calcslive id="..."]` in any page builder that supports WordPress shortcodes. = 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 physical quantity 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 by the PQ shortcodes? = The physical-quantity library supports units across length, mass, temperature, energy, force, pressure, and more. Visitors can click the unit dropdown to convert between compatible units. == 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 == 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 == Changelog == = 1.1.2 = * Added physical quantity 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.2 = New physical quantity shortcodes for inline unit-aware values with live conversion. = 1.0.0 = Initial release of CalcsLive Article Embed for WordPress.