Merge pull request #448 from chirizxc/feature/link_preview

add docs, example for LinkPreview widget

docs/conf.py

@@ -13,13 +13,10 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath("."))
-
-import datetime
-
 # -- Project information -----------------------------------------------------
 
 project = "aiogram-dialog"
-copyright = f"{datetime.date.today().year}, Tishka17"
+copyright = "%Y, Tishka17"
 author = "Tishka17"
 master_doc = "index"
 

docs/widgets/index.rst

@@ -4,13 +4,14 @@ Widgets and Rendering
 Base information
 ********************
 
-Currently there are 4 kinds of widgets: :ref:`texts <text_widgets>`, :ref:`keyboards <keyboard_widgets>`,
-:ref:`input <input_widgets>`, :ref:`media<media_widgets>` and you can create your own :ref:`widgets<custom_widgets>`.
+Currently there are 5 kinds of widgets: :ref:`texts <text_widgets>`, :ref:`keyboards <keyboard_widgets>`,
+:ref:`input <input_widgets>`, :ref:`media<media_widgets>`, :ref:`link preview<link_preview>` and you can create your own :ref:`widgets<custom_widgets>`.
 
 * **Texts** used to render text anywhere in dialog. It can be message text, button title and so on.
 * **Keyboards** represent parts of ``InlineKeyboard``
 * **Media** represent media attachment to message
 * **Input** allows to process incoming messages from user. Is has no representation.
+* **Link Preview** used to manage link previews in messages.
 
 Widgets can display static (e.g. ``Const``) and dynamic (e.g. ``Format``) content. To use dynamic data you have to set it. See :ref:`passing data <passing_data>`.
 
@@ -37,5 +38,6 @@ Also there are 2 general types:
     keyboard/index
     input/index
     media/index
+    link_preview/index
     hiding/index
-    custom_widgets/index
+    custom_widgets/index

docs/widgets/link_preview/example.py

@@ -0,0 +1,27 @@
+from aiogram.filters.state import State, StatesGroup
+
+from aiogram_dialog import Window
+from aiogram_dialog.widgets.link_preview import LinkPreview
+from aiogram_dialog.widgets.text import Const
+
+
+class SG(StatesGroup):
+    MAIN = State()
+    SECOND = State()
+
+
+window = Window(
+    Const("https://nplus1.ru/news/2024/05/23/voyager-1-science-data"),
+    LinkPreview(is_disabled=True),
+    state=SG.MAIN,
+)
+
+second_window = Window(
+    Const("some text"),
+    LinkPreview(
+        url=Const("https://nplus1.ru/news/2024/05/23/voyager-1-science-data"),
+        prefer_small_media=True,
+        show_above_text=True,
+    ),
+    state=SG.MAIN,
+)

docs/widgets/link_preview/index.rst

@@ -0,0 +1,23 @@
+.. _link_preview:
+
+LinkPreview
+*************
+
+The **LinkPreview** widget is used to manage link previews in messages.
+
+Parameters:
+
+* ``url``: A ``TextWidget`` with URL to be used in the link preview. If not provided, the first URL found in the message will be used.
+* ``is_disabled``: that controls whether the link preview is displayed. If ``True``, the preview will be disabled.
+* ``prefer_small_media``: that controls if the media in the link preview should be displayed in a smaller size. Ignored if media size change is not supported.
+* ``prefer_large_media``: that controls if the media in the link preview should be enlarged. Ignored if media size change is not supported.
+* ``show_above_text``: that specifies whether the link preview should be displayed above the message text. If ``True``, link preview be displayed above the message text.
+
+
+Code example:
+
+.. literalinclude:: ./example.py
+
+.. autoclass:: aiogram_dialog.widgets.link_preview.LinkPreview
+   :special-members: __init__
+   :members: render_link_preview, _render_link_preview

example/link_preview.py

