=== SpreadsheetConverter Calculator ===
Contributors: spreadsheetconverter
Tags: calculator, excel, spreadsheet, form, embed
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 12.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Embed live, calculating web pages converted from Excel by SpreadsheetConverter — inline in your theme, no iframe.

== Description ==

SpreadsheetConverter (https://www.spreadsheetconverter.com/) turns an Excel
workbook into an interactive, calculating web page. This plugin embeds that
calculator in WordPress as a Gutenberg block — rendered inline by your
theme (no iframe), SEO-visible, and recalculating live as visitors type.

You create the calculator with the SpreadsheetConverter add-in for Excel. It
works in Excel desktop (Windows or Mac) **and** in Excel on the web, which is
free with a Microsoft account — so most people can use it without buying Excel.
There is a free trial — install it from
https://addin.spreadsheetconverter.com/install

**Three hosting modes:**

* **Server form (recommended)** — click *Publish to the Server* in Excel
  (SpreadsheetConverter Server), then *Copy link*, and paste it. The form
  mounts inline on your page straight from the Server — calculating live,
  **saving what visitors type as records on the Server**, no Server menus,
  no iframe. Any conversion flavor works; you do not need the Embeddable
  option for this mode.
* **Host on this site** — paste the conversion link copied from the
  SpreadsheetConverter task pane in Excel and click *Host on this
  site*. WordPress fetches the calculator from the SpreadsheetConverter
  cloud and stores it inside your own site
  (`wp-content/uploads/ssc-embed/`). Everything is then served same-origin
  — fast, no CORS, and the calculator keeps working forever, even after
  the conversion link expires.
* **Link to the cloud** — click *Publish to Cloud* in Excel, paste the
  permanent link. The calculator stays on the SpreadsheetConverter cloud;
  your page references it and is always current when you re-publish.

An offline fallback lets you upload the calculator zip manually if your
WordPress host cannot reach the SpreadsheetConverter cloud. Classic
(non-block) themes can use the `[ssc_calc]` shortcode.

One calculator per page. The block validates the pasted link and tells
you exactly what to do if it is the wrong kind (for example a temporary
"Test in Cloud" link).

== External services ==

This plugin connects to SpreadsheetConverter services in three situations,
each initiated explicitly by an editor — never on a public page view in
self-host mode:

1. **Host on this site** — when an editor clicks the button, the WordPress
   server downloads the calculator bundle from the conversion link's host
   (`*.spreadsheetconverter.com`). The pasted URL (containing the
   conversion job id) is the only data sent.
2. **Link to the cloud** — the page embeds the calculator directly from
   the SpreadsheetConverter hosting cloud (`*.spreadsheethosting.com`);
   visitors' browsers request the calculator files from that host. When
   configuring the block, the WordPress server fetches the published
   calculator's index page once to read its name.
3. **Server form** — the page embeds the form directly from
   SpreadsheetConverter Server (`server.spreadsheetconverter.com`);
   visitors' browsers request the form and its assets from that host, and
   what a visitor types into the form is saved as a record on the Server
   (that is the product: a saving form). Nothing is fetched by your
   WordPress server in this mode.

Both services are provided by Framtidsforum I&M AB (SpreadsheetConverter).
Terms of use: https://www.spreadsheetconverter.com/terms-of-use/
Privacy policy: https://www.spreadsheetconverter.com/privacy-policy/

== Getting started ==

= Part 1 — Convert your spreadsheet (in Excel) =

You need the SpreadsheetConverter add-in for Excel to convert your workbook. It
runs in Excel desktop (Windows or Mac) or in Excel on the web (free with a
Microsoft account — no need to buy Excel). Install it (free trial) from
https://addin.spreadsheetconverter.com/install

1. **Start Excel and open your workbook** — e.g. `mortgage-calculator.xlsx`.
2. **Open the SpreadsheetConverter task pane** (Home ribbon →
   SpreadsheetConverter).
3. **Sign in** if prompted (required to convert).
4. **Press Convert.** For the recommended Server mode any flavor is fine —
   the Server compiles the workbook itself. For *Host on this site* or
   *Link to the cloud* you must select **Flavor = HTML and tick the
   Embeddable checkbox** first — those two modes embed the converted bundle,
   and only an Embeddable HTML conversion produces it. The spreadsheet
   becomes an interactive web calculator (a few seconds).
5. **Get the link to paste into WordPress.** On the green **Converted** card:
   * *Recommended:* press **Publish to the Server**, then **Copy link** on
     the *Published to the Server* card — a permanent link to your form on
     SpreadsheetConverter Server (visitors' entries are saved as records
     there).
   * To host it on your own WordPress site: under **▸ More options →
     WordPress**, press **Copy link** — the short-lived conversion link (use
     it within a few minutes).
   * To link to the SpreadsheetConverter cloud instead: under **Classic
     cloud**, press **Publish to cloud**, then copy the permanent link. Only a
     permanent Publish-to-cloud link works for cloud-linking — a temporary
     "Test in cloud" link (its address contains `/tmp/`) is rejected by the
     block.
   * In every case you paste the **whole link** and the block double-checks
     it. Nothing is downloaded to your computer.

= Part 2 — Add it to your WordPress page =

6. **Open your WordPress page for editing** (Pages → Add New). You are
   already signed in to WordPress here — that is why you never type a
   password into Excel.
7. **Add the SpreadsheetConverter block** (＋ → "SpreadsheetConverter
   Calculator").
8. **Paste your link.** The block recognizes the link type and offers the
   matching option:
   * Server form link (`…/forms/your-form`, a record link
     `…/forms/your-form/17`, or the `…/embed.html` address itself) →
     **Embed from the Server** (recommended). Click it. The form mounts
     inline straight from the Server — no Server header, menu or records
     row, just the form, styled by your theme.
   * Conversion link → **Host on this site**. Click it.
     WordPress fetches your calculator and stores it inside your own site.
   * Publish-to-Cloud link → **Link to the cloud.** The calculator stays
     on the cloud; your page references it.
   * Temporary "Test in Cloud" link → the block shows: *"This is a
     temporary test link — click Publish to Cloud in Excel for a permanent
     one."*
   * A Server link that is not a form (a Records list, a Properties page,
     a private link) → *"Paste the form's own link — the address 'Open
     your form' opens in Excel (…/forms/your-form). Records lists,
     Properties pages and private links can't be embedded."*
   * Anything unrecognized → *"That doesn't look like a
     SpreadsheetConverter link — copy it again from the Excel panel."*
9. **See the live preview** inside the editor — no grey iframe,
   theme-styled, calculates live.
10. **Press Publish** (the WordPress button). The page goes live.
11. **View your live page.** It calculates, validates, moves between
    sheets, and Submit works. On a Server form, what a visitor types is
    saved to the Server exactly as on the Server's own page: a small save
    status sits at the top of the form, action buttons show their outcome
    in the page, and you find the records under **Records** on the Server.

= Server forms — notes and limits =

* **One calculator per page** (all modes; the calculator is page-global).
* **Classic themes:**
  `[ssc_calc token="https://server.spreadsheetconverter.com/t/acme/forms/order"]`.
* **Updating later:** re-publish to the Server — your page mounts the new
  version on reload; nothing to change in WordPress.
* **Returning visitors:** in most browsers a visitor who comes back to your
  page is recognized again (the Server keeps their identity in a partitioned
  cookie) and continues with their earlier entry. A browser that refuses
  partitioned cookies starts a fresh entry instead — the earlier one stays
  safe on the Server.
* **No sign-in inside the mount:** a members-only form shows the Server's
  refusal in the save status with a link to sign in on the Server's own
  page.
* **Forms published before this release:** re-publish once so images inside
  the form and returning-visitor recognition work in the mount (both ride a
  per-form file that updates on publish).
* **Your site sends its own Content-Security-Policy?** Allow
  `https://server.spreadsheetconverter.com` in `script-src`, `style-src`,
  `img-src` and `connect-src` — the same four the cloud-link mode needs for
  spreadsheethosting. WordPress itself sends no CSP by default.
* **Troubleshooting:** open `…/forms/your-form/embed.html` directly in a
  browser. If it works there but not on your page, the issue is your page's
  CSP, a plugin stripping the custom element, or a theme script clashing
  with a global the calculator uses.

== Screenshots ==

1. The published page — the calculator renders inline in your theme, no
   iframe, and recalculates live as visitors type.
2. Add the SpreadsheetConverter Calculator block from the block inserter.
3. The block asks for one thing: the link you copied from the
   SpreadsheetConverter task pane in Excel.
4. Paste a conversion link and the block offers *Host on this site* — one
   click stores the calculator inside your own WordPress site (same-origin,
   permanent, no CORS).
5. The live preview in the editor is the real calculator, already
   calculating — what you see is what your visitors get.

== Frequently Asked Questions ==

= How many calculators can I put on one page? =

One. Each page hosts a single calculator; put more on their own pages.

= My theme uses the classic editor — can I still embed? =

Yes: `[ssc_calc token="…"]` (a link you pasted/hosted via the block, a
permanent cloud link, or a Server form link) or `[ssc_calc src="…"]` (the
calculator's base URL).

= What is the difference between a Server form and the other modes? =

A Server form is hosted on SpreadsheetConverter Server and **saves what
visitors type as records** you can review there — it is a form, not just a
calculator. The other two modes embed a static calculating page (self-hosted
or on the cloud); nothing is stored unless the workbook has its own Submit.
For other websites (Squarespace, Wix, plain HTML) the form's Properties page
on the Server shows the same two-line embed code to copy.

= How do I update the calculator later? =

Convert again in Excel and re-click *Host on this site* (or re-Publish to
Cloud). Re-hosting replaces the stored copy.

= I am upgrading from the classic version — will my existing calculators break? =

No. The classic plugin embedded each calculator as a fixed `<iframe>` saved
directly in your page, pointing at files in `wp-content/uploads/ssc/`.
Version 12 does not touch those files, so your existing pages keep working
exactly as before. What changes is only the editor: the old upload screen is
replaced by the new "SpreadsheetConverter Calculator" block. To add a *new*
calculator, use that block (or the `[ssc_calc]` shortcode). After updating you
will see a one-time admin notice with the same reminder; you can dismiss it.

= The calculator isn't working on my page =

If you self-hosted, open
`https://<your-site>/wp-content/uploads/ssc-embed/<name>/index.html`
directly in a browser. That page runs the calculator on its own — if it
works there but not on your page, the issue is page/theme integration,
not the calculator.

= My WordPress host cannot reach the internet =

Use the offline fallback: click *Download zip* in the Excel task pane and
upload the zip in the block.

== Changelog ==

= 12.1.0 =
* New: **Server form** mode — paste a SpreadsheetConverter Server form link
  (`…/forms/your-form`) and press *Embed from the Server*. The form mounts
  inline in your theme (no iframe, no Server menus), calculates live, and
  saves visitors' entries as records on the Server. Record links and
  `?view=1` links work too.
* The `[ssc_calc]` shortcode accepts Server form links.
* Images and other assets inside an embedded calculator now load from the
  calculator's own host in every mode (previously they could wrongly be
  requested from your page's address).
* Clearer message when a pasted Server link is not a form's own address
  (a Records list, a Properties page, a private link).

= 12.0.2 =
* Editor: the link field's placeholder no longer shows a full example URL,
  which could be mistaken for an already-entered value. It now reads
  "Paste calculator link…" (and is translatable).

= 12.0.1 =
* Add a one-time, dismissible admin notice for sites upgrading from the
  classic (pre-12) plugin: confirms existing iframe embeds keep working and
  points to the new block. Shown only when classic data is detected.
* Add an "Upgrading from the classic version?" FAQ entry.

= 12.0.0 =
* Complete rewrite for SpreadsheetConverter v12.
* Gutenberg block with inline (no-iframe) rendering via the `<ssc-calc>`
  embed mount.
* Self-host mode: block-initiated pull — WordPress fetches the calculator
  bundle server-side; no credentials, no CORS.
* Cloud-link mode: reference a permanent Publish-to-Cloud URL.
* Manual zip upload fallback for air-gapped hosts.
* `[ssc_calc]` shortcode for classic themes.
* Removed: custom post type, upload-triggered ZIP extraction, version
  regex, debug file logging, TinyMCE iframe inserter.

== Upgrade Notice ==

= 12.1.0 =
New Server form mode: paste a Publish-to-Server link and embed a saving form
inline on your page. Existing embeds are untouched.

= 12.0.2 =
Minor editor polish: clearer placeholder in the block's link field.

= 12.0.1 =
Major rewrite (v12). Your existing embedded calculators keep working — nothing
is removed. The editor changes: add new calculators with the new
SpreadsheetConverter Calculator block or the [ssc_calc] shortcode. A one-time
admin notice explains this after updating.

= 12.0.0 =
Major rewrite. The old upload-and-iframe flow is replaced by a Gutenberg
block that embeds the calculator inline (no iframe). After updating, re-add
your calculator with the new SpreadsheetConverter Calculator block or the
[ssc_calc] shortcode. Old pages stay as they are until you re-embed.
