Skip to content

getting_started.rst

Latest commit

 

History

History
153 lines (113 loc) · 6.06 KB

getting_started.rst

File metadata and controls

153 lines (113 loc) · 6.06 KB

Getting started

Django-organizations allows you to add multi-user accounts to your application and tie permissions, events, and other data to organization level accounts.

The core of the application consists of three models:

  • An organization model; the group object. This is what you would associate your own app's functionality with, e.g. subscriptions, repositories, projects, etc.
  • An organization user; a through model relating your users to your organization. It provides a convenient link for organization ownership (below) and also a way of storing organization/user specific information.
  • An organization owner. This model links to an organization user who has rights over the life and death of the organization.

You can allow users to invite other users to their organizations and register with organizations as well. This functionality is provided through "backend" interfaces so that you can customize this code or use arbitrary user registration systems.

Installation

First add the application to your Python path. The easiest way is to use pip:

pip install django-organizations

Quickstart Configuration

Note

If however you want to use single-table customized organization models and/or custom organization user models, it may be best to treat Django organizations as a library and not install it in your Django project. See the :ref:`cookbook-advanced` section.

Ensure that you have a user system in place to connect to your organizations.

To install the default models add organizations to INSTALLED_APPS in your settings file.:

INSTALLED_APPS = (
    'django.contrib.auth',
    'organizations',
)

This should work for the majority of cases, from either simple, out-of-the-box installations to custom organization models.

URLs

If you plan on using the default URLs, hook the application URLs into your main application URL configuration in urls.py. If you plan on using the invitation/registration system, set your backend URLs, too:

from organizations.backends import invitation_backend

urlpatterns = [
    url(r'^accounts/', include('organizations.urls')),
    url(r'^invitations/', include(invitation_backend().get_urls())),
]

Registration & invitation

You can specify a different :ref:`invitation backend <invitation-backend>` in your project settings, and the invitation_backend function will provide the URLs defined by that backend. You can do the same with the :ref:`registration backend <registration-backend>`:

INVITATION_BACKEND = 'myapp.backends.MyInvitationBackend'
REGISTRATION_BACKEND = 'myapp.backends.MyRegistrationBackend'

Auto slug field

Django-Organizations relies on django-extensions for the base AutoSlugField. While django-extensions is great, this does require that every project install django-extensions for this one small feature.

If you decide to use the default django-organization models by adding organizations to your INSTALLED_APPS, you can choose a different AutoSlugField. Just specify the full dotted path like so:

ORGS_SLUGFIELD = 'django_extensions.db.fields.AutoSlugField'

While you can specify the source of this class, its interfaces must be consistent, including keyword arguments. Otherwise you will end up generating extraneous and possibly conflicting migrations in your own app. The SlugField must accept the populate_from keyword argument.

Upgrading

Updating Django from a pre-6.0 version to 6.0 or above may result in creating new migrations for custom organization models if you do not already have DEFAULT_AUTO_FIELD set in your project. This is because in Django 6.0 the default field changed from AutoField (with an IntegerField under the hood) to a BigAutoField (with a BigIntegerField under the hood).

This applies to your project and your project migrations, however, so you are free to treat this however you want, e.g. if you want to keep IntegerFields as the field type, configure your project settings as much or separate the database and state operations in the migration (maybe not ideal but safe with regard to your database).

Users and multi-account membership

The key to these relationships is that while an OrganizationUser is associated with one and only one Organization, a User can be associated with multiple OrganizationUsers and hence multiple Organizations.

Note

This means that the OrganizationUser class cannot be used as a UserProfile as that requires a one-to-one relationship with the User class. User profile information is better provided by a profile specific model.

In your project you can associate accounts with things like subscriptions, documents, and other shared resources, all of which the account users can then access.

Views and Mixins

Hooking the django-organizations URLs into your project provides a default set of views for accessing and updating organizations and organization membership.

The included class based views are based on a set of mixins that allow the views to limit access by a user's relationship to an organization and that query the appropriate organization or user based on URL keywords.

Implementing in your own project

While django-organizations has some basic usability 'out-of-the-box', it's designed to be used as a foundation for project specific functionality. The :ref:`view mixins <mixins>` should provide base functionality from which to work for most projects, and the :ref:`cookbook` section provides detailed examples for various integration scenarios.
⚡