Part 5: Customizing

Customizing the application page

The view that we have written above requires a template file. A default template file is provided by the framework. In some cases, we will need to customize this template. Let us create a custom template file in transmission.html.

templates/transmission.html

{% extends "app.html" %}

{% load i18n %}

{% block configuration %}

  {{ block.super }}

  <h3>{% trans "Custom Section" %}</h3>

  <p>
    {% blocktrans trimmed %}
      Custom paragraph content.
    {% endblocktrans %}
  </p>

{% endblock %}

This template extends an existing template known as app.html. This template is available in FreedomBox core to provide all the basic layout, styling, menus, JavaScript and CSS libraries required for a typical app view. We will override the configuration area after inheriting from the app template and keep the rest as is. {{ block.super }} adds back the overwritten content in the configuration block.

Yet again, there is nothing special about the way this template is written. This is a regular Django template. See Django Template documentation.

For styling and UI components, FreedomBox uses the Twitter Bootstrap project. See Bootstrap documentation for reference.

To start using our custom template, we need to pass this to our view. In views.py, add the following line:

views.py

class TransmissionAppView(AppView):
    ...
    template_name = 'transmission.html'

Writing a configuration form

Our app needs some configuration. So, we need to write a configuration form to provide options to the user. Add the following to forms.py.

forms.py

from django import forms


class TransmissionForm(DirectorySelectForm):  # pylint: disable=W0232
    """Transmission configuration form"""

    def __init__(self, *args, **kw):
        validator = DirectoryValidator(username=SYSTEM_USER,
                                       check_creatable=True)
        super().__init__(title=_('Download directory'),
                         default='/var/lib/transmission-daemon/downloads',
                         validator=validator, *args, **kw)

This uses a utility provided by the framework and creates a Django form that shows a single option to set the download directory for our Transmission app. This is similar to how a regular Django form is built. See Django Forms documentation for more information.

Applying the changes from the form

The view we have created needs to display the form and process the form after the user submits it. Let us implement that in views.py.

views.py

from django.contrib import messages

from plinth import actions, views

from .forms import TransmissionForm

class TransmissionAppView(views.AppView):
    """Serve configuration page."""
    form_class = TransmissionForm
    app_id = 'transmission'

    def get_initial(self):
        """Get the current settings from Transmission server."""
        status = super().get_initial()
        configuration = privileged.get_configuration()
        status['storage_path'] = configuration['download-dir']
        status['hostname'] = socket.gethostname()

        return status

    def form_valid(self, form):
        """Apply the changes submitted in the form."""
        old_status = form.initial
        new_status = form.cleaned_data
        if old_status['storage_path'] != new_status['storage_path']:
            new_configuration = {
                'download-dir': new_status['storage_path'],
            }
            privileged.merge_configuration(new_configuration)
            messages.success(self.request, 'Configuration updated')

        return super().form_valid(form)

We check to make sure that the configuration value has actually changed after the form is submitted. Although FreedomBox’s operations are idempotent, meaning that running them twice will not be problematic, we still wish to avoid unnecessary operations for the sake of speed.

We are actually performing the operation using actions. We will implement this action a bit later.

After we perform the operation, we will show a message on the response page that the action was successful or that nothing happened. We use the Django messaging framework to accomplish this. See Django messaging framework for more information.

Writing privileged actions

The actual work of performing the configuration change is carried out by privileged actions. These actions are independent scripts that run with higher privileges required to perform a task. They are placed in a separate python module ‘privileged.py’ and invoked as regular methods. For our application we need to write two privileged actions that can read and write the configuration for transmission daemon. We will do this by creating a file privileged.py.

privileged.py

import json
import pathlib

from plinth import action_utils
from plinth.actions import privileged

_transmission_config = pathlib.Path('/etc/transmission-daemon/settings.json')


@privileged
def get_configuration() -> dict[str, str]:
    """Return the current configuration in JSON format."""
    return json.loads(_transmission_config.read_text(encoding='utf-8'))


@privileged
def merge_configuration(configuration: dict[str, str | bool]) -> None:
    """Merge given JSON configuration with existing configuration."""
    current_configuration = _transmission_config.read_bytes()
    current_configuration = json.loads(current_configuration)

    new_configuration = current_configuration
    new_configuration.update(configuration)
    new_configuration = json.dumps(new_configuration, indent=4, sort_keys=True)

    _transmission_config.write_text(new_configuration, encoding='utf-8')
    action_utils.service_reload('transmission-daemon')

This is a simple Python3 module but it runs in a separate process with superuser privileges due to the plinth.actions.privileged() decorator. All such methods must have full type annotations for the method parameters. Further, the parameters and return value must be JSON serializable. It may use various helper utilities provided by the FreedomBox framework in plinth.action_utils to easily perform it’s duties.