@@ -0,0 +1,95 @@
+from aiogram import Bot, Dispatcher
+from aiogram.filters import Command
+from aiogram.filters.state import State, StatesGroup
+from aiogram.fsm.storage.memory import MemoryStorage
+from aiogram.types import Message
+
+from aiogram_dialog import (
+    Dialog,
+    DialogManager,
+    StartMode,
+    Window,
+    setup_dialogs,
+)
+from aiogram_dialog.widgets.kbd import SwitchTo
+from aiogram_dialog.widgets.link_preview import LinkPreview
+from aiogram_dialog.widgets.text import Const, Format
+
+
+async def photo_getter(**_):
+    return {"photo_url": "https://nplus1.ru/news/2024/05/23/voyager-1-science-data"}
+
+
+class SG(StatesGroup):
+    MAIN = State()
+    IS_DISABLED = State()
+    SMALL_MEDIA = State()
+    LARGE_MEDIA = State()
+    SHOW_ABOVE_TEXT = State()
+
+
+BACK = SwitchTo(Const("back"), "_back", SG.MAIN)
+
+
+dialog = Dialog(
+    Window(
+        Format("Default\n{photo_url}"),
+        SwitchTo(
+            Const("disable"), "_disable", SG.IS_DISABLED,
+        ),
+        SwitchTo(
+            Const("prefer small media"), "_prefer_small_media", SG.SMALL_MEDIA,
+        ),
+        SwitchTo(
+            Const("prefer large media"), "_prefer_large_media", SG.LARGE_MEDIA,
+        ),
+        SwitchTo(
+            Const("show above text"), "_show_above_text", SG.SHOW_ABOVE_TEXT,
+        ),
+        getter=photo_getter,
+        state=SG.MAIN,
+    ),
+    Window(
+        Format("{photo_url}"),
+        LinkPreview(is_disabled=True),
+        BACK,
+        state=SG.IS_DISABLED,
+        getter=photo_getter,
+    ),
+    Window(
+        Const("prefer small media"),
+        LinkPreview(Format("{photo_url}"), prefer_small_media=True),
+        BACK,
+        state=SG.SMALL_MEDIA,
+        getter=photo_getter,
+    ),
+    Window(
+        Const("prefer large media"),
+        LinkPreview(Format("{photo_url}"), prefer_large_media=True),
+        BACK,
+        state=SG.LARGE_MEDIA,
+        getter=photo_getter,
+    ),
+    Window(
+        Const("show above text"),
+        LinkPreview(Format("{photo_url}"), show_above_text=True),
+        BACK,
+        state=SG.SHOW_ABOVE_TEXT,
+        getter=photo_getter,
+    ),
+)
+
+storage = MemoryStorage()
+bot = Bot("token")
+dp = Dispatcher(storage=storage)
+dp.include_router(dialog)
+setup_dialogs(dp)
+
+
+@dp.message(Command("start"))
+async def start(message: Message, dialog_manager: DialogManager):
+    await dialog_manager.start(SG.MAIN, mode=StartMode.RESET_STACK)
+
+
+if __name__ == "__main__":
+    dp.run_polling(bot, skip_updates=True)

src/aiogram_dialog/widgets/link_preview/base.py

@@ -27,7 +27,7 @@ async def _render_link_preview(
 class LinkPreview(LinkPreviewBase):
     def __init__(
             self,
-            url: TextWidget,
+            url: Optional[TextWidget] = None,
             is_disabled: bool = False,
             prefer_small_media: bool = False,
             prefer_large_media: bool = False,
@@ -51,9 +51,8 @@ async def render_link_preview(
     async def _render_link_preview(
             self, data: dict, manager: DialogManager,
     ) -> Optional[LinkPreviewOptions]:
-        url = await self.url.render_text(data, manager)
         return LinkPreviewOptions(
-            url=url,
+            url=await self.url.render_text(data, manager) if self.url else None,
             is_disabled=self.is_disabled,
             prefer_small_media=self.prefer_small_media,
             prefer_large_media=self.prefer_large_media,