Quick Start

This section provides a fast and easy guide to getting the dj-announcement-api package up and running in your Django project. Follow the steps below to quickly set up the package and start using it.

1. Install the Package

Option 1: Using `pip` (Recommended)

Install the package via pip:

$ pip install dj-announcement-api

Option 2: Using `Poetry`

If you’re using Poetry, add the package with:

$ poetry add dj-announcement-api

Option 3: Using `pipenv`

If you’re using pipenv, install the package with:

$ pipenv install dj-announcement-api

The package requires djangorestframework for API support. If it’s not already installed in your project, you can install it using one of the above methods:

Using pip:

$ pip install djangorestframework

2. Add to Installed Apps

After installing the necessary packages, ensure that both rest_framework and django_announcement are added to the INSTALLED_APPS in your Django settings.py file:

INSTALLED_APPS = [
    # ...
    "rest_framework",  # Required for API support
    "django_announcement",
    # ...
]

3. (Optional) Configure API Filters

To enable filtering of announcements through the API, install django-filter, include django_filters in your INSTALLED_APPS and configure the filter settings.

Install django-filter using one of the above methods:

Using pip:

$ pip install django-filter

Add django_filters to your INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django_filters",
    # ...
]

Then, set the filter class configuration in your settings.py:

DJANGO_announcement_API_FILTERSET_CLASS = (
    "django_announcement.api.filters.announcement_filter.AnnouncementFilter"
)

You can also define your custom FilterClass and reference it in here if needed. This allows you to customize the filtering behavior according to your requirements.

4. Apply Migrations

Run the following command to apply the necessary migrations:

python manage.py migrate

5. Add Announcement API URLs

Include the announcement API routes in your project’s urls.py file:

from django.urls import path, include

urlpatterns = [
    # ...
    path("announcement/", include("django_announcement.api.routers")),
    # ...
]

6. Generate Audiences and Profiles

After setting up the package and applying the migrations, run the management commands to generate the necessary audiences based on user related models and generate announcement profiles for users to assign audience to them.

First, generate the audiences using the generate_audiences command:

$ python manage.py generate_audiences

Then, assign users to these audiences by running the generate_profiles command:

$ python manage.py generate_profiles

7. Create Announcements via Django Admin

Now, you can create announcements using the Django admin interface.

Log in to the Django admin site.
Navigate to the Announcements section.
Click Add Announcement to create a new announcement, filling out the required fields such as title, content and category.
Optionally, select the target audiences and attach files if needed.

Once saved, your announcements will be available to the users assigned to the relevant audiences.

8. Verify Announcements

Once announcements are created, they can be viewed through the API endpoints. To test and verify the creation, make a request to the relevant endpoint, for example:

curl -X GET http://localhost:8000/announcement/annoucements/

This will return a list of announcements created in the admin.

With the setup complete, the dj-announcement-api is ready for use in your project. For further customizations and settings, refer to the API Guide and Settings sections.