Skip to content

Commit f80b27e

Browse files
JohananOppongAmoatengadamghill
authored andcommitted
Docs: Add Context Processors and Component Re-rendering section
1 parent 08de8dd commit f80b27e

File tree

1 file changed

+87
-0
lines changed

1 file changed

+87
-0
lines changed

docs/source/templates.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -232,3 +232,90 @@ class JsView(UnicornView):
232232
print("select_state selected_idx", selected_idx)
233233
self.selected_state = state_name
234234
```
235+
236+
## Context Processors and Component Re-rendering
237+
238+
Django context processors are executed when Django builds a `RequestContext`
239+
during a full template render. Because django-unicorn performs partial,
240+
component-level rendering, context processors are **not automatically re-run**
241+
during component updates or when `force_render` is used.
242+
243+
### Understanding the Difference
244+
245+
In a traditional Django request/response cycle:
246+
247+
1. A request is received
248+
2. A view prepares context data
249+
3. Context processors run
250+
4. The template is rendered
251+
252+
In django-unicorn, component updates work differently:
253+
254+
1. A request triggers a component action
255+
2. The component state is updated
256+
3. Only the component template is re-rendered
257+
4. The DOM is patched with the updated HTML
258+
259+
Since django-unicorn does not rebuild the full Django template rendering
260+
pipeline for component updates, context processors are not executed again.
261+
262+
### Force Render Behavior
263+
264+
Setting `force_render = True` on a component or parent component triggers a
265+
template re-evaluation using the existing component state. It does **not**
266+
recreate the full Django `RequestContext` and does not re-run context processors.
267+
268+
This is intentional and helps maintain performance by avoiding unnecessary
269+
recomputation and database queries.
270+
271+
### Recommended Patterns
272+
273+
If you need values from settings or global context to persist across component
274+
updates, consider one of the following approaches.
275+
276+
#### Store Values in Component State
277+
278+
Instead of relying on context processors, store values directly in the component:
279+
280+
```python
281+
from django.conf import settings
282+
from django_unicorn.components import UnicornView
283+
284+
285+
class ExampleView(UnicornView):
286+
my_flag = settings.MY_FLAG
287+
```
288+
289+
#### Use Lifecycle Hooks
290+
291+
If values must be refreshed periodically, update them during lifecycle events:
292+
293+
```python
294+
def hydrate(self):
295+
self.my_flag = settings.MY_FLAG
296+
```
297+
298+
#### Pass Values Explicitly
299+
300+
If using nested components, pass values through component parameters rather
301+
than relying on template context.
302+
303+
### When to Use Context Processors
304+
305+
Context processors are still useful for:
306+
307+
* Initial page rendering
308+
* Global template values shared across many pages
309+
* Request-specific data (e.g., user, permissions)
310+
311+
However, they should not be relied upon for reactive UI state inside components.
312+
313+
### Performance Considerations
314+
315+
Context processors run during template rendering and may execute database
316+
queries or other expensive operations. Automatically running them during every
317+
component update would negatively impact performance and network efficiency.
318+
319+
For this reason, django-unicorn keeps component rendering separate from Django's
320+
request-level context processing.
321+

0 commit comments

Comments
 (0)