wbcore 2.2.1__py2.py3-none-any.whl

wbcore/metadata/configs/display/instance_display/display.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass
+from typing import Iterable
+
+from wbcore.utils.importlib import parse_signal_received_for_module
+
+from .enums import NavigationType
+from .pages import Page, SerializedPage
+from .signals import add_display_pages
+
+type SerializedDisplay = dict[str, NavigationType | SerializedPage]
+
+
+@dataclass
+class Display:
+    """A display contains multiple pages and a navigation type. When only 1 page is specified, the navigation type is irrelevant"""
+
+    pages: Iterable[Page]
+    navigation_type: NavigationType = NavigationType.TAB
+
+    def serialize(self, view_config=None, view=None, request=None, key_prefix=None) -> SerializedDisplay:
+        """Serializes a `Display`
+
+        Returns:
+            A dictionary with all pages and the navigation type
+
+        """
+        serialized_pages = [
+            page.serialize(key_prefix=key_prefix, view_config=view_config, view=view, request=request)
+            for page in self.pages
+        ]
+        if view_config:
+            for prefix, remote_pages in parse_signal_received_for_module(
+                add_display_pages.send(view_config.__class__, request=request, view=view)
+            ):
+                for remote_page in remote_pages:
+                    serialized_pages.append(remote_page.serialize(prefix, view_config, view, request))
+        return {"navigationType": self.navigation_type.value, "pages": serialized_pages}

wbcore/metadata/configs/display/instance_display/enums.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class NavigationType(Enum):
+    TAB = "tab"
+    PAGE = "page"
+    PANEL = "panel"

wbcore/metadata/configs/display/instance_display/layouts/__init__.py

@@ -0,0 +1,3 @@
+from .inlines import Inline
+from .layouts import Layout
+from .sections import Section

wbcore/metadata/configs/display/instance_display/layouts/inlines.py

@@ -0,0 +1,58 @@
+import typing
+from dataclasses import dataclass
+
+from wbcore.metadata.utils import prefix_key
+
+if typing.TYPE_CHECKING:
+    from ..display import Display, SerializedDisplay
+
+
+type SerializedInline = dict[str, str | SerializedDisplay | list[str] | bool]
+
+
+@dataclass
+class Inline:
+    """An inline can be used to display a different endpoint in a form
+
+    When generating a form, only fields of the original endpoint can be displayed. An inline allows you to specify
+    remote content, for example a chart or a table, which the form asynchronously loads. This is very useful to
+    create dashboard like views and to seperate the load to multiple endpoints
+
+    Attributes:
+        key: A reference for the positioning on the grid
+        endpoint: A reference to the endpoint in the additional resources
+        display: An optional `Display` to override the `display` behind the `endpoint` in the additional resources
+
+    """
+
+    key: str
+    endpoint: str
+    title: str | None = None
+    display: typing.Optional["Display"] = None
+    aligned_keys: list[str] | None = None
+    hide_controls: bool = False
+
+    def serialize(self, key_prefix: str | None = None) -> SerializedInline:
+        """Serializes this `Inline`
+        Attributes:
+            key_prefix(Optional): if specified, append a prefix to the inline key
+        Returns:
+            A dictionairy containing all serialized fields
+
+        """
+        serialized_inline: SerializedInline = {
+            "key": self.key,
+            "endpoint": prefix_key(self.endpoint, key_prefix),
+            "hide_controls": self.hide_controls,
+        }
+
+        if self.title is not None:
+            serialized_inline["title"] = self.title
+
+        if self.display:
+            serialized_inline["display"] = self.display.serialize()
+
+        if self.aligned_keys:
+            serialized_inline["aligned_keys"] = self.aligned_keys
+
+        return serialized_inline

