mirror of
https://github.com/django-components/django-components.git
synced 2025-08-17 12:40:15 +00:00
refactor: add generated API docs to git (#802)
* refactor: add generated API docs to git * refactor: add comment to autogenerated files
This commit is contained in:
Juro Oravec
GitHub
parent
9879a0ab07
commit
a3710fe8cf
12 changed files with 1163 additions and 11 deletions
1
src/docs/.gitignore
vendored
1
src/docs/.gitignore
vendored
|
|
@ -1 +0,0 @@
|
|||
reference/
|
||||
105
src/docs/reference/api.md
Normal file
105
src/docs/reference/api.md
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
<!-- Autogenerated by reference.py -->
|
||||
|
||||
# API
|
||||
|
||||
|
||||
::: django_components.Component
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.ComponentFileEntry
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.ComponentRegistry
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.ComponentVars
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.ComponentView
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.ComponentsSettings
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.ContextBehavior
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.EmptyDict
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.EmptyTuple
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.RegistrySettings
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.Slot
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.SlotContent
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.SlotFunc
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.SlotRef
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.SlotResult
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.TagFormatterABC
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.TagResult
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.autodiscover
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.cached_template
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.get_component_dirs
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.get_component_files
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.import_libraries
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.register
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.registry
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.render_dependencies
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
166
src/docs/reference/commands.md
Normal file
166
src/docs/reference/commands.md
Normal file
|
|
@ -0,0 +1,166 @@
|
|||
<!-- Autogenerated by reference.py -->
|
||||
|
||||
# Commands
|
||||
|
||||
These are all the [Django management commands](https://docs.djangoproject.com/en/5.1/ref/django-admin)
|
||||
that will be added by installing `django_components`:
|
||||
|
||||
|
||||
## `upgradecomponent`
|
||||
|
||||
```txt
|
||||
usage: manage.py upgradecomponent [-h] [--path PATH] [--version] [-v {0,1,2,3}] [--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color]
|
||||
[--force-color] [--skip-checks]
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/management/commands/upgradecomponent.py#L12" target="_blank">See source code</a>
|
||||
|
||||
|
||||
|
||||
Updates component and component_block tags to the new syntax
|
||||
|
||||
**Options:**
|
||||
|
||||
- `-h`, `--help`
|
||||
- show this help message and exit
|
||||
- `--path PATH`
|
||||
- Path to search for components
|
||||
- `--version`
|
||||
- Show program's version number and exit.
|
||||
- `-v {0,1,2,3}`, `--verbosity {0,1,2,3}`
|
||||
- Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
|
||||
- `--settings SETTINGS`
|
||||
- The Python path to a settings module, e.g. "myproject.settings.main". If this isn't provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
|
||||
- `--pythonpath PYTHONPATH`
|
||||
- A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
|
||||
- `--traceback`
|
||||
- Raise on CommandError exceptions.
|
||||
- `--no-color`
|
||||
- Don't colorize the command output.
|
||||
- `--force-color`
|
||||
- Force colorization of the command output.
|
||||
- `--skip-checks`
|
||||
- Skip system checks.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## `startcomponent`
|
||||
|
||||
```txt
|
||||
usage: manage.py startcomponent [-h] [--path PATH] [--js JS] [--css CSS] [--template TEMPLATE] [--force] [--verbose] [--dry-run] [--version] [-v {0,1,2,3}]
|
||||
[--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color] [--skip-checks]
|
||||
name
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/management/commands/startcomponent.py#L8" target="_blank">See source code</a>
|
||||
|
||||
|
||||
|
||||
Create a new django component.
|
||||
|
||||
**Positional Arguments:**
|
||||
|
||||
- `name`
|
||||
- The name of the component to create. This is a required argument.
|
||||
|
||||
**Options:**
|
||||
|
||||
- `-h`, `--help`
|
||||
- show this help message and exit
|
||||
- `--path PATH`
|
||||
- The path to the component's directory. This is an optional argument. If not provided, the command will use the `COMPONENTS.dirs` setting from your Django settings.
|
||||
- `--js JS`
|
||||
- The name of the JavaScript file. This is an optional argument. The default value is `script.js`.
|
||||
- `--css CSS`
|
||||
- The name of the CSS file. This is an optional argument. The default value is `style.css`.
|
||||
- `--template TEMPLATE`
|
||||
- The name of the template file. This is an optional argument. The default value is `template.html`.
|
||||
- `--force`
|
||||
- This option allows you to overwrite existing files if they exist. This is an optional argument.
|
||||
- `--verbose`
|
||||
- This option allows the command to print additional information during component creation. This is an optional argument.
|
||||
- `--dry-run`
|
||||
- This option allows you to simulate component creation without actually creating any files. This is an optional argument. The default value is `False`.
|
||||
- `--version`
|
||||
- Show program's version number and exit.
|
||||
- `-v {0,1,2,3}`, `--verbosity {0,1,2,3}`
|
||||
- Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
|
||||
- `--settings SETTINGS`
|
||||
- The Python path to a settings module, e.g. "myproject.settings.main". If this isn't provided, the DJANGO_SETTINGS_MODULE environment variable will be used.
|
||||
- `--pythonpath PYTHONPATH`
|
||||
- A directory to add to the Python path, e.g. "/home/djangoprojects/myproject".
|
||||
- `--traceback`
|
||||
- Raise on CommandError exceptions.
|
||||
- `--no-color`
|
||||
- Don't colorize the command output.
|
||||
- `--force-color`
|
||||
- Force colorization of the command output.
|
||||
- `--skip-checks`
|
||||
- Skip system checks.
|
||||
|
||||
|
||||
|
||||
|
||||
### Management Command Usage
|
||||
|
||||
To use the command, run the following command in your terminal:
|
||||
|
||||
```bash
|
||||
python manage.py startcomponent <name> --path <path> --js <js_filename> --css <css_filename> --template <template_filename> --force --verbose --dry-run
|
||||
```
|
||||
|
||||
Replace `<name>`, `<path>`, `<js_filename>`, `<css_filename>`, and `<template_filename>` with your desired values.
|
||||
|
||||
### Management Command Examples
|
||||
|
||||
Here are some examples of how you can use the command:
|
||||
|
||||
#### Creating a Component with Default Settings
|
||||
|
||||
To create a component with the default settings, you only need to provide the name of the component:
|
||||
|
||||
```bash
|
||||
python manage.py startcomponent my_component
|
||||
```
|
||||
|
||||
This will create a new component named `my_component` in the `components` directory of your Django project. The JavaScript, CSS, and template files will be named `script.js`, `style.css`, and `template.html`, respectively.
|
||||
|
||||
#### Creating a Component with Custom Settings
|
||||
|
||||
You can also create a component with custom settings by providing additional arguments:
|
||||
|
||||
```bash
|
||||
python manage.py startcomponent new_component --path my_components --js my_script.js --css my_style.css --template my_template.html
|
||||
```
|
||||
|
||||
This will create a new component named `new_component` in the `my_components` directory. The JavaScript, CSS, and template files will be named `my_script.js`, `my_style.css`, and `my_template.html`, respectively.
|
||||
|
||||
#### Overwriting an Existing Component
|
||||
|
||||
If you want to overwrite an existing component, you can use the `--force` option:
|
||||
|
||||
```bash
|
||||
python manage.py startcomponent my_component --force
|
||||
```
|
||||
|
||||
This will overwrite the existing `my_component` if it exists.
|
||||
|
||||
#### Simulating Component Creation
|
||||
|
||||
If you want to simulate the creation of a component without actually creating any files, you can use the `--dry-run` option:
|
||||
|
||||
```bash
|
||||
python manage.py startcomponent my_component --dry-run
|
||||
```
|
||||
|
||||
This will simulate the creation of `my_component` without creating any files.
|
||||
|
||||
|
||||
15
src/docs/reference/components.md
Normal file
15
src/docs/reference/components.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
<!-- Autogenerated by reference.py -->
|
||||
|
||||
# Components
|
||||
|
||||
These are the components provided by django_components.
|
||||
|
||||
|
||||
::: django_components.components.dynamic.DynamicComponent
|
||||
options:
|
||||
inherited_members: false
|
||||
show_root_heading: true
|
||||
show_signature: false
|
||||
separate_signature: false
|
||||
members: false
|
||||
|
||||
17
src/docs/reference/exceptions.md
Normal file
17
src/docs/reference/exceptions.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
<!-- Autogenerated by reference.py -->
|
||||
|
||||
# Exceptions
|
||||
|
||||
|
||||
::: django_components.AlreadyRegistered
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.NotRegistered
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
::: django_components.TagProtectedError
|
||||
options:
|
||||
show_if_no_docstring: true
|
||||
|
||||
16
src/docs/reference/middlewares.md
Normal file
16
src/docs/reference/middlewares.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
<!-- Autogenerated by reference.py -->
|
||||
|
||||
# Middlewares
|
||||
|
||||
|
||||
::: django_components.dependencies.ComponentDependencyMiddleware
|
||||
options:
|
||||
inherited_members: false
|
||||
show_root_heading: true
|
||||
show_signature: false
|
||||
separate_signature: false
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
205
src/docs/reference/settings.md
Normal file
205
src/docs/reference/settings.md
Normal file
|
|
@ -0,0 +1,205 @@
|
|||
<!-- Autogenerated by reference.py -->
|
||||
|
||||
# Settings
|
||||
|
||||
You can configure django_components with a global `COMPONENTS` variable in your Django settings file, e.g. `settings.py`.
|
||||
By default you don't need it set, there are resonable [defaults](#settings-defaults).
|
||||
|
||||
To configure the settings you can instantiate [`ComponentsSettings`](../api#django_components.ComponentsSettings)
|
||||
for validation and type hints. Or, for backwards compatibility, you can also use plain dictionary:
|
||||
|
||||
```python
|
||||
# settings.py
|
||||
from django_components import ComponentsSettings
|
||||
|
||||
COMPONENTS = ComponentsSettings(
|
||||
autodiscover=True,
|
||||
...
|
||||
)
|
||||
|
||||
# or
|
||||
|
||||
COMPONENTS = {
|
||||
"autodiscover": True,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Settings defaults
|
||||
|
||||
Here's overview of all available settings and their defaults:
|
||||
|
||||
```py
|
||||
defaults = ComponentsSettings(
|
||||
autodiscover=True,
|
||||
context_behavior=ContextBehavior.DJANGO.value, # "django" | "isolated"
|
||||
# Root-level "components" dirs, e.g. `/path/to/proj/components/`
|
||||
dirs=[Path(settings.BASE_DIR) / "components"],
|
||||
# App-level "components" dirs, e.g. `[app]/components/`
|
||||
app_dirs=["components"],
|
||||
dynamic_component_name="dynamic",
|
||||
libraries=[], # E.g. ["mysite.components.forms", ...]
|
||||
multiline_tags=True,
|
||||
reload_on_file_change=False,
|
||||
static_files_allowed=[
|
||||
".css",
|
||||
".js", ".jsx", ".ts", ".tsx",
|
||||
# Images
|
||||
".apng", ".png", ".avif", ".gif", ".jpg",
|
||||
".jpeg", ".jfif", ".pjpeg", ".pjp", ".svg",
|
||||
".webp", ".bmp", ".ico", ".cur", ".tif", ".tiff",
|
||||
# Fonts
|
||||
".eot", ".ttf", ".woff", ".otf", ".svg",
|
||||
],
|
||||
static_files_forbidden=[
|
||||
# See https://marketplace.visualstudio.com/items?itemName=junstyle.vscode-django-support
|
||||
".html", ".django", ".dj", ".tpl",
|
||||
# Python files
|
||||
".py", ".pyc",
|
||||
],
|
||||
tag_formatter="django_components.component_formatter",
|
||||
template_cache_size=128,
|
||||
)
|
||||
```
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.app_dirs
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.autodiscover
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.context_behavior
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.dirs
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.dynamic_component_name
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.forbidden_static_files
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.libraries
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.multiline_tags
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.reload_on_file_change
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.reload_on_template_change
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.static_files_allowed
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.static_files_forbidden
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.tag_formatter
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
::: django_components.app_settings.ComponentsSettings.template_cache_size
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_signature: true
|
||||
separate_signature: true
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
|
||||
40
src/docs/reference/tag_formatters.md
Normal file
40
src/docs/reference/tag_formatters.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
<!-- Autogenerated by reference.py -->
|
||||
|
||||
# Tag Formatters
|
||||
|
||||
[Tag formatters](../../concepts/advanced/tag_formatter) allow you to change the syntax for calling components from within
|
||||
the Django templates.
|
||||
|
||||
Tag formatter are set via the [tag_formatter](../settings#django_components.app_settings.ComponentsSettings.tag_formatter)
|
||||
setting.
|
||||
|
||||
|
||||
### Available tag formatters
|
||||
|
||||
- `django_components.component_formatter` for [ComponentFormatter](#django_components.tag_formatter.ComponentFormatter)
|
||||
|
||||
- `django_components.component_shorthand_formatter` for [ShorthandComponentFormatter](#django_components.tag_formatter.ShorthandComponentFormatter)
|
||||
::: django_components.tag_formatter.ComponentFormatter
|
||||
options:
|
||||
inherited_members: false
|
||||
show_root_heading: true
|
||||
show_signature: false
|
||||
separate_signature: false
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
members: false
|
||||
|
||||
::: django_components.tag_formatter.ShorthandComponentFormatter
|
||||
options:
|
||||
inherited_members: false
|
||||
show_root_heading: true
|
||||
show_signature: false
|
||||
separate_signature: false
|
||||
show_symbol_type_heading: false
|
||||
show_symbol_type_toc: false
|
||||
show_if_no_docstring: true
|
||||
show_labels: false
|
||||
members: false
|
||||
|
||||
543
src/docs/reference/template_tags.md
Normal file
543
src/docs/reference/template_tags.md
Normal file
|
|
@ -0,0 +1,543 @@
|
|||
<!-- Autogenerated by reference.py -->
|
||||
|
||||
# Template tags
|
||||
|
||||
|
||||
All following template tags are defined in
|
||||
|
||||
`django_components.templatetags.component_tags`
|
||||
|
||||
Import as
|
||||
```django
|
||||
{% load component_tags %}
|
||||
```
|
||||
|
||||
## component
|
||||
|
||||
```django
|
||||
{% component [arg, ...] **kwargs [only] %}
|
||||
{% endcomponent %}
|
||||
```
|
||||
|
||||
|
||||
|
||||
<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
|
||||
|
||||
|
||||
|
||||
Renders one of the components that was previously registered with
|
||||
[`@register()`](./api.md#django_components.register)
|
||||
decorator.
|
||||
|
||||
**Args:**
|
||||
|
||||
- `name` (str, required): Registered name of the component to render
|
||||
- All other args and kwargs are defined based on the component itself.
|
||||
|
||||
If you defined a component `"my_table"`
|
||||
|
||||
```python
|
||||
from django_component import Component, register
|
||||
|
||||
@register("my_table")
|
||||
class MyTable(Component):
|
||||
template = """
|
||||
<table>
|
||||
<thead>
|
||||
{% for header in headers %}
|
||||
<th>{{ header }}</th>
|
||||
{% endfor %}
|
||||
</thead>
|
||||
<tbody>
|
||||
{% for row in rows %}
|
||||
<tr>
|
||||
{% for cell in row %}
|
||||
<td>{{ cell }}</td>
|
||||
{% endfor %}
|
||||
</tr>
|
||||
{% endfor %}
|
||||
<tbody>
|
||||
</table>
|
||||
"""
|
||||
|
||||
def get_context_data(self, rows: List, headers: List):
|
||||
return {
|
||||
"rows": rows,
|
||||
"headers": headers,
|
||||
}
|
||||
```
|
||||
|
||||
Then you can render this component by referring to `MyTable` via its
|
||||
registered name `"my_table"`:
|
||||
|
||||
```django
|
||||
{% component "my_table" rows=rows headers=headers ... / %}
|
||||
```
|
||||
|
||||
### Component input
|
||||
|
||||
Positional and keyword arguments can be literals or template variables.
|
||||
|
||||
The component name must be a single- or double-quotes string and must
|
||||
be either:
|
||||
|
||||
- The first positional argument after `component`:
|
||||
|
||||
```django
|
||||
{% component "my_table" rows=rows headers=headers ... / %}
|
||||
```
|
||||
|
||||
- Passed as kwarg `name`:
|
||||
|
||||
```django
|
||||
{% component rows=rows headers=headers name="my_table" ... / %}
|
||||
```
|
||||
|
||||
### Inserting into slots
|
||||
|
||||
If the component defined any [slots](../concepts/fundamentals/slots.md), you can
|
||||
pass in the content to be placed inside those slots by inserting [`{% fill %}`](#fill) tags,
|
||||
directly within the `{% component %}` tag:
|
||||
|
||||
```django
|
||||
{% component "my_table" rows=rows headers=headers ... / %}
|
||||
{% fill "pagination" %}
|
||||
< 1 | 2 | 3 >
|
||||
{% endfill %}
|
||||
{% endcomponent %}
|
||||
```
|
||||
|
||||
### Isolating components
|
||||
|
||||
By default, components behave similarly to Django's
|
||||
[`{% include %}`](https://docs.djangoproject.com/en/5.1/ref/templates/builtins/#include),
|
||||
and the template inside the component has access to the variables defined in the outer template.
|
||||
|
||||
You can selectively isolate a component, using the `only` flag, so that the inner template
|
||||
can access only the data that was explicitly passed to it:
|
||||
|
||||
```django
|
||||
{% component "name" positional_arg keyword_arg=value ... only %}
|
||||
```
|
||||
|
||||
## component_css_dependencies
|
||||
|
||||
```django
|
||||
{% component_css_dependencies %}
|
||||
```
|
||||
|
||||
|
||||
|
||||
<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
|
||||
|
||||
|
||||
|
||||
Marks location where CSS link tags should be rendered after the whole HTML has been generated.
|
||||
|
||||
Generally, this should be inserted into the `<head>` tag of the HTML.
|
||||
|
||||
If the generated HTML does NOT contain any `{% component_css_dependencies %}` tags, CSS links
|
||||
are by default inserted into the `<head>` tag of the HTML. (See
|
||||
[JS and CSS output locations](../../concepts/advanced/rendering_js_css/#js-and-css-output-locations))
|
||||
|
||||
Note that there should be only one `{% component_css_dependencies %}` for the whole HTML document.
|
||||
If you insert this tag multiple times, ALL CSS links will be duplicately inserted into ALL these places.
|
||||
|
||||
## component_js_dependencies
|
||||
|
||||
```django
|
||||
{% component_js_dependencies %}
|
||||
```
|
||||
|
||||
|
||||
|
||||
<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
|
||||
|
||||
|
||||
|
||||
Marks location where JS link tags should be rendered after the whole HTML has been generated.
|
||||
|
||||
Generally, this should be inserted at the end of the `<body>` tag of the HTML.
|
||||
|
||||
If the generated HTML does NOT contain any `{% component_js_dependencies %}` tags, JS scripts
|
||||
are by default inserted at the end of the `<body>` tag of the HTML. (See
|
||||
[JS and CSS output locations](../../concepts/advanced/rendering_js_css/#js-and-css-output-locations))
|
||||
|
||||
Note that there should be only one `{% component_js_dependencies %}` for the whole HTML document.
|
||||
If you insert this tag multiple times, ALL JS scripts will be duplicately inserted into ALL these places.
|
||||
|
||||
## fill
|
||||
|
||||
```django
|
||||
{% fill name data=None default=None %}
|
||||
{% endfill %}
|
||||
```
|
||||
|
||||
|
||||
|
||||
<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
|
||||
|
||||
|
||||
|
||||
Use this tag to insert content into component's slots.
|
||||
|
||||
`{% fill %}` tag may be used only within a `{% component %}..{% endcomponent %}` block.
|
||||
Runtime checks should prohibit other usages.
|
||||
|
||||
**Args:**
|
||||
|
||||
- `name` (str, required): Name of the slot to insert this content into. Use `"default"` for
|
||||
the default slot.
|
||||
- `default` (str, optional): This argument allows you to access the original content of the slot
|
||||
under the specified variable name. See
|
||||
[Accessing original content of slots](../../concepts/fundamentals/slots#accessing-original-content-of-slots)
|
||||
- `data` (str, optional): This argument allows you to access the data passed to the slot
|
||||
under the specified variable name. See [Scoped slots](../../concepts/fundamentals/slots#scoped-slots)
|
||||
|
||||
**Examples:**
|
||||
|
||||
Basic usage:
|
||||
```django
|
||||
{% component "my_table" %}
|
||||
{% fill "pagination" %}
|
||||
< 1 | 2 | 3 >
|
||||
{% endfill %}
|
||||
{% endcomponent %}
|
||||
```
|
||||
|
||||
### Accessing slot's default content with the `default` kwarg
|
||||
|
||||
```django
|
||||
{# my_table.html #}
|
||||
<table>
|
||||
...
|
||||
{% slot "pagination" %}
|
||||
< 1 | 2 | 3 >
|
||||
{% endslot %}
|
||||
</table>
|
||||
```
|
||||
|
||||
```django
|
||||
{% component "my_table" %}
|
||||
{% fill "pagination" default="default_pag" %}
|
||||
<div class="my-class">
|
||||
{{ default_pag }}
|
||||
</div>
|
||||
{% endfill %}
|
||||
{% endcomponent %}
|
||||
```
|
||||
|
||||
### Accessing slot's data with the `data` kwarg
|
||||
|
||||
```django
|
||||
{# my_table.html #}
|
||||
<table>
|
||||
...
|
||||
{% slot "pagination" pages=pages %}
|
||||
< 1 | 2 | 3 >
|
||||
{% endslot %}
|
||||
</table>
|
||||
```
|
||||
|
||||
```django
|
||||
{% component "my_table" %}
|
||||
{% fill "pagination" data="slot_data" %}
|
||||
{% for page in slot_data.pages %}
|
||||
<a href="{{ page.link }}">
|
||||
{{ page.index }}
|
||||
</a>
|
||||
{% endfor %}
|
||||
{% endfill %}
|
||||
{% endcomponent %}
|
||||
```
|
||||
|
||||
### Accessing slot data and default content on the default slot
|
||||
|
||||
To access slot data and the default slot content on the default slot,
|
||||
use `{% fill %}` with `name` set to `"default"`:
|
||||
|
||||
```django
|
||||
{% component "button" %}
|
||||
{% fill name="default" data="slot_data" default="default_slot" %}
|
||||
You clicked me {{ slot_data.count }} times!
|
||||
{{ default_slot }}
|
||||
{% endfill %}
|
||||
{% endcomponent %}
|
||||
```
|
||||
|
||||
## html_attrs
|
||||
|
||||
```django
|
||||
{% html_attrs attrs=None defaults=None **kwargs %}
|
||||
```
|
||||
|
||||
|
||||
|
||||
<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
|
||||
|
||||
|
||||
|
||||
Generate HTML attributes (`key="value"`), combining data from multiple sources,
|
||||
whether its template variables or static text.
|
||||
|
||||
It is designed to easily merge HTML attributes passed from outside with the internal.
|
||||
See how to in [Passing HTML attributes to components](../../guides/howto/passing_html_attrs/).
|
||||
|
||||
**Args:**
|
||||
|
||||
- `attrs` (dict, optional): Optional dictionary that holds HTML attributes. On conflict, overrides
|
||||
values in the `default` dictionary.
|
||||
- `default` (str, optional): Optional dictionary that holds HTML attributes. On conflict, is overriden
|
||||
with values in the `attrs` dictionary.
|
||||
- Any extra kwargs will be appended to the corresponding keys
|
||||
|
||||
The attributes in `attrs` and `defaults` are merged and resulting dict is rendered as HTML attributes
|
||||
(`key="value"`).
|
||||
|
||||
Extra kwargs (`key=value`) are concatenated to existing keys. So if we have
|
||||
|
||||
```python
|
||||
attrs = {"class": "my-class"}
|
||||
```
|
||||
|
||||
Then
|
||||
|
||||
```django
|
||||
{% html_attrs attrs class="extra-class" %}
|
||||
```
|
||||
|
||||
will result in `class="my-class extra-class"`.
|
||||
|
||||
**Example:**
|
||||
```django
|
||||
<div {% html_attrs
|
||||
attrs
|
||||
defaults:class="default-class"
|
||||
class="extra-class"
|
||||
data-id="123"
|
||||
%}>
|
||||
```
|
||||
|
||||
renders
|
||||
|
||||
```html
|
||||
<div class="my-class extra-class" data-id="123">
|
||||
```
|
||||
|
||||
**See more usage examples in
|
||||
[HTML attributes](../../concepts/fundamentals/html_attributes#examples-for-html_attrs).**
|
||||
|
||||
## provide
|
||||
|
||||
```django
|
||||
{% provide name **kwargs %}
|
||||
{% endprovide %}
|
||||
```
|
||||
|
||||
|
||||
|
||||
<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
|
||||
|
||||
|
||||
|
||||
The "provider" part of the [provide / inject feature](../../concepts/advanced/provide_inject).
|
||||
Pass kwargs to this tag to define the provider's data.
|
||||
Any components defined within the `{% provide %}..{% endprovide %}` tags will be able to access this data
|
||||
with [`Component.inject()`](../api#django_components.Component.inject).
|
||||
|
||||
This is similar to React's [`ContextProvider`](https://react.dev/learn/passing-data-deeply-with-context),
|
||||
or Vue's [`provide()`](https://vuejs.org/guide/components/provide-inject).
|
||||
|
||||
**Args:**
|
||||
|
||||
- `name` (str, required): Provider name. This is the name you will then use in
|
||||
[`Component.inject()`](../api#django_components.Component.inject).
|
||||
- `**kwargs`: Any extra kwargs will be passed as the provided data.
|
||||
|
||||
**Example:**
|
||||
|
||||
Provide the "user_data" in parent component:
|
||||
|
||||
```python
|
||||
@register("parent")
|
||||
class Parent(Component):
|
||||
template = """
|
||||
<div>
|
||||
{% provide "user_data" user=user %}
|
||||
{% component "child" / %}
|
||||
{% endprovide %}
|
||||
</div>
|
||||
"""
|
||||
|
||||
def get_context_data(self, user: User):
|
||||
return {
|
||||
"user": user,
|
||||
}
|
||||
```
|
||||
|
||||
Since the "child" component is used within the `{% provide %} / {% endprovide %}` tags,
|
||||
we can request the "user_data" using `Component.inject("user_data")`:
|
||||
|
||||
```python
|
||||
@register("child")
|
||||
class Child(Component):
|
||||
template = """
|
||||
<div>
|
||||
User is: {{ user }}
|
||||
</div>
|
||||
"""
|
||||
|
||||
def get_context_data(self):
|
||||
user = self.inject("user_data").user
|
||||
return {
|
||||
"user": user,
|
||||
}
|
||||
```
|
||||
|
||||
Notice that the keys defined on the `{% provide %}` tag are then accessed as attributes
|
||||
when accessing them with [`Component.inject()`](../api#django_components.Component.inject).
|
||||
|
||||
✅ Do this
|
||||
```python
|
||||
user = self.inject("user_data").user
|
||||
```
|
||||
|
||||
❌ Don't do this
|
||||
```python
|
||||
user = self.inject("user_data")["user"]
|
||||
```
|
||||
|
||||
## slot
|
||||
|
||||
```django
|
||||
{% slot name **kwargs [default] [required] %}
|
||||
{% endslot %}
|
||||
```
|
||||
|
||||
|
||||
|
||||
<a href="https://github.com/EmilStenstrom/django-components/tree/master/.venv/lib/python3.11/site-packages/django_components/templatetags/component_tags.py#L117" target="_blank">See source code</a>
|
||||
|
||||
|
||||
|
||||
Slot tag marks a place inside a component where content can be inserted
|
||||
from outside.
|
||||
|
||||
[Learn more](../../concepts/fundamentals/slots) about using slots.
|
||||
|
||||
This is similar to slots as seen in
|
||||
[Web components](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot),
|
||||
[Vue](https://vuejs.org/guide/components/slots.html)
|
||||
or [React's `children`](https://react.dev/learn/passing-props-to-a-component#passing-jsx-as-children).
|
||||
|
||||
**Args:**
|
||||
|
||||
- `name` (str, required): Registered name of the component to render
|
||||
- `default`: Optional flag. If there is a default slot, you can pass the component slot content
|
||||
without using the [`{% fill %}`](#fill) tag. See
|
||||
[Default slot](../../concepts/fundamentals/slots#default-slot)
|
||||
- `required`: Optional flag. Will raise an error if a slot is required but not given.
|
||||
- `**kwargs`: Any extra kwargs will be passed as the slot data.
|
||||
|
||||
**Example:**
|
||||
|
||||
```python
|
||||
@register("child")
|
||||
class Child(Component):
|
||||
template = """
|
||||
<div>
|
||||
{% slot "content" default %}
|
||||
This is shown if not overriden!
|
||||
{% endslot %}
|
||||
</div>
|
||||
<aside>
|
||||
{% slot "sidebar" required / %}
|
||||
</aside>
|
||||
"""
|
||||
```
|
||||
|
||||
```python
|
||||
@register("parent")
|
||||
class Parent(Component):
|
||||
template = """
|
||||
<div>
|
||||
{% component "child" %}
|
||||
{% fill "content" %}
|
||||
🗞️📰
|
||||
{% endfill %}
|
||||
|
||||
{% fill "sidebar" %}
|
||||
🍷🧉🍾
|
||||
{% endfill %}
|
||||
{% endcomponent %}
|
||||
</div>
|
||||
"""
|
||||
```
|
||||
|
||||
### Passing data to slots
|
||||
|
||||
Any extra kwargs will be considered as slot data, and will be accessible in the [`{% fill %}`](#fill)
|
||||
tag via fill's `data` kwarg:
|
||||
|
||||
```python
|
||||
@register("child")
|
||||
class Child(Component):
|
||||
template = """
|
||||
<div>
|
||||
{# Passing data to the slot #}
|
||||
{% slot "content" user=user %}
|
||||
This is shown if not overriden!
|
||||
{% endslot %}
|
||||
</div>
|
||||
"""
|
||||
```
|
||||
|
||||
```python
|
||||
@register("parent")
|
||||
class Parent(Component):
|
||||
template = """
|
||||
{# Parent can access the slot data #}
|
||||
{% component "child" %}
|
||||
{% fill "content" data="data" %}
|
||||
<div class="wrapper-class">
|
||||
{{ data.user }}
|
||||
</div>
|
||||
{% endfill %}
|
||||
{% endcomponent %}
|
||||
"""
|
||||
```
|
||||
|
||||
### Accessing default slot content
|
||||
|
||||
The content between the `{% slot %}..{% endslot %}` tags is the default content that
|
||||
will be rendered if no fill is given for the slot.
|
||||
|
||||
This default content can then be accessed from within the [`{% fill %}`](#fill) tag using
|
||||
the fill's `default` kwarg.
|
||||
This is useful if you need to wrap / prepend / append the original slot's content.
|
||||
|
||||
```python
|
||||
@register("child")
|
||||
class Child(Component):
|
||||
template = """
|
||||
<div>
|
||||
{% slot "content" %}
|
||||
This is default content!
|
||||
{% endslot %}
|
||||
</div>
|
||||
"""
|
||||
```
|
||||
|
||||
```python
|
||||
@register("parent")
|
||||
class Parent(Component):
|
||||
template = """
|
||||
{# Parent can access the slot's default content #}
|
||||
{% component "child" %}
|
||||
{% fill "content" default="default" %}
|
||||
{{ default }}
|
||||
{% endfill %}
|
||||
{% endcomponent %}
|
||||
"""
|
||||
```
|
||||
|
||||
11
src/docs/reference/template_vars.md
Normal file
11
src/docs/reference/template_vars.md
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
<!-- Autogenerated by reference.py -->
|
||||
|
||||
# Template variables
|
||||
|
||||
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)
|
||||
hooks.
|
||||
|
||||
|
||||
::: django_components.component.ComponentVars.is_filled
|
||||
|
||||
25
src/docs/reference/urls.md
Normal file
25
src/docs/reference/urls.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
<!-- Autogenerated by reference.py -->
|
||||
|
||||
# URLs
|
||||
|
||||
Below are all the URL patterns that will be added by adding `django_components.urls`.
|
||||
|
||||
See [Installation](../overview/installation.md#adding-support-for-js-and-css)
|
||||
on how to add these URLs to your Django project.
|
||||
|
||||
Django components already prefixes all URLs with `components/`. So when you are
|
||||
adding the URLs to `urlpatterns`, you can use an empty string as the first argument:
|
||||
|
||||
```python
|
||||
from django.urls import include, path
|
||||
|
||||
urlpatterns = [
|
||||
...
|
||||
path("", include("django_components.urls")),
|
||||
]
|
||||
```
|
||||
|
||||
## List of URLs
|
||||
|
||||
|
||||
- `components/cache/<str:comp_cls_hash>.<str:script_type>/`
|
||||
|
|
@ -80,7 +80,8 @@ def gen_reference_api():
|
|||
"""
|
||||
module = import_module("django_components")
|
||||
|
||||
preface = (root / "src/docs/templates/reference_api.md").read_text()
|
||||
preface = "<!-- Autogenerated by reference.py -->\n\n"
|
||||
preface += (root / "src/docs/templates/reference_api.md").read_text()
|
||||
out_file = root / "src/docs/reference/api.md"
|
||||
|
||||
out_file.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
|
@ -116,7 +117,8 @@ def gen_reference_exceptions():
|
|||
"""
|
||||
module = import_module("django_components")
|
||||
|
||||
preface = (root / "src/docs/templates/reference_exceptions.md").read_text()
|
||||
preface = "<!-- Autogenerated by reference.py -->\n\n"
|
||||
preface += (root / "src/docs/templates/reference_exceptions.md").read_text()
|
||||
out_file = root / "src/docs/reference/exceptions.md"
|
||||
|
||||
out_file.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
|
@ -150,7 +152,8 @@ def gen_reference_components():
|
|||
"""
|
||||
module = import_module("django_components.components")
|
||||
|
||||
preface = (root / "src/docs/templates/reference_components.md").read_text()
|
||||
preface = "<!-- Autogenerated by reference.py -->\n\n"
|
||||
preface += (root / "src/docs/templates/reference_components.md").read_text()
|
||||
out_file = root / "src/docs/reference/components.md"
|
||||
|
||||
out_file.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
|
@ -199,7 +202,8 @@ def gen_reference_settings():
|
|||
"""
|
||||
module = import_module("django_components.app_settings")
|
||||
|
||||
preface = (root / "src/docs/templates/reference_settings.md").read_text()
|
||||
preface = "<!-- Autogenerated by reference.py -->\n\n"
|
||||
preface += (root / "src/docs/templates/reference_settings.md").read_text()
|
||||
out_file = root / "src/docs/reference/settings.md"
|
||||
|
||||
out_file.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
|
@ -303,7 +307,8 @@ def gen_reference_middlewares():
|
|||
"""
|
||||
module = import_module("django_components.middleware")
|
||||
|
||||
preface = (root / "src/docs/templates/reference_middlewares.md").read_text()
|
||||
preface = "<!-- Autogenerated by reference.py -->\n\n"
|
||||
preface += (root / "src/docs/templates/reference_middlewares.md").read_text()
|
||||
out_file = root / "src/docs/reference/middlewares.md"
|
||||
|
||||
out_file.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
|
@ -345,7 +350,8 @@ def gen_reference_tagformatters():
|
|||
"""
|
||||
module = import_module("django_components")
|
||||
|
||||
preface = (root / "src/docs/templates/reference_tagformatters.md").read_text()
|
||||
preface = "<!-- Autogenerated by reference.py -->\n\n"
|
||||
preface += (root / "src/docs/templates/reference_tagformatters.md").read_text()
|
||||
out_file = root / "src/docs/reference/tag_formatters.md"
|
||||
|
||||
tag_formatter_classes: Dict[str, Type[TagFormatterABC]] = {}
|
||||
|
|
@ -407,7 +413,8 @@ def gen_reference_urls():
|
|||
"""
|
||||
module = import_module("django_components.urls")
|
||||
|
||||
preface = (root / "src/docs/templates/reference_urls.md").read_text()
|
||||
preface = "<!-- Autogenerated by reference.py -->\n\n"
|
||||
preface += (root / "src/docs/templates/reference_urls.md").read_text()
|
||||
out_file = root / "src/docs/reference/urls.md"
|
||||
|
||||
all_urls = _list_urls(module.urlpatterns)
|
||||
|
|
@ -434,7 +441,8 @@ def gen_reference_commands():
|
|||
if not p.stem.startswith("_")
|
||||
]
|
||||
|
||||
preface = (root / "src/docs/templates/reference_commands.md").read_text()
|
||||
preface = "<!-- Autogenerated by reference.py -->\n\n"
|
||||
preface += (root / "src/docs/templates/reference_commands.md").read_text()
|
||||
out_file = root / "src/docs/reference/commands.md"
|
||||
|
||||
out_file.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
|
@ -481,7 +489,8 @@ def gen_reference_templatetags():
|
|||
(p.stem, f"django_components.templatetags.{p.stem}") for p in tags_files if not p.stem.startswith("_")
|
||||
]
|
||||
|
||||
preface = (root / "src/docs/templates/reference_templatetags.md").read_text()
|
||||
preface = "<!-- Autogenerated by reference.py -->\n\n"
|
||||
preface += (root / "src/docs/templates/reference_templatetags.md").read_text()
|
||||
out_file = root / "src/docs/reference/template_tags.md"
|
||||
|
||||
out_file.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
|
@ -533,7 +542,8 @@ def gen_reference_templatevars():
|
|||
Generate documentation for all variables that are available inside the component templates
|
||||
under the `{{ component_vars }}` variable, as defined by `ComponentVars`.
|
||||
"""
|
||||
preface = (root / "src/docs/templates/reference_templatevars.md").read_text()
|
||||
preface = "<!-- Autogenerated by reference.py -->\n\n"
|
||||
preface += (root / "src/docs/templates/reference_templatevars.md").read_text()
|
||||
out_file = root / "src/docs/reference/template_vars.md"
|
||||
|
||||
out_file.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue