1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
.. SPDX-License-Identifier: CC-BY-SA-4.0
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``.
.. code-block:: django
:caption: ``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 :doc:`Django Template documentation
<django:topics/templates>`.
For styling and UI components, FreedomBox uses the Twitter Bootstrap project.
See `Bootstrap documentation <http://getbootstrap.com/css/>`_ for reference.
To start using our custom template, we need to pass this to our view. In
``views.py``, add the following line:
.. code-block:: python3
:caption: ``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``.
.. code-block:: python3
:caption: ``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 :doc:`Django Forms
documentation <django:topics/forms/index>` for more information.
.. tip: Too many options
Resist the temptation to create a lot of configuration options. Although this
will put more control in the hands of the users, it will make FreedomBox less
usable. FreedomBox is a consumer product. Our target users are not technically
savvy and we have make most of the decisions on behalf of the user to make the
interface as simple and easy to use as possible.
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``.
.. code-block:: python3
:caption: ``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 :doc:`Django messaging framework
<django:ref/contrib/messages>` 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``.
.. code-block:: python3
:caption: ``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 :meth:`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 :obj:`plinth.action_utils` to
easily perform it's duties.
|
