utnkar / bocken

A digital journal system for UTN's car Bocken

Bocken

A digital journal system for UTN's car Bocken.

Installing

1. Install Python 3, at least version 3.8 or up.
2. Install NodeJs and npm (npm is included in the nodejs installation). This is needed for tailwind.
3. Install the following packages
   • Python virtual environment
     • Ubuntu: sudo apt install python3-venv
     • Mac: brew install virtualenv
     • Windows: pip install virtualenv
   • GNU gettext:
     • Ubuntu: sudo apt install gettext
     • Mac: brew install gettext
     • Windows: Download gettext here
4. Clone the repository.
5. Run source ./source_me.sh to create a virtual environment.
6. Run pip install -r dev-requirements.txt
7. Use cd src to enter the website directory.
8. Run ./manage.py tailwind install to install tailwind
9. Run ./manage.py migrate to initialize the database.
10. Run ./manage.py compilemessages to create all translations
11. Run ./manage.py createsuperuser to create an admin user that you will use to log in to the admin pages.

The journal system is now installed!

During development, you need to use two terminals. Dont forget to run source ./source_me.sh in both terminals before running these commands!

1. In one run the command ./manage.py runserver to start the django server.
2. In the other run ./manage.py tailwind start to start tailwind.

You can now visit the journal system on http://localhost:8000.

Troubleshooting

The styles from tailwind is not loading in the browser

If the styles from tailwind are not loading in the browser, (a.k.a. the css file gets error 404), stop the command that runs the server (./manage.py runserver) and then restart it.

This is because django must be restarted when new static files are added which can happen if the django server is started before the tailwind command (which creates the css file for tailwind).

Documentation

Documentation for the journal system can be found on docs.utn.se

Testing

All code in this repository is tested in two ways: we use Django test suites and we run the flake8 style enforcer. Together they can promote clean and good code.

These tests are run automatically using Github Actions. If, however, you want to run these tests locally you can run the following commands in the project root directory:

• ./src/manage.py test src - to test with our Django test suites
• flake8 src - to run the flake8 style enforcer

Translating

The journal system for Bocken intends to be multilingual. The web application is available in both Swedish and English. Whenever any translatable text is added or changed it should be translated using translation files.

To create or edit translations:

1. cd src/
2. ./manage.py makemessages -l sv
3. This will create or update the files under src/bocken/locale/.
4. Edit the translations in your editor
5. Run ./manage.py compilemessages for the changes to take effect

Tailwind

The journal system uses a css framework for the frontend called Tailwind and it is installed via the pip package django-tailwind. Tailwind adds a bunch of css classes that do only one thing. For example the class bg-red-400 adds a red background, the 400 is one of the predefined red colors that tailwind offers. The idea of tailwind is that instead of creating a bunch of css classes with many attributes, you add these classes on the HTML elements directly and thus not having to write any own css.

All tailwind documentation and classes can be found on their website.

It should be noted that it is not used in the admin pages since those pages uses their own predefined styling

bocken's Issues

Apply a clear mark when a gap occurs

In the admin pages, it would be good if gaps were automatically highlighted between journal entries that create a gap

Remove blank on email

Email should be null but not blank since blank only affects form validation

bocken/src/bocken/models/agreement.py

Line 43 in d8755eb

blank=True,

Add link to /add on home page

Whenever I go to my phone to log a hot new driving sesh I enter "boc" into my phone's browser and press the first suggestion that comes up. This brings me to bocken.utn.se. I then get frustrated that I have to press the URL bar again and append /add to it.

Wouldn't it be nice to add a shortcut/button on the home page along the lines of "Looking to add an entry? Press here!", just to make it easier for simpletons like me?

Create a journal entry form

This form will be used by those who drive bocken when they report how far they have driven. It should be possible to enter:

• your name,
• agreement number,
• the mile tracker when you started and ended,
• which committee, workgroup or other organ within UTN you drive for.
• A checkbox that you verify that bocken is in good shape for the next driver

Create a form for finding your agreement number

Many people forget their agreement number. There for it would be good with a form when you can enter your personnummer and it shows your agreement number

Make email not allowed to be blank on agreements when all agreements have an email

The agreement model has an email field that has blank=True. This is because when this system was created, emails were not collected so not all agreements have emails. When all agreements have an email this should be removed so that email is required.

When this is changed, the email field in the AgreementForm in forms.py can be removed

Ask the klubbmästare if all the old agreements in their folder in their desk have been removed and check in the admin pages on the production server if all users have an attached agreement

Error occurs when you visit the reports in the admin view

When you go the page where you see all reports in the admin view and you have no previous reports have been created you encounter an error. The error is caused by this function:

bocken/src/bocken/models/journal_entry.py

Lines 92 to 95 in ba0ec47

	latest_report = report.Report.get_latest_report()
	entries = JournalEntry.objects.exclude(
	created__lte=latest_report.created
	)

The code doesn't handle the case when there is no latest report

Create a report view in the admin pages

In the admin pages, there should be a view where a report can be generated. This report will show how many kilometers each committee or workgroup has driven and how much they must pay

Add tailwind steps to installation instructions

When you install bocken you need to perform two tailwind commands which aren't written down in the README

django-cron is deprecated

The package for handling cron jobs (django-cron) has been deprecated and will not support django 4. It has to be exchanged for django-extentions which provides the same functionality and is currently being maintained

Change get latest by on journal entries

If one person forgets to add a journal entry and another creates one i.e. creating a gap, if a new journal entry is added to fix the gap it gets created after the previous and the order becomes wrong.

This is because journal entries have their get_latest_by set to created which becomes completely wrong. This needs to be changed to meter_stop. The sorting should also be changed to this

Total kilometers not updated on invalid submissions

If an invalid submission is made in the journal entry create form the total kilometers displays 0 when the page is reloaded. It should show the total kilometers

Instructions for new bocken avtal needs numbers

Make agreement file not blank when everyone has an agreement

Currently all agreement files are allowed to be blank since there are people who have signed the old agreement when the system was created. Instead of having them resign their agreements, those agreements will continue to live in their folder on klubbmästarens desk. Therefor the field is blank. When every user has an agreement file, blank=True can be removed.

The agreement_file field can also be removed from the AgreementForm in forms.py

Ask the klubbmästare if all the old agreements in their folder in their desk have been removed and check in the admin pages on the production server if all users have an attached agreement