diff --git a/dev/reference/api/index.html b/dev/reference/api/index.html index e1d44d0f..8c8fda58 100644 --- a/dev/reference/api/index.html +++ b/dev/reference/api/index.html @@ -34,7 +34,7 @@

unregister classmethod ¤

unregister(library: Library) -> None

See source code

Unregisters the node from the given library.

Component ¤

Component(registered_name: Optional[str] = None, outer_context: Optional[Context] = None, registry: Optional[ComponentRegistry] = None)

Methods:

Attributes:

Media class-attribute instance-attribute ¤

Media: Optional[Type[ComponentMediaInput]] = None
-

See source code

Defines JS and CSS media files associated with this component.

This Media class behaves similarly to Django's Media class:

  • Paths are generally handled as static file paths, and resolved URLs are rendered to HTML with media_class.render_js() or media_class.render_css().
  • A path that starts with http, https, or / is considered a URL, skipping the static file resolution. This path is still rendered to HTML with media_class.render_js() or media_class.render_css().
  • A SafeString (with __html__ method) is considered an already-formatted HTML tag, skipping both static file resolution and rendering with media_class.render_js() or media_class.render_css().
  • You can set extend to configure whether to inherit JS / CSS from parent components. See Controlling Media Inheritance.

However, there's a few differences from Django's Media class:

  1. Our Media class accepts various formats for the JS and CSS files: either a single file, a list, or (CSS-only) a dictionary (See ComponentMediaInput).
  2. Individual JS / CSS files can be any of str, bytes, Path, SafeString, or a function (See ComponentMediaInputPath).

Example:

class MyTable(Component):
+

See source code

Defines JS and CSS media files associated with this component.

This Media class behaves similarly to Django's Media class:

  • Paths are generally handled as static file paths, and resolved URLs are rendered to HTML with media_class.render_js() or media_class.render_css().
  • A path that starts with http, https, or / is considered a URL, skipping the static file resolution. This path is still rendered to HTML with media_class.render_js() or media_class.render_css().
  • A SafeString (with __html__ method) is considered an already-formatted HTML tag, skipping both static file resolution and rendering with media_class.render_js() or media_class.render_css().
  • You can set extend to configure whether to inherit JS / CSS from parent components. See Controlling Media Inheritance.

However, there's a few differences from Django's Media class:

  1. Our Media class accepts various formats for the JS and CSS files: either a single file, a list, or (CSS-only) a dictionary (See ComponentMediaInput).
  2. Individual JS / CSS files can be any of str, bytes, Path, SafeString, or a function (See ComponentMediaInputPath).

Example:

class MyTable(Component):
     class Media:
         js = [
             "path/to/script.js",
@@ -49,14 +49,14 @@
         }

View class-attribute instance-attribute ¤

View = ComponentView

css class-attribute instance-attribute ¤

css: Optional[str] = None
-

See source code

Main CSS associated with this component inlined as string.

Only one of css or css_file must be defined.

Example:

class MyComponent(Component):
+

See source code

Main CSS associated with this component inlined as string.

Only one of css or css_file must be defined.

Example:

class MyComponent(Component):
     css = """
     .my-class {
         color: red;
     }
     """

css_file class-attribute instance-attribute ¤

css_file: Optional[str] = None
-

See source code

Main CSS associated with this component as file path.

The filepath must be either:

  • Relative to the directory where the Component's Python file is defined.
  • Relative to one of the component directories, as set by COMPONENTS.dirs or COMPONENTS.app_dirs (e.g. <root>/components/).
  • Relative to the staticfiles directories, as set by Django's STATICFILES_DIRS setting (e.g. <root>/static/).

When you create a Component class with css_file, these will happen:

  1. If the file path is relative to the directory where the component's Python file is, the path is resolved.
  2. The file is read and its contents is set to Component.css.

Only one of css or css_file must be defined.

Example:

