Skip to main content

Integrate Hotwire Turbo with Django allowing for a Python-driven dynamic web experience.

Project description

Build Status Documentation Status Issues Twitter

Turbo for Django

Integrate Hotwire Turbo with Django with ease.

Requirements

  • Python 3.8+
  • Django 3.1+
  • Channels 3.0+ (Optional for Turbo Frames, but needed for Turbo Stream support)

##Installation

Turbo Django is available on PyPI - to install it, just run:

pip install turbo-django

Note: Both Hotwire and this library are still in beta development and may introduce breaking API changes between releases. It is advised to pin the library to a specific version during install.

Quickstart

Want to see Hotwire in action? Here's a simple broadcast that can be setup in less than a minute.

The basics:

  • A web page subscribes to a specific broadcast name.

  • A view sends a rendered template to all subscribed pages telling the page where to position the new content.

Example

First, create a view that takes a broadcast name.

from django.urls import path
from django.views.generic import TemplateView

urlpatterns = [
    path('quickstart/', TemplateView.as_view(template_name='broadcast_example.html'))
]
# broadcast_example.html

{% load turbo_streams %}
<!DOCTYPE html>
<html lang="en">
<head>
    {% include "turbo/head.html" %}
</head>
<body>
    {% turbo_subscribe 'broadcast_name' %}

    <p class="broadcast_box_class" id="broadcast_box">Placeholder for broadcast</p>
</body>
</html>

Now run ./manage.py shell. Create a Turbo object that references the broadcast name. Tell the object to render a TurboRender object from the string, and then broadcast a command to update the inside of the element with id broadcast_box on all subscribed pages.

from turbo import Turbo
from datetime import datetime

Turbo('broadcast_name').render_from_string(
    f"{datetime.now()}: This is a broadcast."
).update(id="broadcast_box")

With the quickstart/ path open in a browser window, watch as the broadcast pushes messages to the page.

Now change .update() to .append() and resend the broadcast a few times. Notice you do not have to reload the page to get this modified behavior.

Excited to learn more? Be sure to walk through the tutorial and read more about what Turbo can do for you.

Documentation

Read the full documentation at readthedocs.io.

Contribute

Discussions about a Django/Hotwire integration are happening on the Hotwire forum. And on Slack, which you can join by clicking here!

As this new magic is discovered, you can expect to see a few repositories with experiments and demos appear in @hotwire-django. If you too are experimenting, we encourage you to ask for write access to the GitHub organization and to publish your work in a @hotwire-django repository.

License

Turbo-Django is released under the MIT License to keep compatibility with the Hotwire project.

If you submit a pull request. Remember to add yourself to CONTRIBUTORS.md!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

turbo-django-0.2.4.tar.gz (28.9 kB view hashes)

Uploaded Source

Built Distribution

turbo_django-0.2.4-py3-none-any.whl (29.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page