GitLocker: The Coding Marketplace

Description:

djangotenantoptions 2024.8.2

django-tenant-options

[][license]

Empowering Your SaaS Tenants with Custom Options and Sane Defaults
django-tenant-options provides a powerful and flexible way for your SaaS application’s tenants to customize the selectable options in user-facing forms. This package allows you to offer a balance between providing default options—either mandatory or optional—and giving your tenants the freedom to define their own custom choices, all within a structured framework that ensures consistency and ease of use.
Why Use django-tenant-options?
In a SaaS environment, one size doesn't fit all. Tenants often have unique needs for the choices they offer in user-facing forms, but building an entirely custom solution for each tenant - or requiring each tenant to define their own options from scratch - can be complex and time-consuming. django-tenant-options addresses this challenge by offering:

Flexibility: Tenants can tailor the options available in forms to better meet their specific needs.
Control: Provide mandatory defaults to maintain a consistent experience across all tenants, while still allowing for customization.
Scalability: Easily manage multiple tenants with differing requirements without compromising on performance or maintainability.
Simplicity: Avoid the complexity of dynamic models or JSON fields, offering a more structured and maintainable solution.

Key Features

Customizable Options: Allow tenants to define their own sets of values for form input while still offering global defaults.
Mandatory and Optional Defaults: Define which options are mandatory for all tenants and which can be optionally used by tenants in their forms.
Seamless Integration: Designed to work smoothly with your existing Django models, making it easy to integrate into your project.
Tenant-Specific Logic: Built-in support for tenant-specific logic, ensuring that each tenant’s unique needs are met.

Potential Use-Cases
django-tenant-options is versatile and can be applied to a wide range of scenarios across different industries. Here are some examples to illustrate its utility:
1. Project Management for Engineering Firms
Scenario: A Django-based project management tool used by multiple engineering firms.

Tenant Structure: Each engineering firm acts as a tenant, with employees as end-users.
Implementation: The app developer sets mandatory task statuses like "Assigned" and "Completed" for all firms. Each firm can then choose whether to include optional statuses like "In Review" or "Pending Approval," and even create their own unique statuses to fit their workflow. Likewise, the developer can provide mandatory task priorities like "High" and "Low," with firms able to add optional priorities like "Urgent" or "Deferred."

2. HR Management System
Scenario: An HR management system used within a large organization.

Tenant Structure: The HR department is the tenant, and different departments within the organization are the end-users.
Implementation: Mandatory job titles like "Manager" or "Team Lead" are predefined by the developer. The HR department can choose whether to include optional titles that were provided by the developer, and can create custom roles titles specific to their organizational structure.

3. Real Estate Management
Scenario: A property management tool for real estate companies.

Tenant Structure: Real estate companies are tenants, and agents are the end-users.
Implementation: Some property types like "Residential" are mandatorily available to agents in all companies. Companies can choose to make optional property types like "Commercial" available, and can also create custom categories like "Luxury" or "Affordable Housing" to match market segments.

4. Municipal Building Permit Management
Scenario: A system for managing building permits in various municipalities.

Tenant Structure: Municipalities are tenants, and residents or businesses are the end-users.
Implementation: Each municipality has mandatory permit types, required by Federal or State law, but they can also offer optional and custom permit types specific to local regulations.

5. Other Use-Cases
See the options cookbook in the documentation for more inspiration.
Example Implementation
Consider a scenario where your SaaS provides project management tools for businesses. Each User is associated with a Tenant, and can create Tasks. You want each tenant to be able to customize the available task "priorities" and "status" provided in user-facing task tracking forms. Here’s how you can implement this with django-tenant-options.

🟩 Note
See the example project for the more detailed demonstration of how to set up a multi-tenant application with custom options using django-tenant-options.

Existing Models
We will define a very basic Tenant model and a Task model to illustrate the implementation. You can adapt this to your project's models as needed. In this example, it is assumed that the project already has a User model and the User model has a ForeignKey to the Tenant model. Your project's tenant architecture may (and probably will) differ.
from django.contrib.auth import get_user_model
from django.db import models

User = get_user_model()

class Tenant(models.Model):
"""A very simplistic example of how one might implement a Tenant architecture."""
name = models.CharField(max_length=100)
subdomain = models.CharField(max_length=100, unique=True)

def __str__(self):
return self.name

class Task(models.Model):
"""A very simplistic example of a Task model."""

title = models.CharField(max_length=100)
description = models.TextField()
user = models.ForeignKey(User, on_delete=models.CASCADE, related_name="tasks")

Customizable Task Priorities
Each Set of options in django-tenant-options is defined by two models: an Option model, which stores all mandatory, optional, and custom options, and a Selection model, which identifies which options are currently associated with a tenant.
With a Tenant model and a Task model in your project, you can implement the TaskPriorityOption and TaskPrioritySelection models, which inherit from AbstractOption and AbstractSelection respectively.
In each Option model, you can define the default_options dictionary for task priorities or status, including which options are mandatory and which are optional. In this example, "High" and "Low" priorities are mandatory for all tenants (and users will always see these options in forms), while "Critical" and "Medium" priorities are optional for selection by tenants. Tenants can also create custom priorities as needed.
from django.db import models

