diff --git a/dev/reference/api/index.html b/dev/reference/api/index.html index 224e4dc5..0dfe4d76 100644 --- a/dev/reference/api/index.html +++ b/dev/reference/api/index.html @@ -1,7 +1,7 @@ Api - Django-Components
Skip to content

API¤

BaseNode ¤

BaseNode(
     params: List[TagAttr], flags: Optional[Dict[str, bool]] = None, nodelist: Optional[NodeList] = None, node_id: Optional[str] = None
 )
-

Bases: django.template.base.Node

See source code

Node class for all django-components custom template tags.

This class has a dual role:

  1. It declares how a particular template tag should be parsed - By setting the tag, end_tag, and allowed_flags attributes:

    class SlotNode(BaseNode):
+

    Bases: django.template.base.Node

    See source code

    Node class for all django-components custom template tags.

    This class has a dual role:

    1. It declares how a particular template tag should be parsed - By setting the tag, end_tag, and allowed_flags attributes:

      class SlotNode(BaseNode):
     tag = "slot"
     end_tag = "endslot"
     allowed_flags = ["required"]
@@ -13,26 +13,26 @@
         return f"Hello, {name}!"

      This will allow the template tag {% mynode %} to be used like this:

      {% mynode name="John" %}

    The template tag accepts parameters as defined on the render method's signature.

    For more info, see BaseNode.render().

    Methods:

    Attributes:

    active_flags property ¤

    active_flags: List[str]
-

    See source code

    Flags that were set for this specific instance.

    allowed_flags class-attribute instance-attribute ¤

    allowed_flags: Optional[List[str]] = None
-

    See source code

    The allowed flags for this tag.

    E.g. ["required"] will allow this tag to be used like {% slot required %}.

    end_tag class-attribute instance-attribute ¤

    end_tag: Optional[str] = None
-

    See source code

    The end tag name.

    E.g. "endcomponent" or "endslot" will make this class match template tags {% endcomponent %} or {% endslot %}.

    If not set, then this template tag has no end tag.

    So instead of {% component %} ... {% endcomponent %}, you'd use only {% component %}.

    flags instance-attribute ¤

    flags = flags or {flag: Falsefor flag in allowed_flags or []}
+

    See source code

    Flags that were set for this specific instance.

    allowed_flags class-attribute instance-attribute ¤

    allowed_flags: Optional[List[str]] = None
+

    See source code

    The allowed flags for this tag.

    E.g. ["required"] will allow this tag to be used like {% slot required %}.

    end_tag class-attribute instance-attribute ¤

    end_tag: Optional[str] = None
+

    See source code

    The end tag name.

    E.g. "endcomponent" or "endslot" will make this class match template tags {% endcomponent %} or {% endslot %}.

    If not set, then this template tag has no end tag.

    So instead of {% component %} ... {% endcomponent %}, you'd use only {% component %}.

    flags instance-attribute ¤

    flags = flags or {flag: Falsefor flag in allowed_flags or []}

    node_id instance-attribute ¤

    node_id = node_id or gen_id()

    nodelist instance-attribute ¤

    nodelist = nodelist or NodeList()

    params instance-attribute ¤

    params = params

    tag instance-attribute ¤

    tag: str
-

    See source code

    The tag name.

    E.g. "component" or "slot" will make this class match template tags {% component %} or {% slot %}.

    parse classmethod ¤

    parse(parser: Parser, token: Token, **kwargs: Any) -> BaseNode
-

    See source code

    This function is what is passed to Django's Library.tag() when registering the tag.

    In other words, this method is called by Django's template parser when we encounter a tag that matches this node's tag, e.g. {% component %} or {% slot %}.

    To register the tag, you can use BaseNode.register().

    register classmethod ¤

    register(library: Library) -> None
-

    See source code

    A convenience method for registering the tag with the given library.

    class MyNode(BaseNode):
+

    See source code

    The tag name.

    E.g. "component" or "slot" will make this class match template tags {% component %} or {% slot %}.

    parse classmethod ¤

    parse(parser: Parser, token: Token, **kwargs: Any) -> BaseNode
+

    See source code

    This function is what is passed to Django's Library.tag() when registering the tag.

    In other words, this method is called by Django's template parser when we encounter a tag that matches this node's tag, e.g. {% component %} or {% slot %}.

    To register the tag, you can use BaseNode.register().

    register classmethod ¤

    register(library: Library) -> None
+

    See source code

    A convenience method for registering the tag with the given library.

    class MyNode(BaseNode):
     tag = "mynode"
 
 MyNode.register(library)

    Allows you to then use the node in templates like so:

    {% load mylibrary %}
 {% mynode %}

    render ¤

    render(context: Context, *args: Any, **kwargs: Any) -> str
-

    See source code

    Render the node. This method is meant to be overridden by subclasses.

    The signature of this function decides what input the template tag accepts.

    The render() method MUST accept a context argument. Any arguments after that will be part of the tag's input parameters.

    So if you define a render method like this:

    def render(self, context: Context, name: str, **kwargs: Any) -> str:
+

    See source code

    Render the node. This method is meant to be overridden by subclasses.

    The signature of this function decides what input the template tag accepts.

    The render() method MUST accept a context argument. Any arguments after that will be part of the tag's input parameters.

    So if you define a render method like this:

    def render(self, context: Context, name: str, **kwargs: Any) -> str:

    Then the tag will require the name parameter, and accept any extra keyword arguments:

    {% component name="John" age=20 %}

    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)
+

    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):
     class Media:
@@ -693,7 +693,7 @@

template_tag ¤

template_tag(
     library: Library, tag: str, end_tag: Optional[str] = None, allowed_flags: Optional[List[str]] = None
 ) -> Callable[[Callable], Callable]
-

See source code

A simplified version of creating a template tag based on BaseNode.

Instead of defining the whole class, you can just define the render() method.

from django.template import Context, Library
+

See source code

A simplified version of creating a template tag based on BaseNode.

Instead of defining the whole class, you can just define the render() method.

from django.template import Context, Library
 from django_components import BaseNode, template_tag
 
 library = Library()
diff --git a/versions.json b/versions.json
index 414f5e93..9ff36f18 100644
--- a/versions.json
+++ b/versions.json
@@ -1,7 +1,7 @@
 [
   {
     "version": "dev",
-    "title": "dev (f52f125)",
+    "title": "dev (c7aba40)",
     "aliases": []
   },
   {