wbcore/metadata/configs/display/instance_display/layouts/layouts.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass, field
+
+from wbcore.metadata.configs.display.instance_display.styles import Style
+from wbcore.metadata.configs.display.instance_display.utils import grid_definition
+
+from .inlines import Inline, SerializedInline
+from .sections import Section, SerializedSection
+
+type SerializedLayout = dict[str, str | list[SerializedInline] | list[SerializedSection]]
+
+
+@dataclass
+class Layout:
+    """A layout contains all the information on how a form is build.
+
+    A form is rendered based on a grid, which is closely modelled after a CSS Grid. Essentially, we can define
+    rows and columns and places fields on this grid, either in one cell, or spanning multiple rows and columns.
+
+    In the future we will add all other features of css grid to ensure full control over the grid.
+
+    Attributes:
+        grid_template_areas: A 2D string Array containing the areas on the grid. The strings are the keys references to all fields
+        grid_template_columns: A string array containing the column definitions for the width of each column
+        grid_template_rows: A string array containing the row definitions for the height of each row
+        sections: A list of sections that can be positioned in `grid_template_areas`
+        inlines: A list of inlines that can be positioned in `grid_template_areas`
+        gap: A string specifying the gap between all rows and columns. Should be used with a helper method like `Style.px(10)`
+
+    """
+
+    grid_template_areas: list[list[str]]
+    grid_auto_columns: str | None = None
+    grid_template_columns: list[str] | None = None
+    grid_auto_rows: str = Style.MIN_CONTENT
+    grid_template_rows: list[str] | None = None
+
+    sections: list[Section] = field(default_factory=list)
+    inlines: list[Inline] = field(default_factory=list)
+
+    gap: str = Style.px(10)
+    row_gap: str | None = None
+    column_gap: str | None = None
+
+    def serialize(self, key_prefix: str | None = None) -> SerializedLayout:
+        """Serializes this `Layout`
+        Attributes:
+            key_prefix(Optional): if specified, append a prefix to underlying inlines key
+        Returns:
+            A dictionairy containing all serialized fields
+
+        """
+        serialized_layout = {
+            "gridTemplateAreas": " ".join([f"'{' '.join(row)}'" for row in self.grid_template_areas]),
+            "sections": [section.serialize(key_prefix=key_prefix) for section in self.sections],
+            "inlines": [inline.serialize(key_prefix=key_prefix) for inline in self.inlines],
+            "gap": self.gap,
+        }
+
+        if self.row_gap:
+            serialized_layout["rowGap"] = self.row_gap
+
+        if self.column_gap:
+            serialized_layout["columnGap"] = self.column_gap
+
+        if self.grid_auto_columns:
+            serialized_layout["gridAutoColumns"] = self.grid_auto_columns
+
+        if self.grid_template_columns:
+            serialized_layout["gridTemplateColumns"] = grid_definition(*self.grid_template_columns)
+
+        if self.grid_auto_rows:
+            serialized_layout["gridAutoRows"] = self.grid_auto_rows
+
+        if self.grid_template_rows:
+            serialized_layout["gridTemplateRows"] = grid_definition(*self.grid_template_rows)
+
+        return serialized_layout

wbcore/metadata/configs/display/instance_display/layouts/sections.py

@@ -0,0 +1,43 @@
+import typing
+from dataclasses import dataclass
+
+if typing.TYPE_CHECKING:
+    from ..display import Display, SerializedDisplay
+
+
+SerializedSection = dict[str, typing.Union[str, bool, "SerializedDisplay"]]
+
+
+@dataclass
+class Section:
+    """A section makes it possible to grid certain fields together into an area inside a form
+
+    Attributes:
+        key: A reference for the positioning on the grid
+        title: The title of the section, it will be displayed in on the top of a section
+        display: The `Display` which holds the grid of the fields in this section
+        collapsed: A flag to indicate whether this section is initially collapsed
+        collapsible: A flag to indicate whether this section is collapsible
+
+    """
+
+    key: str
+    title: str
+    display: "Display"
+    collapsed: bool = False
+    collapsible: bool = True
+
+    def serialize(self, key_prefix: str | None = None) -> SerializedSection:
+        """Serializes this `Section`
+
+        Returns:
+            A dictionairy containing all serialized fields
+
+        """
+        return {
+            "key": self.key,
+            "title": self.title,
+            "display": self.display.serialize(key_prefix=key_prefix),
+            "collapsed": self.collapsed,
+            "collapsible": self.collapsible,
+        }

wbcore/metadata/configs/display/instance_display/operators.py

