diff --git a/docs/source/extend-turbo-stream.md b/docs/source/extend-turbo-stream.md new file mode 100644 index 0000000..d28e94f --- /dev/null +++ b/docs/source/extend-turbo-stream.md @@ -0,0 +1,62 @@ +# Extend Turbo Stream + +## Simple Example + +You can extend Turbo Stream Action by `register_turbo_stream_action` decorator. + +```python +from turbo_helper import ( + register_turbo_stream_action, + turbo_stream, +) + + +# register toast action +@register_turbo_stream_action("toast") +def toast(target, content=None, **kwargs): + position = kwargs.get('position', 'left') + return turbo_stream.action( + "toast", target=target, message=kwargs['message'], position=position + ) + + +turbo_stream.toast("dom_id", message="hello world", position="right") +# +``` + +Or you can render it in template: + +```django +{% load turbo_helper %} + +{% turbo_stream "toast" "target" message="Hello Word" position="right" %}{% endturbo_stream %} +``` + +Next, you can update your frontend code to make it work with new `action` + +[https://turbo.hotwired.dev/handbook/streams#custom-actions](https://turbo.hotwired.dev/handbook/streams#custom-actions) + +## Ecosystem + +There are some good projects on GitHub that can save our time: + +1. [https://github.com/marcoroth/turbo_power](https://github.com/marcoroth/turbo_power) +2. [https://github.com/hopsoft/turbo_boost-streams](https://github.com/hopsoft/turbo_boost-streams) + +For example, to add css class to a DOM element, we can use + +```python +turbo_stream.add_css_class( + targets="#element", classes="container text-center" +) +``` + +and it can generate HTML snippet like this + +```html + +``` + +And registering the action handler on the frontend side, we can add css class on server side, without writing Javascript code. + +Now "django-turbo-helper" already contains some `turbo_power` actions, please check the source code and test cases for more details. diff --git a/docs/source/index.rst b/docs/source/index.rst index 78de131..a89f65b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,6 +21,7 @@ Topics turbo_frame.md turbo_stream.md real-time-updates.md + extend-turbo-stream.md multi-format.md redirect.md test.md diff --git a/docs/source/real-time-updates.md b/docs/source/real-time-updates.md index 3f06e94..288419f 100644 --- a/docs/source/real-time-updates.md +++ b/docs/source/real-time-updates.md @@ -1,4 +1,4 @@ -# turbo_stream_from +# Update Page in Real Time via Websocket Use Websocket and Turbo Stream to update the web page in real time, without writing Javascript. diff --git a/docs/source/turbo_stream.md b/docs/source/turbo_stream.md index 283f83f..6528ac4 100644 --- a/docs/source/turbo_stream.md +++ b/docs/source/turbo_stream.md @@ -99,38 +99,6 @@ Notes: 3. Other arguments can be passed as `key=value` pairs 4. We can generate **multiple** turbo stream elements in one template and render it in one response, and update multiple part of the page in one response. -## Extend Turbo Stream Action - -You can extend Turbo Stream Action by `register_turbo_stream_action` decorator. - -```python -from turbo_helper import ( - register_turbo_stream_action, - turbo_stream, -) - - -# register toast action -@register_turbo_stream_action("toast") -def toast(target, content=None, **kwargs): - position = kwargs.get('position', 'left') - return turbo_stream.action( - "toast", target=target, message=kwargs['message'], position=position - ) - - -turbo_stream.toast("dom_id", message="hello world", position="right") -# -``` - -Or you can do it in template: - -```django -{% load turbo_helper %} - -{% turbo_stream "toast" "target" message="Hello Word" position="right" %}{% endturbo_stream %} -``` - ## Targeting Multiple Elements To target multiple elements with a single action, use the `targets` attribute with a CSS query selector instead of the `target` attribute