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 (only for provided templates)
• Django >= 6.0
• django-phonenumber-field >= 8.4.0
• phonenumberslite >= 9.0.26

Installation

Install via pip.

pip install django-phonedir

Add to Django settings INSTALLED_APPS like so...

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...

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.

<!-- 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.

{% 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.

pipenv install --dev

Testing

Tests can be run using the command below.

pipenv run test