joop.web.html — joop 0.0.1 documentation

# joop.web.html

An HTML Component is a joop Component that renders to HTML.

Like many projects, joop achieves this via jinja templating. There is a specific structure for template variables that joop imposes to meet its goals of providing a “place for everything and everything in its place.”

Classes:
  HTML:

    A base class for managing Jinja2 templates and rendering HTML content.

  HTMLComponent:

    A component class that extends both Component and HTML to provide functionality for rendering HTML components with subcomponents and data.

Classes

`HTML`([j_env]) | A base class for managing Jinja2 templates and rendering HTML content.
`HTMLComponent`([j_env, parent]) | A component class that extends both Component and HTML to provide functionality for rendering HTML components with subcomponents and data.

class joop.web.html.HTML(j_env: Environment | None = None)

  Bases: `object`

  A base class for managing Jinja2 templates and rendering HTML content.

  Its main purpose is to tie behavior to a specific Jinja2 env, especially

    in terms of template location.

  This class provides methods for initializing and managing a Jinja2 environment and loading templates for rendering HTML.

  _template_location

    The location of the Jinja2 template file.

    Type:

      str

  _jinja_env

    The Jinja2 environment used for rendering.

    Type:

      Optional[jinja2.Environment]

  __init__(j_env

    Optional[jinja2.Environment] = None): Initializes the HTML class with a Jinja2 environment.

  _get_template() → jinja2.Template

    Retrieves the Jinja2 template based on the template location.

  __init__(j_env: Environment | None = None)

    Initialize the HTML class with a Jinja2 environment.

    Parameters:

      j_env (Optional[jinja2.Environment]) – The Jinja2 environment to use for rendering.

    Raises:

      ValueError – If no Jinja2 environment is provided or available.

class joop.web.html.HTMLComponent(j_env: Environment | None = None, parent: Component | None = None)

  Bases: `Component`, `HTML`

  A component class that extends both Component and HTML to provide functionality for rendering HTML components with subcomponents and data.

  This class integrates the base Component class with the HTML class to enable dynamic rendering of HTML components using Jinja2 templates.

  _loaded_template

    The loaded Jinja2 template for the component.

    Type:

      jinja2.Template

  __init__(j_env

    Optional[jinja2.Environment] = None, parent: Optional[Component] = None): Initializes the HTMLComponent with a Jinja2 environment and an optional parent component.

  _load_template()

    Loads the Jinja2 template for the component.

  render(as_subcomponent

    bool = False, **kwargs) -> str: Renders the component as a string, optionally as a subcomponent.

  Nested Classes:
    SubComponents:

      A class for managing subcomponents of the HTMLComponent.

      Methods:
        get_all -> dict[str, ‘Component’]:

          Retrieves all subcomponents as a dictionary.

        render():

          Renders all subcomponents and stores their HTML output.

        get_rendered() -> dict[str, str]:

          Returns the rendered HTML output of all subcomponents.

  class Data

    Bases: `_Data`

    Class for defining the processed data of a component.

    _from_inputs(inputs

      Component.Inputs) -> Component.Data: Creates a Data instance from the given Inputs.

    from_inputs(inputs

      Component.Inputs) -> Component.Data: Abstract method to create a Data instance from the given Inputs.

    __init__() → None
    from_inputs

      A descriptor for defining abstract methods in classes.

      This class is particularly useful when working with ABCMeta classes and/or dataclasses. It allows marking methods as abstract, ensuring that they must be overridden in subclasses.

      Example usage:

        @classmethod def _my_abstract_class_method(cls, something: Any):

        > raise NotImplementedError(“Abstract; not implemented”)

        _my_abstract_class_method = AbstractMethod(_my_abstract_class_method)

      func

        The function to be marked as abstract.

        Type:

          callable

      _isabstract

        A flag indicating whether the method is abstract.

        Type:

          bool

  class Inputs

    Bases: `object`

    Abstract base class for defining the input data structure of a component.

    __init__() → None
  class SubComponents

    Bases: `SubComponents`

    A class for managing subcomponents of the HTMLComponent.

    get_all -> dict[str, 'Component']

      Retrieves all subcomponents as a dictionary.

    render()

      Renders all subcomponents and stores their HTML output.

    get_rendered() → dict[str, str]

      Returns the rendered HTML output of all subcomponents.

    __init__() → None
    property get_all: dict[str, Component]

      Retrieve all subcomponents as a dictionary.

      Returns:

        A dictionary where keys are subcomponent names and values are the subcomponent instances.

      Return type:

        dict[str, Component]

    get_rendered() → dict[str, str]

      Return the rendered HTML output of all subcomponents.

      This method ensures that all subcomponents are rendered and returns their HTML output as a dictionary.

      Returns:

        A dictionary where keys are subcomponent names and values are their rendered HTML output.

      Return type:

        dict[str, str]

    render()

      Render all subcomponents and store their HTML output.

      This method iterates through all subcomponents, renders each one, and stores the resulting HTML in a dictionary.

  __init__(j_env: Environment | None = None, parent: Component | None = None)

    Initialize the HTMLComponent with a Jinja2 environment and an optional parent component.

    Parameters:

      - j_env (Optional[jinja2.Environment]) – The Jinja2 environment to use for rendering.

      - parent (Optional[Component]) – The parent component, if any.

  data: Data
  inputs: Inputs
  render(as_subcomponent: bool = False, **kwargs) → str

    Render the component as a string, optionally as a subcomponent.

    This method prepares the component for rendering, loads the template, and renders the HTML output using the provided data and subcomponents.

    Parameters:

      - as_subcomponent (bool) – Whether to render the component as a subcomponent.

      - **kwargs – Additional keyword arguments for rendering.

    Returns:

      The rendered HTML output.

    Return type:

      str

  subs: SubComponents