mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-01-21 07:55:00 +00:00
80498919fb
- This is completely reworked but based on /Developer page in the FreedomBox Manual. - This documentation can be made available as static site on https://docs.freedombox.org and the /Developer page in the FreedomBox Manual can be dropped. Signed-off-by: Sunil Mohan Adapa <sunil@medhas.org> Reviewed-by: James Valleroy <jvalleroy@mailbox.org>
113 lines
4.0 KiB
ReStructuredText
113 lines
4.0 KiB
ReStructuredText
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
|
|
|
Part 3: View
|
|
------------
|
|
|
|
Writing the URLs
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
For a user to visit our app in FreedomBox, we need to provide a URL. When the
|
|
user visits this URL, a view is executed and a page is displayed. In ``urls.py``
|
|
write the following:
|
|
|
|
.. code-block:: python3
|
|
|
|
from django.conf.urls import url
|
|
|
|
from .views import TransmissionAppView
|
|
|
|
urlpatterns = [
|
|
url(r'^apps/transmission/$', TransmissionAppView.as_view(), name='index'),
|
|
]
|
|
|
|
This routes the ``/apps/transmission/`` URL to a view called
|
|
``TransmissionAppView`` defined in ``plinth/modules/transmission/views.py``.
|
|
This is no different than how routing URLs is done in Django. See :doc:`Django
|
|
URL dispatcher <django:topics/http/urls>` for more information.
|
|
|
|
Adding a menu item
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
We have added a URL to be handled by our app but this does not yet show up to be
|
|
a link in FreedomBox web interface. Let us add a link in the apps list. In
|
|
``__init__.py`` add the following:
|
|
|
|
.. code-block:: python3
|
|
|
|
from plinth.menu import main_menu
|
|
|
|
name = 'Transmission'
|
|
|
|
short_description = 'BitTorrent Web Client'
|
|
|
|
description = [
|
|
'BitTorrent is a peer-to-peer file sharing protocol. '
|
|
'Transmission daemon handles Bitorrent file sharing. Note that '
|
|
'BitTorrent is not anonymous.',
|
|
'Access the web interface at <a href="/transmission">/transmission</a>.'
|
|
]
|
|
|
|
class TransmissionApp(app_module.App):
|
|
...
|
|
|
|
def __init__(self):
|
|
...
|
|
|
|
menu_item = menu.Menu('menu-transmission', name, short_description,
|
|
'transmission', 'transmission:index',
|
|
parent_url_name='apps')
|
|
self.add(menu_item)
|
|
|
|
What this does is add a menu item component into the our app. In FreedomBox
|
|
framework, an app is made up of many simple components. When operations such as
|
|
enable/disable are performed on the app, they will be applied on all the
|
|
components. In case of menu components, FreedomBox framework takes care of
|
|
presenting them appropriately. The component captures various details about the
|
|
menu item we want to present.
|
|
|
|
* The first parameter is simply a unique ID for the component.
|
|
|
|
* The second parameter is the display name to use for our menu item which
|
|
happens to be the name of the app as well.
|
|
|
|
* The third parameter is a short description for the menu item.
|
|
|
|
* The fourth parameter is the name of the icon to use when showing the menu
|
|
item. An SVG file and a PNG should be created in the ``static/theme/icons/``
|
|
directory.
|
|
|
|
* The fifth parameter is the URL that the user should be directed to when the
|
|
menu item is clicked. This is a Django URL name and we have already created a
|
|
URL with this name. Note that when including our app's URLs, FreedomBox will
|
|
automatically set the name of the module as the Django URL namespace. Hence it
|
|
is ``transmission:index`` and not just ``index``.
|
|
|
|
* We wish to add our menu item to the list of apps in the apps page which is why
|
|
we have specified ``apps`` as the parent URL for the this app in the final
|
|
parameter.
|
|
|
|
Writing a view
|
|
^^^^^^^^^^^^^^
|
|
|
|
We have a URL pointing to our view. We have also added a menu item in the apps
|
|
section of the web interface that points to our view. We now need to create a
|
|
view to show the app page for our app. In ``views.py``, let us add a view.
|
|
|
|
.. code-block:: python3
|
|
|
|
from plinth import views
|
|
from plinth.modules import transmission
|
|
|
|
class TransmissionAppView(views.AppView):
|
|
"""Serve configuration page."""
|
|
name = transmission.name
|
|
description = transmission.description
|
|
app_id = 'transmission'
|
|
|
|
The base view :class:`~plinth.views.AppView` takes care of a lot of details for
|
|
us. First, it shows basic information about the app like name, description,
|
|
desktop/mobiles clients for the service (described later), link to the manual
|
|
page (described later), link to diagnostics button, etc. Then it shows the
|
|
status of the app whether it is running and can also present a form for
|
|
configuration. It also presents a way to enable/disable the app.
|