mirrors/django-components
1
0
Fork 0
mirror of https://github.com/django-components/django-components.git synced 2025-08-04 06:18:17 +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

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.
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),
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)).
[`{% 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](../../concepts/advanced/rendering_js_css/#js-and-css-output-locations)).
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">`).
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),
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)).
[`{% 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](../../concepts/advanced/rendering_js_css/#js-and-css-output-locations)).
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.
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:
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:
```python title="[project root]/components/calendar/calendar.py"
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),
2. Relative to any of the component directories as defined by
[`COMPONENTS.dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.dirs)
and/or [`COMPONENTS.app_dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.app_dirs)
[`COMPONENTS.dirs`](../../reference/settings#django_components.app_settings.ComponentsSettings.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`)
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
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),
with a few differences:
@ -264,8 +264,8 @@ class Calendar(Component):
1. Relative to the Python component file (as seen above),
2. Relative to any of the component directories as defined by
[`COMPONENTS.dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.dirs)
and/or [`COMPONENTS.app_dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.app_dirs)
[`COMPONENTS.dirs`](../../reference/settings#django_components.app_settings.ComponentsSettings.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`)
!!! 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
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
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...
- `{% 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.
### 2. Add a slot tag
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
<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" %}`
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.
### 3. Add fill tag
Now we can use [`{% fill %}`](../../reference/template_tags.md#fill) tags inside the
[`{% component %}`](../../reference/template_tags.md#component) tags to override the `date` slot
Now we can use [`{% fill %}`](../../reference/template_tags#fill) tags inside the
[`{% component %}`](../../reference/template_tags#component) tags to override the `date` slot
to generate the bold and italics variants:
```htmldjango
@ -117,15 +117,15 @@ Which will render as:
{% endcomponent %}
```
2. Implicitly as the [default slot](../fundamentals/slots.md#default-slot) (Omitting the
[`{% fill %}`](../../reference/template_tags.md#fill) tag)
2. Implicitly as the [default slot](../../concepts/fundamentals/slots#default-slot) (Omitting the
[`{% fill %}`](../../reference/template_tags#fill) tag)
```htmldjango
{% component "calendar" date="2024-12-13" %}
<i> 2024-12-13 </i>
{% 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
{% component "calendar" date="2024-12-13" %}
{% 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`!
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:
```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.
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:
1. Pass the `date` variable to the [`{% slot %}`](../../reference/template_tags.md#slot) tag
2. Access the `date` variable in the [`{% fill %}`](../../reference/template_tags.md#fill)
1. Pass the `date` variable to the [`{% slot %}`](../../reference/template_tags#slot) tag
2. Access the `date` variable in the [`{% fill %}`](../../reference/template_tags#fill)
tag by using the special `data` kwarg
Let's update the Calendar's template:
@ -210,7 +210,7 @@ Let's update the Calendar's template:
!!! 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
{% slot "date" / %}
@ -222,7 +222,7 @@ Let's update the Calendar's template:
{% 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.
```htmldjango
@ -231,10 +231,10 @@ Let's update the Calendar's template:
### 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 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`:

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
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),
we will use the [`@register`](../../../reference/api#django_components.register)
To register a component with a [`ComponentRegistry`](../../reference/api#django_components.ComponentRegistry),
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:
```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 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`.
That way, when you include `{% load component_tags %}` in your template, you are able to "call" components
like `{% component "calendar" / %}`.
`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
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.
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,
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
@ -102,7 +102,7 @@ and render the component inside a template:
!!! 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:
```htmldjango
@ -157,19 +157,19 @@ and keeping your CSS and Javascript in the static directory.
!!! info
Remember that you can use
[`{% component_js_dependencies %}`](../../reference/template_tags.md#component_js_dependencies)
and [`{% component_css_dependencies %}`](../../reference/template_tags.md#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)).
[`{% component_js_dependencies %}`](../../reference/template_tags#component_js_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](../../concepts/advanced/rendering_js_css/#js-and-css-output-locations)).
!!! info
**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.
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:

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
In section [Create your first component](./your_first_component.md), we defined
the [`get_context_data()`](../../../reference/api#django_components.Component.get_context_data) method
In section [Create your first component](../your_first_component), we defined
the [`get_context_data()`](../../reference/api#django_components.Component.get_context_data) method
that defines what variables will be available within the template:
```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.
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`
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:
```python title="[project root]/components/calendar/calendar.py"
@ -77,12 +77,12 @@ class Calendar(Component):
!!! 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.
!!! 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.
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`
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
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

18
docs/getting_started/your_first_component.md
View file

@ -72,7 +72,7 @@ class Calendar(Component):
!!! note
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.
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
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.
!!! note
@ -115,10 +115,10 @@ when creating an instance of this component.
### 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 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.
```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),
2. Relative to any of the component directories as defined by
[`COMPONENTS.dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.dirs)
and/or [`COMPONENTS.app_dirs`](../../reference/settings.md#django_components.app_settings.ComponentsSettings.app_dirs)
[`COMPONENTS.dirs`](../../reference/settings#django_components.app_settings.ComponentsSettings.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`)
### 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.
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
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:
```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).