Improve API for embedding elements into tables

[marcuslimdw]

Currently, in ui.table's documentation, to insert anything that isn't text in a table, you need to use slots and custom HTML.

This provides a suboptimal developer experience because there is a need to know not just HTML, but also Vue-specific syntax.

I propose that the API of ui.table be modified to allow specifying objects that will abstract away this process of creating and populating slots.

Summary of changes

1. Define a new abstract class TableFieldType with a reify method that returns a string representing the content to be inserted into a Quasar slot.
2. Replace the raw Dict type used in the columns setter (and parameter in ui.table) with an explicitly defined TypedDict.
3. In this TypedDict, add a new field_type key of type Optional[TableFieldType]. For backwards compatibility, this key will be marked as not required (using typing.NotRequired).
4. Modify the implementation of Table._normalize_columns to add slots as necessary (see below).
5. Add TableFieldType implementations as needed to cover common use cases.
6. Modify ui.table documentation to use TableFieldType.

API comparison

Old:

@columns.setter
def columns(self, value: List[Dict]) -> None:

New:

@columns.setter
def columns(self, value: List[ColumnDefinition]) -> None:

Type definitions and example

from __future__ import annotations

from abc import abstractmethod, ABCMeta
from dataclasses import dataclass
from typing import TypedDict


class ColumnDefinition(TypedDict):
    name: str
    label: str
    field: str
    field_type: TableFieldType


class TableFieldType(metaclass=ABCMeta):
    @abstractmethod
    def reify(self) -> str:
        pass


@dataclass
class Link(TableFieldType):
    text_field: str
    url_field: str

    def reify(self) -> str:
        # add error checking here
        return f'''
    <q-td :props="props">
        <a :href="props.value.{self.text_field}">{{{{ props.value.{self.url_field} }}}}</a>
    </q-td>
    '''

Example new _normalize_columns implementation

    def _normalize_columns(self, columns: List[Dict]) -> List[Dict]:
        columns_with_defaults = [{**self._column_defaults, **column} for column in columns] if self._column_defaults else columns
        for column in columns_with_defaults:
            field_type = column.get("field_type")
            if field_type is None:
                continue

            self.add_slot(f'body-cell-{column["label"]}', field_type.reify())
            
        return columns_with_defaults

Notes

1. Based on my understanding of the slot mechanism, this will override the existing slot, if any, applied to that column. This seems intuitive to me from a user's perspective...?

Open design questions

1. How might the user specify event handlers on the elements created in this way?
2. How might the user cause events to be triggered from the elements created in this way?
3. What if the user wants to apply a different element for each row, based on some predicate applied to the row/cell?

[falkoschindler]

Thanks for the proposal, @marcuslimdw!

If I understand correctly, this basically moves the template definition into a new TableFieldType class. But the users would still need to write the template somewhere. Only if they pick from a set of simple pre-defined field types, they don't have to touch HTML.

We still have hope for PR #3261, which would solve the problem more generically. But it might not be possible after all.

[marcuslimdw]

yup, that kind of looks like what I'm thinking of, but better!

I agree that users would still have to write HTML to do anything they want. however, AIUI, the dev team's model of NiceGUI is basically "Python for most of the common things, with a raw HTML/JS escape hatch".

IMO, adding specific elements (inputs, dropdowns, links, and badges) is a pretty common usecase for tables, which is why I think the framework should make doing so easier.

[falkoschindler]

This feature has just been released via PR #5592 in NiceGUI 3.5.0.