=== AltiusForms ===
Contributors: altiusgroup
Tags: form, collaborative, survey, form builder, api
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Forms that several people fill in together, live. Every form is also an API. Show them on WordPress with one block.

== Description ==

**AltiusForms** is a form builder made in Switzerland. Each customer has their own instance (https://your-name.altiusforms.com) and a mobile app for iOS and Android. This free plugin connects your WordPress site to your instance, so your forms appear in your pages with one block.

= What makes AltiusForms different =

* **Filled in together, live.** Several people open the same form and fill it in at the same time: each answer appears for everyone as it is typed, with who is editing what. Inspections, meetings, site reports, registrations made as a team.
* **Every form is an API.** When you publish a form, it gets its own REST endpoint: your software reads, filters, creates and updates answers like with any web service, with the same rights as in the application, plus a webhook on each answer.
* **A mobile app.** The same forms on phones and tablets, with photos, signatures, GPS and offline work.
* **Easy to embed.** Inline in the page, in a frame, behind a button, as a live session or as a table of results.

= What the plugin adds to WordPress =

* The **AltiusForms form** block: pick a form from your instance and choose how it appears:
  * **Inline form**: drawn in your page with your theme's fonts, answers and files sent directly to your instance;
  * **Frame that adjusts its height**: the form's page, with the look chosen in your instance;
  * **Button that opens a popup**: with your button text;
  * **Filled in together, live**: a collaborative session joined from your page;
  * **Results table**: the answers you chose to share publicly, with pages and CSV/Excel downloads.
* A live preview in the editor, and a warning when a form does not allow your site yet.
* The `[altiusforms]` shortcode and a classic widget for older themes.
* Settings › AltiusForms: instance address, API key, appearance (light, dark or following the visitor's system), and a « Test the connection » button.
* In French, German, Italian and English.

= Privacy =

The plugin sets no cookie and adds no tracking. The instance's script is only loaded on pages that contain a form. The API key stays on your server: it is never sent to visitors' browsers. See « External services » below.

= Français =

**AltiusForms** est un générateur de formulaires suisse. Chaque client a sa propre instance (https://votre-nom.altiusforms.com) et une application mobile iOS et Android. Cette extension gratuite relie votre site WordPress à votre instance.

* **Rempli à plusieurs, en direct** : plusieurs personnes remplissent le même formulaire en même temps et voient les réponses des autres au fur et à mesure.
* **Chaque formulaire est une API** : à la publication, le formulaire reçoit son point d'accès REST (lire, filtrer, créer, modifier), avec les mêmes droits que dans l'application, et un webhook à chaque réponse.
* **Une application mobile** : les mêmes formulaires sur téléphone et tablette, avec photos, signatures, GPS et travail hors ligne.
* **Facile à intégrer** : le bloc « Formulaire AltiusForms » affiche un formulaire dans la page, dans un cadre, derrière un bouton, en session à plusieurs ou en tableau de résultats, avec un aperçu dans l'éditeur.

L'extension ne pose aucun cookie et n'ajoute aucun suivi. La clé d'API reste sur votre serveur.

== Installation ==

1. Install and activate the plugin.
2. Go to **Settings › AltiusForms** and enter the address of your instance, for example `https://your-name.altiusforms.com`.
3. Optional: in your instance, open **API & Integration › Integration keys**, create a key for this site and paste it as the API key.
4. Click **Test the connection**.
5. In a page, add the **AltiusForms form** block and choose a form.

To show forms in a frame or a popup, each form must allow your site: in the form's settings, **Embedding on other sites**, keep **On any site** or add your site's address (shown on the settings page). The inline form needs nothing.

== Frequently Asked Questions ==

= Do I need an AltiusForms account? =

Yes. The plugin shows forms from your own AltiusForms instance. You can start with the free plan at https://altiusforms.com/.

= Is the API key required? =

No. Without a key, every public or code-protected form can already be embedded. With an integration key, the block lists your forms with their embedding settings, finds results tables, offers the open live sessions and can allow your site on a form in one click.

= Which rights does the API key have? =

Use an integration key: an administrator creates it in **API & Integration › Integration keys**. « Read only » lists the published forms, how they may be embedded and their public results. « Manage the integration » also lets this site add its own address to a form's allowed sites and list live sessions. The key can be revoked at any time, and the instance shows when it was last used. A personal API token still works, with all the rights of its account.

= The editor says that the form does not allow this site =

The form only allows some sites to show it in a frame. With an integration key that may manage the integration, click **Allow this site** in the block. Otherwise, in the form's settings, under **Embedding on other sites**, add the address shown in Settings › AltiusForms, or use the inline form, which works on every site.

= How does filling in together work on my site? =

In your instance, open **API & Integration › Embed a collaborative session** and tick **Allow collaborative embed for this form** (with a « Manage the integration » key, the block then adds your site's address in one click). Start a session, then choose it in the block, or type its six-character code. Visitors enter their name and fill in the form together.

= Does it work with my theme's dark mode? =

Choose **Follow the visitor's system** under Appearance if your theme has a dark mode, or force light or dark. Forms in a frame or a popup follow the same choice.

= Can I use a shortcode? =

Yes: `[altiusforms form="FORM-TOKEN" mode="inline"]`. Modes: `inline`, `frame`, `popup` (with `label="…"`), `collab` (with `code="K7Q4P2"`) and `results` (with `results="RESULTS-TOKEN"`, `page_size="25"`, `export="false"`).

= What is removed when I delete the plugin? =

Its settings, the API key, cached form lists and widget settings.

== External services ==

This plugin connects to **your own AltiusForms instance**, the address you enter in Settings › AltiusForms (for example `https://your-name.altiusforms.com`). The instance is operated by Altius Group SNC, Switzerland, for its customer. Nothing is sent before you enter that address.

From your WordPress server (never with visitors' data):

* when you test the connection, edit a page with the block or open the widget settings: the list of public forms (`/api/v1/public/forms/`), the instance configuration (`/api/v1/public/config/`), with a key the forms and their embedding settings (`/api/v1/integration/forms/`), what the key may do (`/api/v1/integration/`) and the open live sessions of a form (`…/sessions/`), the account that owns a personal token (`/api/v1/users/me/`), whether a form shares its results (`/api/v1/forms/{id}/`), a few rows of a shared results table for the preview, and the form's public page to read which sites may show it. When an administrator clicks « Allow this site », the site's address (for example `https://www.example.ch`) is sent to `/api/v1/integration/forms/{token}/origins/`. The API key is sent in the `Authorization` header of the calls that need it. Each call also carries the plugin and WordPress versions in its `User-Agent` header. No data about your visitors, users or content is sent.

In the block editor, in the browser of the person editing:

* the preview of a form in a frame loads the form's public page from the instance.

From your visitors' browsers, only on pages that contain a form:

* the instance's script (`/static/sdk/v1/altiusforms.js`, or `/static/sdk/altiusforms.js` on older instances) is loaded, and the form, the live session or the results are loaded from the instance. When a visitor sends a form, their answers and files go to the instance. When a visitor joins a live session, the name they give is sent to the instance, and a session token is kept in their browser's local storage for that instance (no cookie). If your instance enables bot protection, the script also loads Cloudflare Turnstile from challenges.cloudflare.com.

AltiusForms terms of use: https://altiusforms.com/en/legal/conditions-utilisation/
AltiusForms privacy policy: https://altiusforms.com/en/legal/politique-confidentialite/
Cloudflare Turnstile privacy policy: https://www.cloudflare.com/turnstile-privacy-policy/
Cloudflare website terms of use: https://www.cloudflare.com/website-terms/

== Source code ==

The block editor script in `build/` is compiled from the readable sources shipped in `src/`, with `@wordpress/scripts` (see `package.json`): run `npm install` then `npm run build`. The other scripts and styles are not compiled.

== Changelog ==

= 1.0.0 =
* First version: settings with connection test, AltiusForms form block (inline, frame, popup, filled in together, results), shortcode, classic widget, French, German and Italian translations.

== Upgrade Notice ==

= 1.0.0 =
First version.
