Howto build compound widgets? Best Practice Question

[UlrichGoebel]

It's another beginner question...

I build a UI for a number of database tables. Each table should be edited in a form in a TabPane inside a TabbedContent. To navigate in the tables searching the row the user is looking for and to save or delete them (an some more) I would like to offer the user a "navi-and-filter/choose-area" on the left, the form should be shown on the right.

Therefore I would like to build a Navi-Widget which will be instantiated and yielded in each of my TabPanes as the "navi-areas". As I understand, it would not be a real Widget in meaning that it has a few Widgets inside, but it is more a Layout.

But how to build this Navi?

What I tried until now: (have a look in the code below)

1. A simple function (in the code it is navi_factory and used in Tab 1).
   The function takes a parameter base_name (a string) which makes it possible to give all the widgets a useful id for later manipulation.
   In a Vertical there comes a single line with a few Labels, Inputs and Buttons. Some of them (the Buttons) are buildet and assigned to the variable Btn to add a tooltip, then they are yielded.
   Under this first line there comes a VerticalScroll with a number of lines showing Buttons, one for each row in the database table, if necessary filtered by some value entered in the fist line Input. Pressing these Buttons later on should show the accordingly row from the database in the form on the right hand side of the TabPane.
   This funcion is used like this:

for Wdg in navi_factory('nav-1'):
    yield Wdg

2. A function which returns an iterator (in the code it is navi_generator and used in Tab 2).
   This funcion returns an iterator which does exactly what navi_factory did in 1. The base_name is passed to navi_generator and is used in the navi_factory. The only thing I can imagine why to prefere this way could be to safely keep separated the iterators when using more then one of them. (I have no idea whether this could be necessary.)
   So it is used like this:

NaviFact = navi_generator('nav-2')
for Wdg in NaviFact():
    yield Wdg

3. A class to instantiate (in the code it is NaviFactory and used in Tab 3).
   The base_name is passed to the instance.
   The work is done by the method NaviFactory.navi_factory. Again, it does exactly what navi_factory did in 1.
   So it is used like this:

navifact = NaviFactory('nav-3')
for Wdg in navifact.navi_factory():
    yield Wdg

What I would like to build:

4. A class which could used as a widget (in the code it is commented out, but should be Navi and could be used in Tab-4).
   As I understand I had to build a subclass of Widget (or Container?). But how? May be it is more a python question then a textual question. But e.g. how to handle the base_name when initiating Navi?
   Finally I would like to use it like this:

yield Navi('nav-3')

The code I wrote until now:

Of course the CSS is more then minimal and can be ignored.

#!/usr/bin/env python3

from textual.app import App
from textual.containers import Horizontal, Vertical, VerticalScroll
from textual.widgets import Button, Input, Label, Placeholder, Static, TabbedContent, TabPane

def navi_factory(base_name):
    with Vertical():
        with Horizontal():
            yield Label('Filter')
            yield Input(id=f'filter-{base_name}')
            Btn = Button('Save', id=f'save-{base_name}')
            Btn.tooltip = f'Save Form {base_name}'
            yield Btn
            Btn = Button('Delete', id=f'delete-{base_name}')
            Btn.tooltip = f'Delete Data {base_name}'
            yield Btn
        with VerticalScroll():
            for id in range(25):
                Btn =  Button(
                          f'{id:2} Filtered from Database',
                          id=f'show-{id}-{base_name}')
                Btn.tooltip = f'Show Data with ID={id} in Form {base_name}'
                yield Btn

def navi_generator(base_name):

    def navi_factory():
        with Vertical():
            with Horizontal():
                yield Label('Filter')
                yield Input(id=f'filter-{base_name}')
                Btn = Button('Save', id=f'save-{base_name}')
                Btn.tooltip = f'Save Form {base_name}'
                yield Btn
                Btn = Button('Delete', id=f'delete-{base_name}')
                Btn.tooltip = f'Delete Data {base_name}'
                yield Btn
            with VerticalScroll():
                for id in range(25):
                    Btn = Button(
                              f'{id:2} Filtered from Database',
                              id=f'show-{id}-{base_name}')
                    Btn.tooltip = f'Show Data with ID={id} in Form {base_name}'
                    yield Btn
    
    return navi_factory

class NaviFactory():
    
    def __init__(self, base_name):
        self.base_name = base_name
    
    def navi_factory(self):
        with Vertical():
            with Horizontal():
                yield Label('Filter')
                yield Input(id=f'filter-{self.base_name}')
                Btn = Button('Save', id=f'save-{self.base_name}')
                Btn.tooltip = f'Save Form {self.base_name}'
                yield Btn
                Btn = Button('Delete', id=f'delete-{self.base_name}')
                Btn.tooltip = f'Delete Data {self.base_name}'
                yield Btn
            with VerticalScroll():
                for id in range(25):
                    Btn = Button(
                              f'{id:2} Filtered from Database',
                              id=f'show-{id}-{self.base_name}')
                    Btn.tooltip = f'Show Data with ID={id} in Form {self.base_name}'
                    yield Btn

