django-basic-form-builder 0.1.2__py3-none-any.whl

django_basic_form_builder-0.1.2.dist-info/METADATA

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: django-basic-form-builder
+Version: 0.1.2
+Summary: Reusable Django app for building JSON-driven forms via the admin
+Author-email: Göktürk Burak Köse <02macaw.others@icloud.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gokturkbrk/django-basic-form-builder
+Project-URL: Documentation, https://github.com/gokturkbrk/django-basic-form-builder
+Project-URL: Source, https://github.com/gokturkbrk/django-basic-form-builder
+Project-URL: Tracker, https://github.com/gokturkbrk/django-basic-form-builder/issues
+Keywords: django,forms,builder,json,admin,schema
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django<5.2,>=5.1
+Requires-Dist: djangorestframework>=3.15.0
+Requires-Dist: drf-spectacular>=0.29.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-django>=4.8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.11.0; extra == "dev"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2.0; extra == "postgres"
+Provides-Extra: html
+Requires-Dist: nh3>=0.3.2; extra == "html"
+Dynamic: license-file
+
+# django-formbuilder
+
+Reusable Django app that lets admins define JSON-rendered forms directly in the Django admin, then expose them via a read-only API endpoint. Works with Django 5.1+, DRF 3.15+, and the dependency stack listed in `pyproject.toml`.
+
+## Installation
+
+1. Install with [uv](https://github.com/astral-sh/uv) (preferred) or pip:
+
+   ```bash
+   uv pip install django-formbuilder
+   ```
+
+   Optional extras:
+
+   - PostgreSQL support: `uv pip install "django-formbuilder[postgres]"`
+   - HTML sanitization utilities (if you integrate them yourself): `uv pip install "django-formbuilder[html]"`
+
+2. Add `formbuilder` (and `rest_framework` if not already present) to `INSTALLED_APPS`.
+3. Explicitly enable the read-only API endpoint (it is off by default to avoid exposing form data unintentionally):
+
+   ```python
+   FORMBUILDER_API_ENABLED = True
+   ```
+
+4. Include the API URLs in your project routes:
+
+   ```python
+   from django.urls import include, path
+
+   urlpatterns = [
+       path('api/forms/', include('formbuilder.api.urls')),
+   ]
+   ```
+
+5. Run migrations (`python manage.py migrate`).
+
+## Admin Usage
+
+- Create a **Custom Form** entry in admin (name, slug, description, status).
+- Add **Form Fields** using the stacked inline editor; supported types are `text`, `number`, `textarea`, `dropdown`, `radio`, `checkbox`, `rating`, `boolean`, `email`, `date`.
+- For each field:
+  - **Label**: Short technical identifier (e.g., "Email", "Full Name") - used internally and in compact UIs
+  - **Question**: Detailed question or explanation for users (e.g., "What is your email address? We'll use this to send you updates.")
+    - For feedback forms, this is the primary text users see
+    - Can be left blank if the label is self-explanatory
+  - **Slug**: Technical field identifier (auto-generated from label)
+  - Configure shared attributes (required, placeholder, default value, help text)
+- For dropdown, radio, and checkbox fields:
+  - After saving the form, click "Save and continue editing"
+  - Click on a field to edit it individually
+  - Use the "Field options" inline editor at the bottom to add options
+- For text/number/rating fields:
+  - Expand the relevant configuration section (Text/Number/Rating Configuration)
+  - Use the dedicated config fields (min/max length, min/max value, rating scale)
+  - These fields are type-specific and only apply to their respective field types
+  - Or use the advanced JSON config section for power users
+- **Position auto-update**: When you add or remove fields, positions are automatically renumbered (1, 2, 3, etc.)
+- **Visual separation**: Each form field is shown in a separate bordered box for clarity
+- On every save, the app regenerates a JSON snapshot stored on `CustomForm.json_schema`.
+- Use the "Preview JSON" link to inspect the generated schema in a new tab.
+- Running on Python 3.14? A compatibility shim automatically patches Django's template context copy routine.
+
+### Label vs Question - When to Use Which?
+
+**Label** (required):
+
+- Short, concise identifier: "Email", "Phone", "Rating"
+- Used in compact form layouts, tables, and admin interfaces
+- Technical reference for developers
+- Appears in form labels and summaries
+
+**Question** (optional but recommended for feedback forms):
+
+- Full question or detailed explanation: "How satisfied are you with our service?"
+- Primary text shown to users in feedback/survey forms
+- Can include context, examples, or instructions
+- Better user experience for participation forms
+
+**Example:**
+
+```text
+Label: "Service Quality"
+Question: "On a scale of 1-5 stars, how would you rate the quality of service you received today?"
+
+Label: "Email"
+Question: "What email address should we use to send you updates about your inquiry?"
+```
+
+### Quick Start Guide
+
+1. **Create a form in Django admin:**
+   - Navigate to `/admin/formbuilder/customform/add/`
+   - Fill in: Name = "Contact Us", Slug = "contact-us", Status = "published"
+   - Click "Add another Form field" in the inline section:
+     - Label = "Full Name"
+     - Slug = "full_name"
+     - Question = "What is your full name?"
+     - Type = "text"
+     - Required = ✓
+   - Add another field:
+     - Label = "Department"
+     - Slug = "department"
+     - Question = "Which department would you like to contact?"
+     - Type = "dropdown"
+   - Click "Save and continue editing"
+   - Click on the Department field link to edit it
+   - In the "Field options" section at the bottom, add:
+     - Option 1: Value = "sales", Label = "Sales Team", Position = 1
+     - Option 2: Value = "support", Label = "Customer Support", Position = 2
+   - Add a rating field back in the main form:
+     - Label = "Satisfaction"
+     - Question = "How satisfied are you with our service?"
+     - Type = "rating"
+     - Expand "Rating Configuration" section
+     - Set Scale = 5, Style = "stars"
+   - Positions will auto-update as you add/remove fields
+   - Save the form
+
+2. **Fetch the JSON schema via API:**
+
+   ```bash
+   curl http://localhost:8000/api/forms/contact-us/
+   ```
+
+   You'll receive:
+
+   ```json
+   {
+     "form": {
+       "name": "Contact Us",
+       "slug": "contact-us",
+       "status": "published"
+     },
+     "fields": [
+       {
+         "id": "full_name",
+         "type": "text",
+         "label": "Full Name",
+         "question": "What is your full name?",
+         "required": true,
+         "position": 1,
+         ...
+       },
+       {
+         "id": "department",
+         "type": "dropdown",
+         "label": "Department",
+         "question": "Which department would you like to contact?",
+         "config": {
+           "options": [
+             {"value": "sales", "label": "Sales Team", "isDefault": false},
+             {"value": "support", "label": "Customer Support", "isDefault": false}
+           ]
+         },
+         "position": 2,
+         ...
+       },
+       {
+         "id": "satisfaction",
+         "type": "rating",
+         "label": "Satisfaction",
+         "question": "How satisfied are you with our service?",
+         "config": {
+           "scale": 5,
+           "style": "stars"
+         },
+         "position": 3,
+         ...
+       }
+     ]
+   }
+   ```
+
+3. **Preview before publishing:**
+   - While editing a form in admin, click the "Preview JSON" link to see the generated schema
+   - Forms with `status="draft"` return 404 from the API but are visible in admin preview
+
+## JSON Schema Contract
+
+Returned from `/api/forms/<slug>/` when the form status is `published`.
+
+```json
+{
+  "form": {
+    "name": "Contact Us",
+    "slug": "contact-us",
+    "description": "Lead capture form",
+    "status": "published"
+  },
+  "fields": [
+    {
+      "id": "full_name",
+      "type": "text",
+      "label": "Full Name",
+      "required": true,
+      "helpText": "As shown on ID",
+      "placeholder": "Jane Doe",
+      "defaultValue": null,
+      "position": 1,
+      "config": {
+        "minLength": 2,
+        "maxLength": 120,
+        "inputMode": "text",
+        "prefix": "",
+        "suffix": ""
+      }
+    }
+  ]
+}
+```
+
+### Field Attribute Matrix
+
+| Field Type | Config Keys | Notes |
+| --- | --- | --- |
+| `text` | `minLength`, `maxLength`, `pattern`, `inputMode`, `prefix`, `suffix` | Single-line text input |
+| `number` | `min`, `max`, `step`, `prefix`, `suffix`, `unit` | Numeric input with validation |
+| `textarea` | `rows`, `minLength`, `maxLength`, `autoResize` | Multi-line text input |
+| `dropdown` | `allowMultiple`, `allowOther`, `options`, `defaultOption` | Options managed via FieldOption model (inline editor) |
+| `radio` | `allowOther`, `options`, `defaultOption` | Single selection, options via FieldOption model |
+| `checkbox` | `minSelections`, `maxSelections`, `allowOther`, `options`, `defaultOption` | Multiple selections, options via FieldOption model |
+| `rating` | `scale` (5 or 10), `style` (stars/numeric/emoji), `minLabel`, `maxLabel` | Rating scale input |
+| `boolean` | `trueLabel`, `falseLabel`, `style` | Yes/No or True/False |
+| `email` | `confirmEmail` | Email with validation |
+| `date` | `minDate`, `maxDate`, `format` | Date picker |
+
+## Sample Fixture
+
+Load an example form (Contact Us) into any project:
+
+```bash
+python manage.py loaddata formbuilder/fixtures/demo_form.json
+```
+
+The fixture seeds one published `CustomForm` with two fields (text + dropdown) so you can immediately hit `/api/forms/contact-demo/` and inspect the JSON. Use this as a template when sharing schemas with frontend teams.
+
+## Testing Locally
+
+This repo includes a tiny Django settings module (`formbuilder_test_site`) used only for running the test suite:
+
+```bash
+uv sync --group dev
+pytest
+```
+
+The configured `pytest` run uses `-vv --cov=formbuilder --cov-report=term-missing`, so the CLI output lists each test, statuses, and line coverage to help you verify exactly what executed.
+
+## Development Setup
+
+To enable pre-commit hooks for linting and formatting:
+
+```bash
+uv tool install pre-commit
+pre-commit install
+```
+
+## Feature Flag
+
+Toggle the read-only API via the `FORMBUILDER_API_ENABLED` setting. The API is disabled unless you explicitly set `FORMBUILDER_API_ENABLED = True`; when left `False`, `/api/forms/<slug>/` returns 404 regardless of form status.
+
+## Compatibility Notes
+
+- Django 5.1 on Python 3.14 has a known bug in `django.template.context.BaseContext.__copy__`. This package patches the method at import time so admin pages continue to work. No action is required from host projects besides including `formbuilder` in `INSTALLED_APPS`.

django_basic_form_builder-0.1.2.dist-info/RECORD

@@ -0,0 +1,29 @@
+django_basic_form_builder-0.1.2.dist-info/licenses/LICENSE,sha256=DKWp0GaHtPLZnBBY0raAuoucn7eDZbDdQonqfV9b7wI,1078
+formbuilder/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+formbuilder/admin.py,sha256=RuRjkEoYupmHIqcbFH3AOVQ3svga9yTpF84cu89ffrs,16972
+formbuilder/apps.py,sha256=60reK5EstcxIpiLCSo3ZObhEKUWLMVmKDvQMctrQBCw,297
+formbuilder/compat.py,sha256=mDX0fqbRZ2j3MqVAhK_hd6R-CrzfkbTvVR7Nv6arlho,1016
+formbuilder/models.py,sha256=txzygJvApWRA6UwjcxAa1nKslEGSEsYjTHb5veal8k8,13723
+formbuilder/schema_types.py,sha256=qFRFiy-m5ADA9JA_iTQD82-theklzQ-TDsYtvRix9xo,2357
+formbuilder/views.py,sha256=F42JXgnqFqK0fajXeutyJJxwOszRxoLMNkIhfc4Z7KI,26
+formbuilder/api/serializers.py,sha256=VoE2-3MRMi5spFCCahooWBOs7Env1vuJ4L7Qw5_Y6Ns,278
+formbuilder/api/urls.py,sha256=I7NaLFhJ_2m03mDvZztMlquBJmYZEVhTX8W4zyQKQSQ,191
+formbuilder/api/views.py,sha256=VuQG4gk0mlGb3Jx5Zzomalj-DlgFt0ECAoui9ohVxNk,968
+formbuilder/migrations/0001_initial.py,sha256=b4ygW7B8oDTmG0gRYb1eRd_ujYKg23NYcZCCKQ5BeG0,3569
+formbuilder/migrations/0002_alter_formfield_field_type_fieldoption.py,sha256=PlRa9PgESWUkYS81Tit8s8vZYzZJbLn1BqNM_ibmiyE,2305
+formbuilder/migrations/0003_formfield_question_alter_formfield_label.py,sha256=tDWUZyFkEvvLzZcBEzDlnEwspQrh2vlykB1sn-G3TF8,703
+formbuilder/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+formbuilder/services/schema_builder.py,sha256=4MPpcUngzwd48NsmwKU5sbWWi_N7_YWUW0K4SoG9MIs,3524
+formbuilder/static/formbuilder/admin/css/formfield_admin.css,sha256=NYIlkNeP3GupJ7QhaB2BizlaxfTT9OYTw4tOBIPkAaw,3683
+formbuilder/static/formbuilder/admin/js/formfield_admin.js,sha256=H8L97Zb4IpuwUAZWjgeF2rAxDT7gSm9UADpR6O9tMpM,7016
+formbuilder/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+formbuilder/tests/conftest.py,sha256=Vi7tIOGt8dbJcNksa1qQ2-RoxAGudUQknJbpRqFBiZc,191
+formbuilder/tests/test_admin.py,sha256=sliE66mW2NXnQU8prtMne5auuEnkAfLapSfn1kXr-yQ,1655
+formbuilder/tests/test_api.py,sha256=ym77heWCyWDRIYEDc2YAUtLkfeuqNNM1MvEjIsMu6Bc,1738
+formbuilder/tests/test_compat.py,sha256=o55fcFV-rz8u2u1kI2uwHB9ZQBNHC0dx40h49oyNv8s,477
+formbuilder/tests/test_models.py,sha256=_uj6818kcg9O053tYZrBhfk5_gAkKp86zDnBeJGMrho,8151
+formbuilder/tests/test_schema_builder.py,sha256=HPgAiubf4nz8vsl2oWBgiuSXqc-d2r16HC_V64fYTwI,1992
+django_basic_form_builder-0.1.2.dist-info/METADATA,sha256=-Z9MjXnbzkzKpls09wb8ZC9NIxIdJV4Rwt7OgsoFucI,11322
+django_basic_form_builder-0.1.2.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+django_basic_form_builder-0.1.2.dist-info/top_level.txt,sha256=3cWOFLIgADOSoJAU12DQIg9n0Ju1cgI0PBAcZ-0CNgY,12
+django_basic_form_builder-0.1.2.dist-info/RECORD,,

django_basic_form_builder-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_basic_form_builder-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Göktürk Burak Köse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_basic_form_builder-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+formbuilder