Release notes¤
🚨📢 Version 0.100 - BREAKING CHANGE: - django_components.safer_staticfiles app was removed. It is no longer needed. - Installation changes: - Instead of defining component directories in STATICFILES_DIRS, set them to COMPONENTS.dirs. - You now must define STATICFILES_FINDERS - See here how to migrate your settings.py - Beside the top-level /components directory, you can now define also app-level components dirs, e.g. [app]/components (See COMPONENTS.app_dirs). - When you call as_view() on a component instance, that instance will be passed to View.as_view()
Version 0.97 - Fixed template caching. You can now also manually create cached templates with cached_template() - The previously undocumented get_template was made private. - In it's place, there's a new get_template, which supersedes get_template_string (will be removed in v1). The new get_template is the same as get_template_string, except it allows to return either a string or a Template instance. - You now must use only one of template, get_template, template_name, or get_template_name.
Version 0.96 - Run-time type validation for Python 3.11+ - If the Component class is typed, e.g. Component[Args, Kwargs, ...], the args, kwargs, slots, and data are validated against the given types. (See Runtime input validation with types) - Render hooks - Set on_render_before and on_render_after methods on Component to intercept or modify the template or context before rendering, or the rendered result afterwards. (See Component hooks) - component_vars.is_filled context variable can be accessed from within on_render_before and on_render_after hooks as self.is_filled.my_slot
Version 0.95 - Added support for dynamic components, where the component name is passed as a variable. (See Dynamic components) - Changed Component.input to raise RuntimeError if accessed outside of render context. Previously it returned None if unset.
Version 0.94 - django_components now automatically configures Django to support multi-line tags. (See Multi-line tags) - New setting reload_on_template_change. Set this to True to reload the dev server on changes to component template files. (See Reload dev server on component file changes)
Version 0.93 - Spread operator ...dict inside template tags. (See Spread operator) - Use template tags inside string literals in component inputs. (See Use template tags inside component inputs) - Dynamic slots, fills and provides - The name argument for these can now be a variable, a template expression, or via spread operator - Component library authors can now configure CONTEXT_BEHAVIOR and TAG_FORMATTER settings independently from user settings.
🚨📢 Version 0.92 - BREAKING CHANGE: Component class is no longer a subclass of View. To configure the View class, set the Component.View nested class. HTTP methods like get or post can still be defined directly on Component class, and Component.as_view() internally calls Component.View.as_view(). (See Modifying the View class)
-
The inputs (args, kwargs, slots, context, ...) that you pass to
Component.render()can be accessed from withinget_context_data,get_templateandget_template_nameviaself.input. (See Accessing data passed to the component) -
Typing:
Componentclass supports generics that specify types forComponent.render(See Adding type hints with Generics)
Version 0.90 - All tags (component, slot, fill, ...) now support "self-closing" or "inline" form, where you can omit the closing tag:
{# Before #}
+ Changelog - Django-Components Release notes¤
🚨📢 Version 0.100 - BREAKING CHANGE: - django_components.safer_staticfiles app was removed. It is no longer needed. - Installation changes: - Instead of defining component directories in STATICFILES_DIRS, set them to COMPONENTS.dirs. - You now must define STATICFILES_FINDERS - See here how to migrate your settings.py - Beside the top-level /components directory, you can now define also app-level components dirs, e.g. [app]/components (See COMPONENTS.app_dirs). - When you call as_view() on a component instance, that instance will be passed to View.as_view()
Version 0.97 - Fixed template caching. You can now also manually create cached templates with cached_template() - The previously undocumented get_template was made private. - In it's place, there's a new get_template, which supersedes get_template_string (will be removed in v1). The new get_template is the same as get_template_string, except it allows to return either a string or a Template instance. - You now must use only one of template, get_template, template_name, or get_template_name.
Version 0.96 - Run-time type validation for Python 3.11+ - If the Component class is typed, e.g. Component[Args, Kwargs, ...], the args, kwargs, slots, and data are validated against the given types. (See Runtime input validation with types) - Render hooks - Set on_render_before and on_render_after methods on Component to intercept or modify the template or context before rendering, or the rendered result afterwards. (See Component hooks) - component_vars.is_filled context variable can be accessed from within on_render_before and on_render_after hooks as self.is_filled.my_slot
Version 0.95 - Added support for dynamic components, where the component name is passed as a variable. (See Dynamic components) - Changed Component.input to raise RuntimeError if accessed outside of render context. Previously it returned None if unset.
Version 0.94 - django_components now automatically configures Django to support multi-line tags. (See Multi-line tags) - New setting reload_on_template_change. Set this to True to reload the dev server on changes to component template files. (See Reload dev server on component file changes)
Version 0.93 - Spread operator ...dict inside template tags. (See Spread operator) - Use template tags inside string literals in component inputs. (See Use template tags inside component inputs) - Dynamic slots, fills and provides - The name argument for these can now be a variable, a template expression, or via spread operator - Component library authors can now configure CONTEXT_BEHAVIOR and TAG_FORMATTER settings independently from user settings.
🚨📢 Version 0.92 - BREAKING CHANGE: Component class is no longer a subclass of View. To configure the View class, set the Component.View nested class. HTTP methods like get or post can still be defined directly on Component class, and Component.as_view() internally calls Component.View.as_view(). (See Modifying the View class)
-
The inputs (args, kwargs, slots, context, ...) that you pass to Component.render() can be accessed from within get_context_data, get_template and get_template_name via self.input. (See Accessing data passed to the component)
-
Typing: Component class supports generics that specify types for Component.render (See Adding type hints with Generics)
Version 0.90 - All tags (component, slot, fill, ...) now support "self-closing" or "inline" form, where you can omit the closing tag:
{# Before #}
{% component "button" %}{% endcomponent %}
{# After #}
{% component "button" / %}
@@ -10,7 +10,7 @@
{% endcomponent %}
```
-While `django_components.shorthand_component_formatter` allows you to write components like so:
+While `django_components.component_shorthand_formatter` allows you to write components like so:
```django
{% button href="..." disabled %}
@@ -547,7 +547,7 @@ def on_render_after(self, context, template, content):
{% endfill %}
{% endcomponent %}
Example as inlined tag:
ShorthandComponentFormatter (django_components.shorthand_component_formatter)
Uses the component name as start tag, and end<component_name> as an end tag.
Example as block:
ShorthandComponentFormatter (django_components.component_shorthand_formatter)
Uses the component name as start tag, and end<component_name> as an end tag.
Example as block:
Example as inlined tag:
{% button href="..." / %}
diff --git a/dev/CODE_OF_CONDUCT/index.html b/dev/CODE_OF_CONDUCT/index.html
index 14e40d35..5af213fa 100644
--- a/dev/CODE_OF_CONDUCT/index.html
+++ b/dev/CODE_OF_CONDUCT/index.html
@@ -1 +1 @@
- Code of Conduct - Django-Components Contributor Covenant Code of Conduct¤
Our Pledge¤
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
Our Standards¤
Examples of behavior that contributes to creating a positive environment include:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
Our Responsibilities¤
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
Scope¤
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
Enforcement¤
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at emil@emilstenstrom.se. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
Attribution¤
This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq
\ No newline at end of file
+ Code of Conduct - Django-Components Contributor Covenant Code of Conduct¤
Our Pledge¤
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
Our Standards¤
Examples of behavior that contributes to creating a positive environment include:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
Our Responsibilities¤
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
Scope¤
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
Enforcement¤
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at emil@emilstenstrom.se. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
Attribution¤
This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq
\ No newline at end of file
diff --git a/dev/SUMMARY/index.html b/dev/SUMMARY/index.html
index c3bbbb84..b28a6fa5 100644
--- a/dev/SUMMARY/index.html
+++ b/dev/SUMMARY/index.html
@@ -1 +1 @@
- SUMMARY - Django-Components SUMMARY
- README
- Changelog
- Code of Conduct
- License
- Reference
- API Reference
\ No newline at end of file
+ SUMMARY - Django-Components SUMMARY
- README
- Changelog
- Code of Conduct
- License
- Reference
- API Reference
\ No newline at end of file
diff --git a/dev/assets/_mkdocstrings.css b/dev/assets/_mkdocstrings.css
index 85449ec7..b500381b 100644
--- a/dev/assets/_mkdocstrings.css
+++ b/dev/assets/_mkdocstrings.css
@@ -26,20 +26,33 @@
float: right;
}
+/* Parameter headings must be inline, not blocks. */
+.doc-heading-parameter {
+ display: inline;
+}
+
+/* Prefer space on the right, not the left of parameter permalinks. */
+.doc-heading-parameter .headerlink {
+ margin-left: 0 !important;
+ margin-right: 0.2rem;
+}
+
/* Backward-compatibility: docstring section titles in bold. */
.doc-section-title {
font-weight: bold;
}
/* Symbols in Navigation and ToC. */
-:root,
+:root, :host,
[data-md-color-scheme="default"] {
+ --doc-symbol-parameter-fg-color: #df50af;
--doc-symbol-attribute-fg-color: #953800;
--doc-symbol-function-fg-color: #8250df;
--doc-symbol-method-fg-color: #8250df;
--doc-symbol-class-fg-color: #0550ae;
--doc-symbol-module-fg-color: #5cad0f;
+ --doc-symbol-parameter-bg-color: #df50af1a;
--doc-symbol-attribute-bg-color: #9538001a;
--doc-symbol-function-bg-color: #8250df1a;
--doc-symbol-method-bg-color: #8250df1a;
@@ -48,12 +61,14 @@
}
[data-md-color-scheme="slate"] {
+ --doc-symbol-parameter-fg-color: #ffa8cc;
--doc-symbol-attribute-fg-color: #ffa657;
--doc-symbol-function-fg-color: #d2a8ff;
--doc-symbol-method-fg-color: #d2a8ff;
--doc-symbol-class-fg-color: #79c0ff;
--doc-symbol-module-fg-color: #baff79;
+ --doc-symbol-parameter-bg-color: #ffa8cc1a;
--doc-symbol-attribute-bg-color: #ffa6571a;
--doc-symbol-function-bg-color: #d2a8ff1a;
--doc-symbol-method-bg-color: #d2a8ff1a;
@@ -68,6 +83,15 @@ code.doc-symbol {
font-weight: bold;
}
+code.doc-symbol-parameter {
+ color: var(--doc-symbol-parameter-fg-color);
+ background-color: var(--doc-symbol-parameter-bg-color);
+}
+
+code.doc-symbol-parameter::after {
+ content: "param";
+}
+
code.doc-symbol-attribute {
color: var(--doc-symbol-attribute-fg-color);
background-color: var(--doc-symbol-attribute-bg-color);
diff --git a/dev/index.html b/dev/index.html
index 112238d1..c4c44531 100644
--- a/dev/index.html
+++ b/dev/index.html
@@ -1,4 +1,4 @@
- Index - Django-Components 
¤
Django-components is a package that introduces component-based architecture to Django's server-side rendering. It aims to combine Django's templating system with the modularity seen in modern frontend frameworks.
Features¤
- 🧩 Reusability: Allows creation of self-contained, reusable UI elements.
- 📦 Encapsulation: Each component can include its own HTML, CSS, and JavaScript.
- 🚀 Server-side rendering: Components render on the server, improving initial load times and SEO.
- 🐍 Django integration: Works within the Django ecosystem, using familiar concepts like template tags.
- ⚡ Asynchronous loading: Components can render independently opening up for integration with JS frameworks like HTMX or AlpineJS.
Potential benefits:
- 🔄 Reduced code duplication
- 🛠️ Improved maintainability through modular design
- 🧠 Easier management of complex UIs
- 🤝 Enhanced collaboration between frontend and backend developers
Django-components can be particularly useful for larger Django projects that require a more structured approach to UI development, without necessitating a shift to a separate frontend framework.
Summary¤
It lets you create "template components", that contains both the template, the Javascript and the CSS needed to generate the front end code you need for a modern app. Use components like this:
{% component "calendar" date="2015-06-19" %}{% endcomponent %}
+ Index - Django-Components ¤
Django-components is a package that introduces component-based architecture to Django's server-side rendering. It aims to combine Django's templating system with the modularity seen in modern frontend frameworks.
Features¤
- 🧩 Reusability: Allows creation of self-contained, reusable UI elements.
- 📦 Encapsulation: Each component can include its own HTML, CSS, and JavaScript.
- 🚀 Server-side rendering: Components render on the server, improving initial load times and SEO.
- 🐍 Django integration: Works within the Django ecosystem, using familiar concepts like template tags.
- ⚡ Asynchronous loading: Components can render independently opening up for integration with JS frameworks like HTMX or AlpineJS.
Potential benefits:
- 🔄 Reduced code duplication
- 🛠️ Improved maintainability through modular design
- 🧠 Easier management of complex UIs
- 🤝 Enhanced collaboration between frontend and backend developers
Django-components can be particularly useful for larger Django projects that require a more structured approach to UI development, without necessitating a shift to a separate frontend framework.
Summary¤
It lets you create "template components", that contains both the template, the Javascript and the CSS needed to generate the front end code you need for a modern app. Use components like this:
And this is what gets rendered (plus the CSS and Javascript you've specified):
See the example project or read on to learn about the details!
Table of Contents¤
- Release notes
- Security notes 🚨
- Installation
- Compatibility
- Create your first component
- Using single-file components
- Use components in templates
- Use components outside of templates
- Use components as views
- Typing and validating components
- Pre-defined components
- Registering components
- Autodiscovery
- Using slots in templates
- Accessing data passed to the component
- Rendering HTML attributes
- Template tag syntax
- Prop drilling and dependency injection (provide / inject)
- Component hooks
- Component context and scope
- Pre-defined template variables
- Customizing component tags with TagFormatter
- Defining HTML/JS/CSS files
- Rendering JS/CSS dependencies
- Available settings
- Running with development server
- Logging and debugging
- Management Command
- Writing and sharing component libraries
- Community examples
- Running django-components project locally
- Development guides
Release notes¤
🚨📢 Version 0.100 - BREAKING CHANGE: - django_components.safer_staticfiles app was removed. It is no longer needed. - Installation changes: - Instead of defining component directories in STATICFILES_DIRS, set them to COMPONENTS.dirs. - You now must define STATICFILES_FINDERS - See here how to migrate your settings.py - Beside the top-level /components directory, you can now define also app-level components dirs, e.g. [app]/components (See COMPONENTS.app_dirs). - When you call as_view() on a component instance, that instance will be passed to View.as_view()
Version 0.97 - Fixed template caching. You can now also manually create cached templates with cached_template() - The previously undocumented get_template was made private. - In it's place, there's a new get_template, which supersedes get_template_string (will be removed in v1). The new get_template is the same as get_template_string, except it allows to return either a string or a Template instance. - You now must use only one of template, get_template, template_name, or get_template_name.
Version 0.96 - Run-time type validation for Python 3.11+ - If the Component class is typed, e.g. Component[Args, Kwargs, ...], the args, kwargs, slots, and data are validated against the given types. (See Runtime input validation with types) - Render hooks - Set on_render_before and on_render_after methods on Component to intercept or modify the template or context before rendering, or the rendered result afterwards. (See Component hooks) - component_vars.is_filled context variable can be accessed from within on_render_before and on_render_after hooks as self.is_filled.my_slot
Version 0.95 - Added support for dynamic components, where the component name is passed as a variable. (See Dynamic components) - Changed Component.input to raise RuntimeError if accessed outside of render context. Previously it returned None if unset.
Version 0.94 - django_components now automatically configures Django to support multi-line tags. (See Multi-line tags) - New setting reload_on_template_change. Set this to True to reload the dev server on changes to component template files. (See Reload dev server on component file changes)
Version 0.93 - Spread operator ...dict inside template tags. (See Spread operator) - Use template tags inside string literals in component inputs. (See Use template tags inside component inputs) - Dynamic slots, fills and provides - The name argument for these can now be a variable, a template expression, or via spread operator - Component library authors can now configure CONTEXT_BEHAVIOR and TAG_FORMATTER settings independently from user settings.
🚨📢 Version 0.92 - BREAKING CHANGE: Component class is no longer a subclass of View. To configure the View class, set the Component.View nested class. HTTP methods like get or post can still be defined directly on Component class, and Component.as_view() internally calls Component.View.as_view(). (See Modifying the View class)
-
The inputs (args, kwargs, slots, context, ...) that you pass to Component.render() can be accessed from within get_context_data, get_template and get_template_name via self.input. (See Accessing data passed to the component)
-
Typing: Component class supports generics that specify types for Component.render (See Adding type hints with Generics)
Version 0.90 - All tags (component, slot, fill, ...) now support "self-closing" or "inline" form, where you can omit the closing tag:
{# Before #}
{% component "button" %}{% endcomponent %}
@@ -12,7 +12,7 @@
{% endcomponent %}
```
-While `django_components.shorthand_component_formatter` allows you to write components like so:
+While `django_components.component_shorthand_formatter` allows you to write components like so:
```django
{% button href="..." disabled %}
@@ -1082,7 +1082,7 @@ def on_render_after(self, context, template, content):
{# or #}
{% component "button" href="..." disabled / %}
-
You can change this behaviour in the settings under the COMPONENTS.tag_formatter.
For example, if you set the tag formatter to django_components.shorthand_component_formatter, the components will use their name as the template tags:
You can change this behaviour in the settings under the COMPONENTS.tag_formatter.
For example, if you set the tag formatter to django_components.component_shorthand_formatter, the components will use their name as the template tags:
{% button href="..." disabled %}
Click me!
{% endbutton %}
@@ -1095,7 +1095,7 @@ def on_render_after(self, context, template, content):
{% endfill %}
{% endcomponent %}
Example as inlined tag:
ShorthandComponentFormatter (django_components.shorthand_component_formatter)
Uses the component name as start tag, and end<component_name> as an end tag.
Example as block:
ShorthandComponentFormatter (django_components.component_shorthand_formatter)
Uses the component name as start tag, and end<component_name> as an end tag.
Example as block:
Example as inlined tag:
{% button href="..." / %}
diff --git a/dev/license/index.html b/dev/license/index.html
index af475570..38046877 100644
--- a/dev/license/index.html
+++ b/dev/license/index.html
@@ -1 +1 @@
- License - Django-Components License¤
MIT License
Copyright (c) 2019 Emil Stenström
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\ No newline at end of file
+ License - Django-Components License¤
MIT License
Copyright (c) 2019 Emil Stenström
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\ No newline at end of file
diff --git a/dev/migrating_from_safer_staticfiles/index.html b/dev/migrating_from_safer_staticfiles/index.html
index f5166a61..f1ec9ecd 100644
--- a/dev/migrating_from_safer_staticfiles/index.html
+++ b/dev/migrating_from_safer_staticfiles/index.html
@@ -1,4 +1,4 @@
- Migrating from safer_staticfiles - Django-Components Migrating from safer_staticfiles¤
This guide is for you if you're upgrating django_components to v0.100 or later from older versions.
In version 0.100, we changed how components' static JS and CSS files are handled. See more in the "Static files" section.
Migration steps:
- Remove
django_components.safer_staticfiles from INSTALLED_APPS in your settings.py, and replace it with django.contrib.staticfiles.
Before:
INSTALLED_APPS = [
+ Migrating from safer_staticfiles - Django-Components Migrating from safer_staticfiles¤
This guide is for you if you're upgrating django_components to v0.100 or later from older versions.
In version 0.100, we changed how components' static JS and CSS files are handled. See more in the "Static files" section.
Migration steps:
- Remove
django_components.safer_staticfiles from INSTALLED_APPS in your settings.py, and replace it with django.contrib.staticfiles.
Before:
INSTALLED_APPS = [
"django.contrib.admin",
...
# "django.contrib.staticfiles", # <-- ADD
diff --git a/dev/reference/SUMMARY/index.html b/dev/reference/SUMMARY/index.html
index af6d31e7..d539e55c 100644
--- a/dev/reference/SUMMARY/index.html
+++ b/dev/reference/SUMMARY/index.html
@@ -1 +1 @@
- SUMMARY - Django-Components SUMMARY
\ No newline at end of file
+ SUMMARY - Django-Components SUMMARY
\ No newline at end of file
diff --git a/dev/reference/django_components/app_settings/index.html b/dev/reference/django_components/app_settings/index.html
index 2c5ad9a2..5734b7fe 100644
--- a/dev/reference/django_components/app_settings/index.html
+++ b/dev/reference/django_components/app_settings/index.html
@@ -1,4 +1,4 @@
- app_settings - Django-Components app_settings - Django-Components" > app_settings - Django-Components" >
class-attribute instance-attribute ¤
DJANGO = 'django'
+ app_settings - Django-Components app_settings - Django-Components" > app_settings - Django-Components" >
Classes:
Attributes:
-
DJANGO – With this setting, component fills behave as usual Django tags.
-
ISOLATED – This setting makes the component fills behave similar to Vue or React, where
class-attribute instance-attribute ¤
With this setting, component fills behave as usual Django tags. That is, they enrich the context, and pass it along.
- Component fills use the context of the component they are within.
- Variables from
get_context_data are available to the component fill.
Example:
Given this template
{% with cheese="feta" %}
{% component 'my_comp' %}
{{ my_var }} # my_var
diff --git a/dev/reference/django_components/apps/index.html b/dev/reference/django_components/apps/index.html
index 098ef1de..4506d6d5 100644
--- a/dev/reference/django_components/apps/index.html
+++ b/dev/reference/django_components/apps/index.html
@@ -1 +1 @@
- apps - Django-Components apps - Django-Components" > apps - Django-Components" >
\ No newline at end of file
+ apps - Django-Components apps - Django-Components" > apps - Django-Components" >
\ No newline at end of file
diff --git a/dev/reference/django_components/attributes/index.html b/dev/reference/django_components/attributes/index.html
index f9d19391..ce03f530 100644
--- a/dev/reference/django_components/attributes/index.html
+++ b/dev/reference/django_components/attributes/index.html
@@ -1,4 +1,4 @@
- attributes - Django-Components attributes - Django-Components" > attributes - Django-Components" >
append_attributes(*args: Tuple[str, Any]) -> Dict
+ attributes - Django-Components attributes - Django-Components" > attributes - Django-Components" >
Functions:
-
append_attributes – Merges the key-value pairs and returns a new dictionary.
-
attributes_to_string – Convert a dict of attributes to a string.
Merges the key-value pairs and returns a new dictionary.
If a key is present multiple times, its values are concatenated with a space character as separator in the final dictionary.
Source code in src/django_components/attributes.py
71
72
73
diff --git a/dev/reference/django_components/autodiscover/index.html b/dev/reference/django_components/autodiscover/index.html
index 508ca95c..bc426126 100644
--- a/dev/reference/django_components/autodiscover/index.html
+++ b/dev/reference/django_components/autodiscover/index.html
@@ -1,4 +1,4 @@
- autodiscover - Django-Components autodiscover - Django-Components" > autodiscover - Django-Components" >
autodiscover(map_module: Optional[Callable[[str], str]] = None) -> List[str]
+ autodiscover - Django-Components autodiscover - Django-Components" > autodiscover - Django-Components" >
Functions:
-
autodiscover – Search for component files and import them. Returns a list of module
-
import_libraries – Import modules set in COMPONENTS.libraries setting.
-
search_dirs – Search the directories for the given glob pattern. Glob search results are returned
Search for component files and import them. Returns a list of module paths of imported files.
Autodiscover searches in the locations as defined by Loader.get_dirs.
You can map the module paths with map_module function. This serves as an escape hatch for when you need to use this function in tests.
Source code in src/django_components/autodiscover.py
15
16
17
diff --git a/dev/reference/django_components/component/index.html b/dev/reference/django_components/component/index.html
index 01284576..b1e821bd 100644
--- a/dev/reference/django_components/component/index.html
+++ b/dev/reference/django_components/component/index.html
@@ -1,11 +1,11 @@
- component - Django-Components component - Django-Components" > component - Django-Components" >
Component(
+ component - Django-Components component - Django-Components" > component - Django-Components" >
Classes:
-
Component – -
ComponentNode – Django.template.Node subclass that renders a django-components component
-
ComponentView – Subclass of django.views.View where the Component instance is available
Component(
registered_name: Optional[str] = None,
component_id: Optional[str] = None,
outer_context: Optional[Context] = None,
fill_content: Optional[Dict[str, FillContent]] = None,
registry: Optional[ComponentRegistry] = None,
)
-
Bases: Generic[ArgsType, KwargsType, DataType, SlotsType]
Source code in src/django_components/component.py
233
+ Bases: Generic[ArgsType, KwargsType, DataType, SlotsType]
Methods:
-
as_view – Shortcut for calling Component.View.as_view and passing component instance to it.
-
get_template – Inlined Django template associated with this component. Can be a plain string or a Template instance.
-
get_template_name – Filepath to the Django template associated with this component.
-
inject – Use this method to retrieve the data that was passed to a {% provide %} tag
-
on_render_after – Hook that runs just after the component's template was rendered.
-
on_render_before – Hook that runs just before the component's template is rendered.
-
render – Render the component into a string.
-
render_css_dependencies – Render only CSS dependencies available in the media class or provided as a string.
-
render_dependencies – Helper function to render all dependencies for a component.
-
render_js_dependencies – Render only JS dependencies available in the media class or provided as a string.
-
render_to_response – Render the component and wrap the content in the response class.
Attributes:
-
Media – Defines JS and CSS media files associated with this component.
-
css (Optional[str]) – Inlined CSS associated with this component.
-
input (RenderInput[ArgsType, KwargsType, SlotsType]) – Input holds the data (like arg, kwargs, slots) that were passsed to
-
is_filled (Dict[str, bool]) – Dictionary describing which slots have or have not been filled.
-
js (Optional[str]) – Inlined JS associated with this component.
-
media (Media) – Normalized definition of JS and CSS media files associated with this component.
-
response_class – This allows to configure what class is used to generate response from render_to_response
-
template (Optional[Union[str, Template]]) – Inlined Django template associated with this component. Can be a plain string or a Template instance.
-
template_name (Optional[str]) – Filepath to the Django template associated with this component.
Source code in src/django_components/component.py
233
234
235
236
diff --git a/dev/reference/django_components/component_media/index.html b/dev/reference/django_components/component_media/index.html
index aec94a02..8dfec5e8 100644
--- a/dev/reference/django_components/component_media/index.html
+++ b/dev/reference/django_components/component_media/index.html
@@ -1,4 +1,4 @@
- component_media - Django-Components component_media - Django-Components" > component_media - Django-Components" >
Defines JS and CSS media files associated with this component.
Bases: MediaDefiningClass
Metaclass for handling media files for components.
Similar to MediaDefiningClass, this class supports the use of Media attribute to define associated JS/CSS files, which are then available under media attribute as a instance of Media class.
This subclass has following changes:
1. Support for multiple interfaces of JS/CSS¤
-
As plain strings
class MyComponent(Component):
+ component_media - Django-Components component_media - Django-Components" > component_media - Django-Components" >
Classes:
-
ComponentMediaInput – Defines JS and CSS media files associated with this component.
-
MediaMeta – Metaclass for handling media files for components.
Defines JS and CSS media files associated with this component.
Bases: MediaDefiningClass
Metaclass for handling media files for components.
Similar to MediaDefiningClass, this class supports the use of Media attribute to define associated JS/CSS files, which are then available under media attribute as a instance of Media class.
This subclass has following changes:
1. Support for multiple interfaces of JS/CSS¤
-
As plain strings
class MyComponent(Component):
class Media:
js = "path/to/script.js"
css = "path/to/style.css"
diff --git a/dev/reference/django_components/component_registry/index.html b/dev/reference/django_components/component_registry/index.html
index bc4e56db..d96b66e6 100644
--- a/dev/reference/django_components/component_registry/index.html
+++ b/dev/reference/django_components/component_registry/index.html
@@ -1,4 +1,4 @@
- component_registry - Django-Components component_registry - Django-Components" > component_registry - Django-Components" >
module-attribute ¤
registry: ComponentRegistry = ComponentRegistry()
+ component_registry - Django-Components component_registry - Django-Components" > component_registry - Django-Components" >
Classes:
-
ComponentRegistry – Manages which components can be used in the template tags.
Functions:
-
register – Class decorator to register a component.
Attributes:
-
registry (ComponentRegistry) – The default and global component registry. Use this instance to directly
module-attribute ¤
registry: ComponentRegistry = ComponentRegistry()
The default and global component registry. Use this instance to directly register or remove components:
# Register components
registry.register("button", ButtonComponent)
registry.register("card", CardComponent)
@@ -26,7 +26,7 @@
registry.all()
registry.clear()
registry.get()
-
Source code in src/django_components/component_registry.py
86
+ Methods:
-
all – Retrieve all registered component classes.
-
clear – Clears the registry, unregistering all components.
-
get – Retrieve a component class registered under the given name.
-
register – Register a component with this registry under the given name.
-
unregister – Unlinks a previously-registered component from the registry under the given name.
Attributes:
-
library (Library) – The template tag library with which the component registry is associated.
Source code in src/django_components/component_registry.py
86
87
88
89
diff --git a/dev/reference/django_components/components/dynamic/index.html b/dev/reference/django_components/components/dynamic/index.html
index 36ad419f..a75440be 100644
--- a/dev/reference/django_components/components/dynamic/index.html
+++ b/dev/reference/django_components/components/dynamic/index.html
@@ -1,11 +1,11 @@
- dynamic - Django-Components dynamic - Django-Components" > dynamic - Django-Components" >