Metadata-Version: 2.4
Name: django-phonedir
Version: 0.5.3
Summary: A reusable Django app for a phone directory system.
Project-URL: Homepage, https://github.com/dixonbegay/django-phonedir
Project-URL: Repository, https://github.com/dixonbegay/django-phonedir.git
Project-URL: Issues, https://github.com/dixonbegay/django-phonedir/issues
Author-email: Dixon Begay <dixon@dixon-labs.net>
License: LGPL-3.0-or-later
License-File: LICENSE
Keywords: app,book,company,dir,directory,django,internal,intranet,ldap,phone,phonedir,reusable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 6
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.14
Requires-Dist: django-phonenumber-field>=8.4.0
Requires-Dist: django>=6.0
Requires-Dist: phonenumberslite>=9.0.26
Description-Content-Type: text/markdown

# django_phonedir

A reusable Django app for a phone directory system.

Tested and known to work with Django 5.2 and newer. Tested with Python 3.12 and
newer.

## Requirements
- Python >= 3.14
- [daisyUI](https://daisyui.com/) (only for provided templates)
- Django >= 6.0
- django-phonenumber-field >= 8.4.0
- phonenumberslite >= 9.0.26

## Installation

Install via pip.

```bash
pip install django-phonedir
```

Add to Django settings `INSTALLED_APPS` like so...

```python
INSTALLED_APPS = [
    ...
    "django-phonedir",
    ...
]
```

## URL Paths

By default, there are certain URL paths that are provided to help get you
started. The built-in URL paths and templates can be utilized by adding
`django_phonedir.urls` to your main list of urlpatterns in a urls.py file like
so...

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

urlspatterns = [
    ...
    path("", include("django_phonedir.urls")),
    ...
]
```

You don't have to use these URL paths and associated templates. Below is a
listing of the paths with the associated views and template names.

- Path: `departments`
  - View: DepartmentListView
  - Template Name: department_list
  - Template File: django_phonedir/department_listing.html
- Path: `department/<slug:short_name>/`
  - View: DepartmentDetailView
  - Template Name: department_detail
  - Template File: django_phonedir/department_detail.html
- Path: `search?q=<query>`
  - View: SearchResultsView
  - Template Name: search_results
  - Template File: django_phonedir/search_contact_results.html

## Templates
The templates that are provided require daisyUI version 5.5 or newer, Tailwind version 4 or newer, and Font Awesome version 7.0.1 or newer. You can copy the below and add to your base template file to get started quickly.

```HTML
<!-- DaisyUI + Tailwind CSS -->
<link href="https://cdn.jsdelivr.net/npm/daisyui@5"
      rel="stylesheet"
      type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<!-- Font Awesome for Icons -->
<link rel="stylesheet"
      href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.1/css/all.min.css">
<style>
```

Templates are extending from `"base.html"` and are structured like so.
```django
{% extends "base.html" %}
{% block title %}
Title to be used by base.html
{% endblock title %}
{% block content %}
<div>Content on the page in base.html</div>
{% endblock content %}
```

Views can still be utilized from this library and templates can be overriden in your Django application by creating a folder in a templates folder called `django_phonedir` and creating your own HTML files with the same name of the template that is used by that particular view. This way you can still utilize the views in this library and override the templates to change how the data is displayed.

## Models

To use a model, import from `django_phonedir.models` like so...
```
from django_phonedir.models import Department, FaxNumber, Contact
```

Below is a listing of each model, their attributes, and description for each attribute..

### Department

- name : Name of the department.
- short_name : Short name that is used in the URL.
- supervisor : Foreign key that points to a user (typically the supervisor).

### FaxNumber

- department : Foreign key that points to a Department model.
- description : Description of the fax number.
- phone : PhoneNumberField
- location: Location of fax number.

### Contact

- department : Foreign key that points to a Department model.
- first_name : First name.
- last_name : Last name.
- title : Job title.
- extension : Phone extension.
- location : location of the contact.
- phone : PhoneNumberField (can be blank.)

## Development

Better documentation will be provided at a later date.

### Setup

Use pipenv for managing the package requirements for development.

```bash
pipenv install --dev
```

### Testing

Tests can be run using the command below.
```bash
pipenv run test
```
