PyBlade

Appearance

Quick Start ​

To begin your PyBlade Live journey, we will create a simple "counter" component and render it in the browser. This example is a great way to experience PyBlade Live for the first time as it demonstrates PyBlade's liveness in the simplest way possible.

Install PyBlade Live ​

Since PyBlade Live is a part of PyBlade, you first need to install PyBlade inside a virtual environment. To do this, run:

bash
pip install pyblade

Once installed, initialize a new project for your preferred Python framework:

bash
pyblade init

During the project initialization, PyBlade will ask whether you want to enable PyBlade Live:

  • If you select Yes, PyBlade Live will be fully configured, and you can start using it right away.
  • If you select No, PyBlade Live won’t be set up initially, but you can enable it later by running:
bash
pyblade live:install

This command will automatically configure everything for PyBlade Live to work inside your project.

Create a PyBlade Live component ​

PyBlade provides a convenient command to generate new Livablade components quickly. Run the following command to make a new counter component:

bash
pyblade make:live counter

This command will generate two new files in your project:

  • live/counter.py
  • templates/live/counter.html

Writing the class ​

Open live/counter.py and replace its contents with the following:

python
from pyblade import live

class Counter(live.Component):
    count = 0

    def increment(self):
        self.count += 1

    def decrement(self):
        self.count -= 1

    def render(self):
        return self.view("live.counter")

Here's a brief explanation of the code above:

  • count = 0 — Declares a class property named count with an initial value of 0.
  • def increment(self) — Declares a method named increment that increments the count property each time it's called. Methods like this can be triggered from the browser in a variety of ways, including when a user clicks a button.
  • def decrement(self) — Declares a method named decrement that decrements the count property each time it's called.
  • def render(self) — Declares a render method that returns a PyBlade Live view. This view will contain the HTML template for our component.

Writing the template ​

Open the templates/live/counter.html file and replace its content with the following:

html
<div >
    <h1>{{ count }}</h1>

    <button pb-click="decrease">-</button>
    <button pb-click="increase">+</button>
</div>

This code will display the value of the count property and two buttons that decrement and increment the count property, respectively.

Warning

In order for PyBlade Live to work, components must have just one single element as its root. If multiple root elements are detected, an exception is thrown. Comments don't count as separate elements and can be put inside the root element.

Create the component wrapper ​

You just created the live component. But, how to use it ? Now we need a HTML template for our component to render inside. Let's create one:

bash
pyblade make:template index

This command will generate a file called templates/index.html. Open it and add the following content :

html
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Title</title>
    </head>
    <body>
        @live("counter")
    </body>
</html>

The counter component will be rendered in place of the @live("counter") directive in the template above.

You may have noticed there is no JavaScript or CSS assets provided by PyBlade Live. That is because PyBlade Live automatically injects any frontend assets it needs.

Now let's create the view function that will render our index.html template. Open the view.py file and add the following content:

python
from django.shortcuts import render

def index(request):
    return render(request, "index")

Register a route for the component ​

Open the urls.py file in your Django application and add the following code:

python
from django.urls import path
from .views import index

urlpatterns = [
    path('counter/', index)
]

Warning

Make sure the views.py and urls.py files are in the same folder.

Now, our counter component is assigned to the counter/ route, so that when a user visits the counter/ endpoint in your application, PyBlade will load our index.html template, parse it, and when it will encouter the @live("counter") directive, the directive will render our component, finally PyBlade Engine will render the full page.

Test it out ​

With our component class and templates in place, our component is ready to test!

Start the development server by running:

bash
pyblade serve

Visit whatever the link shown in your terminal plus counter/ in your browser (most likely http:127.0.0.1:8000/counter/), and you should see a number displayed on the screen with two buttons to increment and decrement the number.

After clicking one of the buttons, you will notice that the count updates in real time, without the page reloading. This is the magic of PyBlade Live: dynamic frontend applications written entirely in Python.

We've barely scratched the surface of what PyBlade Live is capable of. Keep reading the documentation to see everything PyBlade Live has to offer.