Views

Interactive

By default all Lona views are interactive. Interactive Lona views run over a websocket connection, which makes input events and background views possible.

More information: Basic Concept

Non-Interactive

Non interactive views run on HTTP, not websockets. This is useful to add a JSON-API to your project for example.

To mark a view non interactive, use the interactive keyword in the routes.py.

# routes.py

from lona import Route

routes = [
    Route('/json-api.json', 'views/json_api.py::JSONAPIView', interactive=False)
]

# views/json_api.py

from lona import LonaView, JsonResponse


class JSONAPIView(LonaView):
    def handle_request(self, request):
        return JsonResponse({'exit_code': 0, 'value': 'foo'})

HTTP Pass Through

HTTP pass through views bypass the most of the Lona server infrastructure and speak directly to aiohttp. Therefore HTTP pass through views get aiohttp request objects passed in and have to return aiohttp response objects.

This is useful to use basic HTTP features like file upload, or connect Lona to WSGI based frameworks like Django.

HTTP pass through views can be callbacks instead of classes, to make projects like aiohttp wsgi work. More information: Integrating Django.

To mark a view as HTTP pass through, use the http_pass_through keyword in the routes.py.

# routes.py

from lona import Route

routes = [
    Route('/http-pass-through/', 'views/http_pass_through.py::HTTPPassThroughView',
          http_pass_through=True),
]

# views/http_pass_through.py

from aiohttp.web import Response

from lona import LonaView


class HTTPPassThroughView(LonaView):
    def handle_request(self, request):
        return Response(
            body='<h1>HTTP Pass Through</h1>',
            content_type='text/html',
        )

Simple Patterns

# routes.py

from lona import Route

routes = [
    Route('/<arg1>/<arg2>/', 'views/my_view.py::MyView'),
]

# views/my_view.py

from lona import LonaView


class MyView(LonaView):
    def handle_request(self, request):
        arg1 = request.match_info['arg1']
        arg2 = request.match_info['arg2']

Custom Patterns

Custom patterns can be any valid regex:

# routes.py

from lona import Route

routes = [
    Route('/<arg1:[a-z]{3}>/', 'views/my_view.py::MyView'),
]

It is possible to match any character (including the /). The following route matches any URL beginning with prefix:

# routes.py

from lona import Route

routes = [
    Route('/prefix<path:.*>', 'views/my_view.py::MyView'),
]

Trailing Slashes

Make the trailing slash in a URL optional by ending the route with (/)):

# routes.py

from lona import Route

routes = [
    Route('/<arg1>(/)', 'views/my_view.py::MyView'),
]

Attributes

GET

By default all Lona view requests are GET requests. The URL query is stored in request.GET.

from lona import LonaView


class MyLonaView(LonaView):
    def handle_request(self, request):
        print(request.method)
        print(request.GET)

        return ''

POST

It is possible to use traditional POST requests. This doesn't require the view to wait for user input and saves resources.

from lona.html import HTML, Form, TextInput, Submit, H1
from lona import LonaView


class MyLonaView(LonaView):
    def handle_request(self, request):
        if request.method == 'POST':
            return f'<h1>Hello {request.POST["name"]}</h1>'

        return HTML(
            H1('Enter your name'),
            Form(
                TextInput(name='name'),
                Submit('Submit'),
                action='.',
                method='post',
            ),
        )

HTML Responses

from lona import LonaView


class MyLonaView(LonaView):
    def handle_request(self, request):
        return """
            <h1>Hello World</h1>
        """

from lona import LonaView
from lona.html import H1


class MyLonaView(LonaView):
    def handle_request(self, request):
        return H1('Hello World')

Template Responses

from lona import LonaView


class MyLonaView(LonaView):
    def handle_request(self, request):
        return {
            'template': 'path/to/your/template.html',
            'foo': 'bar',
        }

from lona import LonaView


class MyLonaView(LonaView):
    def handle_request(self, request):
        return {
            'template_string': '<h1>{{ header }}}</h1>',
            'header': 'Hello World',
        }

from lona import LonaView, TemplateResponse, TemplateStringResponse


class MyLonaView(LonaView):
    def handle_request(self, request):
        return TemplateResponse(
            'template_name.html',
            {
                'variable_name': 'foo',
            },
        )

