Skip to content

Home Information - Your home, your data, organized.

Python
3.6 KB
Raw Blame
"""
External-data view models for the entity-detail modal.

An integration's gateway returns an ``ExternalViewData`` subclass
instance from ``get_external_view_data(entity)`` to render the
external-data view region of the modal; returning ``None`` suppresses
that region entirely. ``template_name`` is a class-level attribute on
each subclass pointing at the partial that renders it; integrations
can provide their own subclass with a custom ``template_name`` for
fully bespoke layouts.

Default partials live under
``hi/integrations/templates/integrations/external_data/entity/``.
"""
from dataclasses import dataclass, field
from typing import Dict, List, Optional


@dataclass
class NameValuePair:
    """A single named value for display in a ``StructuredViewData``
    attribute list. Order is determined by list position."""
    name: str
    value: str


@dataclass
class AttachmentRef:
    """A reference to an externally-hosted attachment for display in a
    ``StructuredViewData`` attachment grid. The integration is
    responsible for providing a working ``thumbnail_url`` and
    ``open_url`` (which may point at HI proxy endpoints for auth-gated
    upstreams)."""
    id: str
    title: str
    mime_type: str
    thumbnail_url: Optional[str] = None
    open_url: Optional[str] = None


@dataclass
class ExternalViewData:
    """Base for external-data view payloads. Subclasses set
    ``template_name`` to the partial that renders them."""

    template_name: str = ''
    deep_link_url: Optional[str] = None

    @property
    def has_content(self) -> bool:
        """True when the rendered partial would produce visible
        content. The tabbed UI consults this to decide whether to
        show the integration's data tab at all."""
        return False


@dataclass
class StructuredViewData(ExternalViewData):
    """Common case: name/value rows plus a grid of attachments."""

    template_name: str = 'integrations/external_data/entity/structured.html'
    attributes: List[NameValuePair] = field(default_factory=list)
    attachments: List[AttachmentRef] = field(default_factory=list)

    @property
    def has_content(self) -> bool:
        return bool(self.attachments or self.attributes)


@dataclass
class CustomTemplateViewData(ExternalViewData):
    """Escape hatch for integrations needing a fully custom layout.
    The integration sets ``template_name`` to a path under its own
    ``services/<name>/templates/...`` and supplies whatever
    ``context`` it needs."""

    template_name: str = ''
    context: Dict = field(default_factory=dict)

    def __post_init__(self):
        if not self.template_name or not self.template_name.strip():
            raise ValueError(
                'CustomTemplateViewData requires a non-empty template_name.'
            )

    @property
    def has_content(self) -> bool:
        # Custom template implies the integration knows what it
        # wants; assume the partial produces something.
        return True


@dataclass
class MinimalViewData(ExternalViewData):
    """Placeholder when a full view payload is unavailable. Renders the
    deep link and the optional ``error_message``."""

    template_name: str = 'integrations/external_data/entity/minimal.html'
    error_message: Optional[str] = None

    @property
    def has_content(self) -> bool:
        # Renders the alert when error_message is set, and the
        # "External data unavailable" hint when deep_link_url is
        # absent. With only a deep_link, the partial body is empty
        # (the link is surfaced elsewhere).
        return bool(self.error_message) or not self.deep_link_url