Metadata-Version: 2.4
Name: e3-django-learning-materials
Version: 0.3.0
Summary: A bilingual learning materials CMS for Django — create, manage, and serve articles, videos, and PDFs with role-based targeting
Project-URL: Homepage, https://github.com/e3tools/e3-django-learning-materials
Project-URL: Repository, https://github.com/e3tools/e3-django-learning-materials
Project-URL: Bug Tracker, https://github.com/e3tools/e3-django-learning-materials/issues
Author: Andrea Sucre
License-Expression: MIT
License-File: LICENSE
Keywords: bilingual,cms,django,learning,materials,training
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: django>=4.1
Requires-Dist: djangorestframework>=3.14
Requires-Dist: drf-yasg>=1.21
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-django; extra == 'dev'
Description-Content-Type: text/markdown

# e3-django-learning-materials

[![PyPI version](https://img.shields.io/pypi/v/e3-django-learning-materials)](https://pypi.org/project/e3-django-learning-materials/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python versions](https://img.shields.io/pypi/pyversions/e3-django-learning-materials)](https://pypi.org/project/e3-django-learning-materials/)

A bilingual (French/English) learning materials CMS for Django. Create, organize, translate, publish, and serve articles, videos, and PDFs with role-based targeting.

## Installation

```bash
pip install e3-django-learning-materials
```

## Quick Start

### 1. Add to `INSTALLED_APPS`

```python
# settings.py
INSTALLED_APPS = [
    ...
    "rest_framework",
    "e3_learning_materials",
]
```

### 2. Include URLs

```python
# urls.py
from django.urls import include, path

urlpatterns = [
    ...
    path("learning-materials/", include("e3_learning_materials.urls")),
    path("api/learning-materials/", include("e3_learning_materials.api_urls")),
]
```

### 3. Run migrations

```bash
python manage.py migrate e3_learning_materials
```

### 4. Visit `/learning-materials/`

Start creating and managing learning materials.

## Templates

The package ships with a built-in base template (`e3_learning_materials/base.html`) so it works out of the box — no need to provide your own `base.html`.

To use your project's base template instead, set `BASE_TEMPLATE` in your settings:

```python
E3_LEARNING_MATERIALS = {
    'BASE_TEMPLATE': 'my_project/base.html',
}
```

The only requirement is that your base template defines these Django blocks:

- `{% block content %}` — main content area (required)
- `{% block extracss %}` — extra stylesheets (optional)
- `{% block javascript %}` — extra scripts, must include `{{ block.super }}` for jQuery/DataTables (optional)

## Configuration

All settings go in an `E3_LEARNING_MATERIALS` dict in your Django settings:

```python
E3_LEARNING_MATERIALS = {
    # Template extended by all learning-materials templates.
    # Default: "e3_learning_materials/base.html"
    "BASE_TEMPLATE": "myapp/base.html",

    # Dotted path to a permission-check function.
    # The function receives the request and returns True/False.
    # Example: "myapp.utils.is_admin"
    # If None (default), any authenticated user can access.
    "PERMISSION_CALLBACK": "myapp.utils.is_admin",

    # Directory prefix for file uploads under MEDIA_ROOT.
    # Default: "learning_materials"
    "UPLOAD_PATH_PREFIX": "my_uploads",

    # URL namespace used by the package.
    # Default: "e3_learning_materials"
    "URL_NAMESPACE": "e3_learning_materials",
}
```

## Features

### Content Model

| Field | Type | Description |
|-------|------|-------------|
| `title_fr` / `title_en` | CharField | Bilingual titles |
| `summary_fr` / `summary_en` | TextField | Bilingual summaries |
| `body_fr` / `body_en` | TextField | Bilingual body content |
| `category` | ChoiceField | Getting Started, Filing a Grievance, Your Rights, Triage & Processing, Escalation, Reporting Duties, FAQ |
| `content_type` | ChoiceField | Article, Video, PDF |
| `target_roles` | JSONField | Citizen, Facilitator, Village Secretary |
| `languages` | JSONField | French, English |
| `status` | ChoiceField | Draft, Published, Archived |
| `read_time` | CharField | Estimated reading time |
| `file` | FileField | PDF, JPG, PNG, MP4 upload |

### Web UI URLs

| URL | View | Name |
|-----|------|------|
| `/learning-materials/` | List + KPIs | `home` |
| `/learning-materials/data/` | AJAX DataTable data | `data` |
| `/learning-materials/create/` | Create form | `create` |
| `/learning-materials/<pk>/` | Redirect to update | `detail` |
| `/learning-materials/<pk>/update/` | Update form | `update` |
| `/learning-materials/<pk>/delete/` | Delete confirmation | `delete` |

Use with `{% url 'e3_learning_materials:home' %}` (or your configured `URL_NAMESPACE`).

### REST API

| Method | URL | Auth | Description |
|--------|-----|------|-------------|
| `GET` | `/api/learning-materials/` | None | List published materials (filtered by audience) |
| `GET` | `/api/learning-materials/<id>/` | Token | Retrieve a single material |

**Audience filtering:**

```
GET /api/learning-materials/?audience=facilitator
GET /api/learning-materials/?audience=citizen
GET /api/learning-materials/?audience=both
```

### Admin Integration

The `LearningMaterial` model is registered with Django admin with list display, filtering by category/content_type/status, and search.

## Permissions

By default, any authenticated user can access learning materials. Set `PERMISSION_CALLBACK` to restrict access:

```python
# myapp/utils.py
def is_admin(request):
    return request.user.is_staff
```

The callback receives the `request` object and must return `True` (grant access) or `False` (return 403).

## Requirements

- Django >= 4.1
- Django REST Framework >= 3.14
- Python >= 3.10

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## Publishing

See [PUBLISH.md](PUBLISH.md) for instructions on publishing to PyPI.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.

## License

MIT
