Info
The deps_strategy parameter is ultimately passed to render_dependencies().
Why is deps_strategy required?
This is a technical limitation of the current implementation.
When a component is rendered, django-components embeds metadata about the component's JS and CSS into the HTML.
This way we can compose components together, and know which JS / CSS dependencies are needed.
As the last step of rendering, django-components extracts this metadata and uses a selected strategy to insert the JS / CSS into the HTML.
There are six dependencies strategies:
document (default)<head> and <body> tags.fragment strategy to work.fragmentsimple<head> and <body> tags.prependappendignorerender_dependencies().document¤deps_strategy="document" is the default. Use this if you are rendering a whole page, or if no other option suits better.
Info
The deps_strategy parameter is ultimately passed to render_dependencies().
Why is deps_strategy required?
This is a technical limitation of the current implementation.
When a component is rendered, django-components embeds metadata about the component's JS and CSS into the HTML.
This way we can compose components together, and know which JS / CSS dependencies are needed.
As the last step of rendering, django-components extracts this metadata and uses a selected strategy to insert the JS / CSS into the HTML.
There are six dependencies strategies:
document (default)<head> and <body> tags.fragmentsimple<head> and <body> tags.prependappendignorerender_dependencies().document¤deps_strategy="document" is the default. Use this if you are rendering a whole page, or if no other option suits better.
When you render a component tree with the "document" strategy, it is expected that:
Location:
JS and CSS is inserted:
{% component_js_dependencies %}<body> element, and CSS into <head> elementIncluded scripts:
For the "document" strategy, the JS and CSS is set up to avoid any delays when the end user loads the page in the browser:
Components' primary JS and CSS scripts (Component.js and Component.css) - fully inlined:
Components' secondary JS and CSS scripts (Component.Media) - inserted as links:
A JS script is injected to manage component dependencies, enabling lazy loading of JS and CSS for HTML fragments.
Info
This strategy is required for fragments to work properly, as it sets up the dependency manager that fragments rely on.
How the dependency manager works
The dependency manager is a JS script that keeps track of all the JS and CSS dependencies that have already been loaded.
When a fragment is inserted into the page, it will also insert a JSON <script> tag with fragment metadata.
The dependency manager will pick up on that, and check which scripts the fragment needs.
It will then fetch only the scripts that haven't been loaded yet.
fragment¤deps_strategy="fragment" is used when rendering a piece of HTML that will be inserted into a page that has already been rendered with the "document" strategy:
A JS script is injected to manage component dependencies, enabling lazy loading of JS and CSS for HTML fragments.
How the dependency manager works
The dependency manager is a JS script that keeps track of all the JS and CSS dependencies that have already been loaded.
When a fragment is inserted into the page, it will also insert a JSON <script> tag with fragment metadata.
The dependency manager will pick up on that, and check which scripts the fragment needs.
It will then fetch only the scripts that haven't been loaded yet.
fragment¤deps_strategy="fragment" is used when rendering a piece of HTML that will be inserted into a page:
The HTML of fragments is very lightweight because it doesn't include the JS and CSS scripts of the rendered components.
With fragments, even if a component has JS and CSS, you can insert the same component into a page hundreds of times, and the JS and CSS will only ever be loaded once.
This is intended for dynamic content that's loaded with AJAX after the initial page load, such as with jQuery, HTMX, AlpineJS or similar libraries.
Location:
None. The fragment's JS and CSS files will be loaded dynamically into the page.
Included scripts:
<script> tag that tells the dependency manager what JS and CSS to load.simple¤deps_strategy="simple" is used either for non-browser use cases, or when you don't want to use the dependency manager.
Practically, this is the same as the "document" strategy, except that the dependency manager is not used.
Location:
JS and CSS is inserted:
{% component_js_dependencies %}<body> element, and CSS into <head> elementIncluded scripts:
Components' primary JS and CSS scripts (Component.js and Component.css) - fully inlined:
<script>
console.log("Hello from Button!");
@@ -106,4 +106,4 @@
html2 = MyComponent.render(deps_strategy="document")
assert html == html2
-Django-components provides a seamless integration with HTML fragments with AJAX (HTML over the wire), whether you're using jQuery, HTMX, AlpineJS, vanilla JavaScript, or other.
This is achieved by the combination of the "document" and "fragment" strategies.
Read more about HTML fragments.