=== Qowwa Forms for HubSpot === Contributors: qowwa Tags: hubspot, forms, crm, contact form, lead generation Requires at least: 5.8 Tested up to: 7.0 Requires PHP: 7.4 Stable tag: 1.1.0 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html Embed and customize HubSpot CRM forms on WordPress with full styling control. Works with HubSpot free tier. == Description == Qowwa Forms for HubSpot allows you to embed and fully customize HubSpot CRM forms on your WordPress site with complete styling control. Perfect for users on HubSpot's free tier who want to customize form appearance beyond the limitations of embedded iframes. = Key Features = * Full Styling Control - Customize colors, fonts, and layout * Hybrid Connection Mode - Choose between Direct to Contacts or Existing Forms * Gutenberg Block - Easy drag-and-drop form builder * Elementor Widget - Add forms via Elementor page builder * No Coding Required - Visual form builder with live preview * Spam Protection - Built-in honeypot field * Responsive Design - Mobile-friendly forms out of the box * Custom Field Mapping - Map WordPress fields to HubSpot properties == Installation == = Method 1: Manual Installation = 1. Download the plugin files 2. Upload the `qowwa-forms-for-hubspot` folder to `/wp-content/plugins/` 3. Activate the plugin through the 'Plugins' menu in WordPress 4. Go to Settings → Qowwa Forms to configure = Method 2: From WordPress.org = 1. Go to Plugins → Add New 2. Search for "Qowwa Forms for HubSpot" 3. Click "Install Now" and then "Activate" == Setup Guide == = Option 1: Direct to Contacts (Recommended) = This mode creates contacts directly in HubSpot without needing to create forms in HubSpot first. 1. Go to Settings → Qowwa Forms 2. Select "Direct to Contacts" mode 3. Get your HubSpot Access Token (see plugin settings for steps) 4. Paste the token into the "Private App Access Token" field 5. Click "Test Connection" to verify 6. Save Changes = Option 2: Use Existing HubSpot Forms = This mode submits to existing HubSpot forms and triggers form-specific workflows. Enter your Portal ID and Form GUID in the plugin settings. == Frequently Asked Questions == = Does this work with HubSpot's free tier? = Yes! This plugin was specifically designed to work with HubSpot's free tier. = Can I use multiple forms on one page? = Yes, each form block or widget is independent and can have different settings. = Does this support custom HubSpot properties? = Yes, in "Direct to Contacts" mode, use the exact property name from HubSpot in the field name. = What shortcode should I use? = Use `[hscf_form]`. Optional attributes: `form_id`, `form_name`, `button_text`, `success_message`, `redirect_url`, `primary_color`, `button_color`, `success_color`, `error_color` and `fields`. `fields` is a comma-separated list of `name:Label:type:required[:options[:help]]`. Types: `text`, `email`, `tel`, `url`, `number`, `textarea`, `select`, `radio`. Options for dropdowns and radio buttons are separated by `|` (write `value=Label` to send a different internal value). Example: `[hscf_form redirect_url="/thank-you/" fields="firstname:First name:text:yes,email:Work email:email:yes,service:What do you need?:select:yes:Website|Online store|Not sure yet"]` = Can I send visitors to a thank-you page after they submit? = Yes. Set "Redirect after success" in the block or widget, or `redirect_url` in the shortcode, to a page on your site (for example `/thank-you/`). Only addresses on your own site are allowed. = How do I track submissions in Google Tag Manager / Analytics? = The form pushes `hscf_form_start` (first interaction) and `hscf_form_submit` (successful submission) to the `dataLayer`, with `hscf_form_id` and `hscf_form_name`. Create a Custom Event trigger on `hscf_form_submit`. When a redirect is set, the plugin waits for GTM (up to 1.5 seconds) before leaving the page. = Does it work with page caching? = Yes. The security token is refreshed in the background when a visitor starts filling in the form, so cached pages don't cause "session expired" errors. = Can I style the form with my theme? = Yes. All plugin styles have zero specificity, so normal theme CSS wins. You can also set the custom properties `--hscf-primary`, `--hscf-button`, `--hscf-button-text`, `--hscf-border`, `--hscf-field-bg`, `--hscf-error`, `--hscf-success` and `--hscf-radius` on `.hscf-form-wrapper`. Colours picked in the block or widget are only applied when they differ from the defaults. = I use Elementor and my widget disappeared after updating. What happened? = Version 1.0.5 renames the Elementor widget ID to meet WordPress.org prefix rules. Re-add the "Qowwa HubSpot Form" widget from the Elementor panel and configure it again, or restore the widget from a revision if needed. == External services == This plugin is not affiliated with or endorsed by HubSpot, Inc. "HubSpot" is a trademark of HubSpot, Inc. This plugin connects to HubSpot's APIs (hosted at `api.hubapi.com`) to send form submissions and, when you use the settings "Test Connection" feature, to verify your HubSpot credentials. * **What the service is:** HubSpot provides customer relationship management (CRM), marketing, and related services. This plugin uses HubSpot's APIs so visitors can submit your WordPress forms into your HubSpot account (either as CRM contacts or as submissions to a HubSpot form, depending on the mode you choose). * **What data is sent and when:** When a visitor submits a form on your site, the field values they entered (for example name, email, phone, and any other mapped fields) are transmitted to HubSpot. In "Existing HubSpot Forms" mode the submission also includes the address and title of the page the form was on and, if the visitor already has one, the value of HubSpot's `hubspotutk` tracking cookie (set by HubSpot's own tracking code, not by this plugin), so HubSpot can attribute the contact to the right source. If you use "Direct to Contacts" mode, the plugin may also send your HubSpot Private App access token with those API requests (stored in your WordPress database as a site option). If you use "Existing HubSpot Forms" mode, your Portal ID and form identifiers are used to route submissions. When you click "Test Connection" in the plugin settings, the plugin sends a request to HubSpot using the credentials you entered to confirm they work. * **Terms and privacy:** HubSpot's services are provided by HubSpot, Inc. Please review HubSpot's terms of service and privacy policy: https://legal.hubspot.com/terms-of-service and https://legal.hubspot.com/privacy-policy == Changelog == = 1.1.0 = * Fixed: "Existing form" mode submitted to `api.hubapi.com`, which answers 404 for unauthenticated form submissions, so every submission failed. It now uses HubSpot's form submission host, `api.hsforms.com`. * New: Dropdown (`select`), radio button and number fields, with optional help text per field. * New: Redirect after a successful submission (block, widget and `redirect_url` shortcode attribute), e.g. to a thank-you page. * New: `dataLayer` events `hscf_form_start` and `hscf_form_submit` for Google Tag Manager. * New: HubSpot submissions include the visitor's page URL, page title and HubSpot tracking cookie (`hutk`), so contacts keep their original source. * New: Works behind page caches: the security token is refreshed when the visitor starts typing. * New: Forms still submit when JavaScript is unavailable. * Improved: Front-end script no longer needs jQuery and loads deferred. * Improved: Accessible validation: messages next to each field, `aria-invalid`, focus moves to the first problem; status messages are announced to screen readers. * Improved: Autocomplete hints for common fields (name, email, phone, company, website). * Improved: Styles have zero specificity and use CSS custom properties, so themes can restyle forms easily. * Fixed: The block now renders on the front end and in the editor (it was registered too late and printed nothing). * Fixed: Right-to-left pages no longer get a very wide horizontal scroll from the hidden spam-trap field. * Fixed: Field help text meets WCAG AA contrast (it was dimmed with opacity). * Fix: The block editor script could not load (it shipped untranspiled), so the block could not be added. The editor now shows a live preview of the form. * Fix: Forms added with the shortcode or the Elementor widget loaded no script or styles unless a block was also on the page. * Fix: A form field named `website` was treated as spam (the honeypot used the same name). * Fix: HubSpot recorded `admin-ajax.php` as the page the form was submitted from. = 1.0.6 = * Removed legacy `[hubspot_custom_form]` shortcode; only `[hscf_form]` is registered. = 1.0.5 = * Prefixed shortcode: `[hscf_form]` (previously also registered a legacy tag for compatibility). * Elementor widget internal name updated to `hscf_hubspot_form` for WordPress.org naming rules; re-insert the widget on existing Elementor layouts if needed. = 1.0.4 = * Renamed plugin to Qowwa Forms for HubSpot; text domain and slug `qowwa-forms-for-hubspot`. * Documented HubSpot as an external service in this readme. * Registered the Gutenberg block under the new name while keeping the previous block name for existing content. = 1.0.3 = * Version bump for release. = 1.0.2 = * WordPress.org plugin directory compliance (escaping, sanitization, readme) = 1.0.0 - 2025-01-13 = * Initial release * Hybrid connection mode (Direct to Contacts / Existing Forms) * Gutenberg block with visual editor * Elementor widget support * Full color customization * Spam protection with honeypot * Responsive design == Upgrade Notice == = 1.1.0 = Dropdown and radio fields, redirect after submit, GTM events and better HubSpot attribution. Fixes the block editor and shortcode/Elementor assets. If you cache pages, clear the cache after updating. = 1.0.6 = Only `[hscf_form]` is supported. If you still used the old shortcode tag, replace it with `[hscf_form]` in your content. = 1.0.5 = Shortcode `[hscf_form]` is preferred; Elementor widget was renamed—re-add the widget if your layout shows a missing block. = 1.0.4 = Renamed for WordPress.org guidelines; readme documents external services. Existing blocks continue to work. = 1.0.3 = Version bump for release. = 1.0.2 = WordPress.org compliance updates: output escaping, input sanitization, and readme format.