=== BPOTech Confirm Step for Contact Form 7 ===
Contributors:      wphuebpo
Tags:              contact form 7, confirm, review, two-step, cf7
Requires at least: 6.0
Tested up to:      7.0
Requires PHP:      8.0
Stable tag:        1.1.4
License:           GPL-2.0-or-later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Adds a confirmation step so visitors can review Contact Form 7 input before the message is sent.

== Description ==

**Confirm Step for Contact Form 7** adds a review step between filling in a form and sending it. Visitors see a confirmation screen with their answers (using the same mail-tags as your emails), can go back to edit, or submit for real.

All options are managed **inside each Contact Form 7 form** (a **Confirm** tab in the form editor). There is no separate settings page in WordPress admin.

**Requires [Contact Form 7](https://wordpress.org/plugins/contact-form-7/) to be installed and active.** If CF7 is missing, this plugin deactivates itself and shows an admin notice.

= How it works (front end) =

1. The visitor completes the **input step** (your normal Form tab template) and clicks the **Confirm** button (`[confirm]`).
2. Contact Form 7 validates the input. The plugin **does not send mail yet**; the response switches to the **confirm step**.
3. The confirm template (Confirm tab) is shown with values filled in via mail-tags.
4. The visitor clicks **Submit** (`[submit]`) to send, or **Back** (`[back]`) to return to the input step without reloading the page.
5. After a successful send, the form returns to the input step.

= Features =

* **Per-form enable** — Checkbox “Enable confirm step” on the Confirm tab; disabled forms behave like plain CF7 forms.
* **Confirm tab** — Dedicated template textarea, mail-tag helper, and tag generator buttons for Submit and Back.
* **Form tags** — `[confirm]` (step 1, Form tab generator), `[submit]` (CF7 core, insert from Confirm tab), `[back]` (step 2, Confirm tab generator). Labels and classes follow CF7 conventions.
* **Step status markers** — Add `cf7cfstep-status-class` or `cf7cfstep-status-class-{formid}` to any page element; the plugin toggles `cf7cfstep-status-input` / `cf7cfstep-status-confirm` for theme CSS (progress text, sidebars, etc.).
* **Confirm Settings** — Optional scroll target **class** and **offset (px)** when entering the confirm step only (positive offset scrolls further down, negative scrolls further up; leave class empty to disable).
* **Editor UX** — Confirm tab panel hides when disabled; admin styles and collapsible help/settings boxes on the Confirm tab.
* **Legacy-compatible storage** — Confirm body and options use the same meta keys as the earlier function-based plugin where applicable.

= For developers =

* PHP **8.0+**, namespaced class architecture (`CF7ConfirmStep\`), no Composer dependency.
* Front-end script is vanilla JavaScript (no jQuery on the public site).
* Form-specific scroll options are passed via `window.cf7csFormSettings[formId]` when a scroll class is configured.

= Hooks & Filters =

**`cf7cs_custom_confirm_tags`** *(filter)* — Register custom tags for the confirm template. Each tag appears as a clickable mail-tag in the Confirm tab editor and is replaced by its `content` on the front end.

Parameters:

* `$tags` *(array)* — Array of tag definitions. Each item has keys: `tag` (string, tag name without brackets), `content` (string, HTML replacement on front end).
* `$contact_form` *(WPCF7_ContactForm)* — The current contact form instance.

Example:

`add_filter( 'cf7cs_custom_confirm_tags', function ( $tags, $form ) {`
`    $tags[] = array(`
`        'tag'     => 'privacy-notice',`
`        'content' => '<p class="privacy">Your data is safe.</p>',`
`    );`
`    return $tags;`
`}, 10, 2 );`

In the Confirm tab, `[privacy-notice]` appears alongside other mail-tags. Click it to insert into the template.

---

**`cf7cs_before_confirm_step`** *(filter)* — Add HTML before the confirm step content on the front end.

Parameters:

* `$html` *(string)* — HTML to prepend (default empty).
* `$contact_form` *(WPCF7_ContactForm)* — The current contact form.

Example:

`add_filter( 'cf7cs_before_confirm_step', function ( $html, $form ) {`
`    return '<div class="confirm-header">Please review your data</div>';`
`}, 10, 2 );`

---

**`cf7cs_after_confirm_step`** *(filter)* — Add HTML after the confirm step content on the front end.

Parameters:

* `$html` *(string)* — HTML to append (default empty).
* `$contact_form` *(WPCF7_ContactForm)* — The current contact form.

Example:

`add_filter( 'cf7cs_after_confirm_step', function ( $html, $form ) {`
`    return '<p class="confirm-footer">Click Submit to send or Back to edit.</p>';`
`}, 10, 2 );`

---

**`cf7cs_confirm_template`** *(filter)* — Filter the confirm template HTML after all built-in processing (mail-tag placeholders, control tags, and custom tags have been replaced).

Parameters:

* `$template` *(string)* — Processed confirm template HTML.
* `$contact_form` *(WPCF7_ContactForm)* — The current contact form.

---

**`cf7cs_confirm_tag_buttons`** *(action)* — Fires after the default and custom tag generator buttons on the Confirm tab. Use this to output fully custom button HTML.

== Installation ==

1. Install and activate **Contact Form 7**.
2. Upload the `bpotech-confirm-step-for-contact-form-7` folder to `/wp-content/plugins/` (or install from the WordPress plugin directory when available).
3. Activate **Confirm Step for Contact Form 7** under **Plugins**.
4. Edit a contact form, open the **Confirm** tab, enable the confirm step, and configure the template and settings.
5. On the **Form** tab, add a `[confirm]` button (use the **Confirm Button** tag generator). Save the form.

== Usage ==

1. **Confirm tab** — Enable confirm step, write the review template with mail-tags, add `[submit]` and `[back]`, save.
2. **Form tab** — Add your fields and a `[confirm]` button (tag generator: **Confirm Button**). Use `[submit]` only on the confirm step if you want a single send action.
3. **Confirm Settings** (optional) — Scroll target class + offset when entering the confirm step; leave class empty to skip scrolling.
4. **Step status markers** (optional) — Add `cf7cfstep-status-class` or `cf7cfstep-status-class-{formid}` on page elements; style with `cf7cfstep-status-input` / `cf7cfstep-status-confirm`.

== Frequently Asked Questions ==

= Does this work without Contact Form 7? =

No. CF7 must be active. Otherwise the plugin will not run (and will deactivate on load if CF7 was removed).

= Can I use it on only some forms? =

Yes. Enable **Enable confirm step** only on the forms that need a review step.

= When is email actually sent? =

Only when the visitor submits from the **confirm step** with `[submit]` (step 2). The first `[confirm]` click only validates and shows the review screen.

= What happens if I disable “Enable confirm step”? =

The form submits in one step like normal CF7.

= Do I need to wrap fields manually? =

No. The input wrapper is added when the form is rendered. The confirm wrapper is built from the Confirm tab template automatically.

= Can I have multiple CF7 forms on one page? =

Yes. Each form has its own step state. Global status markers (`cf7cfstep-status-class`) reflect the last confirm-enabled form that changed step; use `cf7cfstep-status-class-{formid}` to scope styling per form.

= Does uninstalling remove form data? =

Uninstall does not delete confirm templates or per-form meta stored on contact forms. Remove or disable confirm in each form before uninstall if you want a clean editor state.

== Screenshots ==

1. Confirm tab with enable checkbox, confirm template, and tag buttons.
2. Confirm Settings metabox (scroll class and offset).
3. Step status markers help on the Confirm tab.

== Changelog ==

= 1.1.4 =
* Developer hooks: `cf7cs_custom_confirm_tags` filter for registering custom tags (tag/label/content) with auto admin buttons.
* Developer hooks: `cf7cs_before_confirm_step` and `cf7cs_after_confirm_step` filters for injecting HTML around the confirm step.
* Developer hooks: `cf7cs_confirm_template` filter and `cf7cs_confirm_tag_buttons` action for advanced customisation.

= 1.1.3 =
* Hot fix.

= 1.1.1 =
* i18n: use plugin text domain consistently in the CF7 editor.
* Front-end: scope mail error response handling to the submitting form only.
* Readme: PHP 8.0, WordPress 7.0 tested, tag limit compliance.

= 1.1.0 =
* First release on WordPress.org.
* Two-step confirm flow for Contact Form 7 (`[confirm]`, review template, `[submit]` / `[back]`).
* Confirm tab settings: per-form enable, step status markers, optional scroll on confirm step.

== Upgrade Notice ==

= 1.1.4 =
New developer hooks for custom confirm tags and template customisation. Requires Contact Form 7.

= 1.1.3 =
Hot fix. Requires Contact Form 7.

= 1.1.1 =
Maintenance release. Requires Contact Form 7.

= 1.1.0 =
First release on WordPress.org. Requires Contact Form 7.
