Merge pull request #402 from chirizxc/develop

Update docs: ListGroup

docs/widgets/keyboard/list_group/example.py

@@ -0,0 +1,60 @@
+from aiogram import F
+from aiogram.filters.state import State, StatesGroup
+from aiogram_dialog import (
+    Window,
+    Dialog,
+)
+from aiogram_dialog.widgets.kbd import (
+    Url,
+    ListGroup,
+    SwitchTo,
+    Back,
+)
+from aiogram_dialog.widgets.text import Const, Format
+
+
+class SG(StatesGroup):
+    main = State()
+    result = State()
+
+
+success = F["products"]
+fail = ~success
+
+
+async def actions(**kwargs):
+    products = [
+        {"id": 1, "name": "Ferrari", "category": "car",
+         "url": "https://www.ferrari.com/"},
+        {"id": 2, "name": "Detroit", "category": "game",
+         "url": "https://wikipedia.org/wiki/Detroit:_Become_Human"},
+    ]
+    return {
+        "products": products,
+    }
+
+
+dialog = Dialog(
+    Window(
+        Const("Click find products to show a list of available products:"),
+        SwitchTo(Const("Find products"), id="search", state=SG.result),
+        state=SG.main,
+    ),
+    Window(
+        Const("Searching results:", when=success),
+        Const("Search did not return any results", when=fail),
+        ListGroup(
+            Url(
+                Format("{item[name]} ({item[category]})"),
+                Format("{item[url]}"),
+                id="url",
+            ),
+            id="select_search",
+            item_id_getter=lambda item: item["id"],
+            items="products",
+        ),
+        Back(Const("Back")),
+        state=SG.result,
+        getter=actions,
+    )
+)

docs/widgets/keyboard/list_group/index.rst

@@ -3,10 +3,27 @@
 ListGroup
 *************
 
-``ListGroup`` is more complex way to render widgets for list of items. While ``Select`` generates simple buttons, with ``ListGroup`` you can create any set of keyboard widgets and repeat them.
+**ListGroup** is more complex way to render widgets for list of items. While ``Select`` generates simple buttons, with ``ListGroup`` you can create any set of keyboard widgets and repeat them.
 
 To identity ``item`` inside keyboard event you can check ``dialog_manager.item_id``. This is possible because ``SubManager`` is passed instead of ``DialogManager`` while corresponding widget is located inside ``ListGroup``.
 
+To find widget for specific ``item_id`` in a ``ListGroup``, you can use the ``.find_for_item`` method from ``ManagedListGroup``.
+
+
+Manager methods:
+
+* **.find**: if manager already adapted for current ``ListGroup`` row, finds the widget within the current manager (``SubManager``).
+
+* **.find_in_parent**: if you need to find widgets outside the row, finds the widget within the parent manager (``DialogManager``).
+
+.. note::
+
+    If you nest a ``ListGroup`` in ``ListGroup`` your parent manager will be ``SubManager``
+
+Code example:
+
+.. literalinclude:: ./example.py
+   :language: python
 
 .. autoclass:: aiogram_dialog.widgets.kbd.ListGroup
    :special-members: __init__,