0
# Template System
1
2
Comprehensive template tag library with element-based UI framework, slot system for template composition, and customizable layouts for authentication UI. Provides a sophisticated system for building and customizing authentication interfaces.
3
4
## Capabilities
5
6
### Template Tags
7
8
Core template tags for UI composition and customization.
9
10
```python { .api }
11
@register.tag(name="slot")
12
def do_slot(parser: Parser, token: Token) -> SlotNode:
13
"""
14
Template tag for defining content slots.
15
16
Usage:
17
{% slot slot_name %}
18
Default content here
19
{% endslot %}
20
21
Parameters:
22
- parser: Django template parser
23
- token: Template token
24
25
Returns:
26
SlotNode instance
27
"""
28
29
@register.tag(name="element")
30
def do_element(parser: Parser, token: Token) -> ElementNode:
31
"""
32
Template tag for rendering UI elements with layout support.
33
34
Usage:
35
{% element "button" type="submit" class="btn-primary" %}
36
Button content
37
{% endelement %}
38
39
Parameters:
40
- parser: Django template parser
41
- token: Template token
42
43
Returns:
44
ElementNode instance
45
"""
46
47
@register.tag(name="setvar")
48
def do_setvar(parser: Parser, token: Token) -> SetVarNode:
49
"""
50
Template tag for setting template variables.
51
52
Usage:
53
{% setvar variable_name %}
54
Variable content
55
{% endsetvar %}
56
57
Parameters:
58
- parser: Django template parser
59
- token: Template token
60
61
Returns:
62
SetVarNode instance
63
"""
64
```
65
66
### Template Nodes
67
68
Template node classes implementing the tag functionality.
69
70
```python { .api }
71
class SlotNode(Node):
72
"""
73
Template node for slot functionality.
74
"""
75
76
def __init__(self, name: str, nodelist: NodeList): ...
77
78
def render(self, context: Context) -> str:
79
"""
80
Render slot content with context.
81
82
Parameters:
83
- context: Template context
84
85
Returns:
86
Rendered HTML string
87
"""
88
89
class ElementNode(Node):
90
"""
91
Template node for element rendering with layout awareness.
92
"""
93
94
def __init__(self, nodelist: NodeList, element: FilterExpression, kwargs: Dict[str, FilterExpression]): ...
95
96
def render(self, context: Context) -> str:
97
"""
98
Render element with layout-specific template.
99
100
Parameters:
101
- context: Template context
102
103
Returns:
104
Rendered HTML string
105
"""
106
107
class SetVarNode(Node):
108
"""
109
Template node for variable setting.
110
"""
111
112
def __init__(self, nodelist: NodeList, var: str): ...
113
114
def render(self, context: Context) -> str:
115
"""
116
Set variable in template context.
117
118
Parameters:
119
- context: Template context
120
121
Returns:
122
Empty string (sets variable as side effect)
123
"""
124
```
125
126
### Utility Functions
127
128
Template utility functions for parsing and processing.
129
130
```python { .api }
131
def parse_tag(token: Token, parser: Parser) -> Tuple[str, List[FilterExpression], Dict[str, FilterExpression]]:
132
"""
133
Parse template tag arguments into positional and keyword arguments.
134
135
Parameters:
136
- token: Template token to parse
137
- parser: Template parser instance
138
139
Returns:
140
Tuple of (tag_name, args, kwargs)
141
"""
142
```
143
144
### Element System
145
146
The element system provides a flexible way to render UI components with layout-specific templates.
147
148
```python { .api }
149
class ElementRenderer:
150
"""
151
Renderer for UI elements with layout support.
152
"""
153
154
def __init__(self, element_name: str, layout: str = None): ...
155
156
def render(self, context: Context, attrs: Dict[str, Any] = None, slots: Dict[str, List[str]] = None) -> str:
157
"""
158
Render element with given context and attributes.
159
160
Parameters:
161
- context: Template context
162
- attrs: Element attributes
163
- slots: Slot content dictionary
164
165
Returns:
166
Rendered HTML string
167
"""
168
169
def get_template_names(self) -> List[str]:
170
"""
171
Get template names to try for this element.
172
173
Returns:
174
List of template names in priority order
175
"""
176
177
def render_element(element_name: str, context: Context, **kwargs) -> str:
178
"""
179
Render element with context and attributes.
180
181
Parameters:
182
- element_name: Name of element to render
183
- context: Template context
184
- kwargs: Element attributes
185
186
Returns:
187
Rendered HTML string
188
"""
189
```
190
191
### Layout System
192
193
Layout detection and management for responsive UI templates.
194
195
```python { .api }
196
class LayoutManager:
197
"""
198
Manager for detecting and applying layouts.
199
"""
200
201
def get_current_layout(self, context: Context) -> Optional[str]:
202
"""
203
Get current layout from template context.
204
205
Parameters:
206
- context: Template context
207
208
Returns:
209
Layout name or None
210
"""
211
212
def get_element_template(self, element_name: str, layout: str = None) -> str:
213
"""
214
Get template path for element with layout.
215
216
Parameters:
217
- element_name: Element name
218
- layout: Optional layout name
219
220
Returns:
221
Template path string
222
"""
223
224
def detect_layout_from_extends(context: Context) -> Optional[str]:
225
"""
226
Detect layout from {% extends %} tag in template context.
227
228
Parameters:
229
- context: Template context
230
231
Returns:
232
Layout name or None
233
"""
234
```
235
236
### Built-in Elements
237
238
Pre-defined UI elements for common authentication interface components.
239
240
```python { .api }
241
# Form Elements
242
FORM_ELEMENTS = {
243
'form': 'Form container with CSRF and action handling',
244
'field': 'Form field with label, input, and error display',
245
'input': 'Form input with type and validation',
246
'button': 'Form button with type and styling',
247
'submit': 'Submit button with loading states',
248
}
249
250
# Navigation Elements
251
NAVIGATION_ELEMENTS = {
252
'nav': 'Navigation container',
253
'menu': 'Menu with items and active states',
254
'breadcrumb': 'Breadcrumb navigation',
255
'pagination': 'Pagination controls',
256
}
257
258
# Content Elements
259
CONTENT_ELEMENTS = {
260
'card': 'Content card with header and body',
261
'alert': 'Alert/message with dismissal',
262
'modal': 'Modal dialog with backdrop',
263
'tabs': 'Tabbed content interface',
264
}
265
266
# Authentication Elements
267
AUTH_ELEMENTS = {
268
'login_form': 'Complete login form',
269
'signup_form': 'Complete registration form',
270
'password_reset_form': 'Password reset request form',
271
'social_login': 'Social authentication buttons',
272
'mfa_form': 'Multi-factor authentication form',
273
}
274
```
275
276
## Usage Examples
277
278
### Basic Element Usage
279
280
```html
281
<!-- Basic button element -->
282
{% load allauth %}
283
284
{% element "button" type="submit" class="btn btn-primary" %}
285
Sign In
286
{% endelement %}
287
288
<!-- Form field with validation -->
289
{% element "field" name="email" type="email" required=True %}
290
{% slot label %}Email Address{% endslot %}
291
{% slot help_text %}We'll never share your email{% endslot %}
292
{% endelement %}
293
294
<!-- Alert message -->
295
{% element "alert" type="success" dismissible=True %}
296
Your account has been created successfully!
297
{% endelement %}
298
```
299
300
### Slot System
301
302
```html
303
<!-- Define slots in parent template -->
304
{% element "card" %}
305
{% slot header %}
306
<h3>Login to Your Account</h3>
307
{% endslot %}
308
309
{% slot body %}
310
{% element "login_form" %}
311
{% endelement %}
312
{% endslot %}
313
314
{% slot footer %}
315
<p>Don't have an account? <a href="{% url 'account_signup' %}">Sign up</a></p>
316
{% endslot %}
317
{% endelement %}
318
```
319
320
### Layout-Specific Templates
321
322
```html
323
<!-- Base template with layout -->
324
{% extends "allauth/layouts/bootstrap5.html" %}
325
326
{% block content %}
327
<!-- Elements will automatically use bootstrap5-specific templates -->
328
{% element "form" action="{% url 'account_login' %}" method="post" %}
329
{% element "field" name="login" %}
330
{% element "field" name="password" type="password" %}
331
{% element "submit" %}Login{% endelement %}
332
{% endelement %}
333
{% endblock %}
334
```
335
336
### Custom Element Templates
337
338
```html
339
<!-- templates/allauth/elements/custom_button.html -->
340
<button type="{{ attrs.type|default:'button' }}"
341
class="custom-btn {{ attrs.class|default:'' }}"
342
{% if attrs.disabled %}disabled{% endif %}>
343
{{ slots.default|join:'' }}
344
</button>
345
346
<!-- templates/allauth/elements/custom_button__mobile.html -->
347
<button type="{{ attrs.type|default:'button' }}"
348
class="mobile-btn {{ attrs.class|default:'' }}"
349
{% if attrs.disabled %}disabled{% endif %}>
350
{{ slots.default|join:'' }}
351
</button>
352
```
353
354
### Variable Setting
355
356
```html
357
<!-- Set variables for reuse -->
358
{% setvar page_title %}User Dashboard{% endsetvar %}
359
{% setvar sidebar_active %}profile{% endsetvar %}
360
361
<title>{{ page_title }}</title>
362
363
<nav class="sidebar">
364
<a href="#" {% if sidebar_active == 'profile' %}class="active"{% endif %}>
365
Profile
366
</a>
367
</nav>
368
```
369
370
### Complete Authentication Forms
371
372
```html
373
<!-- Login page with full element system -->
374
{% extends "allauth/layouts/base.html" %}
375
{% load allauth %}
376
377
{% block content %}
378
{% element "card" class="auth-card" %}
379
{% slot header %}
380
<h2>Sign In</h2>
381
{% endslot %}
382
383
{% slot body %}
384
{% if form.errors %}
385
{% element "alert" type="danger" %}
386
Please correct the errors below.
387
{% endelement %}
388
{% endif %}
389
390
{% element "form" action="{% url 'account_login' %}" method="post" %}
391
{% element "field" name="login" %}
392
{% slot label %}Email or Username{% endslot %}
393
{% endelement %}
394
395
{% element "field" name="password" type="password" %}
396
{% slot label %}Password{% endslot %}
397
{% endelement %}
398
399
{% if form.remember %}
400
{% element "field" name="remember" type="checkbox" %}
401
{% slot label %}Remember me{% endslot %}
402
{% endelement %}
403
{% endif %}
404
405
{% element "submit" class="btn-primary btn-block" %}
406
Sign In
407
{% endelement %}
408
{% endelement %}
409
410
<hr>
411
412
{% element "social_login" %}
413
{% endelement %}
414
{% endslot %}
415
416
{% slot footer %}
417
<div class="auth-links">
418
<a href="{% url 'account_reset_password' %}">Forgot Password?</a>
419
<a href="{% url 'account_signup' %}">Create Account</a>
420
</div>
421
{% endslot %}
422
{% endelement %}
423
{% endblock %}
424
```
425
426
### Social Authentication Elements
427
428
```html
429
<!-- Social login buttons -->
430
{% load socialaccount %}
431
432
{% element "social_login" %}
433
{% get_providers as socialaccount_providers %}
434
{% for provider in socialaccount_providers %}
435
{% element "button" class="btn-social btn-{{ provider.id }}" %}
436
{% slot icon %}
437
<i class="fab fa-{{ provider.id }}"></i>
438
{% endslot %}
439
Continue with {{ provider.name }}
440
{% endelement %}
441
{% endfor %}
442
{% endelement %}
443
```
444
445
### MFA Elements
446
447
```html
448
<!-- TOTP authentication form -->
449
{% element "mfa_form" method="totp" %}
450
{% slot header %}
451
<h3>Enter Authentication Code</h3>
452
<p>Enter the 6-digit code from your authenticator app.</p>
453
{% endslot %}
454
455
{% element "field" name="code" type="text" maxlength="6" %}
456
{% slot label %}Authentication Code{% endslot %}
457
{% endelement %}
458
459
{% element "submit" %}Verify{% endelement %}
460
461
{% slot footer %}
462
<a href="{% url 'mfa_recovery_codes' %}">Use recovery code instead</a>
463
{% endslot %}
464
{% endelement %}
465
```
466
467
### Responsive Layout Support
468
469
```html
470
<!-- Different layouts for different devices -->
471
{% extends "allauth/layouts/responsive.html" %}
472
473
{% block content %}
474
<!-- Desktop layout -->
475
<div class="d-none d-md-block">
476
{% element "form" class="wide-form" %}
477
<!-- Wide form layout -->
478
{% endelement %}
479
</div>
480
481
<!-- Mobile layout -->
482
<div class="d-md-none">
483
{% element "form" class="compact-form" %}
484
<!-- Compact form layout -->
485
{% endelement %}
486
</div>
487
{% endblock %}
488
```
489
490
### Custom Template Tags
491
492
```python
493
# In your app's templatetags/custom_allauth.py
494
from django import template
495
from allauth.templatetags.allauth import ElementNode
496
497
register = template.Library()
498
499
@register.tag(name="custom_element")
500
def do_custom_element(parser, token):
501
"""Custom element tag with additional processing."""
502
# Parse token and create custom ElementNode
503
return CustomElementNode()
504
505
class CustomElementNode(ElementNode):
506
def render(self, context):
507
# Custom rendering logic
508
return super().render(context)
509
```
510
511
### Settings Configuration
512
513
```python
514
# In Django settings.py
515
516
# Template settings
517
TEMPLATES = [
518
{
519
'BACKEND': 'django.template.backends.django.DjangoTemplates',
520
'DIRS': [
521
BASE_DIR / 'templates',
522
],
523
'APP_DIRS': True,
524
'OPTIONS': {
525
'context_processors': [
526
# ... standard context processors
527
'allauth.templatetags.context_processors.allauth',
528
],
529
},
530
},
531
]
532
533
# Allauth template settings
534
ACCOUNT_TEMPLATE_EXTENSION = 'html' # Template file extension
535
536
# Layout settings
537
ALLAUTH_LAYOUTS = {
538
'bootstrap5': 'allauth/layouts/bootstrap5.html',
539
'bootstrap4': 'allauth/layouts/bootstrap4.html',
540
'tailwind': 'allauth/layouts/tailwind.html',
541
'custom': 'allauth/layouts/custom.html',
542
}
543
544
# Element settings
545
ALLAUTH_ELEMENTS = {
546
'button': 'allauth/elements/button.html',
547
'field': 'allauth/elements/field.html',
548
'form': 'allauth/elements/form.html',
549
# ... other elements
550
}
551
```
552
553
### Template Customization
554
555
```html
556
<!-- Override default templates -->
557
<!-- templates/allauth/elements/button.html -->
558
<button type="{{ attrs.type|default:'button' }}"
559
class="custom-button {{ attrs.class|default:'' }}"
560
{% for key, value in attrs.items %}
561
{% if key not in 'type,class' %}{{ key }}="{{ value }}"{% endif %}
562
{% endfor %}>
563
{% if slots.icon %}
564
<span class="icon">{{ slots.icon|join:'' }}</span>
565
{% endif %}
566
<span class="text">{{ slots.default|join:'' }}</span>
567
</button>
568
569
<!-- Layout-specific override -->
570
<!-- templates/allauth/elements/button__mobile.html -->
571
<button type="{{ attrs.type|default:'button' }}"
572
class="mobile-button {{ attrs.class|default:'' }}"
573
data-mobile="true">
574
{{ slots.default|join:'' }}
575
</button>
576
```