RASCSI/python/web
Daniel Markstedt 0589a0efad
Improve UX for file upload forms (#1299)
* Improve UX for file upload forms

* Fix styles for admin service list

* Turn tabs into spaces
2023-11-04 02:21:54 -07:00
..
mock/bin Add web UI notification for under voltage/throttling events (#1203) 2023-08-31 23:23:12 -07:00
service-infra Launch python client services only after network-online target (#1197) 2023-07-31 12:12:53 -07:00
src Improve UX for file upload forms (#1299) 2023-11-04 02:21:54 -07:00
tests Update tests 2023-11-04 11:59:54 +09:00
__init__.py restructuring towards python client library #455 (#613) 2022-01-21 15:08:29 -08:00
.prettierrc.json New theme for web UI (#957) 2022-11-14 09:32:15 -08:00
.stylelintrc.json Bump stylelint to 15.10.2 and remove deprecated module (#1189) 2023-07-28 22:53:12 -07:00
babel.cfg Remove Jinja extentions that are now built in (#1008) 2022-11-28 13:05:19 -08:00
package-lock.json Bump postcss from 8.4.18 to 8.4.31 in /python/web (#1241) 2023-10-22 19:06:48 +09:00
package.json Bump stylelint to 15.10.2 and remove deprecated module (#1189) 2023-07-28 22:53:12 -07:00
pyproject.toml Run web API test suite in GitHub Actions (#1009) 2022-12-04 14:31:57 +00:00
README.md Run pybabel extract against the src subdir to pull in only piscsi strings (#1032) 2022-12-11 14:17:14 -08:00
requirements-dev.txt Fix test failures in low-voltage PR (#1207) 2023-09-04 08:08:42 -07:00
requirements.txt Bump to Flask 3 / Werkzeug 3 2023-10-30 08:46:06 +09:00
start.sh Rebrand project to PiSCSI (#1016) 2022-12-05 09:58:23 -08:00
translation_update.sh Create venv if it is missing (#1089) 2023-02-03 22:24:21 -08:00

PiSCSI Web

Setup local dev env

# Change to python/web/src
$ cd python/web
# Make a virtual env named venv
$ python3 -m venv venv
# Use that virtual env in this shell
$ source venv/bin/activate
# Install requirements
$ pip install -r requirements.txt
# Use mocks and a temp dir - start the web server
$ BASE_DIR=/tmp/images/ PATH=$PATH:`pwd`/mock/bin/ cd python/web && PYTHON_COMMON_PATH=$(dirname $PWD)/common/src PYTHONPATH=$PWD/src:${PYTHON_COMMON_PATH} python3 src/web.py

Mocks for local development

You may edit the files under mock/bin to simulate Linux command responses. TODO: piscsi-web uses protobuf commands to send and receive data from piscsi. A separate mocking solution will be needed for this interface.

(Optional) Pushing to the Pi via git

This is a setup for pushing code changes from your local development environment to the Raspberry Pi without a roundtrip to the remote GitHub repository.

Setup a bare repo on the piscsi

$ ssh pi@piscsi
$ mkdir /home/pi/dev.git && cd /home/pi/dev.git
$ git --bare init
Initialized empty Git repository in /home/pi/dev.git

Locally

$ cd ~/source/PISCSI
$ git remote add pi ssh://pi@piscsi/home/pi/dev.git
$ git push pi master

Localizing the Web Interface

We use the Flask-Babel library and Flask/Jinja2 extension for internationalization (i18n).

It uses the 'pybabel' command line tool for extracting and compiling localizations. The Web Interface start script will automatically compile localizations upon launch.

Activate the Python venv in src/web/ to use it:

$ cd python/web
$ source venv/bin/activate
$ pybabel --help

To create a new localization, it needs to be added to the LANGAUGES constant in web/settings.py. To localize messages coming from the PiSCSI backend, update also code in raspberrypi/localizer.cpp in the PiSCSI C++ code.

Once this is done, it is time to localize the Python code. The below steps are derived from the Flask-Babel documentation.

First, generate the raw messages.pot file containing extracted strings.

$ pybabel extract -F babel.cfg -o messages.pot src

Initialize a new localization

When adding a localization for a new language, initialize the directory structure. Replace 'xx' with the two character code for the language.

$ pybabel init -i messages.pot -d src/translations -l xx

Update an existing localization

Tip: Use the script translation_update.sh in this dir to automatically extract strings, update existing localizations, and print translation statistics.

After strings have been added or changed in the code, update the existing localizations.

$ pybabel update -i messages.pot -d src/translations

Then edit the updated messages.po file for your language. Make sure to update fuzzy strings and translate new ones.

When you are ready to contribute new or updated localizations, use the same Gitflow Workflow as used for any code contributions to submit PRs against the develop branch.

Working with PO files

See the GNU gettext documentation for an introduction to the PO file format.

We make heavy use of python-format for formatting, for instance:

#: file_cmds.py:353
#, python-format
msgid "%(file_name)s downloaded to %(save_dir)s"
msgstr "Laddade ner %(file_name)s till %(save_dir)s"

There are also a few instances of formatting in JavaScript:

#: templates/index.html:381
msgid "Server responded with code: {{statusCode}}"
msgstr "Servern svarade med kod: {{statusCode}}"

And with html tags:

#: templates/index.html:304
#, python-format
msgid ""
"Emulates a SCSI DaynaPORT Ethernet Adapter. <a href=\"%(url)s\">Host "
"drivers and configuration required</a>."
msgstr ""
"Emulerar en SCSI DaynaPORT ethernet-adapter. <a href=\"%(url)s\">Kräver "
"drivrutiner och inställningar</a>."

Contributing to the project

New or updated localizations are treated just like any other code change. See the project README for further information.

(Optional) See translation stats for a localization

Install the gettext package and use msgfmt to see the translation progress.

$ sudo apt install gettext
$ cd python/web/src
$ msgfmt --statistics translations/sv/LC_MESSAGES/messages.po
215 translated messages, 1 untranslated message.