class Full(App):
    
    CSS = """
            Placeholder {
                width: 50%;
                }
            
            Input {
                width: 10;
            }
            
            VerticalScroll {
                height: 80%;
                }
        """
  
    def compose(self):
        with TabbedContent():
            with TabPane('Tab 1'):
                with Horizontal():
                    for Wdg in navi_factory('nav-1'):
                        yield Wdg
                    yield Placeholder('Form Tab 1')
            with TabPane('Tab 2'):
                with Horizontal():
                    NaviFact = navi_generator('nav-2')
                    for Wdg in NaviFact():
                        yield Wdg
                    yield Placeholder('Form Tab 2')
            with TabPane('Tab 3'):
                with Horizontal():
                    navifact = NaviFactory('nav-3')
                    for Wdg in navifact.navi_factory():
                        yield Wdg
                    yield Placeholder('Form Tab 3')
        #   with TabPane('Tab 4'):
        #       with Horizontal():
        #           yield Navi('nav-3')
        #           yield Placeholder('Form Tab 3')

if __name__ == '__main__':
    app = Full()
    app.run()

I would be glad to get some hints.

[TomJGooding]

What I would like to build:
A class which could used as a widget (in the code it is commented out, but should be Navi and could be used in Tab-4).
As I understand I had to build a subclass of Widget (or Container?). But how? May be it is more a python question then a textual > question. But e.g. how to handle the base_name when initiating Navi?

Could you explain a bit more what part you are struggling with? There's an example of a compound widget in the docs which might be helpful (though I do think perhaps this needs expanding)

[UlrichGoebel]

I'm not far from saying sorry for asking. The example mentioned solves my problem. Thank you for the hint.

[TomJGooding]

Glad this helped and no need to apologise! I think the docs for compound widgets should be more discoverable as mentioned in the issue I linked above.

[UlrichGoebel]

Well, in this case it was TomjGoodings hint to the docu, which solves the problem.

For the sake of completeness, have a look to the solution below.

One question remains: why isn't it necessary to pass any parameter in the new build Widget's __init__ to the

super().__init__()

Isn't it possible to pass the new build Navi an id?

For the sake of completeness, have a look to the solution below:

class Navi(Widget):
    
    DEFAULT_CSS = """
        Navi {
            width: 30%;
            }
        """
  
    def __init__(self, base_name):
        self.base_name = base_name
        super().__init__()
    
    def compose(self):
        # the rest does what the navi_factory did; nothing news from here down
        with Vertical():
            with Horizontal():
                yield Label('Filter')
                yield Input(id=f'filter-{self.base_name}')
                Btn = Button('Save', id=f'save-{self.base_name}')
                Btn.tooltip = f'Save Form {self.base_name}'
                yield Btn
                Btn = Button('Delete', id=f'delete-{self.base_name}')
                Btn.tooltip = f'Delete Data {self.base_name}'
                yield Btn
            with VerticalScroll():
                for id in range(25):
                    Btn = Button(
                              f'{id:2} Filtered from Database',
                              id=f'show-{id}-{self.base_name}')
                    Btn.tooltip = f'Show Data with ID={id} in Form {self.base_name}'
                    yield Btn

[TomJGooding]

One question remains: why isn't it necessary to pass any parameter in the new build Widget's __init__ to the super().__init__()

Isn't it possible to pass the new build Navi an id?

I think this is another example where the docs could be improved. Here's an adapted example from the docs:

class InputWithLabel(Widget):
    def __init__(
        self,
        input_label: str,
        *,
        name: str | None = None,
        id: str | None = None,
        classes: str | None = None,
        disabled: bool = False
    ) -> None:
        self.input_label = input_label
        super().__init__(name=name, id=id, classes=classes, disabled=disabled)

[UlrichGoebel]

O.k., that makes it clear. By the way: Can I possibly help improving the docs?

[TomJGooding]

That's not really up to me, but contributions are normally welcome! (I'm not a maintainer of Textual just an annoying hanger-on eager contributor!)

If you're planning on any major doc updates, it might just be worth getting feedback from maintainers before starting work. Here's the related issue I mentioned before:

• Clarify docs about creating custom widgets #4018

[TomJGooding]

I should add: of course you don't actually have to write the documentation to help improve it! Your perspective as a "beginner" (your words not mine!) is valuable to understand what might be missing or confusing.