@@ -0,0 +1,22 @@
+def lt(value: int) -> str:
+    return _stringify("<", value)
+
+
+def lte(value: int) -> str:
+    return _stringify("<=", value)
+
+
+def gt(value: int) -> str:
+    return _stringify(">", value)
+
+
+def gte(value: int) -> str:
+    return _stringify(">=", value)
+
+
+def default() -> str:
+    return "default"
+
+
+def _stringify(operator: str, value: int) -> str:
+    return f"{operator}{value}"

wbcore/metadata/configs/display/instance_display/pages.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .layouts.layouts import Layout, SerializedLayout
+
+if TYPE_CHECKING:
+    from .display import Display, SerializedDisplay
+
+
+type SerializedPage = dict[str, None | str | dict[str, SerializedLayout] | SerializedDisplay]
+
+
+@dataclass
+class Page:
+    """Represents a page, which may include an optional title and a dictionary defining layout boundaries along with a Layout. Alternatively, a list of subpages can also be specified."""
+
+    title: str | None = None
+    layouts: dict[str, Layout] | None = None
+    display: "Display | None" = None
+
+    def serialize(self, key_prefix: str | None = None, view_config=None, view=None, request=None) -> SerializedPage:
+        """Serializes the `Page` into a dictionairy
+
+        Returns:
+            A dictionairy containing all fields of a `Page`
+
+        """
+        page: SerializedPage = {
+            "title": self.title,
+        }
+
+        if self.layouts is not None:
+            page["layouts"] = {key: layout.serialize(key_prefix=key_prefix) for key, layout in self.layouts.items()}
+
+        elif self.display is not None:
+            page["display"] = self.display.serialize(
+                view_config=view_config, view=view, request=request, key_prefix=key_prefix
+            )
+
+        return page

wbcore/metadata/configs/display/instance_display/shortcuts.py

@@ -0,0 +1,70 @@
+from .display import Display
+from .layouts import Inline, Layout, Section
+from .operators import default
+from .pages import Page
+from .styles import Style
+
+
+def create_simple_display(
+    grid_template_areas: list[list[str]],
+    sections: list[Section] | None = None,
+    inlines: list[Inline] | None = None,
+) -> Display:
+    """Creates a simple display without having to specify all the intermediary classes
+
+    Args:
+        grid_template_areas: 2D string array containing all fields that should be displayed
+        sections: A list of sections included in the `grid_template_areas`
+        inlines: A list of inlines if necessary.
+
+    Returns:
+        A `Display` containing 1 `Page` with all fields in 1 `Section` with all columns and rows having the same dimensions
+
+    """
+    return Display(
+        pages=[
+            Page(
+                layouts={
+                    default(): Layout(
+                        grid_template_areas=grid_template_areas,
+                        grid_auto_columns=Style.fr(1),
+                        inlines=inlines if inlines else [],
+                        sections=sections if sections else [],
+                    )
+                }
+            )
+        ]
+    )
+
+
+def create_simple_section(
+    key: str,
+    title: str,
+    grid_template_areas: list[list[str]] | None = None,
+    inline_key: str | None = None,
+    extra_display_kwargs: dict | None = None,
+    **kwargs
+) -> Section:
+    """Creates a simple section without having to specify everything
+
+    Args:
+        key: A string that will be later referenced in the display's `grid_template_areas`
+        title: A string which is used as a header
+        grid_template_areas: 2D string array containing all fields that should be displayed
+        inline_key: if the section is a nested table, the inline is the corresponding endpoint
+        extra_display_kwargs: an additional dictionary for create_simple_display parameters.
+
+    Returns:
+        A `Section` containing a simple `Display`
+
+    """
+    return Section(
+        key=key,
+        title=title,
+        display=create_simple_display(
+            grid_template_areas=grid_template_areas if grid_template_areas else [],
+            inlines=[Inline(key=inline_key, endpoint=inline_key)] if inline_key else [],
+            **extra_display_kwargs if extra_display_kwargs else {},
+        ),
+        **kwargs,
+    )

wbcore/metadata/configs/display/instance_display/signals.py