class MyLonaView(LonaView):
    def handle_request(self, request):
        return TemplateStringResponse(
            '{{ message }}',
            {
                'variable_name': 'Template String Response',
            },
        )

Redirects

from lona import LonaView
from lona.html import H1


class MyLonaView(LonaView):
    def handle_request(self, request):
        return {
            'redirect': '/',
        }

from lona import LonaView, RedirectResponse


class MyLonaView(LonaView):
    def handle_request(self, request):
        return RedirectResponse('/')

HTTP Redirects

from lona import LonaView
from lona.html import H1


class MyLonaView(LonaView):
    def handle_request(self, request):
        return {
            'http_redirect': '/',
        }

from lona import LonaView, HttpRedirectResponse


class MyLonaView(LonaView):
    def handle_request(self, request):
        return HttpRedirectResponse('/')

JSON Responses

from lona import LonaView


class MyLonaView(LonaView):
    def handle_request(self, request):
        return {
            'json': {
                'foo': 'bar',
            },
        }

from lona import LonaView, JsonResponse


class MyLonaView(LonaView):
    def handle_request(self, request):
        return JsonResponse({'foo': 'bar'})

Binary Responses

from lona import LonaView


class MyLonaView(LonaView):
    def handle_request(self, request):
        return {
            'content_type': 'application/pdf',
            'body': open('foo.pdf', 'rb').read(),
        }

from lona import LonaView, Response


class MyLonaView(LonaView):
    def handle_request(self, request):
        return Response(
            content_type='application/pdf',
            body=open('foo.pdf', 'rb').read(),
        )

Custom Headers

from lona import LonaView


class MyLonaView(LonaView):
    def handle_request(self, request):
        return {
            'headers': {
                'foo': 'bar',
            },
            'text': 'foo',
        }

from lona import LonaView, Response


class MyLonaView(LonaView):
    def handle_request(self, request):
        return Response(
            headers={
                'foo': 'bar',
            },
            text='foo',
        )

LonaView.handle_request(request)

Gets called with a lona.request.Request object, and has to return a response object described in Response Objects.

handle_request() is the main entry point for every view. Your main logic should be stored here.

LonaView.handle_input_event_root(input_event)

This hook is gets called first for every input event and is able to override all input event behavior.

This hook is required to return the given input event or None. If the input event is returned, the chain of input events described in Input Events continues. If the return value is None Lona regards the input event as handled and aborts the chain.

LonaView.handle_input_event(input_event)

This hook is gets called for every input event that is not awaited in handle_request() or handled by a widget.

LonaView.on_view_event(view_event)

This hook gets called for every incoming view event.

LonaView.on_stop(reason)

This hook gets called after handle_request() stops. reason is either None if handle_request() finished normally, or an exception if handle_request() was interrupted or crashed. If it crashed, reason contains the original exception.

If the handle_request() was interrupted by the server shutting down, reason contains a lona.exceptions.ServerStop exception.

If the handle_request() was interrupted by the user by closing the connection, either intentionally or due connection loss, reason contains a lona.exceptions.UserAbort exception.

LonaView.on_cleanup()

This hook gets called after the view is fully shutdown and gets removed from the server.

LonaView.on_shutdown(reason)

This hook gets called after the view is stopped. The stop reason is None if the view finished normally or contains a lona.exceptions.ServerStop or lona.exceptions.UserAbort if the connected user closed the browser.

It does not run if the view ran into a 403 error, a 500 error or returned a response dict.

Input Event types

from lona.html import HTML, Div, Button, CLICK
from lona import LonaView


class MyLonaView(LonaView):
    def handle_click(self, input_event):
        print(input_event.tag_name, 'was clicked')

    def handle_request(self, request):
        return HTML(
            Div('Click me', events=[CLICK], handle_click=self.handle_click),

            # Buttons have CLICK set by default
            Button('Click Me', handle_click=self.handle_click),
        )

from lona.html import HTML, TextInput
from lona import LonaView


class MyLonaView(LonaView):
    def handle_change(self, input_event):
        print('TextInput is set to', input_event.node.value)

    def handle_request(self, request):
        return HTML(
            TextInput(value='foo', handle_change=self.handle_change),
        )

from lona.html import HTML, TextInput, FOCUS
from lona import LonaView


