Rendering logic

pantra is intended to manipulate DOM tree and content, where each component is declared in HTML-like text file. This part of magic named is doing by rendering engine, or renderer:

1. Locate component related template file.

2. Read and parse it by ANTLR4 parser.

3. Generate HTMLTemplate templates objects tree.

4. Use template objects tree as a factory to render components:

• Generate specific render nodes

• Precompile local scripts

• Run context initializers

1. Update components states on demand.

2. Additionally, renderer controls access to the static and media files, so, it is connected with routing.

digraph "Rendering engine" { size="4,4"; Templates -> Factory; Factory [label="Renderer"]; Factory -> "DOM tree" [label="rendering"]; "DOM tree" -> Browser; Browser -> Events; Events [shape=diamond]; Events -> Factory [label="actions"]; }

Node templates

class pantra.components.template.HTMLTemplate(tag_name: str, parent: Self | None = None, attributes: dict | None = None, text: str = None)

The rendering node template based on HTML-like source file

Parameters:

• tag_name (str)

• parent (Self | None)

• attributes (dict | None)

• text (str)

tag_name

tag name of the node

Type:

str

node_type

node type

Type:

NodeType

attributes

node attributes

Type:

dict[str, …]

attr_specs

attribute specifications

Type:

dict[str, tuple[AttrType, str | None, bool]]

content

content of the node

Type:

str | MacroCode | None

name

component name for the root node

Type:

str

filename

component source file name (for the root node)

Type:

Path

code

compiled Python script

Type:

str | CodeType | None

code_metrics

compiled Python code metrics

Type:

CodeMetrics

script_index

JavaScript index for renderer

Type:

int

hex_digest

hexadecimal digest of the source text file for observer watchdog

Type:

str

class pantra.components.template.NodeType(*values)

Enumerated type of the node

class pantra.components.template.AttrType(*values)

Enumerated type of the attribute

class pantra.components.template.MacroType(*values)

Enumerated type of the macro

class pantra.components.template.MacroCode(type: MacroType, reactive: bool, evaluated: bool, code: CodeType | list[str] | str | None, src: str)

Python code adaptation for scripts and expressions

Parameters:

• type (MacroType)

• reactive (bool)

• evaluated (bool)

• code (CodeType | list[str] | str | None)

• src (str)

type

type of this macro code

Type:

MacroType

reactive

marked as reactive

Type:

bool

evaluated

marked as evaluated

Type:

bool

src

source text

Type:

str

code

compiled code in one of three forms

Type:

CodeType | list[str] | str | None

vars

reactive variables list

Type:

set[str]

pantra.components.template.collect_template(name: str, session: Session | None = None, app: str | None = None) → HTMLTemplate | None

Use DEFAULT_RENDERER to collect template of the specified component name

Parameters:

• name (str) – name of the component

• session (Optional[Session]) – Optional session instance, used for loading feedback messages

• app (Optional[str]) – Optional application instance if session is not defined

Return type:

Optional[HTMLTemplate]

pantra.components.template.collect_styles(app: str, app_path: Path, error_callback: Callable[[str], None]) → str

Collect and compile all CSS styles from all components

Parameters:

• app (str) – application name (needed to generate static file urls)

• app_path (Path) – application path (needed to find template files)

• error_callback (Callable[[str], None]) – callback function to handle errors during parsing and compilation

Return type:

str

Rendering model

class pantra.components.render.renderer_base.RendererBase(ctx: Context)

Renderer base class

Parameters:

ctx (Context)

ctx

Local context of component

templates

(class variable) dictionary of all loaded templates

Type:

ClassVar[dict[str, Any]]

abstractmethod classmethod collect_template(name: str, session: Session | None = None, app: str | None = None) → HTMLTemplate | CodeType | None

Abstract method to collect component’s template by given name

Parameters:

• name (str) – component name

• session (Optional[Session]) – Optional session instance, used for loading feedback messages

• app (Optional[str]) – Optional application instance if session is not defined

Returns:

HTMLTemplate or factory

Return type:

Optional[HTMLTemplate | CodeType]

add(tag_name: str, parent: RenderNode) → HTMLElement

Add HTML element with specified tag to this context.

Parameters:

• tag_name (str) – tag name (“div”, “p”, etc.)

• parent (RenderNode) – parent node inside this context, if specified

Return type:

HTMLElement

build()

Build this node by associated template and prepare for continues rendering

abstractmethod build_node(template: Any, parent: RenderNode | None = None) → RenderNode | None

Build child node from given template within current context

Note

Not necessary to call this method directly. Use build() and render() instead.

Parameters:

• template (Any) – template node or factory

• parent (Optional[RenderNode]) – parent node inside this context, if specified

Return type:

Optional[RenderNode]

update_children(node: RenderNode)

Update all child nodes recursively

Parameters:

node (RenderNode) – node to update

abstractmethod update(node: RenderNode, recursive: bool = False)

Update rendered node, to sync changes

Parameters:

• node (RenderNode) – node to update

• recursive (bool) – update children recursively

render(template: str | HTMLTemplate | CodeType, parent: RenderNode = None, locals: dict = None, build: bool = True)

Render new node.

Parameters:

• template (str | HTMLTemplate | CodeType) – template to render or code

• parent (RenderNode) – parent node inside this context, if specified

• locals (dict) – locals dict for current context

• build (bool) – whether to build the node

There are two builtin renderers:

• RendererHTML - to render from HTML-like files

• RendererCached - to render from cached classes

Default renderer is specified by parameter DEFAULT_RENDERER in configuration.

class pantra.components.render.renderer_html.RendererHTML(ctx: Context)

Renderer from HTML-like files

Parameters:

ctx (Context)

class pantra.cached.renderer.RendererCached(ctx: Context)

Renderer from cached component classes

Parameters:

ctx (Context)