diff --git a/doc/dev/tutorial/components.rst b/doc/dev/tutorial/components.rst index ce8945119..5f89cd257 100644 --- a/doc/dev/tutorial/components.rst +++ b/doc/dev/tutorial/components.rst @@ -30,23 +30,21 @@ function normally. def __init__(self): ... - info = app_module.Info(app_id=self.app_id, version=1, - name=_('Transmission'), - icon_filename='transmission', - short_description=_('BitTorrent Web Client'), - description=description, - manual_page='Transmission', - clients=manifest.clients, - donation_url='https://transmissionbt.com/donate/') + info = app_module.Info( + app_id=self.app_id, version=1, name=_('Transmission'), + icon_filename='transmission', description=_description, + manual_page='Transmission', clients=manifest.clients, + donation_url='https://transmissionbt.com/donate/', + tags=manifest.tags) self.add(info) The first argument is app_id that is same as the ID for the app. The version is the version number for this app that must be incremented whenever setup() method -needs to be called again. name, icon_filename, short_description, description, -manual_page and clients provide information that is shown on the app's main -page. The donation_url encourages our users to contribute to upstream projects -in order ensure their long term sustainability. More information about the -parameters is available in :class:`~plinth.app.Info` class documentation. +needs to be called again. name, icon_filename, description, manual_page, +clients, and tags provide information that is shown on the app's main page. The +donation_url encourages our users to contribute to upstream projects in order +ensure their long term sustainability. More information about the parameters is +available in :class:`~plinth.app.Info` class documentation. The description of app should provide basic information on what the app is about and how to use it. It is impractical, however, to explain everything about the @@ -322,22 +320,24 @@ when they visit FreedomBox. To provide this shortcut, a def __init__(self): ... - shortcut = frontpage.Shortcut( - 'shortcut-transmission', name, short_description=short_description, - icon='transmission', url='/transmission', clients=clients, - login_required=True, allowed_groups=[group[0]]) + shortcut = frontpage.Shortcut('shortcut-transmission', info.name, + icon=info.icon_filename, + url='/transmission', + clients=info.clients, tags=info.tags, + login_required=True, + allowed_groups=list(groups)) self.add(shortcut) -The first parameter, as usual, is a unique ID. The next three parameters are -basic information about the app similar to the menu item. The URL parameter -specifies the URL that the user should be directed to when the shortcut is -clicked. This is the web interface provided by our app. The next parameter -provides a list of clients. This is useful for the FreedomBox mobile app when -the information is used to suggest installing mobile apps. This is described in -a later section of this tutorial. The next parameter specifies whether anonymous -users who are not logged into FreedomBox should be shown this shortcut. The -final parameter further restricts to which group of users this shortcut must be -shown. +The first parameter, as usual, is a unique ID. The next two parameters are basic +information about the app similar to the menu item. The URL parameter specifies +the URL that the user should be directed to when the shortcut is clicked. This +is the web interface provided by our app. The next parameter provides a list of +clients. This is useful for the FreedomBox mobile app when the information is +used to suggest installing mobile apps. This is described in a later section of +this tutorial. The next parameter specifies the list of tags to show on the +shortcut. The next parameter specifies whether anonymous users who are not +logged into FreedomBox should be shown this shortcut. The final parameter +further restricts to which group of users this shortcut must be shown. Adding backup/restore functionality ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/dev/tutorial/other.rst b/doc/dev/tutorial/other.rst index 2a99fbe9f..f4ca0ab40 100644 --- a/doc/dev/tutorial/other.rst +++ b/doc/dev/tutorial/other.rst @@ -89,22 +89,23 @@ the Django's localization methods to make that happen. info = app_module.Info(... name=_('Transmission'), + description=[_('Transmission is a...'), + _('BitTorrent is a peer-to-peer...')], ... - short_description=_('BitTorrent Web Client'), + tags=[_('File sharing'), _('BitTorrent'), ...]) ...) -Notice that the app's name, description, etc. are wrapped in the ``_()`` method -call. This needs to be done for the rest of our app. We use the +Notice that the app's name, description, tags, etc. are wrapped in the ``_()`` +method calls. This needs to be done for the rest of our app. We use the :obj:`~django.utils.translation.gettext_lazy` in some cases and we use the -regular :obj:`~django.utils.translation.gettext` in other cases. This is -because in the second case the :obj:`~django.utils.translation.gettext` lookup -is made once and reused for every user looking at the interface. These users may -each have a different language set for their interface. Lookup made for one -language for a user should not be used for other users. The ``_lazy`` methods -provided by Django makes sure that the return value is an object that will -actually be converted to string at the final moment when the string is being -displayed. In the first case, the lookup is made and string is returned -immediately. +regular :obj:`~django.utils.translation.gettext` in other cases. This is because +in the second case the :obj:`~django.utils.translation.gettext` lookup is made +once and reused for every user looking at the interface. These users may each +have a different language set for their interface. Lookup made for one language +for a user should not be used for other users. The ``_lazy`` methods provided by +Django makes sure that the return value is an object that will actually be +converted to string at the final moment when the string is being displayed. In +the first case, the lookup is made and string is returned immediately. All of this is the usual way internationalization is done in Django. See :doc:`Internationalization and localization ` diff --git a/doc/dev/tutorial/view.rst b/doc/dev/tutorial/view.rst index b9b94229c..aa7cb4332 100644 --- a/doc/dev/tutorial/view.rst +++ b/doc/dev/tutorial/view.rst @@ -45,7 +45,7 @@ a link in FreedomBox web interface. Let us add a link in the apps list. In ... menu_item = menu.Menu('menu-transmission', 'Transmission', - 'BitTorrrent Web Client', 'transmission', + 'transmission', info.tags, 'transmission:index', parent_url_name='apps') self.add(menu_item) @@ -61,12 +61,12 @@ menu item we want to present. * 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 +* The third 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 ``plinth/modules/transmission/static/icons/`` directory. +* The fourth parameter is the list of tags to show on the menu item. + * 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