feat(templates): document templating system for .kc files #306

forbes · 2026-02-21T15:07:25Z

forbes commented

2026-02-21 15:07:25 +00:00

Summary

Add a document templating system integrated with Silo's new-item creation flow. Users can create parts and assemblies from pre-configured .kc template files, and save existing documents as reusable templates.

Changes

Template Use (New Item form)

templates.py (new) — template discovery, filtering, TemplateInfo dataclass, inject_template_json() helper, 3-tier search paths
schema_form.py — template combo picker in the Identity section, filtered by item type and category
silo_commands.py — SiloSync.create_document_from_template() copies template .kc, strips identity, stamps Silo properties; _on_created routing

Template Creation (Save as Template)

SaveAsTemplateDialog — modal dialog capturing name, description, item types, categories, author, and tags
Silo_SaveAsTemplate command — copies current doc, strips Silo identity, injects silo/template.json, optionally uploads to Silo for team sharing
InitGui.py — registered in Silo menu

Template Search Paths (3-tier, later shadows earlier by name)

mods/silo/freecad/templates/ — system templates shipped with addon
~/.local/share/FreeCAD/Templates/ — personal templates (sister to Macro/)
~/projects/templates/ — org-shared project templates

Documentation

docs/src/guide/templates.md — full user guide covering usage, creation, search paths, descriptor schema, and CLI tooling
docs/src/guide/silo.md — updated command table and directory structure
docs/src/SUMMARY.md — added Templates page to navigation

How it works

A template is a normal .kc file with an extra silo/template.json descriptor inside the ZIP. The copy-and-stamp approach avoids complex object-by-object cloning:

Copy the template .kc to the canonical file path
Strip silo/template.json and silo/manifest.json from the copy
Open in FreeCAD and stamp Silo properties (part number, item ID, revision)
Save — kc_format.py auto-creates a fresh manifest

Testing

Save as Template dialog pre-populates from document state (label, Silo item type, category, auth username)
Template picker in New Item form filters by selected type and category
Fallback: no template selected = existing bare document creation
Fallback: invalid template path = falls back to create_document_for_item()
Silo upload is non-blocking — failures log a warning, template remains saved locally

## Summary Add a document templating system integrated with Silo's new-item creation flow. Users can create parts and assemblies from pre-configured `.kc` template files, and save existing documents as reusable templates. ## Changes ### Template Use (New Item form) - **`templates.py`** (new) — template discovery, filtering, `TemplateInfo` dataclass, `inject_template_json()` helper, 3-tier search paths - **`schema_form.py`** — template combo picker in the Identity section, filtered by item type and category - **`silo_commands.py`** — `SiloSync.create_document_from_template()` copies template `.kc`, strips identity, stamps Silo properties; `_on_created` routing ### Template Creation (Save as Template) - **`SaveAsTemplateDialog`** — modal dialog capturing name, description, item types, categories, author, and tags - **`Silo_SaveAsTemplate`** command — copies current doc, strips Silo identity, injects `silo/template.json`, optionally uploads to Silo for team sharing - **`InitGui.py`** — registered in Silo menu ### Template Search Paths (3-tier, later shadows earlier by name) 1. `mods/silo/freecad/templates/` — system templates shipped with addon 2. `~/.local/share/FreeCAD/Templates/` — personal templates (sister to `Macro/`) 3. `~/projects/templates/` — org-shared project templates ### Documentation - **`docs/src/guide/templates.md`** — full user guide covering usage, creation, search paths, descriptor schema, and CLI tooling - **`docs/src/guide/silo.md`** — updated command table and directory structure - **`docs/src/SUMMARY.md`** — added Templates page to navigation ## How it works A template is a normal `.kc` file with an extra `silo/template.json` descriptor inside the ZIP. The copy-and-stamp approach avoids complex object-by-object cloning: 1. **Copy** the template `.kc` to the canonical file path 2. **Strip** `silo/template.json` and `silo/manifest.json` from the copy 3. **Open** in FreeCAD and **stamp** Silo properties (part number, item ID, revision) 4. **Save** — `kc_format.py` auto-creates a fresh manifest ## Testing - Save as Template dialog pre-populates from document state (label, Silo item type, category, auth username) - Template picker in New Item form filters by selected type and category - Fallback: no template selected = existing bare document creation - Fallback: invalid template path = falls back to `create_document_for_item()` - Silo upload is non-blocking — failures log a warning, template remains saved locally

forbes added 1 commit 2026-02-21 15:07:26 +00:00

feat(templates): document templating system for .kc files

Build and Test / build (pull_request) Successful in 29m12s

Details

b8cb7ca267

Add a template system integrated with Silo new-item creation that lets
users create parts from pre-configured .kc templates and save existing
documents as reusable templates.

Changes:
- mods/silo: template discovery, picker UI, Save as Template command,
  3-tier search paths (system, personal, org-shared)
- docs: template guide, SUMMARY.md entry, silo.md command reference

forbes merged commit 148bed59f6 into main

2026-02-21 15:07:45 +00:00

forbes deleted branch feat/document-templates

2026-02-21 15:07:46 +00:00

forbes referenced this issue from a commit

2026-02-21 15:07:46 +00:00

Merge pull request 'feat(templates): document templating system for .kc files' (#306) from feat/document-templates into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: kindred/create#306