path/to/style.css
.my-class {
+

See source code

Main CSS associated with this component as file path.

The filepath must be either:

  • Relative to the directory where the Component's Python file is defined.
  • Relative to one of the component directories, as set by COMPONENTS.dirs or COMPONENTS.app_dirs (e.g. <root>/components/).
  • Relative to the staticfiles directories, as set by Django's STATICFILES_DIRS setting (e.g. <root>/static/).

When you create a Component class with css_file, these will happen:

  1. If the file path is relative to the directory where the component's Python file is, the path is resolved.
  2. The file is read and its contents is set to Component.css.

Only one of css or css_file must be defined.

Example:

path/to/style.css
.my-class {
     color: red;
 }
path/to/component.py
class MyComponent(Component):
@@ -68,7 +68,7 @@
 #     color: red;
 # };

id property ¤

id: str
-

See source code

This ID is unique for every time a Component.render() (or equivalent) is called (AKA "render ID").

This is useful for logging or debugging.

Raises RuntimeError if accessed outside of rendering execution.

A single render ID has a chance of collision 1 in 3.3M. However, due to birthday paradox, the chance of collision increases when approaching ~1,000 render IDs.

Thus, there is a soft-cap of 1,000 components rendered on a single page.

If you need to more than that, please open an issue on GitHub.

Example:

class MyComponent(Component):
+

See source code

This ID is unique for every time a Component.render() (or equivalent) is called (AKA "render ID").

This is useful for logging or debugging.

Raises RuntimeError if accessed outside of rendering execution.

A single render ID has a chance of collision 1 in 3.3M. However, due to birthday paradox, the chance of collision increases when approaching ~1,000 render IDs.

Thus, there is a soft-cap of 1,000 components rendered on a single page.

If you need to more than that, please open an issue on GitHub.

Example:

class MyComponent(Component):
     def get_context_data(self):
         print(f"Rendering '{self.id}'")
         return {}
@@ -76,19 +76,19 @@
 MyComponent.render()
 # Rendering 'ab3c4d'

input property ¤

input: RenderInput[ArgsType, KwargsType, SlotsType]
-

See source code

Input holds the data (like arg, kwargs, slots) that were passed to the current execution of the render method.

is_filled property ¤

is_filled: SlotIsFilled
-

See source code

Dictionary describing which slots have or have not been filled.

This attribute is available for use only within the template as {{ component_vars.is_filled.slot_name }}, and within on_render_before and on_render_after hooks.

js class-attribute instance-attribute ¤

js: Optional[str] = None
-

See source code

Main JS associated with this component inlined as string.

Only one of js or js_file must be defined.

Example:

class MyComponent(Component):
+

See source code

Input holds the data (like arg, kwargs, slots) that were passed to the current execution of the render method.

is_filled property ¤

is_filled: SlotIsFilled
+

See source code

Dictionary describing which slots have or have not been filled.

This attribute is available for use only within the template as {{ component_vars.is_filled.slot_name }}, and within on_render_before and on_render_after hooks.

js class-attribute instance-attribute ¤

js: Optional[str] = None
+

See source code

Main JS associated with this component inlined as string.

Only one of js or js_file must be defined.

Example:

class MyComponent(Component):
     js = "console.log('Hello, World!');"

js_file class-attribute instance-attribute ¤

js_file: Optional[str] = None
-

See source code

Main JS associated with this component as file path.

The filepath must be either:

  • Relative to the directory where the Component's Python file is defined.
  • Relative to one of the component directories, as set by COMPONENTS.dirs or COMPONENTS.app_dirs (e.g. <root>/components/).
  • Relative to the staticfiles directories, as set by Django's STATICFILES_DIRS setting (e.g. <root>/static/).

When you create a Component class with js_file, these will happen:

  1. If the file path is relative to the directory where the component's Python file is, the path is resolved.
  2. The file is read and its contents is set to Component.js.

Only one of js or js_file must be defined.

Example:

path/to/script.js
console.log('Hello, World!');
+

See source code

Main JS associated with this component as file path.

The filepath must be either:

  • Relative to the directory where the Component's Python file is defined.
  • Relative to one of the component directories, as set by COMPONENTS.dirs or COMPONENTS.app_dirs (e.g. <root>/components/).
  • Relative to the staticfiles directories, as set by Django's STATICFILES_DIRS setting (e.g. <root>/static/).

When you create a Component class with js_file, these will happen:

  1. If the file path is relative to the directory where the component's Python file is, the path is resolved.
  2. The file is read and its contents is set to Component.js.

Only one of js or js_file must be defined.

Example:

path/to/script.js
console.log('Hello, World!');
path/to/component.py
class MyComponent(Component):
     js_file = "path/to/script.js"
 
 print(MyComponent.js)
 # Output: console.log('Hello, World!');

media class-attribute instance-attribute ¤

media: Optional[Media] = None
-

See source code

Normalized definition of JS and CSS media files associated with this component. None if Component.Media is not defined.

This field is generated from Component.media_class.

Read more on Accessing component's HTML / JS / CSS.

Example:

class MyComponent(Component):
+

See source code

Normalized definition of JS and CSS media files associated with this component. None if Component.Media is not defined.

This field is generated from Component.media_class.

Read more on Accessing component's HTML / JS / CSS.

Example:

class MyComponent(Component):
     class Media:
         js = "path/to/script.js"
         css = "path/to/style.css"
@@ -98,7 +98,7 @@
 # <script src="/static/path/to/script.js"></script>
 # <link href="/static/path/to/style.css" media="all" rel="stylesheet">

media_class class-attribute instance-attribute ¤

media_class: Type[Media] = Media
-

See source code

Set the Media class that will be instantiated with the JS and CSS media files from Component.Media.

This is useful when you want to customize the behavior of the media files, like customizing how the JS or CSS files are rendered into <script> or <link> HTML tags. Read more in Defining HTML / JS / CSS files.

Example:

class MyTable(Component):
+

See source code

Set the Media class that will be instantiated with the JS and CSS media files from Component.Media.

This is useful when you want to customize the behavior of the media files, like customizing how the JS or CSS files are rendered into <script> or <link> HTML tags. Read more in Defining HTML / JS / CSS files.

Example:

class MyTable(Component):
     class Media:
         js = "path/to/script.js"
         css = "path/to/style.css"
@@ -109,25 +109,25 @@

registered_name instance-attribute ¤

registered_name: Optional[str] = registered_name

registry instance-attribute ¤

registry = registry or registry

response_class class-attribute instance-attribute ¤

response_class = HttpResponse
-

See source code

This allows to configure what class is used to generate response from render_to_response

template class-attribute instance-attribute ¤

template: Optional[Union[str, Template]] = None
-

See source code

Inlined Django template associated with this component. Can be a plain string or a Template instance.

Only one of template_file, get_template_name, template or get_template must be defined.

Example:

class MyComponent(Component):
+

See source code

This allows to configure what class is used to generate response from render_to_response

template class-attribute instance-attribute ¤

template: Optional[Union[str, Template]] = None
+

See source code

Inlined Django template associated with this component. Can be a plain string or a Template instance.

Only one of template_file, get_template_name, template or get_template must be defined.

Example:

class MyComponent(Component):
     template = "Hello, {{ name }}!"
 
     def get_context_data(self):
         return {"name": "World"}

template_file class-attribute instance-attribute ¤

template_file: Optional[str] = None
-

See source code

Filepath to the Django template associated with this component.

The filepath must be either:

  • Relative to the directory where the Component's Python file is defined.
  • Relative to one of the component directories, as set by COMPONENTS.dirs or COMPONENTS.app_dirs (e.g. <root>/components/).
  • Relative to the template directories, as set by Django's TEMPLATES setting (e.g. <root>/templates/).

Only one of template_file, get_template_name, template or get_template must be defined.

Example:

class MyComponent(Component):
+

See source code

Filepath to the Django template associated with this component.

The filepath must be either:

  • Relative to the directory where the Component's Python file is defined.
  • Relative to one of the component directories, as set by COMPONENTS.dirs or COMPONENTS.app_dirs (e.g. <root>/components/).
  • Relative to the template directories, as set by Django's TEMPLATES setting (e.g. <root>/templates/).

Only one of template_file, get_template_name, template or get_template must be defined.

Example:

class MyComponent(Component):
     template_file = "path/to/template.html"
 
     def get_context_data(self):
         return {"name": "World"}

template_name instance-attribute ¤

template_name: Optional[str]
-

See source code

Alias for template_file.

For historical reasons, django-components used template_name to align with Django's TemplateView.

template_file was introduced to align with js/js_file and css/css_file.

Setting and accessing this attribute is proxied to template_file.

as_view classmethod ¤

as_view(**initkwargs: Any) -> ViewFn
-

See source code

Shortcut for calling Component.View.as_view and passing component instance to it.

get_context_data ¤

get_context_data(*args: Any, **kwargs: Any) -> DataType
+

See source code

Alias for template_file.

For historical reasons, django-components used template_name to align with Django's TemplateView.

template_file was introduced to align with js/js_file and css/css_file.

Setting and accessing this attribute is proxied to template_file.

as_view classmethod ¤

as_view(**initkwargs: Any) -> ViewFn
+

See source code

Shortcut for calling Component.View.as_view and passing component instance to it.

get_context_data ¤

get_context_data(*args: Any, **kwargs: Any) -> DataType

get_template ¤

get_template(context: Context) -> Optional[Union[str, Template]]
-

See source code

Inlined Django template associated with this component. Can be a plain string or a Template instance.

Only one of template_file, get_template_name, template or get_template must be defined.

get_template_name ¤

get_template_name(context: Context) -> Optional[str]
-

See source code

Filepath to the Django template associated with this component.

The filepath must be relative to either the file where the component class was defined, or one of the roots of STATIFILES_DIRS.

Only one of template_file, get_template_name, template or get_template must be defined.

inject ¤

inject(key: str, default: Optional[Any] = None) -> Any
-

See source code

Use this method to retrieve the data that was passed to a {% provide %} tag with the corresponding key.

To retrieve the data, inject() must be called inside a component that's inside the {% provide %} tag.

You may also pass a default that will be used if the provide tag with given key was NOT found.

This method mut be used inside the get_context_data() method and raises an error if called elsewhere.

Example:

Given this template: 

{% provide "provider" hello="world" %}
+

See source code

Inlined Django template associated with this component. Can be a plain string or a Template instance.

Only one of template_file, get_template_name, template or get_template must be defined.

get_template_name ¤

get_template_name(context: Context) -> Optional[str]
+

See source code

Filepath to the Django template associated with this component.

The filepath must be relative to either the file where the component class was defined, or one of the roots of STATIFILES_DIRS.

Only one of template_file, get_template_name, template or get_template must be defined.

inject ¤

inject(key: str, default: Optional[Any] = None) -> Any
+

See source code

Use this method to retrieve the data that was passed to a {% provide %} tag with the corresponding key.

To retrieve the data, inject() must be called inside a component that's inside the {% provide %} tag.

You may also pass a default that will be used if the provide tag with given key was NOT found.

This method mut be used inside the get_context_data() method and raises an error if called elsewhere.

Example:

Given this template: 

{% provide "provider" hello="world" %}
     {% component "my_comp" %}
     {% endcomponent %}
 {% endprovide %}
@@ -141,8 +141,8 @@
         return {"data": data}

This renders into: 

hi world!

As the {{ data.hello }} is taken from the "provider".

on_render_after ¤

on_render_after(context: Context, template: Template, content: str) -> Optional[SlotResult]
-

See source code

Hook that runs just after the component's template was rendered. It receives the rendered output as the last argument.

You can use this hook to access the context or the template, but modifying them won't have any effect.

To override the content that gets rendered, you can return a string or SafeString from this hook.

on_render_before ¤

on_render_before(context: Context, template: Template) -> None
-

See source code

Hook that runs just before the component's template is rendered.

You can use this hook to access or modify the context or the template.

render classmethod ¤

render(
+

See source code

Hook that runs just after the component's template was rendered. It receives the rendered output as the last argument.

You can use this hook to access the context or the template, but modifying them won't have any effect.

To override the content that gets rendered, you can return a string or SafeString from this hook.

on_render_before ¤

on_render_before(context: Context, template: Template) -> None
+

See source code

Hook that runs just before the component's template is rendered.

You can use this hook to access or modify the context or the template.

render classmethod ¤

render(
     context: Optional[Union[Dict[str, Any], Context]] = None,
     args: Optional[ArgsType] = None,
     kwargs: Optional[KwargsType] = None,
@@ -152,7 +152,7 @@
     render_dependencies: bool = True,
     request: Optional[HttpRequest] = None,
 ) -> str
-

See source code

Render the component into a string.

Inputs: - args - Positional args for the component. This is the same as calling the component as {% component "my_comp" arg1 arg2 ... %} - kwargs - Kwargs for the component. This is the same as calling the component as {% component "my_comp" key1=val1 key2=val2 ... %} - slots - Component slot fills. This is the same as pasing {% fill %} tags to the component. Accepts a dictionary of { slot_name: slot_content } where slot_content can be a string or render function. - escape_slots_content - Whether the content from slots should be escaped. - context - A context (dictionary or Django's Context) within which the component is rendered. The keys on the context can be accessed from within the template. - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via component's args and kwargs. - type - Configure how to handle JS and CSS dependencies. - "document" (default) - JS dependencies are inserted into {% component_js_dependencies %}, or to the end of the <body> tag. CSS dependencies are inserted into {% component_css_dependencies %}, or the end of the <head> tag. - render_dependencies - Set this to False if you want to insert the resulting HTML into another component. - request - The request object. This is only required when needing to use RequestContext, e.g. to enable template context_processors. Unused if context is already an instance of Context Example: 

MyComponent.render(
+

See source code

Render the component into a string.

Inputs: - args - Positional args for the component. This is the same as calling the component as {% component "my_comp" arg1 arg2 ... %} - kwargs - Kwargs for the component. This is the same as calling the component as {% component "my_comp" key1=val1 key2=val2 ... %} - slots - Component slot fills. This is the same as pasing {% fill %} tags to the component. Accepts a dictionary of { slot_name: slot_content } where slot_content can be a string or render function. - escape_slots_content - Whether the content from slots should be escaped. - context - A context (dictionary or Django's Context) within which the component is rendered. The keys on the context can be accessed from within the template. - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via component's args and kwargs. - type - Configure how to handle JS and CSS dependencies. - "document" (default) - JS dependencies are inserted into {% component_js_dependencies %}, or to the end of the <body> tag. CSS dependencies are inserted into {% component_css_dependencies %}, or the end of the <head> tag. - render_dependencies - Set this to False if you want to insert the resulting HTML into another component. - request - The request object. This is only required when needing to use RequestContext, e.g. to enable template context_processors. Unused if context is already an instance of Context Example: 

MyComponent.render(
     args=[1, "two", {}],
     kwargs={
         "key": 123,
@@ -174,7 +174,7 @@
     *response_args: Any,
     **response_kwargs: Any
 ) -> HttpResponse
-

See source code

Render the component and wrap the content in the response class.

The response class is taken from Component.response_class. Defaults to django.http.HttpResponse.

This is the interface for the django.views.View class which allows us to use components as Django views with component.as_view().

Inputs: - args - Positional args for the component. This is the same as calling the component as {% component "my_comp" arg1 arg2 ... %} - kwargs - Kwargs for the component. This is the same as calling the component as {% component "my_comp" key1=val1 key2=val2 ... %} - slots - Component slot fills. This is the same as pasing {% fill %} tags to the component. Accepts a dictionary of { slot_name: slot_content } where slot_content can be a string or render function. - escape_slots_content - Whether the content from slots should be escaped. - context - A context (dictionary or Django's Context) within which the component is rendered. The keys on the context can be accessed from within the template. - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via component's args and kwargs. - type - Configure how to handle JS and CSS dependencies. - "document" (default) - JS dependencies are inserted into {% component_js_dependencies %}, or to the end of the <body> tag. CSS dependencies are inserted into {% component_css_dependencies %}, or the end of the <head> tag. - request - The request object. This is only required when needing to use RequestContext, e.g. to enable template context_processors. Unused if context is already an instance of Context

Any additional args and kwargs are passed to the response_class.

Example: 

MyComponent.render_to_response(
+

See source code

Render the component and wrap the content in the response class.

The response class is taken from Component.response_class. Defaults to django.http.HttpResponse.

This is the interface for the django.views.View class which allows us to use components as Django views with component.as_view().

Inputs: - args - Positional args for the component. This is the same as calling the component as {% component "my_comp" arg1 arg2 ... %} - kwargs - Kwargs for the component. This is the same as calling the component as {% component "my_comp" key1=val1 key2=val2 ... %} - slots - Component slot fills. This is the same as pasing {% fill %} tags to the component. Accepts a dictionary of { slot_name: slot_content } where slot_content can be a string or render function. - escape_slots_content - Whether the content from slots should be escaped. - context - A context (dictionary or Django's Context) within which the component is rendered. The keys on the context can be accessed from within the template. - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via component's args and kwargs. - type - Configure how to handle JS and CSS dependencies. - "document" (default) - JS dependencies are inserted into {% component_js_dependencies %}, or to the end of the <body> tag. CSS dependencies are inserted into {% component_css_dependencies %}, or the end of the <head> tag. - request - The request object. This is only required when needing to use RequestContext, e.g. to enable template context_processors. Unused if context is already an instance of Context

Any additional args and kwargs are passed to the response_class.

Example: 

MyComponent.render_to_response(
     args=[1, "two", {}],
     kwargs={
         "key": 123,
diff --git a/dev/reference/template_tags/index.html b/dev/reference/template_tags/index.html
index 87cf3ebc..fe42fe5a 100644
--- a/dev/reference/template_tags/index.html
+++ b/dev/reference/template_tags/index.html
@@ -3,7 +3,7 @@

See source code

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)

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¤

{% component_js_dependencies  %}

See source code

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)

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.

component¤

{% component *args: Any, **kwargs: Any [only] %}
 {% endcomponent %}
-

See source code

Renders one of the components that was previously registered with @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"

from django_component import Component, register
+

See source code

Renders one of the components that was previously registered with @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"

from django_component import Component, register
 
 @register("my_table")
 class MyTable(Component):
diff --git a/versions.json b/versions.json
index 8498b765..b9705aa6 100644
--- a/versions.json
+++ b/versions.json
@@ -1,7 +1,7 @@
 [
   {
     "version": "dev",
-    "title": "dev (5880538)",
+    "title": "dev (96f48bc)",
     "aliases": []
   },
   {