class MyLonaView(LonaView):
    def handle_focus(self, input_event):
        print('TextInput got focused')

    def handle_request(self, request):
        return HTML(
            TextInput(events=[FOCUS], handle_focus=self.handle_focus),
        )

from lona.html import HTML, TextInput, BLUR
from lona import LonaView


class MyLonaView(LonaView):
    def handle_blur(self, input_event):
        print('TextInput got blurred')

    def handle_request(self, request):
        return HTML(
            TextInput(events=[BLUR], handle_blur=self.handle_blur),
        )

Input Event Attributes

Input Event Methods

Handling Input events In A Callback

Every subclass of lona.html.AbstractNode can implement handle_input_event() to handle its own input events.

A callbacks can be implemented using inheritance or by simply resetting the values of AbstractNode.handle_input_event(), AbstractNode.handle_click() or AbstractNode.handle_change().

Callbacks can also be set by passing them directly into nodes, using the handle_change or handle_click keywords.

from lona.html import HTML, H1, Button
from lona import LonaView


class MyLonaView(LonaView):
    def handle_button_1_click(self, input_event):
        print('button 1 was clicked')

    def handle_button_2_click(self, input_event):
        print('button 2 was clicked')

    def handle_request(self, request):
        button_1 = Button('Button 1')

        button_1.handle_click = self.handle_button_1_click

        html = HTML(
            H1('Click the buttons'),
            button,
            Button('Button 2', handle_click=self.handle_button_2_click),
        )

        self.show(html)

Awaiting Input Events

Input events can be awaited from handle_request(). This makes forms or wizards possible.

from lona.html import HTML, H1, Button
from lona import LonaView


class MyLonaView(LonaView):
    def handle_request(self, request):
        html = HTML(
            H1('Click the button'),
            Button('click me'),
        )

        self.show(html)

        input_event = self.await_click()

        print(input_event.node, 'was clicked')

Handling Input Events In A Hook

Input events can also be handled in handle_input_event() when handle_request() is busy.

from datetime import datetime

from lona.html import HTML, H1, Div, Button
from lona import LonaView


class MyLonaView(LonaView):
    def handle_request(self, request):
        self.timestamp = Div()
        self.message = Div()
        self.button = Button('click me')

        self.html = HTML(
            H1('Click the button'),
            self.timestamp,
            self.message,
        )

        while True:
            timestamp.set_text(str(datetime.now()))

            self.show(self.html)

            self.sleep(1)

    def handle_input_event(self, input_event):
        if not input_event.node == self.button:
            return input_event

        self.message.set_text(f'Button was clicked at {datetime.now()}')

Overriding All Input Event Hooks

handle_input_event_root() gets always called first. This makes it possible to override even widget event handler.

from lona import LonaView


class MyLonaView(LonaView):
    def handle_input_event_root(self, input_event):
        print(input_event)

LonaView.show(html=None, template=None, template_string=None, title=None, template_context=None)

Note

This method works in interactive mode only

Takes a HTML tree from lona.html, a string or a template name and context and sends it to the client.

When the given html is a HTML tree and it is the same object as the in call before, Lona sends only updates, not the entire HTML tree all over again.

More information on HTML trees: HTML

LonaView.set_title(title)

Note

This method works in interactive mode only

This method sets the title of the browser tab.

LonaView.await_input_event(*nodes, html=None)

Note

LonaView.await_* blocks the current thread until a matching event gets send by the browser.

Read Awaiting Input Events for more information.

Returns the next incoming input event.

When nodes is set, the next input event issued by one of the given nodes is returned.

When html is set, LonaView.show() gets called before waiting on an input event

LonaView.await_click(*nodes, html=None)

Note

LonaView.await_* blocks the current thread until a matching event gets send by the browser.

Read Awaiting Input Events for more information.

Returns the next incoming click event.

When nodes is set, the next input event issued by one of the given nodes is returned.

When html is set, LonaView.show() gets called before waiting on an input event

LonaView.await_change(*nodes, html=None)

Note

LonaView.await_* blocks the current thread until a matching event gets send by the browser.

Read Awaiting Input Events for more information.

Returns the next incoming change event.

When nodes is set, the next input event issued by one of the given nodes is returned.

