django-kpforms

A reusable Django application for dynamic form templates and submissions, powered by Lit-based web components.

• Define form templates with sections, groups, and typed fields (numeric, string, text, radio, checkbox, datetime, calculated, ranged-radio)
• Built-in tolerance checking for numeric and string fields
• Interactive web component (<dynamic-form>) for end-user submission
• Visual form-builder web component (<dynamic-form-builder>) for creating and editing templates
• Printable-form component for generating PDFs via html2pdf.js
• Full version history for form templates

Table of Contents

1. Requirements
2. Installation
3. Quick Start
4. Django Models & Helpers
5. Web Components
   • <dynamic-form>
   • <dynamic-form-builder>
   • <printable-form>
6. CSS Customisation Variables
   • Typography
   • Colours
   • Accent Colour
   • Status / Tolerance Colours
   • Layout
   • Compact mode
7. Contributing / Building from Source

Requirements

• Python ≥ 3.14
• Django ≥ 5.0
• Pydantic ≥ 2.0

Installation

pip install django-kpforms

Or with uv:

uv add django-kpforms

Quick Start

1. Add to INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    ...
    "kpforms",
]

2. Run migrations

python manage.py migrate

3. Serve static files

django-kpforms ships with a compiled JavaScript bundle (kpforms.js) and KaTeX font files under kpforms/static/.

Make sure Django's static-file serving is configured and collectstatic has been run in production:

python manage.py collectstatic

4. Load the bundle in your template

{% load static %}

<!-- Load the kpforms web-component bundle -->
<script type="module" src="{% static 'kpforms.js' %}"></script>

<!-- Optional: load html2pdf for the printable-form component -->
<script src="{% static 'html2pdf.bundle.min.js' %}"></script>

Django Models & Helpers

Models

Helper functions (kpforms.helpers)

from kpforms.helpers import (
    create_form_template,
    update_form_template,
    submit_form_data,
    get_form_by_template_id_and_version,
    get_form_template_list,
    get_form_template_list_paginated,
    get_all_results_for_form_template,
)

Schema classes (kpforms.form_schema)

The core schema models are Pydantic models. The most important ones:

Web Components

Include kpforms.js once on the page (see Quick Start above) — all components are self-registering and require no additional setup.

<dynamic-form>

Renders a form for end-user completion and submission.

<dynamic-form id="my-form"></dynamic-form>

<script type="module">
  const formEl = document.getElementById("my-form");

  // Pass the form schema (FormSchema JSON) as a property
  formEl.schema = {
    guid: "...",
    title: "My Form",
    sections: [...],
    generatePdfOption: false,
    generatePdfString: "Generate PDF",
    submitFormString: "Submit",
    submittingString: "Submitting…",
    apiConfig: {
      url: "/api/forms/submit/",
      method: "POST",
      successMessage: "Form submitted!",
      errorMessage: "Submission failed."
    }
  };

  // Optional: add extra keys to the submit POST body.
  // Must be a JSON-formatted string representing an object.
  formEl.extraPostParams = JSON.stringify({
    project_id: "abc123",
    station: "line-7"
  });
</script>

Properties / attributes:

<dynamic-form-builder>

An interactive editor that lets users create and edit form templates.

<dynamic-form-builder id="builder"></dynamic-form-builder>

<script type="module">
  const builder = document.getElementById("builder");

  // Optional: load an existing template for editing
  builder.schema = { guid: "...", name: "...", formSchema: { ... } };

  // Optional: add extra keys to the save-schema POST body.
  // Must be a JSON-formatted string representing an object.
  builder.extraPostParams = JSON.stringify({
    project_id: "abc123",
    edited_by: "frontend"
  });

  // Listen for save events
  builder.addEventListener("form-save", (e) => {
    const payload = e.detail; // CreateFormTemplateSchema | UpdateFormTemplateSchema
    fetch("/api/forms/templates/", {
      method: payload.guid ? "PUT" : "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(payload),
    });
  });
</script>

Properties / attributes:

The builder's preview dialog has a Compact switch that renders the preview <dynamic-form> with compact. It is independent of the builder's own compact.

Events emitted:

<printable-form>

Renders a read-only printable view of a submitted form that can be exported as a PDF using html2pdf.js.

<printable-form id="print-form"></printable-form>

<script type="module">
  const el = document.getElementById("print-form");
  el.schema   = { /* FormTemplateSchema */ };
  el.submission = { /* FormSubmission data */ };
</script>

Properties:

CSS Customisation Variables

All web components use CSS custom properties (variables) to control their appearance. Set these on the element itself or any ancestor to theme the components.

The public API variables are prefixed --df-*. Internal variables map them to --form-* and to Shoelace design tokens.

Typography

Colours

Accent Colour

Used for buttons, active tabs, focused borders, and Shoelace's primary palette.

Status / Tolerance Colours

These control how fields are highlighted when their values are within or outside the defined tolerance range.

Layout

The tokens below are also public --df-* variables. Defaults shown are the regular (non-compact) values. Tokens marked -- in a compact column are not changed by compact mode for that component.

Compact mode

Set the compact attribute on <dynamic-form> or <dynamic-form-builder>:

<dynamic-form compact></dynamic-form>
<dynamic-form-builder compact foldableGroups></dynamic-form-builder>

Compact mode only supplies fallback values (via internal --form-compact-* variables). An explicit --df-* variable always wins over compact, so a consumer theme keeps working unchanged. Example: dynamic-form { --df-font-size-base: 1.1rem; } stays 1.1rem with compact, while other compact values still apply.

Compact values (blank = same as regular default):

Narrow forms fall back to labels above values.

Example: Dark Theme

dynamic-form {
  --df-color-background:            #1e1e2e;
  --df-color-background-section:    #2a2a3e;
  --df-color-background-input-base: #2d2d42;
  --df-color-text:                  #cdd6f4;
  --df-color-text-label:            #cdd6f4;
  --df-color-input-text:            #cdd6f4;
  --df-color-border:                #45475a;
  --df-color-accent:                #89b4fa;
  --df-color-accent-darker:         #74a0e8;
  --df-color-accent-text:           #1e1e2e;
}

Contributing / Building from Source

Prerequisites

• Python ≥ 3.14 (with uv)
• Node.js ≥ 20 with npm

Build

Use the included build.sh to produce a distributable wheel and sdist:

# Build both sdist and wheel (default)
./build.sh

# Build wheel only
./build.sh --wheel

# Build sdist only
./build.sh --sdist

The script will:

1. Run npm run build inside kpforms/kpforms/ to compile the TypeScript web components and copy the output into kpforms/static/.
2. Run python manage.py makemigrations kpforms to ensure migrations are up-to-date.
3. Run uv build to produce the final packages in dist/.

Running Tests

uv run pytest

Licence

MIT — see LICENSE for details.