Redesigned README for dj-multidomain

---

dj-multidomain

Dynamic Multi-Domain Middleware for Django

dj-multidomain is a powerful Django middleware that enables dynamic routing of requests to different URL configurations based on the domain of incoming requests. It also supports automatic redirection for specific domains and provides options for shared common URLs. This middleware is ideal for projects hosted across multiple domains or with subdomain-specific functionalities.

Developed by Ferhat Mousavi. ferhat.mousavi@gmail.com

---

Features

• Domain-Based URL Routing: Route requests to different URL configurations based on the domain.
• Subdomain Handling: Easily manage subdomains and inject subdomain data into requests.
• Automatic Redirects: Redirect specific domains to desired ones seamlessly.
• Shared URLs: Define common URLs accessible across all domains.
• Fallback Support: Set a default domain for unrecognized requests (DEBUG mode).

---

Installation

1. Install the Package

Install dj-multidomain using pip:

pip install dj-multidomain

Ensure publicsuffix2 is also installed:

pip install publicsuffix2

2. Add Middleware

In your settings.py, add the middleware to the MIDDLEWARE list:

MIDDLEWARE = [
    ...
    'dj_multidomain.middleware.MultipleDomainMiddleware',
    ...
]

---

Configuration

1. Map Domains to URL Configurations

Use MULTI_DOMAIN_CONFIG to map domains to their respective URL configuration files. Add this to settings.py:

MULTI_DOMAIN_CONFIG = {
    'example.com': 'project.urls_example_com',
    'example.org': 'project.urls_example_org',
}

2. Redirect Domains (Optional)

If you want to redirect specific domains to others, use MULTI_REDIRECT_CONFIG:

MULTI_REDIRECT_CONFIG = {
    'www.example.com': 'example.com',
    'oldsite.org': 'newsite.org',
}

3. Add Common URLs (Optional)

Define shared URLs that are accessible from any domain using COMMON_URLS:

COMMON_URLS = 'project.urls_common'

4. Subdomain Configuration (Optional)

If subdomain data needs to be injected into requests, use MULTI_SUBDOMAIN_CONFIG to define parameter names:

MULTI_SUBDOMAIN_CONFIG = ['subdomain1', 'subdomain2']

5. Default Domain (Optional)

Set a fallback URL configuration for unrecognized domains (only active in DEBUG mode):

DEFAULT_DOMAIN = 'example.com'

---

Example Project Structure

Below is a typical project structure for dj-multidomain:

project/
├── project/
│   ├── __init__.py
│   ├── settings.py
│   ├── urls_common.py
│   ├── urls_example_com.py
│   ├── urls_example_org.py
│   ├── views.py
├── manage.py

---

Example Usage

1. Domain-Specific URL Configuration

Create domain-specific URL files, e.g., urls_example_com.py:

from django.urls import path
from . import views

urlpatterns = [
    path('', views.home, name='home'),
    path('about/', views.about, name='about'),
]

2. Common URL Configuration

Define shared URLs in urls_common.py:

from django.urls import path
from . import views

urlpatterns = [
    path('contact/', views.contact, name='contact'),
]

3. Subdomain Handling

Subdomains will be available as attributes in the request object. For example:

def subdomain_example(request):
    subdomain1 = getattr(request, 'subdomain1', None)
    return HttpResponse(f"Subdomain 1: {subdomain1}")

---

Sample Configuration

Here’s a complete example of settings.py for dj-multidomain:

MIDDLEWARE = [
    ...
    'dj_multidomain.middleware.MultipleDomainMiddleware',
    ...
]

MULTI_DOMAIN_CONFIG = {
    'example.com': 'project.urls_example_com',
    'example.org': 'project.urls_example_org',
}

MULTI_REDIRECT_CONFIG = {
    'www.example.com': 'example.com',
}

MULTI_SUBDOMAIN_CONFIG = ['subdomain1', 'subdomain2']

COMMON_URLS = 'project.urls_common'

DEFAULT_DOMAIN = 'example.com'

---

Supported Versions

• Python: 3.10 and above
• Django: 4.0 and above

---

Sample Project

Explore a sample implementation:
GitHub: dj-multidomain Example

---

Contribution & Support

• For issues or feedback, open an issue in the GitHub repository.
• Contributions are welcome! Feel free to submit a pull request.

---

License

This project is licensed under the GNU General Public License v3 (GPLv3).