When html is set, LonaView.show() gets called before waiting on an input event

LonaView.await_focus(*nodes, html=None)

Note

Added in 1.9

Note

LonaView.await_* blocks the current thread until a matching event gets send by the browser.

Read Awaiting Input Events for more information.

Returns the next incoming focus event.

When nodes is set, the next input event issued by one of the given nodes is returned.

When html is set, LonaView.show() gets called before waiting on an input event

LonaView.await_blur(*nodes, html=None)

Note

Added in 1.9

Note

LonaView.await_* blocks the current thread until a matching event gets send by the browser.

Read Awaiting Input Events for more information.

Returns the next incoming blur event.

When nodes is set, the next input event issued by one of the given nodes is returned.

When html is set, LonaView.show() gets called before waiting on an input event

LonaView.daemonize()

Warning

This method is deprecated and will be removed in Lona 2.0.

Use LonaView.is_daemon instead.

Allow the view to run in background after the user disconnected.

Note

Daemonized views are not meant to be used to create multi-user views. They are meant to create single-user views that are long running (multiple minutes or hours).

For example if you write a view that process a huge amount of data, and you want to push a progress bar forward.

If you want to create multi-user views, use view events.

LonaView.is_daemon

Note

Added in 1.11

Boolean property. When set to True, the view remains on the server after it finished and can be connected and reconnected by one or more browsers or browser tabs of the same user. The view gets removed from the server after the view explicitly sets LonaView.is_daemon to False.

Note

In all versions prior to 1.11, daemonized views got removed immediately from the server when their LonaView.handle_requset() returned. To maintain compatibility with older code, this new behavior is only active if LonaView.STOP_DAEMON_WHEN_VIEW_FINISHES is set to False.

LonaView.subscribe(topic, handler, implicit_show=True)

Subscribes to a channel with the given topic and handler, and does error handling when the handler crashes, by invoking the 500 error handler. When implicit_show is set to True, LonaView.show() is called after every handled message.

LonaView.subscribe() maintains a list of all subscribed channels and unsubscribes all of them on cleanup, when the view closes, using LonaView.unsubscribe_from_all_channels().

LonaView.unsubscribe_from_all_channels()

Unsubscribes from all channels, subscribed using LonaView.subscribe().

Gets called implicitly on cleanup when the view closes.

LonaView.iter_objects()

Note

Removed in 1.8

Returns a generator over all objects of the view class. This is useful to build multi user views.

LonaView.fire_view_event(name, data=None)

Note

View events are deprecated since 1.14. Use Channels instead.

Note

Added in 1.7.3

Sends a view event to all objects of its class. name has to be a str, data is optional but has to be a dict if set.

To send a view event to multiple view classes use Server.fire_view_event() instead.

LonaView.send_str(string, broadcast=False, filter_connections=lambda connection: True, wait=True)

Sends given string over the websocket connection to all clients, connected to this view. When broadcast is set, the string gets send to all websocket connections connected to the server.

The filter gets called for every connection that is about to get the string send.

from lona import LonaView


class MyLonaView(LonaView):
    def filter_admins(self, connection):
        if connection.user.is_admin:
            return True

        return False

    def handle_request(self, request):
        self.send_str(
            'message only for admins',
            broadcast=True,
            filter_connections=self.filter_admins,
        )

The method returns when the message got send. When wait is set to False, the method returns immediately after the string got written to the connection message queues.

More information: Sending custom messages

LonaView.sleep(**args, **kwargs)

Calls asyncio.sleep(), but is abortable.

When using asyncio.sleep() or time.sleep() directly, the server cannot shutdown til the call returns.

When using LonaView.sleep() the Lona server can the abort the call when shutting down.

LonaView.ping()

This method raises a lona.exception.UserAbort or lona.exception.ServerStop if the server got stopped or the user left.

LonaView.await_sync(awaitable)

Takes a asyncio awaitable and schedules it to server.loop. The method returns the return value of the awaitable, raises its exception or raises lona.exception.UserAbort or lona.exceptions.ServerStop if the server stopped while waiting on awaitable or the user left.

LonaView.embed_shell()

Note

Removed in 1.8. Use rlpython directly instead.

import rlpython
rlpython.embed()

Embeds a rlpython based shell. More info on shells: Debugging.