# Aiogram Dialog
[](https://badge.fury.io/py/aiogram-dialog)
[](https://aiogram-dialog.readthedocs.io)
[](https://pypistats.org/packages/aiogram_dialog)
[](https://github.com/Tishka17/aiogram_dialog/blob/master/LICENSE)
#### Version status:
* v1.x - stable release, supports aiogram v2.x, bugfix only
* v2.x - beta, future release, supports aiogram v3.x
### About
`aiogram-dialog` is a framework for developing interactive messages and menus in your telegram bot like a normal GUI application.
It is inspired by ideas of Android SDK and other tools.
Main ideas are:
* **split data retriving, rendering and action processing** - you need nothing to do for showing same content after some actions, also you can show same data in multiple ways.
* **reusable widgets** - you can create calendar or multiselect at any point of your application without copy-pasting its internal logic
* **limited scope of context** - any dialog keeps some data until closed, multiple opened dialogs process their data separately
Designing you bot with `aiogram-dialog` you **think about user**, what he sees and what he does. Then you split this vision into reusable parts and design your bot combining dialogs, widows and widgets. By this moment you can review interface and add your core logic.
Many components are ready for use, but you can extend and add your own widgets and even core features.
For more details see [documentation](https://aiogram-dialog.readthedocs.io) and [examples](example)
### Supported features:
* Rich text rendering using `format` function or `Jinja2` template engine.
* Automatic message updating after user actions
* Multiple independent dialog stacks with own data storage and transitions
* Inline keyboard widgets like `SwitchTo`, `Start`, `Cancel` for state switching, `Calendar` for date selection and others.
* Stateful widgets: `Checkbox`, `Multiselect`, `Counter`, `TextInput`. They record user actions and allow you to retrieve this data later.
* Multiple buttons layouts including simple grouping (`Group`, `Column`), page scrolling (`ScrollingGroup`), repeating of same buttons for list of data (`ListGroup`).
* Sending media (like photo or video) with fileid caching and handling switching to/from message with no media.
* Different rules of transitions between windows/dialogs like keeping only one dialog on top of stack or force sending enw message instead of updating one.
* Offline HTML-preview for messages and transitions diagram. They can be used to check all states without emulating real use cases or exported for demonstration purposes.
### Usage
Example below is suitable for aiogram_dialog v2.x and aiogram v3.x
#### Declaring Window
Each window consists of:
* Text widgets. Render text of message.
* Keyboard widgets. Render inline keyboard
* Media widget. Renders media if neede
* Message handler. Called when user sends a message when window is shown
* Data getter functions (`getter=`). They load data from any source which can be used in text/keyboard
* State. Used when switching between windows
**Info:** always create `State` inside `StatesGroup`
```python
from aiogram.filters.state import StatesGroup, State
from aiogram_dialog.widgets.text import Format, Const
from aiogram_dialog.widgets.kbd import Button
from aiogram_dialog import Window
class MySG(StatesGroup):
main = State()
async def get_data(**kwargs):
return {"name": "world"}
Window(
Format("Hello, {name}!"),
Button(Const("Empty button"), id="nothing"),
state=MySG.main,
getter=get_data,
)
```
### Declaring dialog
Window itself can do nothing, just prepares message. To use it you need dialog:
```python
from aiogram.filters.state import StatesGroup, State
from aiogram_dialog import Dialog, Window
class MySG(StatesGroup):
first = State()
second = State()
dialog = Dialog(
Window(..., state=MySG.first),
Window(..., state=MySG.second),
)
```
> **Info:** All windows in a dialog MUST have states from then same `StatesGroup`
After creating dialog you need to register it using `DialogRegistry`:
```python
from aiogram import Dispatcher
from aiogram_dialog import DialogRegistry
...
dp = Dispatcher(storage=storage) # create as usual
registry = DialogRegistry(dp) # create registry
registry.register(name_dialog) # create
```
Then start dialog when you are ready to use it. Dialog is started via `start` method of `DialogManager` instance. You
should provide corresponding state to switch into (usually it is state of first window in dialog).
For example in `/start` command handler:
```python
async def user_start(message: Message, dialog_manager: DialogManager):
await dialog_manager.start(MySG.first, mode=StartMode.RESET_STACK)
dp.message.register(user_start, F.text == "/start")
```
> **Info:** Always set `mode=StartMode.RESET_STACK` in your top level start command. Otherwise, dialogs are stacked just as they do
on your mobile phone, so you can reach stackoverflow error
Raw data
{
"_id": null,
"home_page": "https://github.com/tishka17/aiogram_dialog",
"name": "aiogram-dialog-data-ttl-patched",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "A. Tikhonov",
"author_email": "17@itishka.org",
"download_url": "https://files.pythonhosted.org/packages/fd/6c/1fd975e686de1e8e58f43b127ed03f3a110f7fbdaac0cff56b4e77acebd3/aiogram_dialog_data_ttl_patched-2.0.0b15.tar.gz",
"platform": null,
"description": "# Aiogram Dialog\r\n\r\n[](https://badge.fury.io/py/aiogram-dialog)\r\n[](https://aiogram-dialog.readthedocs.io)\r\n[](https://pypistats.org/packages/aiogram_dialog)\r\n[](https://github.com/Tishka17/aiogram_dialog/blob/master/LICENSE)\r\n\r\n#### Version status:\r\n* v1.x - stable release, supports aiogram v2.x, bugfix only\r\n* v2.x - beta, future release, supports aiogram v3.x\r\n\r\n### About \r\n`aiogram-dialog` is a framework for developing interactive messages and menus in your telegram bot like a normal GUI application. \r\n \r\nIt is inspired by ideas of Android SDK and other tools.\r\n\r\nMain ideas are:\r\n* **split data retriving, rendering and action processing** - you need nothing to do for showing same content after some actions, also you can show same data in multiple ways. \r\n* **reusable widgets** - you can create calendar or multiselect at any point of your application without copy-pasting its internal logic \r\n* **limited scope of context** - any dialog keeps some data until closed, multiple opened dialogs process their data separately\r\n\r\nDesigning you bot with `aiogram-dialog` you **think about user**, what he sees and what he does. Then you split this vision into reusable parts and design your bot combining dialogs, widows and widgets. By this moment you can review interface and add your core logic. \r\n\r\nMany components are ready for use, but you can extend and add your own widgets and even core features. \r\n\r\nFor more details see [documentation](https://aiogram-dialog.readthedocs.io) and [examples](example)\r\n\r\n### Supported features:\r\n* Rich text rendering using `format` function or `Jinja2` template engine. \r\n* Automatic message updating after user actions\r\n* Multiple independent dialog stacks with own data storage and transitions\r\n* Inline keyboard widgets like `SwitchTo`, `Start`, `Cancel` for state switching, `Calendar` for date selection and others. \r\n* Stateful widgets: `Checkbox`, `Multiselect`, `Counter`, `TextInput`. They record user actions and allow you to retrieve this data later. \r\n* Multiple buttons layouts including simple grouping (`Group`, `Column`), page scrolling (`ScrollingGroup`), repeating of same buttons for list of data (`ListGroup`). \r\n* Sending media (like photo or video) with fileid caching and handling switching to/from message with no media. \r\n* Different rules of transitions between windows/dialogs like keeping only one dialog on top of stack or force sending enw message instead of updating one. \r\n* Offline HTML-preview for messages and transitions diagram. They can be used to check all states without emulating real use cases or exported for demonstration purposes. \r\n\r\n\r\n### Usage\r\n\r\nExample below is suitable for aiogram_dialog v2.x and aiogram v3.x\r\n\r\n#### Declaring Window\r\n\r\nEach window consists of:\r\n\r\n* Text widgets. Render text of message.\r\n* Keyboard widgets. Render inline keyboard\r\n* Media widget. Renders media if neede\r\n* Message handler. Called when user sends a message when window is shown\r\n* Data getter functions (`getter=`). They load data from any source which can be used in text/keyboard\r\n* State. Used when switching between windows\r\n\r\n**Info:** always create `State` inside `StatesGroup`\r\n\r\n\r\n```python\r\nfrom aiogram.filters.state import StatesGroup, State\r\nfrom aiogram_dialog.widgets.text import Format, Const\r\nfrom aiogram_dialog.widgets.kbd import Button\r\nfrom aiogram_dialog import Window\r\n\r\n\r\nclass MySG(StatesGroup):\r\n main = State()\r\n\r\n\r\nasync def get_data(**kwargs):\r\n return {\"name\": \"world\"}\r\n\r\n\r\nWindow(\r\n Format(\"Hello, {name}!\"),\r\n Button(Const(\"Empty button\"), id=\"nothing\"),\r\n state=MySG.main,\r\n getter=get_data,\r\n)\r\n```\r\n\r\n### Declaring dialog\r\n\r\nWindow itself can do nothing, just prepares message. To use it you need dialog:\r\n\r\n```python\r\nfrom aiogram.filters.state import StatesGroup, State\r\nfrom aiogram_dialog import Dialog, Window\r\n\r\n\r\nclass MySG(StatesGroup):\r\n first = State()\r\n second = State()\r\n\r\n\r\ndialog = Dialog(\r\n Window(..., state=MySG.first),\r\n Window(..., state=MySG.second),\r\n)\r\n```\r\n\r\n> **Info:** All windows in a dialog MUST have states from then same `StatesGroup`\r\n\r\nAfter creating dialog you need to register it using `DialogRegistry`:\r\n\r\n```python\r\nfrom aiogram import Dispatcher\r\nfrom aiogram_dialog import DialogRegistry\r\n\r\n...\r\ndp = Dispatcher(storage=storage) # create as usual\r\nregistry = DialogRegistry(dp) # create registry\r\nregistry.register(name_dialog) # create\r\n```\r\n\r\nThen start dialog when you are ready to use it. Dialog is started via `start` method of `DialogManager` instance. You\r\nshould provide corresponding state to switch into (usually it is state of first window in dialog).\r\n\r\nFor example in `/start` command handler:\r\n\r\n```python\r\nasync def user_start(message: Message, dialog_manager: DialogManager):\r\n await dialog_manager.start(MySG.first, mode=StartMode.RESET_STACK)\r\n\r\ndp.message.register(user_start, F.text == \"/start\")\r\n```\r\n\r\n> **Info:** Always set `mode=StartMode.RESET_STACK` in your top level start command. Otherwise, dialogs are stacked just as they do\r\non your mobile phone, so you can reach stackoverflow error\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "Apache2",
"summary": "Mini-framework for dialogs on top of aiogram",
"version": "2.0.0b15",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "0c21921c70b1161981d98e9a84279f4f",
"sha256": "61cd011e6411992adf6e273257946629bc972b5e24fd08d49db821aae4b02375"
},
"downloads": -1,
"filename": "aiogram_dialog_data_ttl_patched-2.0.0b15.tar.gz",
"has_sig": false,
"md5_digest": "0c21921c70b1161981d98e9a84279f4f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 51543,
"upload_time": "2022-12-10T05:01:17",
"upload_time_iso_8601": "2022-12-10T05:01:17.005867Z",
"url": "https://files.pythonhosted.org/packages/fd/6c/1fd975e686de1e8e58f43b127ed03f3a110f7fbdaac0cff56b4e77acebd3/aiogram_dialog_data_ttl_patched-2.0.0b15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-10 05:01:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "tishka17",
"github_project": "aiogram_dialog",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aiogram-dialog-data-ttl-patched"
}
JSON
