{{ post.title }}
{{ post.excerpt }}
Read More
{% for team in teams %}
{% include "components/cards/card_team.html" %}
{% endfor %}
{% endblock %}
_component_base.html
^^^^^^^^^^^^^^^^^^^^
Base template for all reusable components. Extends ``partial.html``.
**Usage**:
.. code-block:: django
{% extends "components/_component_base.html" %}
{% block content %}
{% else %}
{% if can_manage %}
{% endif %}
Component Examples
------------------
Form Component
^^^^^^^^^^^^^^
A reusable form component with validation support:
**View** (``apps/public/views/teams/member_views.py``):
.. code-block:: python
from django import forms
from django.contrib import messages
from apps.public.views.helpers.htmx_view import HTMXView
from apps.public.views.helpers.session_mixin import TeamSessionMixin
from apps.common.models.team import TeamMember, Role
class AddMemberForm(forms.Form):
email = forms.EmailField(
label="Email Address",
widget=forms.EmailInput(attrs={
'class': 'form-input',
'placeholder': 'user@example.com'
})
)
role = forms.ChoiceField(
choices=[(r.value, r.label) for r in Role],
initial=Role.MEMBER.value
)
class AddMemberFormView(TeamSessionMixin, HTMXView):
template_name = "components/forms/form_add_member.html"
def get(self, request, *args, **kwargs):
self.context['form'] = AddMemberForm()
return self.render(request)
def post(self, request, *args, **kwargs):
form = AddMemberForm(request.POST)
if form.is_valid():
email = form.cleaned_data['email']
role = form.cleaned_data['role']
# Add member logic
try:
user = User.objects.get(email=email)
TeamMember.objects.create(
team=self.team,
user=user,
role=role
)
messages.success(request, f"{user.name} added to team!")
# Return updated member list
self.context['members'] = self.team.members.all()
return self.render(
request,
template_name="components/lists/list_team_members.html"
)
except User.DoesNotExist:
form.add_error('email', 'User not found')
self.context['form'] = form
return self.render(request)
**Template** (``components/forms/form_add_member.html``):
.. code-block:: django
{% extends "components/_component_base.html" %}
{% block content %}
{% endblock %}
List Component
^^^^^^^^^^^^^^
A list component with add/remove operations:
**View** (``apps/public/views/teams/member_views.py``):
.. code-block:: python
class TeamMemberListView(TeamSessionMixin, HTMXView):
template_name = "components/lists/list_team_members.html"
def get(self, request, *args, **kwargs):
self.context.update({
'members': self.team.members.select_related('user').all(),
'can_manage': self.team.user_can_manage(request.user),
})
return self.render(request)
class RemoveMemberView(TeamSessionMixin, HTMXView):
def delete(self, request, *args, **kwargs):
member_id = kwargs.get('member_id')
member = get_object_or_404(TeamMember, id=member_id, team=self.team)
if not self.team.user_can_manage(request.user):
return HttpResponse("Unauthorized", status=403)
member_name = member.user.name
member.delete()
messages.success(request, f"{member_name} removed from team")
# Return updated list
self.context.update({
'members': self.team.members.all(),
'can_manage': True,
})
return self.render(
request,
template_name="components/lists/list_team_members.html"
)
**Template** (``components/lists/list_team_members.html``):
.. code-block:: django
{% extends "components/_component_base.html" %}
{% block content %}
{% endblock %}
Modal Component
^^^^^^^^^^^^^^^
A confirmation modal component:
**View** (``apps/public/views/teams/team_views.py``):
.. code-block:: python
class DeleteTeamConfirmView(TeamSessionMixin, HTMXView):
template_name = "components/modals/modal_confirm.html"
def get(self, request, *args, **kwargs):
if not self.team.user_can_delete(request.user):
messages.error(request, "You don't have permission to delete this team")
return HttpResponse("", status=403)
self.context.update({
'modal_title': 'Delete Team',
'modal_message': f'Are you sure you want to delete "{self.team.name}"? This action cannot be undone.',
'confirm_url': reverse('team:delete', kwargs={'team_id': self.team.id}),
'confirm_text': 'Delete Team',
'confirm_class': 'btn-danger',
'cancel_text': 'Cancel',
})
return self.render(request)
class DeleteTeamView(TeamSessionMixin, HTMXView):
def delete(self, request, *args, **kwargs):
if not self.team.user_can_delete(request.user):
return HttpResponse("Unauthorized", status=403)
team_name = self.team.name
self.team.delete()
messages.success(request, f'Team "{team_name}" has been deleted')
# Redirect to team list
from django_htmx import http as htmx
response = HttpResponse("")
return htmx.redirect(response, reverse('team:list'))
**Template** (``components/modals/modal_confirm.html``):
.. code-block:: django
{% extends "components/modals/modal_base.html" %}
{% block modal_content %}
{% endblock %}
**Modal Base** (``components/modals/modal_base.html``):
.. code-block:: django
{% extends "partial.html" %}
{% block content %}
{% endblock %}
Forms and Validation
====================
Form Handling Patterns
-----------------------
Inline Validation
^^^^^^^^^^^^^^^^^
Validate individual fields as the user types:
**View**:
.. code-block:: python
class ValidateEmailView(HTMXView):
def post(self, request, *args, **kwargs):
email = request.POST.get('email', '')
# Validate email
errors = []
if not email:
errors.append("Email is required")
elif User.objects.filter(email=email).exists():
errors.append("Email already registered")
elif not '@' in email:
errors.append("Invalid email format")
if errors:
return HttpResponse(
f'
Form Submission with Error Handling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Handle validation errors and display them inline:
**View**:
.. code-block:: python
from django import forms
from django.contrib import messages
class TeamForm(forms.ModelForm):
class Meta:
model = Team
fields = ['name', 'description']
def clean_name(self):
name = self.cleaned_data.get('name')
if Team.objects.filter(name__iexact=name).exists():
raise forms.ValidationError("A team with this name already exists")
return name
class CreateTeamView(HTMXView):
template_name = "components/forms/form_team.html"
oob_templates = {
"team-list": "components/lists/list_teams.html"
}
def get(self, request, *args, **kwargs):
self.context['form'] = TeamForm()
return self.render(request)
def post(self, request, *args, **kwargs):
form = TeamForm(request.POST)
if form.is_valid():
team = form.save(commit=False)
team.save()
# Add creator as owner
TeamMember.objects.create(
team=team,
user=request.user,
role=Role.OWNER.value
)
messages.success(request, f'Team "{team.name}" created successfully!')
# Update both form area and team list
self.context['teams'] = request.user.teams.all()
return self.render(
request,
template_name="components/forms/form_team_success.html"
)
# Re-render form with errors
self.context['form'] = form
return self.render(request)
**Template** (``components/forms/form_team.html``):
.. code-block:: django
{% extends "components/_component_base.html" %}
{% block content %}
{% endblock %}
Multi-Step Forms
^^^^^^^^^^^^^^^^
Implement wizard-style forms with HTMX:
**View**:
.. code-block:: python
class TeamOnboardingWizard(HTMXView):
template_name = "components/forms/wizard_step.html"
def get(self, request, *args, **kwargs):
step = request.GET.get('step', '1')
if step == '1':
self.context.update({
'step': 1,
'step_title': 'Create Your Team',
'form': TeamBasicInfoForm(),
'next_url': '?step=2',
})
elif step == '2':
self.context.update({
'step': 2,
'step_title': 'Invite Team Members',
'form': TeamInviteForm(),
'next_url': '?step=3',
'prev_url': '?step=1',
})
elif step == '3':
self.context.update({
'step': 3,
'step_title': 'Customize Settings',
'form': TeamSettingsForm(),
'prev_url': '?step=2',
'is_final': True,
})
return self.render(request)
def post(self, request, *args, **kwargs):
step = request.GET.get('step', '1')
# Store data in session and progress to next step
if step == '1':
form = TeamBasicInfoForm(request.POST)
if form.is_valid():
request.session['team_data'] = form.cleaned_data
return self.get(request, step='2')
elif step == '2':
form = TeamInviteForm(request.POST)
if form.is_valid():
request.session['invite_data'] = form.cleaned_data
return self.get(request, step='3')
elif step == '3':
form = TeamSettingsForm(request.POST)
if form.is_valid():
# Create team with all collected data
team = self.create_team(
request.session.get('team_data'),
request.session.get('invite_data'),
form.cleaned_data
)
# Clear session data
request.session.pop('team_data', None)
request.session.pop('invite_data', None)
messages.success(request, "Team created successfully!")
from django_htmx import http as htmx
response = HttpResponse("")
return htmx.redirect(response, reverse('team:detail', kwargs={'team_id': team.id}))
# Re-render current step with errors
self.context['form'] = form
self.context['step'] = step
return self.render(request)
Dynamic Form Fields
^^^^^^^^^^^^^^^^^^^
Add or remove form fields dynamically:
**View**:
.. code-block:: python
class AddFormFieldView(HTMXView):
template_name = "components/forms/field_email_invite.html"
def get(self, request, *args, **kwargs):
field_index = request.GET.get('index', '0')
self.context['field_index'] = field_index
return self.render(request)
**Template**:
.. code-block:: django
{# components/forms/form_invite_members.html #}
{# components/forms/field_email_invite.html #}
{% extends "partial.html" %}
{% block content %}
{% endblock %}
Out-of-Band Updates
===================
Understanding OOB Swaps
-----------------------
Out-of-band (OOB) updates allow HTMX to update multiple page elements in a single response. The response contains:
1. **Primary content**: Targets the element specified in ``hx-target``
2. **OOB content**: Updates other elements marked with ``hx-swap-oob="true"``
**Example Response**:
.. code-block:: html
Multi-Region Updates
--------------------
Update multiple page sections simultaneously:
**View**:
.. code-block:: python
class TeamDashboardUpdate(TeamSessionMixin, HTMXView):
template_name = "components/team_dashboard_content.html"
oob_templates = {
"team-stats": "components/team_stats.html",
"team-activity": "components/team_activity.html",
"team-members-summary": "components/team_members_summary.html",
}
active_nav = "dashboard"
push_url = "/dashboard/"
def get(self, request, *args, **kwargs):
self.context.update({
'team': self.team,
'recent_activity': self.team.get_recent_activity(),
'stats': {
'member_count': self.team.members.count(),
'project_count': self.team.projects.count(),
'task_count': self.team.tasks.filter(status='open').count(),
},
'members': self.team.members.all()[:5],
})
return self.render(request)
**Template Flow**:
.. code-block:: django
{# Main content template #}
{% extends "components/_component_base.html" %}
{% block content %}
{% endblock %}
{# Stats component (OOB) #}
{% if is_oob %}
{% endif %}
**4. Document Context Requirements**
Add a comment block describing required context variables:
.. code-block:: django
{% comment %}
Component: Team Member Card
Required Context:
- member: TeamMember object
- can_manage: boolean, whether user can edit/remove member
Optional Context:
- show_role: boolean, whether to display role badge (default: True)
Usage:
{% include "components/cards/card_team_member.html" with member=member can_manage=True %}
{% endcomment %}
**5. Make Components Flexible**
Use context defaults and conditionals:
.. code-block:: django
{% load static %}
{{ member.user.name }}
{{ member.user.email }}
{% if show_role|default:True %} {{ member.get_role_display }} {% endif %}Team Members ({{ members|length }})
{% if can_manage %} {% endif %}
{% for member in members %}
{% endif %}
{% empty %}
{% endfor %}
{% if member.user.avatar %}
{% else %}
{% else %}
{{ member.user.name|first|upper }}
{% endif %}
{{ member.user.name }}
{{ member.user.email }}
{{ member.get_role_display }}
{% if can_manage and member.role != 'owner' %}
No team members yet.
{% if can_manage %} {% endif %}{{ modal_title }}
{errors[0]}
',
status=400
)
return HttpResponse(
' Available
'
)
**Template**:
.. code-block:: django
Teams: 5
Team created!