mirrors/django-components
1
0
Fork 0
mirror of https://github.com/django-components/django-components.git synced 2025-09-26 15:39:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: fix links in getting started section + few other (#1026)

Browse source
This commit is contained in:
Juro Oravec 2025-03-17 08:55:42 +01:00 • committed by GitHub
parent 12a64f8e41
commit 8e7acd82be
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 83 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

14
docs/concepts/fundamentals/components_in_python.md
View file

@ -119,15 +119,15 @@ If you want to use a different Response class in `render_to_response`, set the `
```py ```py
class MyResponse(HttpResponse): class MyResponse(HttpResponse):
def __init__(self, *args, **kwargs) -> None: def __init__(self, *args, **kwargs) -> None:
super().__init__(*args, **kwargs) super().__init__(*args, **kwargs)
# Configure response # Configure response
self.headers = ... self.headers = ...
self.status = ... self.status = ...
class SimpleComponent(Component): class SimpleComponent(Component):
response_class = MyResponse response_class = MyResponse
template: types.django_html = "HELLO" template: types.django_html = "HELLO"
response = SimpleComponent.render_to_response() response = SimpleComponent.render_to_response()
assert isinstance(response, MyResponse) assert isinstance(response, MyResponse)

22
docs/getting_started/adding_js_and_css.md
View file

@ -51,8 +51,8 @@ Be sure to prefix your rules with unique CSS class like `calendar`, so the CSS d
about CSS class clashes. about CSS class clashes.
This CSS will be inserted into the page as an inlined `<style>` tag, at the position defined by This CSS will be inserted into the page as an inlined `<style>` tag, at the position defined by
[`{% component_css_dependencies %}`](../../reference/template_tags.md#component_css_dependencies), [`{% component_css_dependencies %}`](../../reference/template_tags#component_css_dependencies),
or at the end of the inside the `<head>` tag (See [JS and CSS output locations](../../advanced/rendering_js_css/#js-and-css-output-locations)). or at the end of the inside the `<head>` tag (See [JS and CSS output locations](../../concepts/advanced/rendering_js_css/#js-and-css-output-locations)).
So in your HTML, you may see something like this: So in your HTML, you may see something like this:
@ -102,8 +102,8 @@ This makes all variables defined only be defined inside this component and not a
(except for JS defined with `<script type="module">`). (except for JS defined with `<script type="module">`).
Similarly to CSS, JS will be inserted into the page as an inlined `<script>` tag, at the position defined by Similarly to CSS, JS will be inserted into the page as an inlined `<script>` tag, at the position defined by
[`{% component_js_dependencies %}`](../../reference/template_tags.md#component_js_dependencies), [`{% component_js_dependencies %}`](../../reference/template_tags#component_js_dependencies),
or at the end of the inside the `<body>` tag (See [JS and CSS output locations](../../advanced/rendering_js_css/#js-and-css-output-locations)). or at the end of the inside the `<body>` tag (See [JS and CSS output locations](../../concepts/advanced/rendering_js_css/#js-and-css-output-locations)).
So in your HTML, you may see something like this: So in your HTML, you may see something like this:
@ -173,8 +173,8 @@ So in your HTML, you may see something like this:
Finally, we return to our Python component in `calendar.py` to tie this together. Finally, we return to our Python component in `calendar.py` to tie this together.
To link JS and CSS defined in other files, use [`js_file`](../../../reference/api#django_components.Component.js_file) To link JS and CSS defined in other files, use [`js_file`](../../reference/api#django_components.Component.js_file)
and [`css_file`](../../../reference/api#django_components.Component.css_file) attributes: and [`css_file`](../../reference/api#django_components.Component.css_file) attributes:
```python title="[project root]/components/calendar/calendar.py" ```python title="[project root]/components/calendar/calendar.py"
from django_components import Component from django_components import Component
@ -199,8 +199,8 @@ automatically embed the associated JS and CSS.
1. Relative to the Python component file (as seen above), 1. Relative to the Python component file (as seen above),
2. Relative to any of the component directories as defined by 2. Relative to any of the component directories as defined by
[`COMPONENTS.dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.dirs) [`COMPONENTS.dirs`](../../reference/settings#django_components.app_settings.ComponentsSettings.dirs)
and/or [`COMPONENTS.app_dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.app_dirs) and/or [`COMPONENTS.app_dirs`](../../reference/settings#django_components.app_settings.ComponentsSettings.app_dirs)
(e.g. `[your apps]/components` dir and `[project root]/components`) (e.g. `[your apps]/components` dir and `[project root]/components`)
3. Relative to any of the directories defined by `STATICFILES_DIRS`. 3. Relative to any of the directories defined by `STATICFILES_DIRS`.
@ -223,7 +223,7 @@ automatically embed the associated JS and CSS.
### 5. Link additional JS and CSS to a component ### 5. Link additional JS and CSS to a component
Your components may depend on third-party packages or styling, or other shared logic. Your components may depend on third-party packages or styling, or other shared logic.
To load these additional dependencies, you can use a nested [`Media` class](../../../reference/api#django_components.Component.Media). To load these additional dependencies, you can use a nested [`Media` class](../../reference/api#django_components.Component.Media).
This `Media` class behaves similarly to [Django's Media class](https://docs.djangoproject.com/en/5.1/topics/forms/media/#assets-as-a-static-definition), This `Media` class behaves similarly to [Django's Media class](https://docs.djangoproject.com/en/5.1/topics/forms/media/#assets-as-a-static-definition),
with a few differences: with a few differences:
@ -264,8 +264,8 @@ class Calendar(Component):
1. Relative to the Python component file (as seen above), 1. Relative to the Python component file (as seen above),
2. Relative to any of the component directories as defined by 2. Relative to any of the component directories as defined by
[`COMPONENTS.dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.dirs) [`COMPONENTS.dirs`](../../reference/settings#django_components.app_settings.ComponentsSettings.dirs)
and/or [`COMPONENTS.app_dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.app_dirs) and/or [`COMPONENTS.app_dirs`](../../reference/settings#django_components.app_settings.ComponentsSettings.app_dirs)
(e.g. `[your apps]/components` dir and `[project root]/components`) (e.g. `[your apps]/components` dir and `[project root]/components`)
!!! info !!! info

36
docs/getting_started/adding_slots.md
View file

@ -25,7 +25,7 @@ implementation. And for the sake of demonstration, we'll solve this challenge wi
### 1. What are slots ### 1. What are slots
Components support something called [Slots](../fundamentals/slots.md). Components support something called [Slots](../../concepts/fundamentals/slots).
When a component is used inside another template, slots allow the parent template When a component is used inside another template, slots allow the parent template
to override specific parts of the child component by passing in different content. to override specific parts of the child component by passing in different content.
@ -37,13 +37,13 @@ This behavior is similar to [slots in Vue](https://vuejs.org/guide/components/sl
In the example below we introduce two tags that work hand in hand to make this work. These are... In the example below we introduce two tags that work hand in hand to make this work. These are...
- `{% slot <name> %}`/`{% endslot %}`: Declares a new slot in the component template. - `{% slot <name> %}`/`{% endslot %}`: Declares a new slot in the component template.
- `{% fill <name> %}`/`{% endfill %}`: (Used inside a [`{% component %}`](../../reference/template_tags.md#component) - `{% fill <name> %}`/`{% endfill %}`: (Used inside a [`{% component %}`](../../reference/template_tags#component)
tag pair.) Fills a declared slot with the specified content. tag pair.) Fills a declared slot with the specified content.
### 2. Add a slot tag ### 2. Add a slot tag
Let's update our calendar component to support more customization. We'll add Let's update our calendar component to support more customization. We'll add
[`{% slot %}`](../../reference/template_tags.md#slot) tag to the template: [`{% slot %}`](../../reference/template_tags#slot) tag to the template:
```htmldjango ```htmldjango
<div class="calendar"> <div class="calendar">
@ -58,15 +58,15 @@ Notice that:
1. We named the slot `date` - so we can fill this slot by using `{% fill "date" %}` 1. We named the slot `date` - so we can fill this slot by using `{% fill "date" %}`
2. We also made it the [default slot](../fundamentals/slots.md#default-slot). 2. We also made it the [default slot](../../concepts/fundamentals/slots#default-slot).
3. We placed our original implementation inside the [`{% slot %}`](../../reference/template_tags.md#slot) 3. We placed our original implementation inside the [`{% slot %}`](../../reference/template_tags#slot)
tag - this is what will be rendered when the slot is NOT overriden. tag - this is what will be rendered when the slot is NOT overriden.
### 3. Add fill tag ### 3. Add fill tag
Now we can use [`{% fill %}`](../../reference/template_tags.md#fill) tags inside the Now we can use [`{% fill %}`](../../reference/template_tags#fill) tags inside the
[`{% component %}`](../../reference/template_tags.md#component) tags to override the `date` slot [`{% component %}`](../../reference/template_tags#component) tags to override the `date` slot
to generate the bold and italics variants: to generate the bold and italics variants:
```htmldjango ```htmldjango
@ -117,15 +117,15 @@ Which will render as:
{% endcomponent %} {% endcomponent %}
``` ```
2. Implicitly as the [default slot](../fundamentals/slots.md#default-slot) (Omitting the 2. Implicitly as the [default slot](../../concepts/fundamentals/slots#default-slot) (Omitting the
[`{% fill %}`](../../reference/template_tags.md#fill) tag) [`{% fill %}`](../../reference/template_tags#fill) tag)
```htmldjango ```htmldjango
{% component "calendar" date="2024-12-13" %} {% component "calendar" date="2024-12-13" %}
<i> 2024-12-13 </i> <i> 2024-12-13 </i>
{% endcomponent %} {% endcomponent %}
``` ```
3. Explicitly as the [default slot](../fundamentals/slots.md#default-slot) (Setting fill name to `default`) 3. Explicitly as the [default slot](../../concepts/fundamentals/slots#default-slot) (Setting fill name to `default`)
```htmldjango ```htmldjango
{% component "calendar" date="2024-12-13" %} {% component "calendar" date="2024-12-13" %}
{% fill "default" %} {% fill "default" %}
@ -158,7 +158,7 @@ the to `2024-12-14`, which is Saturday, our template from previous step would re
The first instance rendered `2024-12-16`, while the rest rendered `2024-12-14`! The first instance rendered `2024-12-16`, while the rest rendered `2024-12-14`!
Why? Remember that in the [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data) Why? Remember that in the [`get_context_data()`](../../reference/api#django_components.Component.get_context_data)
method of our Calendar component, we pre-process the date. If the date falls on Saturday or Sunday, we shift it to next Monday: method of our Calendar component, we pre-process the date. If the date falls on Saturday or Sunday, we shift it to next Monday:
```python title="[project root]/components/calendar/calendar.py" ```python title="[project root]/components/calendar/calendar.py"
@ -189,12 +189,12 @@ which is NOT the same as the `date` variable used inside Calendar's template.
We want to use the same `date` variable that's used inside Calendar's template. We want to use the same `date` variable that's used inside Calendar's template.
Luckily, django-components allows passing data to the slot, also known as [Scoped slots](../fundamentals/slots.md#scoped-slots). Luckily, django-components allows passing data to the slot, also known as [Scoped slots](../../concepts/fundamentals/slots#scoped-slots).
This consists of two steps: This consists of two steps:
1. Pass the `date` variable to the [`{% slot %}`](../../reference/template_tags.md#slot) tag 1. Pass the `date` variable to the [`{% slot %}`](../../reference/template_tags#slot) tag
2. Access the `date` variable in the [`{% fill %}`](../../reference/template_tags.md#fill) 2. Access the `date` variable in the [`{% fill %}`](../../reference/template_tags#fill)
tag by using the special `data` kwarg tag by using the special `data` kwarg
Let's update the Calendar's template: Let's update the Calendar's template:
@ -210,7 +210,7 @@ Let's update the Calendar's template:
!!! info !!! info
The [`{% slot %}`](../../reference/template_tags.md#slot) tag has one special kwarg, `name`. When you write The [`{% slot %}`](../../reference/template_tags#slot) tag has one special kwarg, `name`. When you write
```htmldjango ```htmldjango
{% slot "date" / %} {% slot "date" / %}
@ -222,7 +222,7 @@ Let's update the Calendar's template:
{% slot name="date" / %} {% slot name="date" / %}
``` ```
Other than the `name` kwarg, you can pass any extra kwargs to the [`{% slot %}`](../../reference/template_tags.md#slot) tag, Other than the `name` kwarg, you can pass any extra kwargs to the [`{% slot %}`](../../reference/template_tags#slot) tag,
and these will be exposed as the slot's data. and these will be exposed as the slot's data.
```htmldjango ```htmldjango
@ -231,10 +231,10 @@ Let's update the Calendar's template:
### 6. Accessing slot data in fills ### 6. Accessing slot data in fills
Now, on the [`{% fill %}`](../../reference/template_tags.md#fill) tags, we can use the `data` kwarg to specify the variable under which Now, on the [`{% fill %}`](../../reference/template_tags#fill) tags, we can use the `data` kwarg to specify the variable under which
the slot data will be available. the slot data will be available.
The variable from the `data` kwarg contains all the extra kwargs passed to the [`{% slot %}`](../../reference/template_tags.md#slot) tag. The variable from the `data` kwarg contains all the extra kwargs passed to the [`{% slot %}`](../../reference/template_tags#slot) tag.
So if we set `data="slot_data"`, then we can access the date variable under `slot_data.date`: So if we set `data="slot_data"`, then we can access the date variable under `slot_data.date`:

26
docs/getting_started/components_in_templates.md
View file

@ -15,10 +15,10 @@ By the end of this section, we want to be able to use our components in Django t
### 1. Register component ### 1. Register component
First, however, we need to register our component class with [`ComponentRegistry`](../../../reference/api#django_components.ComponentRegistry). First, however, we need to register our component class with [`ComponentRegistry`](../../reference/api#django_components.ComponentRegistry).
To register a component with a [`ComponentRegistry`](../../../reference/api#django_components.ComponentRegistry), To register a component with a [`ComponentRegistry`](../../reference/api#django_components.ComponentRegistry),
we will use the [`@register`](../../../reference/api#django_components.register) we will use the [`@register`](../../reference/api#django_components.register)
decorator, and give it a name under which the component will be accessible from within the template: decorator, and give it a name under which the component will be accessible from within the template:
```python title="[project root]/components/calendar/calendar.py" ```python title="[project root]/components/calendar/calendar.py"
@ -48,18 +48,18 @@ by calling `{% load component_tags %}` inside the template.
In Django, template tags are managed by the `Library` instances. Whenever you include `{% load xxx %}` In Django, template tags are managed by the `Library` instances. Whenever you include `{% load xxx %}`
in your template, you are loading a `Library` instance into your template. in your template, you are loading a `Library` instance into your template.
[`ComponentRegistry`](../../../reference/api#django_components.ComponentRegistry) acts like a router [`ComponentRegistry`](../../reference/api#django_components.ComponentRegistry) acts like a router
and connects the registered components with the associated `Library`. and connects the registered components with the associated `Library`.
That way, when you include `{% load component_tags %}` in your template, you are able to "call" components That way, when you include `{% load component_tags %}` in your template, you are able to "call" components
like `{% component "calendar" / %}`. like `{% component "calendar" / %}`.
`ComponentRegistries` also make it possible to group and share components as standalone packages. `ComponentRegistries` also make it possible to group and share components as standalone packages.
[Learn more here](../advanced/authoring_component_libraries.md). [Learn more here](../../concepts/advanced/authoring_component_libraries).
!!! note !!! note
You can create custom [`ComponentRegistry`](../../../reference/api#django_components.ComponentRegistry) You can create custom [`ComponentRegistry`](../../reference/api#django_components.ComponentRegistry)
instances, which will use different `Library` instances. instances, which will use different `Library` instances.
In that case you will have to load different libraries depending on which components you want to use: In that case you will have to load different libraries depending on which components you want to use:
@ -80,7 +80,7 @@ by calling `{% load component_tags %}` inside the template.
``` ```
Note that, because the tag name `component` is use by the default ComponentRegistry, Note that, because the tag name `component` is use by the default ComponentRegistry,
the custom registry was configured to use the tag `my_component` instead. [Read more here](../advanced/component_registry.md) the custom registry was configured to use the tag `my_component` instead. [Read more here](../../concepts/advanced/component_registry)
### 2. Load and use the component in template ### 2. Load and use the component in template
@ -102,7 +102,7 @@ and render the component inside a template:
!!! info !!! info
Component tags should end with `/` if they do not contain any [Slot fills](../fundamentals/slots.md). Component tags should end with `/` if they do not contain any [Slot fills](../../concepts/fundamentals/slots#slot-fills).
But you can also use `{% endcomponent %}` instead: But you can also use `{% endcomponent %}` instead:
```htmldjango ```htmldjango
@ -157,19 +157,19 @@ and keeping your CSS and Javascript in the static directory.
!!! info !!! info
Remember that you can use Remember that you can use
[`{% component_js_dependencies %}`](../../reference/template_tags.md#component_js_dependencies) [`{% component_js_dependencies %}`](../../reference/template_tags#component_js_dependencies)
and [`{% component_css_dependencies %}`](../../reference/template_tags.md#component_css_dependencies) and [`{% component_css_dependencies %}`](../../reference/template_tags#component_css_dependencies)
to change where the `<script>` and `<style>` tags will be rendered (See [JS and CSS output locations](../../advanced/rendering_js_css/#js-and-css-output-locations)). to change where the `<script>` and `<style>` tags will be rendered (See [JS and CSS output locations](../../concepts/advanced/rendering_js_css/#js-and-css-output-locations)).
!!! info !!! info
**How does django-components pick up registered components?** **How does django-components pick up registered components?**
Notice that it was enough to add [`@register`](../../../reference/api#django_components.register) to the component. Notice that it was enough to add [`@register`](../../reference/api#django_components.register) to the component.
We didn't need to import the component file anywhere to execute it. We didn't need to import the component file anywhere to execute it.
This is because django-components automatically imports all Python files found in the component directories This is because django-components automatically imports all Python files found in the component directories
during an event called [Autodiscovery](../fundamentals/autodiscovery.md). during an event called [Autodiscovery](../../concepts/fundamentals/autodiscovery).
So with Autodiscovery, it's the same as if you manually imported the component files on the `ready()` hook: So with Autodiscovery, it's the same as if you manually imported the component files on the `ready()` hook:

14
docs/getting_started/parametrising_components.md
View file

@ -9,8 +9,8 @@ What we want is to be able to use the Calendar component within the template lik
### 1. Understading component inputs ### 1. Understading component inputs
In section [Create your first component](./your_first_component.md), we defined In section [Create your first component](../your_first_component), we defined
the [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data) method the [`get_context_data()`](../../reference/api#django_components.Component.get_context_data) method
that defines what variables will be available within the template: that defines what variables will be available within the template:
```python title="[project root]/components/calendar/calendar.py" ```python title="[project root]/components/calendar/calendar.py"
@ -26,7 +26,7 @@ class Calendar(Component):
} }
``` ```
What we didn't say is that [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data) What we didn't say is that [`get_context_data()`](../../reference/api#django_components.Component.get_context_data)
actually receives the args and kwargs that were passed to a component. actually receives the args and kwargs that were passed to a component.
So if we call a component with a `date` and `extra_class` keywords: So if we call a component with a `date` and `extra_class` keywords:
@ -56,7 +56,7 @@ Calendar.get_context_data("2024-12-13", extra_class="text-red")
### 2. Define inputs for `get_context_data` ### 2. Define inputs for `get_context_data`
Let's put this to test. We want to pass `date` and `extra_class` kwargs to the component. Let's put this to test. We want to pass `date` and `extra_class` kwargs to the component.
And so, we can write the [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data) And so, we can write the [`get_context_data()`](../../reference/api#django_components.Component.get_context_data)
method such that it expects those parameters: method such that it expects those parameters:
```python title="[project root]/components/calendar/calendar.py" ```python title="[project root]/components/calendar/calendar.py"
@ -77,12 +77,12 @@ class Calendar(Component):
!!! info !!! info
Since [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data) Since [`get_context_data()`](../../reference/api#django_components.Component.get_context_data)
is just a regular Python function, type hints annotations work the same way as anywhere else. is just a regular Python function, type hints annotations work the same way as anywhere else.
!!! warning !!! warning
Since [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data) Since [`get_context_data()`](../../reference/api#django_components.Component.get_context_data)
is just a regular Python function, it will raise TypeError if it receives incorrect parameters. is just a regular Python function, it will raise TypeError if it receives incorrect parameters.
Since `extra_class` is optional in the function signature, it's optional also in the template. Since `extra_class` is optional in the function signature, it's optional also in the template.
@ -107,7 +107,7 @@ However, `date` is required. Thus we MUST provide it. Same with regular Python f
### 3. Process inputs in `get_context_data` ### 3. Process inputs in `get_context_data`
The [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data) The [`get_context_data()`](../../reference/api#django_components.Component.get_context_data)
method is powerful, because it allows us to decouple method is powerful, because it allows us to decouple
component inputs from the template variables. In other words, we can pre-process component inputs from the template variables. In other words, we can pre-process
the component inputs, and massage them into a shape that's most appropriate for the component inputs, and massage them into a shape that's most appropriate for

18
docs/getting_started/your_first_component.md
View file

@ -72,7 +72,7 @@ class Calendar(Component):
!!! note !!! note
If you "inline" the HTML, JS and CSS code into the Python class, you can set up If you "inline" the HTML, JS and CSS code into the Python class, you can set up
[syntax highlighting](../../guides/setup/syntax_highlight.md) for better experience. [syntax highlighting](../../guides/setup/syntax_highlight) for better experience.
However, autocompletion / intellisense does not work with syntax highlighting. However, autocompletion / intellisense does not work with syntax highlighting.
We'll start by creating a component that defines only a Django template: We'll start by creating a component that defines only a Django template:
@ -104,7 +104,7 @@ Inside `calendar.html`, write:
``` ```
In this example we've defined one template variable `date`. You can use any and as many variables as you like. These variables will be In this example we've defined one template variable `date`. You can use any and as many variables as you like. These variables will be
defined in the Python file in [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data) defined in the Python file in [`get_context_data()`](../../reference/api#django_components.Component.get_context_data)
when creating an instance of this component. when creating an instance of this component.
!!! note !!! note
@ -115,10 +115,10 @@ when creating an instance of this component.
### 3. Create new Component in Python ### 3. Create new Component in Python
In `calendar.py`, create a subclass of [Component](../../../reference/api#django_components.Component) In `calendar.py`, create a subclass of [Component](../../reference/api#django_components.Component)
to create a new component. to create a new component.
To link the HTML template with our component, set [`template_file`](../../../reference/api#django_components.Component.template_file) To link the HTML template with our component, set [`template_file`](../../reference/api#django_components.Component.template_file)
to the name of the HTML file. to the name of the HTML file.
```python title="[project root]/components/calendar/calendar.py" ```python title="[project root]/components/calendar/calendar.py"
@ -134,15 +134,15 @@ class Calendar(Component):
1. Relative to the component's python file (as seen above), 1. Relative to the component's python file (as seen above),
2. Relative to any of the component directories as defined by 2. Relative to any of the component directories as defined by
[`COMPONENTS.dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.dirs) [`COMPONENTS.dirs`](../../reference/settings#django_components.app_settings.ComponentsSettings.dirs)
and/or [`COMPONENTS.app_dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.app_dirs) and/or [`COMPONENTS.app_dirs`](../../reference/settings#django_components.app_settings.ComponentsSettings.app_dirs)
(e.g. `[your apps]/components` dir and `[project root]/components`) (e.g. `[your apps]/components` dir and `[project root]/components`)
### 4. Define the template variables ### 4. Define the template variables
In `calendar.html`, we've used the variable `date`. So we need to define it for the template to work. In `calendar.html`, we've used the variable `date`. So we need to define it for the template to work.
This is done using [`Component.get_context_data()`](../../../reference/api#django_components.Component.get_context_data). This is done using [`Component.get_context_data()`](../../reference/api#django_components.Component.get_context_data).
It's a function that returns a dictionary. The entries in this dictionary It's a function that returns a dictionary. The entries in this dictionary
will become available within the template as variables, e.g. as `{{ date }}`. will become available within the template as variables, e.g. as `{{ date }}`.
@ -158,7 +158,7 @@ class Calendar(Component):
} }
``` ```
Now, when we render the component with [`Component.render()`](../../../reference/api#django_components.Component.render) Now, when we render the component with [`Component.render()`](../../reference/api#django_components.Component.render)
method: method:
```py ```py
@ -177,4 +177,4 @@ And voilá!! We've created our first component.
--- ---
Next, [let's add JS and CSS to this component ➡️](./adding_js_and_css.md). Next, [let's add JS and CSS to this component ➡️](../adding_js_and_css).

19
docs/guides/setup/development_server.md
View file

@ -1,8 +1,21 @@
### Reload dev server on component file changes ## Reload dev server on component file changes
This is relevant if you are using the project structure as shown in our examples, where This is relevant if you are using the project structure as shown in our examples, where
HTML, JS, CSS and Python are in separate files and nested in a directory. HTML, JS, CSS and Python are in separate files and nested in a directory.
```
sampleproject/
├── components/
│ └── calendar/
│ ├── calendar.py
│ └── calendar.html
│ └── calendar.css
│ └── calendar.js
├── sampleproject/
├── manage.py
└── requirements.txt
```
In this case you may notice that when you are running a development server, In this case you may notice that when you are running a development server,
the server sometimes does not reload when you change component files. the server sometimes does not reload when you change component files.
@ -12,10 +25,10 @@ From relevant [StackOverflow thread](https://stackoverflow.com/a/76722393/978863
> or in a nested sub directory of a templates directory. This is by design. > or in a nested sub directory of a templates directory. This is by design.
To make the dev server reload on all component files, set To make the dev server reload on all component files, set
[`reload_on_file_change`](#reload_on_file_change---reload-dev-server-on-component-file-changes) [`reload_on_file_change`](../../../reference/settings#django_components.app_settings.ComponentsSettings.reload_on_file_change)
to `True`. to `True`.
This configures Django to watch for component files too. This configures Django to watch for component files too.
!!! note !!! warning
This setting should be enabled only for the dev environment! This setting should be enabled only for the dev environment!

2
docs/reference/template_vars.md
View file

@ -3,7 +3,7 @@
# Template variables # Template variables
Here is a list of all variables that are automatically available from inside the component's Here is a list of all variables that are automatically available from inside the component's
template and in [`on_render_before` / `on_render_after`](../concepts/advanced/hooks.md##available-hooks) template and in [`on_render_before` / `on_render_after`](../concepts/advanced/hooks.md#available-hooks)
hooks. hooks.

2
docs/templates/reference_templatevars.md vendored
View file

@ -1,5 +1,5 @@
# Template variables # Template variables
Here is a list of all variables that are automatically available from inside the component's Here is a list of all variables that are automatically available from inside the component's
template and in [`on_render_before` / `on_render_after`](../concepts/advanced/hooks.md##available-hooks) template and in [`on_render_before` / `on_render_after`](../concepts/advanced/hooks.md#available-hooks)
hooks. hooks.