@@ -0,0 +1,3 @@
+from django.dispatch import Signal
+
+add_display_pages = Signal()  # many

wbcore/metadata/configs/display/instance_display/styles.py

@@ -0,0 +1,42 @@
+class Style:
+    """A convinience class to have all styles and helper methods contained in one place.
+
+    Static CSS Variables may be used as classmembers, e.g.: `Style.MIN_CONTENT` or `Style.AUTO`
+    Dynamic CSS Variables, such as specific sizes, may be used as static methods, e.g.: `Style.fr(5)`
+    """
+
+    MIN_CONTENT = "min-content"
+    MAX_CONTENT = "max-content"
+    AUTO = "auto"
+
+    @staticmethod
+    def fr(fractions: int) -> str:
+        return Style._stringify(fractions, "fr")
+
+    @staticmethod
+    def px(pixels: int) -> str:
+        return Style._stringify(pixels, "px")
+
+    @staticmethod
+    def pct(percent: float) -> str:
+        return Style._stringify(percent, "%")
+
+    @staticmethod
+    def rem(rem: float) -> str:
+        return Style._stringify(rem, "rem")
+
+    @staticmethod
+    def vh(vh: int) -> str:
+        return Style._stringify(vh, "vh")
+
+    @staticmethod
+    def vw(vw: int) -> str:
+        return Style._stringify(vw, "vw")
+
+    @staticmethod
+    def _stringify(value: int | float, unit: str) -> str:
+        return f"{value}{unit}"
+
+    @staticmethod
+    def minmax(min_value: str, max_value: str) -> str:
+        return f"minmax({min_value}, {max_value})"

wbcore/metadata/configs/display/instance_display/utils.py

@@ -0,0 +1,74 @@
+from django.utils.translation import gettext
+
+
+def repeat(n: int, unit: str) -> str:
+    """Creates a CSS repeat element, that makes the `unit` be repeated `n` times.
+
+    Example:
+        `repeat(5, Style.px(20))` results in the string `'repeat(5, 20px)'`
+
+    Attributes:
+        n (int): The amount of times the unit should be repeated
+        unit (str): The unit that is going to be repeated. Should be generated by the unit helper methods, e.g. `Style.px(20)`
+
+    Returns:
+        A valid css string containing the information about repeated an element `n` times.
+    """
+
+    return f"repeat({n}, {unit})"
+
+
+def repeat_field(n: int, field_name: str) -> str:
+    """Creates a string repeating the `field_name` `n` times
+
+    Example:
+        `repeat_field(5, Style.px(20))` results in the string `'20px 20px 20px 20px 20px'`
+
+    Args:
+        n: An integer specifying how often the the `field_name` should be repeated
+        field_name: A string, which should be repeated `n` times
+
+    Returns:
+        A string where the value of `field_name` is duplicated `n` times
+    """
+    return " ".join([field_name] * n)
+
+
+def grid_definition(*units: str) -> str:
+    """Concatanates the arguments specified as positional arguments with a space to create a valid css string to define a grid
+
+    Arguments:
+        *units: Positional string arguments that will be concatanated
+
+    Returns:
+        A valid css string of space seperated strings
+
+    """
+    return " ".join(units)
+
+
+def split_list_into_grid_template_area_sublists(elem_list: list, column_number: int) -> list[list]:
+    """Splits a list of elements into sublists of the provided column number length and adds empty grid cells at the end if necessary
+
+    Args:
+        elem_list (list): List of elements to split
+        column_number (int): Number of columns in the grid. Must be above 0
+
+    Returns:
+        list: A list of lists of exactly the specified length
+
+    Raises:
+        ValueError: If column_number below 1 is provided
+    """
+
+    if column_number < 1:
+        raise ValueError(gettext("Column number has to be at least 1!"))
+
+    sublists = [elem_list]
+    if column_number <= len(elem_list):
+        # If we don't have enough elements in the list to split into the target column number we avoid the IndexError and instead populate the sublist with empty fields
+        sublists = [elem_list[x : x + column_number] for x in range(0, len(elem_list), column_number)]
+
+    for _ in range(column_number - len(sublists[-1])):
+        sublists[-1].append(".")
+    return sublists