from django_tenant_options.models import AbstractOption, AbstractSelection
from django_tenant_options.choices import OptionType

class TaskPriorityOption(AbstractOption):
"""Concrete implementation of AbstractOption for TaskPriority."""
tenant_model = "example.Tenant" # Can be defined in settings.py for global use
selection_model = "example.TaskPrioritySelection"
default_options = {
"Critical": {"option_type": OptionType.OPTIONAL},
"High": {"option_type": OptionType.MANDATORY},
"Medium": {"option_type": OptionType.OPTIONAL},
"Low": {}, # If no option_type is provided, it defaults to OptionType.MANDATORY
}

class Meta(AbstractOption.Meta):
verbose_name = "Task Priority Option"
verbose_name_plural = "Task Priority Options"

class TaskPrioritySelection(AbstractSelection):
"""Concrete implementation of AbstractSelection for TaskPriority."""
tenant_model = "example.Tenant" # Can be defined in settings.py for global use
option_model = "example.TaskPriorityOption"

class Meta(AbstractSelection.Meta):
verbose_name = "Task Priority Selection"
verbose_name_plural = "Task Priority Selections"

In each tenant's forms, the "High" and "Low" priorities will always be available for users to select in forms. Each tenant can also choose whether to make "Critical" and "Medium" priorities available to users, and they can create new priorities to meet their needs, offering a balance between predefined options and tenant-specific customization.
Finally, add priority and status ForeignKey fields on the Task model to the TaskPriorityOption and TaskStatusOption models respectively, allowing users to select from the various task priorities available to the tenant they belong to.
from django.contrib.auth import get_user_model
from django.db import models

from example.models import TaskPriorityOption, TaskStatusOption, User

User = get_user_model()

class Tenant(models.Model):
"""A very simplistic example of how one might implement a Tenant architecture."""
name = models.CharField(max_length=100)
subdomain = models.CharField(max_length=100, unique=True)

def __str__(self):
return self.name

class Task(models.Model):
"""A very simplistic example of a Task model with priority and status."""

title = models.CharField(max_length=100)
description = models.TextField()
user = models.ForeignKey(User, on_delete=models.CASCADE, related_name="tasks")

priority = models.ForeignKey(
"example.TaskPriorityOption",
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name="tasks",
)
status = models.ForeignKey(
"example.TaskStatusOption",
on_delete=models.SET_NULL,
null=True,
blank=True,
related_name="tasks",
)

Forms
django-tenant-options provides a set of form mixins and fields to manage the options and selections for each tenant. You can use these forms in your views to allow tenants to customize their options.

OptionCreateFormMixin and OptionUpdateFormMixin are provided to create and update Options.
SelectionForm is used to manage the Selections associated with a tenant.
UserFacingFormMixin is provided to ensures ForeignKey fields to an AbstractOption subclass are populated with the correct tenant Selections.
OptionsModelMultipleChoiceField is a customized ModelMultipleChoiceField that retrieves the Options and also displays the option type associated with each Option.

You are encouraged to extend these Mixins and Fields to suit your project's needs.
from django import forms

from django_tenant_options.forms import OptionCreateFormMixin, OptionUpdateFormMixin, SelectionForm, UserFacingFormMixin
from example.models import Task, TaskPriorityOption, TaskPrioritySelection

class TaskForm(UserFacingFormMixin, forms.ModelForm):
"""Form for creating and updating a Task."""
class Meta:
model = Task
fields = "__all__"

class TaskPriorityOptionCreateForm(OptionCreateFormMixin, forms.ModelForm):
"""Form for creating a TaskPriorityOption."""
class Meta:
model = TaskPriorityOption
fields = "__all__"

class TaskPriorityOptionUpdateForm(OptionUpdateFormMixin, forms.ModelForm):
"""Form for updating a TaskPriorityOption."""
class Meta:
model = TaskPriorityOption
fields = "__all__"

class TaskPrioritySelectionForm(SelectionForm):
"""Form for selecting TaskPriorityOptions."""
class Meta:
model = TaskPrioritySelection

Views, Templates, and URLs
Views, Templates, and URLs can be implemented as needed to allow tenants to manage their options. Views tfor forms that use OptionCreateFormMixin, OptionUpdateFormMixin, and SelectionForm must pass the tenant instance to the form's tenant attribute.
Management Commands
django-tenant-options provides management commands for easy maintenance:

listoptions: Lists all available options in the database.
syncoptions: Synchronizes the default_options in each model with the database when a change in the model has been made. Should always be run after any migrations have been completed.
maketriggers: Creates database trigger migrations to ensure there can never be mismatch between a Tenant and an associated Option.

python manage.py syncoptions

Conclusion
django-tenant-options makes it easy to provide your SaaS application’s tenants with customizable form options, while still maintaining the consistency and control needed to ensure a smooth user experience. Whether you're managing project tasks, HR roles, marketplace filters, or any other customizable value sets, this package offers a robust solution.
Explore the full documentation for more details and start empowering your tenants today!