TG Standards
Django patterns and conventions for the World of Darkness application.
Decision Tree
What are you working on?
| Task |
Reference |
| Creating/editing a model |
references/models.md |
| Creating/editing views |
references/views.md |
| Creating/editing forms |
references/forms.md |
| Creating/editing templates |
references/templates.md |
| Setting up URLs |
references/urls.md |
| Permission checks |
references/permissions.md |
| Data validation, transactions |
references/validation.md |
| Database migrations |
references/migrations.md |
| Caching |
references/caching.md |
| Writing tests |
references/testing.md |
| Deployment |
references/deployment.md |
| Management commands |
references/commands.md |
| Character templates |
references/character-templates.md |
| WoD terminology lookup |
references/domain.md |
| Model inventory/status |
references/model-inventory.md |
Core Conventions (Always Apply)
Model Type Registration
type = "model_name" # Snake_case, matches URL pattern
gameline = "gameline" # vtm, wta, mta, wto, ctd, dtf, mtr, htr
URL Namespace Pattern
app:gameline:action:model_type
Required Model Methods
def get_absolute_url(self):
return reverse("app:gameline:detail:model_type", kwargs={"pk": self.pk})
def get_update_url(self):
return reverse("app:gameline:update:model_type", kwargs={"pk": self.pk})
# get_heading() inherited from core.models.Model - returns f"{gameline}_heading"
Mixin Stacking Order
class MyUpdateView(EditPermissionMixin, MessageMixin, UpdateView): pass
class MyListView(VisibilityFilterMixin, ListView): pass
class MyCreateView(LoginRequiredMixin, MessageMixin, CreateView): pass
Template Classes
Use tg-card, tg-table, tg-badge, tg-btn (not Bootstrap defaults).
Gameline Headings
| Gameline |
Class |
Data Attr |
| Vampire |
vtm_heading |
data-gameline="vtm" |
| Werewolf |
wta_heading |
data-gameline="wta" |
| Mage |
mta_heading |
data-gameline="mta" |
| Wraith |
wto_heading |
data-gameline="wto" |
| Changeling |
ctd_heading |
data-gameline="ctd" |
| Demon |
dtf_heading |
data-gameline="dtf" |
| Mummy |
mtr_heading |
data-gameline="mtr" |
| Hunter |
htr_heading |
data-gameline="htr" |
Use {{ object.get_heading }} for dynamic class.
File Location Pattern
| Component |
Path |
| Model |
app/models/gameline/model_name.py |
| Views |
app/views/gameline/{list,detail,create,update}.py |
| Forms |
app/forms/gameline/model_name.py |
| URLs |
app/urls/gameline/{list,detail,create,update}.py |
| Templates |
app/templates/app/gameline/model_name/{detail,list,form}.html |
Quick Checklist
New Model
New View
New Template
1---2name: tg-standards3description: Django development standards for the Tellurium Games World of Darkness application. Use when: creating/editing models (characters, items, locations), implementing CRUD views, building forms, creating templates, configuring URLs, working with permissions, caching, migrations, testing, validation, deployment, or management commands. Triggers on: model inheritance patterns, polymorphic models, view mixins, gameline-specific code (vampire/werewolf/mage/wraith/changeling/demon/mummy/hunter), tg-card components, XP/freebie transactions, ST permissions, character templates, frontend styling.4---5
6# TG Standards
7
8Django patterns and conventions for the World of Darkness application.
9
10## Decision Tree
11
12**What are you working on?**
13
14| Task | Reference |
15|------|-----------|
16| Creating/editing a model | [references/models.md](references/models.md) |
17| Creating/editing views | [references/views.md](references/views.md) |
18| Creating/editing forms | [references/forms.md](references/forms.md) |
19| Creating/editing templates | [references/templates.md](references/templates.md) |
20| Setting up URLs | [references/urls.md](references/urls.md) |
21| Permission checks | [references/permissions.md](references/permissions.md) |
22| Data validation, transactions | [references/validation.md](references/validation.md) |
23| Database migrations | [references/migrations.md](references/migrations.md) |
24| Caching | [references/caching.md](references/caching.md) |
25| Writing tests | [references/testing.md](references/testing.md) |
26| Deployment | [references/deployment.md](references/deployment.md) |
27| Management commands | [references/commands.md](references/commands.md) |
28| Character templates | [references/character-templates.md](references/character-templates.md) |
29| WoD terminology lookup | [references/domain.md](references/domain.md) |
30| Model inventory/status | [references/model-inventory.md](references/model-inventory.md) |
31
32## Core Conventions (Always Apply)
33
34### Model Type Registration
35```python
36type = "model_name" # Snake_case, matches URL pattern
37gameline = "gameline" # vtm, wta, mta, wto, ctd, dtf, mtr, htr
38```
39
40### URL Namespace Pattern
41```
42app:gameline:action:model_type
43```
44
45### Required Model Methods
46```python
47def get_absolute_url(self):
48 return reverse("app:gameline:detail:model_type", kwargs={"pk": self.pk})
49
50def get_update_url(self):
51 return reverse("app:gameline:update:model_type", kwargs={"pk": self.pk})
52# get_heading() inherited from core.models.Model - returns f"{gameline}_heading"
53```
54
55### Mixin Stacking Order
56```python
57class MyUpdateView(EditPermissionMixin, MessageMixin, UpdateView): pass
58class MyListView(VisibilityFilterMixin, ListView): pass
59class MyCreateView(LoginRequiredMixin, MessageMixin, CreateView): pass
60```
61
62### Template Classes
63Use `tg-card`, `tg-table`, `tg-badge`, `tg-btn` (not Bootstrap defaults).
64
65### Gameline Headings
66| Gameline | Class | Data Attr |
67|----------|-------|-----------|
68| Vampire | `vtm_heading` | `data-gameline="vtm"` |
69| Werewolf | `wta_heading` | `data-gameline="wta"` |
70| Mage | `mta_heading` | `data-gameline="mta"` |
71| Wraith | `wto_heading` | `data-gameline="wto"` |
72| Changeling | `ctd_heading` | `data-gameline="ctd"` |
73| Demon | `dtf_heading` | `data-gameline="dtf"` |
74| Mummy | `mtr_heading` | `data-gameline="mtr"` |
75| Hunter | `htr_heading` | `data-gameline="htr"` |
76
77Use `{{ object.get_heading }}` for dynamic class.
78
79### File Location Pattern
80| Component | Path |
81|-----------|------|
82| Model | `app/models/gameline/model_name.py` |
83| Views | `app/views/gameline/{list,detail,create,update}.py` |
84| Forms | `app/forms/gameline/model_name.py` |
85| URLs | `app/urls/gameline/{list,detail,create,update}.py` |
86| Templates | `app/templates/app/gameline/model_name/{detail,list,form}.html` |
87
88## Quick Checklist
89
90### New Model
91- [ ] Proper base class (Character/Human, ItemModel, LocationModel, or Model)
92- [ ] `type` and `gameline` set
93- [ ] `__str__`, `get_absolute_url`, `get_update_url`
94- [ ] Meta with `verbose_name`, `verbose_name_plural`, `ordering`
95- [ ] Migration created
96
97### New View
98- [ ] Correct mixin order
99- [ ] `select_related`/`prefetch_related` for optimization
100- [ ] Form class selection based on permissions in UpdateView
101
102### New Template
103- [ ] Extends appropriate base
104- [ ] Uses `tg-*` classes
105- [ ] Gameline heading on cards
106- [ ] Loads `{% load dots sanitize_text %}` if using those filters
majiayu000