| Name | headless-waf-builder JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | Headless Wagtail Advanced Form Builder - Complete REST API for modern frontend frameworks |
| upload_time | 2025-09-07 22:53:54 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | BSD |
| keywords |
wagtail
django
forms
headless
cms
api
rest
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Headless Wagtail Advanced Form Builder
**A powerful headless-first Wagtail Advanced Form Builder with complete REST API for modern frontend frameworks like React, Vue, Angular, and mobile applications.**
> **🚨 Important**: This is a separate package from the original `wagtail-advanced-form-builder`. Choose `headless-waf-builder` for modern headless/API-first applications, or the original for traditional Wagtail template only usage.
## 🚀 Headless API Features
**Complete REST API with Django Ninja** - Build modern frontend applications with React, Vue, Angular, or any JavaScript framework using our comprehensive headless API.
### API Capabilities
- **📋 Form Retrieval API** - Get form schemas with complete field definitions and validation rules
- **📤 Form Submission API** - Submit forms with automatic validation and processing
- **🔒 Security Built-in** - CSRF protection, reCAPTCHA v2/v3 integration, and rate limiting
- **📧 Email Integration** - Automatic email sending with Celery background processing
- **📖 Auto-Generated Documentation** - Interactive API docs at `/docs` endpoint
- **🎯 Type-Safe Schemas** - Complete Pydantic schemas for all form fields and responses
### Quick API Example
```javascript
// Get form schema
const response = await fetch('/api/form_by_path/contact-form/');
const formSchema = await response.json();
// Submit form data
await fetch('/api/form_by_path/', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-CSRFToken': csrfToken
},
body: JSON.stringify({
path: 'contact-form',
form_fields: { name: 'John', email: 'john@example.com' },
recaptcha_token: recaptchaToken // optional
})
});
```
---
# Versions
This package currently only supports Wagtail 6 above.
### Version 1.0.0
**Brand new headless API capabilities** for use with Wagtail version 6.X.X
- **🎯 Complete Headless API** with Django Ninja for modern frontend frameworks
- **📝 Full Schema Models** for all form fields and pages with Pydantic validation
- **🔌 RESTful APIs** for form retrieval, submission, and validation
- **🔒 Security Features** including optional django-recaptcha and CSRF protection
- **⚡ Background Processing** with Celery for email sending and heavy tasks
- **📖 Auto-Generated API Documentation** with interactive OpenAPI interface
- **🎛️ Enhanced Conditional Logic** with improved rule engine
---
# About
Headless WAF Builder is a comprehensive headless-first extension that enhances Wagtail's built-in Form Builder with:
- **🎛️ Advanced Conditional Logic** - Show/hide fields based on user input with complex rule sets
- **🌐 Headless API Support** - Complete REST API for frontend frameworks and mobile apps
- **📱 Modern Field Types** - Extended field library including phone, date, and custom validation
- **🔧 Developer-Friendly** - Easy integration, comprehensive documentation, and extensible architecture
## 🤔 Why Choose Headless WAF Builder?
| Feature | Headless WAF Builder | Original wagtail-advanced-form-builder |
|---------|---------------------|----------------------------------------|
| **🌐 REST API** | ✅ Complete Django Ninja API | ❌ No API |
| **📱 Frontend Frameworks** | ✅ React, Vue, Angular, Mobile | ❌ Wagtail templates only |
| **🔒 Modern Security** | ✅ CSRF, reCAPTCHA, Rate limiting | ⚠️ Basic |
| **📖 API Documentation** | ✅ Auto-generated OpenAPI docs | ❌ No API docs |
| **⚡ Background Processing** | ✅ Celery integration | ❌ Synchronous only |
| **🎯 Type Safety** | ✅ Pydantic schemas | ❌ No schemas |
| **📊 Headless CMS Ready** | ✅ Built for decoupled architecture | ❌ Traditional Wagtail CMS + Django Templates |
**Choose `headless-waf-builder` if you're building:**
- 🚀 Modern SPA applications (React, Vue, Angular)
- 📱 Mobile apps that need form APIs
- 🌐 Headless/decoupled Wagtail sites
- 🔗 Multi-channel content delivery
- 🎯 API-first applications
---
# 🛠️ Installation & Setup
## Basic Installation
### Production Installation
```bash
pip install headless-waf-builder
```
Add to your `INSTALLED_APPS`:
```python
INSTALLED_APPS = [
# ... other apps
'headless_waf_builder',
# ...
]
```
> **✨ Modern Architecture**: The new `headless_waf_builder` package follows modern Python packaging standards with `src/` layout and `pyproject.toml` configuration.
## Headless API Setup
```python
# urls.py
from headless_waf_builder.api.router import headless_waf_builder_api
urlpatterns = [
# ... your existing URLs
path("api/", headless_waf_builder_api.urls),
]
```
Run migrations:
```bash
./manage.py migrate
```
🎉 After the migration succeed! Your API will be available at `/api/` with documentation at `/api/docs`
---
# 📋 Comprehensive Field Support
### Core Field Types
- **📝 Text Fields** - Single line, multi-line with validation
- **📧 Email Field** - Built-in email validation
- **🔢 Number Field** - Numeric input with min/max validation
- **📞 Phone Field** - International phone number support
- **📅 Simple Date Field** - Date picker with age validation
- **🔗 URL Field** - URL validation and formatting
- **🙈 Hidden Field** - For tracking and default values
### Advanced Input Types
- **📋 Dropdown/Select** - Single and multi-select options
- **✅ Checkbox Fields** - Single checkbox and checkbox groups
- **🔘 Radio Buttons** - Single choice with custom layouts
- **🎨 HTML Field** - Rich content and custom markup
- **📱 Responsive Layouts** - Side-by-side and mobile-optimized displays
### 🎯 Conditional Logic Engine
Create dynamic forms with sophisticated show/hide rules:
- **Comparison Operators**: `equals`, `not equals`, `greater than`, `less than`, `contains`
- **String Matching**: `starts with`, `ends with`, `is blank`, `is not blank`
- **Multiple Conditions**: Combine rules with AND/OR logic
- **Cross-Field Dependencies**: Field visibility based on other field values
- **Real-time Updates**: Instant field visibility changes as users interact
---
# 🌐 Headless API Reference
## Endpoints
### `GET /api/form_by_path/{path}`
Retrieve form schema and configuration
```json
{
"id": 1,
"title": "Contact Form",
"fields": [
{
"id": 1,
"type": "singleline",
"name": "full_name",
"label": "Full Name",
"required": true,
"rules": {
"action": "show",
"conditions": [...]
}
}
],
"use_google_recaptcha": true,
"google_recaptcha_public_key": "..."
}
```
### `POST /api/form_by_path/`
Submit form data with validation
```json
{
"path": "contact-form",
"form_fields": {
"full_name": "John Doe",
"email": "john@example.com"
},
"recaptcha_token": "..."
}
```
### `GET /api/csrf/`
Get CSRF token for secure submissions
```json
{
"csrftoken": "abc123..."
}
```
---
# 📚 Documentation
The complete documentation is available at [here](https://github.com/octavenz/headless-wagtail-advanced-form-builder/blob/master/docs/index.md)
---
# 🆘 Getting Help
- **🐛 Bug Reports**: [Issue Tracker](https://github.com/octavenz/headless-wagtail-advanced-form-builder/issues)
- **💡 Feature Requests**: [GitHub Discussions](https://github.com/octavenz/headless-wagtail-advanced-form-builder/discussions)
# 👥 Authors
* Richard Blake, Dan Brosnan & Vincent Tran ([Octave](https://octave.nz))
# 📄 License
This project is licensed under the BSD License - see the [LICENSE file](./LICENCE) for details
Raw data
{
"_id": null,
"home_page": null,
"name": "headless-waf-builder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "\"Richard Blake (Octave)\" <richard.blake@octave.nz>, \"Dan Brosnan (Octave)\" <dan.brosnan@octave.nz>, \"Vincent Tran (Octave)\" <vincent@octave.nz>",
"keywords": "wagtail, django, forms, headless, cms, api, rest",
"author": null,
"author_email": "\"Richard Blake (Octave)\" <richard.blake@octave.nz>, \"Dan Brosnan (Octave)\" <dan.brosnan@octave.nz>, \"Vincent Tran (Octave)\" <vincent@octave.nz>",
"download_url": "https://files.pythonhosted.org/packages/8a/e4/ad7b3bfc39bd13572780db8b75902b894e7a49ddfc594cda8aa5d2616407/headless_waf_builder-1.0.0.tar.gz",
"platform": null,
"description": "# Headless Wagtail Advanced Form Builder\n\n\n\n\n**A powerful headless-first Wagtail Advanced Form Builder with complete REST API for modern frontend frameworks like React, Vue, Angular, and mobile applications.**\n\n> **\ud83d\udea8 Important**: This is a separate package from the original `wagtail-advanced-form-builder`. Choose `headless-waf-builder` for modern headless/API-first applications, or the original for traditional Wagtail template only usage.\n\n## \ud83d\ude80 Headless API Features\n\n**Complete REST API with Django Ninja** - Build modern frontend applications with React, Vue, Angular, or any JavaScript framework using our comprehensive headless API.\n\n### API Capabilities\n- **\ud83d\udccb Form Retrieval API** - Get form schemas with complete field definitions and validation rules\n- **\ud83d\udce4 Form Submission API** - Submit forms with automatic validation and processing\n- **\ud83d\udd12 Security Built-in** - CSRF protection, reCAPTCHA v2/v3 integration, and rate limiting\n- **\ud83d\udce7 Email Integration** - Automatic email sending with Celery background processing\n- **\ud83d\udcd6 Auto-Generated Documentation** - Interactive API docs at `/docs` endpoint\n- **\ud83c\udfaf Type-Safe Schemas** - Complete Pydantic schemas for all form fields and responses\n\n### Quick API Example\n```javascript\n// Get form schema\nconst response = await fetch('/api/form_by_path/contact-form/');\nconst formSchema = await response.json();\n\n// Submit form data\nawait fetch('/api/form_by_path/', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'X-CSRFToken': csrfToken\n },\n body: JSON.stringify({\n path: 'contact-form',\n form_fields: { name: 'John', email: 'john@example.com' },\n recaptcha_token: recaptchaToken // optional\n })\n});\n```\n\n---\n\n# Versions\n\nThis package currently only supports Wagtail 6 above.\n\n### Version 1.0.0\n\n**Brand new headless API capabilities** for use with Wagtail version 6.X.X\n- **\ud83c\udfaf Complete Headless API** with Django Ninja for modern frontend frameworks\n- **\ud83d\udcdd Full Schema Models** for all form fields and pages with Pydantic validation\n- **\ud83d\udd0c RESTful APIs** for form retrieval, submission, and validation\n- **\ud83d\udd12 Security Features** including optional django-recaptcha and CSRF protection\n- **\u26a1 Background Processing** with Celery for email sending and heavy tasks\n- **\ud83d\udcd6 Auto-Generated API Documentation** with interactive OpenAPI interface\n- **\ud83c\udf9b\ufe0f Enhanced Conditional Logic** with improved rule engine\n\n\n---\n\n# About\n\nHeadless WAF Builder is a comprehensive headless-first extension that enhances Wagtail's built-in Form Builder with:\n\n- **\ud83c\udf9b\ufe0f Advanced Conditional Logic** - Show/hide fields based on user input with complex rule sets\n- **\ud83c\udf10 Headless API Support** - Complete REST API for frontend frameworks and mobile apps\n- **\ud83d\udcf1 Modern Field Types** - Extended field library including phone, date, and custom validation\n- **\ud83d\udd27 Developer-Friendly** - Easy integration, comprehensive documentation, and extensible architecture\n\n## \ud83e\udd14 Why Choose Headless WAF Builder?\n\n| Feature | Headless WAF Builder | Original wagtail-advanced-form-builder |\n|---------|---------------------|----------------------------------------|\n| **\ud83c\udf10 REST API** | \u2705 Complete Django Ninja API | \u274c No API |\n| **\ud83d\udcf1 Frontend Frameworks** | \u2705 React, Vue, Angular, Mobile | \u274c Wagtail templates only |\n| **\ud83d\udd12 Modern Security** | \u2705 CSRF, reCAPTCHA, Rate limiting | \u26a0\ufe0f Basic |\n| **\ud83d\udcd6 API Documentation** | \u2705 Auto-generated OpenAPI docs | \u274c No API docs |\n| **\u26a1 Background Processing** | \u2705 Celery integration | \u274c Synchronous only |\n| **\ud83c\udfaf Type Safety** | \u2705 Pydantic schemas | \u274c No schemas |\n| **\ud83d\udcca Headless CMS Ready** | \u2705 Built for decoupled architecture | \u274c Traditional Wagtail CMS + Django Templates |\n\n**Choose `headless-waf-builder` if you're building:**\n- \ud83d\ude80 Modern SPA applications (React, Vue, Angular)\n- \ud83d\udcf1 Mobile apps that need form APIs\n- \ud83c\udf10 Headless/decoupled Wagtail sites\n- \ud83d\udd17 Multi-channel content delivery\n- \ud83c\udfaf API-first applications\n\n---\n\n# \ud83d\udee0\ufe0f Installation & Setup\n\n## Basic Installation\n\n### Production Installation\n```bash\npip install headless-waf-builder\n```\n\n\nAdd to your `INSTALLED_APPS`:\n```python\nINSTALLED_APPS = [\n # ... other apps\n 'headless_waf_builder',\n # ... \n]\n```\n\n> **\u2728 Modern Architecture**: The new `headless_waf_builder` package follows modern Python packaging standards with `src/` layout and `pyproject.toml` configuration.\n\n## Headless API Setup\n```python\n# urls.py\nfrom headless_waf_builder.api.router import headless_waf_builder_api\n\nurlpatterns = [\n # ... your existing URLs\n path(\"api/\", headless_waf_builder_api.urls),\n]\n```\n\nRun migrations:\n```bash\n./manage.py migrate\n```\n\n\ud83c\udf89 After the migration succeed! Your API will be available at `/api/` with documentation at `/api/docs`\n\n---\n\n# \ud83d\udccb Comprehensive Field Support\n\n### Core Field Types\n- **\ud83d\udcdd Text Fields** - Single line, multi-line with validation\n- **\ud83d\udce7 Email Field** - Built-in email validation \n- **\ud83d\udd22 Number Field** - Numeric input with min/max validation\n- **\ud83d\udcde Phone Field** - International phone number support\n- **\ud83d\udcc5 Simple Date Field** - Date picker with age validation\n- **\ud83d\udd17 URL Field** - URL validation and formatting\n- **\ud83d\ude48 Hidden Field** - For tracking and default values\n\n### Advanced Input Types \n- **\ud83d\udccb Dropdown/Select** - Single and multi-select options\n- **\u2705 Checkbox Fields** - Single checkbox and checkbox groups\n- **\ud83d\udd18 Radio Buttons** - Single choice with custom layouts\n- **\ud83c\udfa8 HTML Field** - Rich content and custom markup\n- **\ud83d\udcf1 Responsive Layouts** - Side-by-side and mobile-optimized displays\n\n### \ud83c\udfaf Conditional Logic Engine\nCreate dynamic forms with sophisticated show/hide rules:\n\n- **Comparison Operators**: `equals`, `not equals`, `greater than`, `less than`, `contains`\n- **String Matching**: `starts with`, `ends with`, `is blank`, `is not blank`\n- **Multiple Conditions**: Combine rules with AND/OR logic\n- **Cross-Field Dependencies**: Field visibility based on other field values\n- **Real-time Updates**: Instant field visibility changes as users interact\n\n---\n\n# \ud83c\udf10 Headless API Reference\n\n## Endpoints\n\n### `GET /api/form_by_path/{path}`\nRetrieve form schema and configuration\n```json\n{\n \"id\": 1,\n \"title\": \"Contact Form\",\n \"fields\": [\n {\n \"id\": 1,\n \"type\": \"singleline\", \n \"name\": \"full_name\",\n \"label\": \"Full Name\",\n \"required\": true,\n \"rules\": {\n \"action\": \"show\",\n \"conditions\": [...]\n }\n }\n ],\n \"use_google_recaptcha\": true,\n \"google_recaptcha_public_key\": \"...\"\n}\n```\n\n### `POST /api/form_by_path/`\nSubmit form data with validation\n```json\n{\n \"path\": \"contact-form\",\n \"form_fields\": {\n \"full_name\": \"John Doe\",\n \"email\": \"john@example.com\"\n },\n \"recaptcha_token\": \"...\"\n}\n```\n\n### `GET /api/csrf/`\nGet CSRF token for secure submissions\n```json\n{\n \"csrftoken\": \"abc123...\"\n}\n```\n\n---\n\n# \ud83d\udcda Documentation\n\nThe complete documentation is available at [here](https://github.com/octavenz/headless-wagtail-advanced-form-builder/blob/master/docs/index.md)\n\n---\n\n# \ud83c\udd98 Getting Help\n\n- **\ud83d\udc1b Bug Reports**: [Issue Tracker](https://github.com/octavenz/headless-wagtail-advanced-form-builder/issues)\n- **\ud83d\udca1 Feature Requests**: [GitHub Discussions](https://github.com/octavenz/headless-wagtail-advanced-form-builder/discussions)\n\n# \ud83d\udc65 Authors\n\n* Richard Blake, Dan Brosnan & Vincent Tran ([Octave](https://octave.nz))\n\n# \ud83d\udcc4 License\n\nThis project is licensed under the BSD License - see the [LICENSE file](./LICENCE) for details\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Headless Wagtail Advanced Form Builder - Complete REST API for modern frontend frameworks",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/octavenz/headless-waf-builder/issues",
"Changelog": "https://github.com/octavenz/headless-waf-builder/blob/main/CHANGELOG.md",
"Documentation": "https://octavenz.github.io/headless-waf-builder/",
"Homepage": "https://github.com/octavenz/headless-waf-builder",
"Repository": "https://github.com/octavenz/headless-waf-builder"
},
"split_keywords": [
"wagtail",
" django",
" forms",
" headless",
" cms",
" api",
" rest"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d7090df1b269f820db62cfab46d70a17371decce5ef7a176e8c94161c24a363b",
"md5": "c37c040c1b5f3dabed05bf647f9e2ba0",
"sha256": "5a2759ea3a7ab6748674809cfe9134f16b7598562a5312651bf0fd0f1e372b53"
},
"downloads": -1,
"filename": "headless_waf_builder-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c37c040c1b5f3dabed05bf647f9e2ba0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 56391,
"upload_time": "2025-09-07T22:53:52",
"upload_time_iso_8601": "2025-09-07T22:53:52.994189Z",
"url": "https://files.pythonhosted.org/packages/d7/09/0df1b269f820db62cfab46d70a17371decce5ef7a176e8c94161c24a363b/headless_waf_builder-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8ae4ad7b3bfc39bd13572780db8b75902b894e7a49ddfc594cda8aa5d2616407",
"md5": "8934c6ce2ef3aa92a50e77a92d13b24a",
"sha256": "eb39dd387c0ef8ee63444173ceb2d8f31979b05cb612bb295fd6dd9bd0affac6"
},
"downloads": -1,
"filename": "headless_waf_builder-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8934c6ce2ef3aa92a50e77a92d13b24a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 223941,
"upload_time": "2025-09-07T22:53:54",
"upload_time_iso_8601": "2025-09-07T22:53:54.172241Z",
"url": "https://files.pythonhosted.org/packages/8a/e4/ad7b3bfc39bd13572780db8b75902b894e7a49ddfc594cda8aa5d2616407/headless_waf_builder-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 22:53:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "octavenz",
"github_project": "headless-waf-builder",
"github_not_found": true,
"lcname": "headless-waf-builder"
}
