README

A modular, accessible, and extensible multi-step frontend form system for WordPress, built with TypeScript, PHP, and SCSS. Supports custom field types, validation, REST API integration, and advanced admin configuration.

Features

Multi-step forms: Create forms with any number of steps, each with its own fields, validation, and UI.
Custom field types: Supports text, email, date, checkbox, select, WYSIWYG, repeater, and more.
Progress bar: Visual step progress indicator with validation feedback.
REST API integration: Submit, update, and read form data via secure endpoints.
Admin configuration: Use ACF to configure steps, fields, handlers, and logic.
Validation: Client and server-side validation, including custom error messages.
Accessibility: ARIA attributes, keyboard navigation, and semantic HTML.
Status overlays: User feedback for loading, errors, and success.
Security: Nonces, token validation, and output escaping.
Extensible: Add custom field types, handlers, and hooks.

Usage

1. Add a Form Module

In WordPress admin, add a new "Frontend Form" module.
Configure steps and fields using the ACF field group "Configure Multistep Form".
Each step can have a title, description, and any number of fields.
Supported field types: text, email, date, checkbox, select, WYSIWYG, repeater, etc.

2. Configure Submission Handlers

Choose where submissions are sent: Database, E-Mail, Webhook.
Configure handler settings in the module admin (e.g., webhook URL, email recipient).

3. Display the Form

Use the module in any Modularity-enabled area (template, block, shortcode).
The form will render with animated step transitions, progress bar, and validation.

4. REST API Endpoints

Submit: POST /wp-json/modularity-frontend-form/v1/submit/post
Update: POST /wp-json/modularity-frontend-form/v1/submit/update
Read: GET /wp-json/modularity-frontend-form/v1/read/get
Nonce: GET /wp-json/modularity-frontend-form/v1/nonce/get
All endpoints require valid nonces and tokens for security.

5. Customization

Add new field types by extending the JS/TS field architecture.
Add new handlers by implementing PHP handler interfaces.
Use SCSS variables for theming in sass/_variables.scss.
Override translations in the admin or via language files.

Example: Basic Usage

Add a module:
- Go to "Add Module" → "Frontend Form".
- Configure steps and fields.
Display in template:
- Use Modularity's template system or shortcode to render the form.
Handle submissions:
- Data is stored, emailed, or sent to a webhook as configured.

Developer Guide

JS/TS: All frontend logic is in /source/js/. Use TypeScript interfaces for all APIs.
PHP: Backend logic, REST API, and admin config in /source/php/.
SCSS: Styles in /source/sass/. Use variables for theming.
Tests: Unit tests are next to source files. Run with npm test (JS/TS) or composer test (PHP).
Linting: Use npm run lint for JS/TS.

Accessibility & UX

All UI components are ARIA-compliant and keyboard accessible.
Animations are smooth and non-blocking.
Progress bar and step navigation are visually clear.

Security

All output is escaped in PHP templates.
All user input is validated and sanitized.
Nonces and tokens are required for all REST API requests.

Extending the Plugin

Add a field type: Create a new JS/TS class in /source/js/fields/field/.
Add a handler: Implement a PHP handler in /source/php/DataProcessor/Handlers/.
Add a REST endpoint: Extend /source/php/Api/.

Contribution Guidelines

Fork, branch, and submit pull requests for all changes.
Write clear commit messages.
Review code for style, security, and performance.
Follow the standards in .github/copilot-instructions.md.

License

MIT

For more details, see .github/copilot-instructions.md and the source code. All code, documentation, and contributions must follow workspace guidelines.

helsingborg-stad / modularity-frontend-form

Maintainers

Details