You will need notifications, whenever you want to inform a Climate Connect user about something going on on the platform. That might be for example the action of another user (following, commenting, liking). Let's say you already have a model that represents the user action (let's call it UserAction for readability), including its serializer and at least one view and endpoint to create a database entry. Within that view, you will then also trigger the notifications. For this you can follow these steps:

Add your notification type and the corresponding foreign key (pointing to the UserAction model) to this model: backend/climateconnect_api/models/notification.py. If you alter the order of the existing types, you need to do the same in the NOTIFICATION_TYPES array in the frontend frontend/src/components/communication/notifications/Notification.js. Then, adapt the serializer to the model changes you just made: backend/climateconnect_api/serializers/notification.py.

Tipp: Don't forget to make a migrations file using python manage.py makemigrations and then run your migrations using python manage.py migrate whenever you change a model or add a new one. (You might need to run your commands with python3 instead of just python if you have multiple versions installed.)

In the app the UserAction model is in, open backend/[some_app]/utility/notifications.py and write a function. You can name it e.g. create_[notification_type]_notification. This function should create a notifications object and also specify the user(s) that will get the notification. But that alone does not notify the user. For that, you can now create a user notification and e-mail notification (both described below).

In frontend/src/components/communication/notifications/Notification.js, add your notification type to the NOTIFICATION_TYPES array. (Remember the order of types has to match with the NOTIFICATION_TYPES from backend/climateconnect_api/models/notification.py in the backend.)

The user notification is represented by a red circle containing the number of unread notifications next to the bell. The bell is located in the header of the page (only visible for logged-in users). Clicking on it opens a pop-up window showing the notifications in a list. Clicking on an entry on that list should take the user to the origin of the notification. After that, the notification should disappear.

The function you need already exists ready to use: create_user_notification(user, notification). You will find it in: backend/climateconnect_api/utility/notification.py. It takes the user who should be notified and the notifications object as arguments. Simply call it within the function you just created.

Again in frontend/src/components/communication/notifications/Notification.js:
Create the component that will be shown to the user when they click on the bell (if there are any unread notifications). Call it something like [NotificationType]Notification and use the GenericNotification. Then add it to the Notification component.

After the user was shown the new content they were notified about, set the associated notification read so it will no longer be shown to the user. Therefore import from the UserContext:

const { notifications, setNotificationsRead, refreshNotifications } = useContext(UserContext);

The notifications array contains all user notifications. Find the notification you need to set read and hand it to setNotificationsRead, afterward refresh the notifications using refreshNotifications. Also, check for a function that might already exist for that matter. E.g. ProjectPageRoot.js already has handleReadNotifications.

If you want to send a notification via e-mail you will probably want to write your own function suiting your particular use case. In addition to that, you will need a Mailjet template for each available language. At the moment these are English and German. Note that right now a user gets an e-mail every 3 hours max.

Tipp: If you want to temporarily disable that restriction for testing purposes comment out the check_send_email_notification function in the send_email function from /backend/climateconnect_api/utility/email_setup.py:

def send_email(
 [...]
):
> #if not check_send_email_notification(user):
> # return
 [...]

If you don't have access to Mailjet yet ask somebody from the core team to give you access. There are marketing and transactional templates. Transactional (Templates -> Transactional) is probably the right category for you (since marketing templates are more for stuff like newsletters). Each template has its own ID. To find it, open the drop-down menu of 'Save & Publish' and click on 'How to use this template'.

After creating the Templates, add the Template IDs to your .backend_env file:

[TEMPLATE_NAME]_ID='[ID]
[TEMPLATE_NAME]_ID_DE='[ID]'

Then add the new environment variables to the settings file: backend/climateconnect_main/settings.py.

[TEMPLATE_NAME]_ID = env('[TEMPLATE_NAME]_ID')
[TEMPLATE_NAME]_ID_DE = env('[TEMPLATE_NAME]_ID_DE')

Hint: Make sure Mailjets API Keys MJ_APIKEY_PUBLIC and MJ_APIKEY_PRIVATE are also added to your local .backend_env file. (As this file is added to the .gitignore file, it will not be pushed to the GitHub repository and therefore never be published.)

You can also add a placeholder for your newly generated template to backend/local-env-setup.md to keep the documentation up to date: PROJECT_[TEMPLATE_NAME]_ID=<TEMPLATE ID>. (Don't put the actual ID of course. The Mailjet Template IDs should not be published. Even more importantly you should never publish the Mailjet API Keys!)

Then write your email notification function in: backend/[some_app]/utility/email.py. These functions are typically called send_[notification_type]_email. Within this function define all your variables and use them to call send_emailfunction from /backend/climateconnect_api/utility/email_setup.py.

Last you need to adjust the settings of the user profile. You must add an option to receive or not receive the particular notification via e-mail.

Therefore add an boolean field to the UserProfile model, called email_on_[user_action]. You will find the model here: backend/climateconnect_api/models/user.py. Then Add the field to the UserAccountSettingsSerializer of the user model located in this file: backend/climateconnect_api/serializers/user.py. In the corresponding view: UserAccountSettingsView in backend/climateconnect_api/views/settings_views.py. Add the field's name to the 'email_preference_values' array and set the value of the field to the corresponding data in the request, like it is done for the other e-mail settings.

In the frontend/src/components/account/SettingsPage.js add a key-value pair for your field. The key has to match with the UserAccountSettingsView, the text contains the description of the button in the frontend. Store the notification text in frontend/public/texts/settings.json.