Invitation and Registration Backends#

The purpose of the backends is to provide scaffolding for adding and managing users and organizations. The scope is limited to the basics of adding new users and creating new organizations.

While the default backends should suffice for basic implementations, the backends are designed to be easily extended for your specific project needs. If you make use of a profile model or a user model other than auth.User you should extend the relevant backends for your own project. If you’ve used custom URL names then you’ll also want to extend the backends to use your own success URLs.

You do not have to implement these backends to use django-organizations, but they will make user management within accounts easier.

The two default backends share a common structure and interface. This includes methods for sending emails, generating URLs, and template references.

The backend URLs will need to be configured to allow for registration and/or user activation. You can add these by referring to the backend’s get_urls method::

from organizations.backends import invitation_backend

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

Registration Backend#

The registration backend is used for creating new users with new organizations, e.g. new user sign up.

Attributes#

RegistrationBackend.activation_subject#

Template path for the activation email subject. Default:

invitation_subject = 'organizations/email/activation_subject.txt'

RegistrationBackend.activation_body#

Template path for the activation email body. Default:

invitation_body = 'organizations/email/activation_body.html'

RegistrationBackend.reminder_subject#

Template path for the reminder email subject. Default:

reminder_subject = 'organizations/email/reminder_subject.txt'

RegistrationBackend.reminder_body#

Template path for the reminder email body. Default:

reminder_body = 'organizations/email/reminder_body.html'

RegistrationBackend.form_class#

Form class which should be used for activating a user account when registering. Default:

form_class = UserRegistrationForm

Invitation backend#

The invitation backend is used for adding new users to an existing organization.

Attributes#

InvitationBackend.invitation_subject#

Template path for the invitation email subject. Default:

invitation_subject = 'organizations/email/invitation_subject.txt'

InvitationBackend.invitation_body#

Template path for the invitation email body. Default:

invitation_body = 'organizations/email/invitation_body.html'

InvitationBackend.reminder_subject#

Template path for the reminder email subject. Default:

reminder_subject = 'organizations/email/reminder_subject.txt'

InvitationBackend.reminder_body#

Template path for the reminder email body. Default:

reminder_body = 'organizations/email/reminder_body.html'

InvitationBackend.form_class#

Form class which should be used for activating a user account in response to an invitation. Default:

form_class = UserRegistrationForm

Methods#

The primary methods of interest are the invite_by_email method and the get_success_url method.

InvitationBackend.get_success_url()#

This method behaves as expected and returns a URL to which the user should be redirected after successfully activating an account. By default it returns the user to the organization list URL, but can be configured to any URL:

def get_success_url(self):
    return reverse('my_fave_app')

InvitationBackend.invite_by_email(email, sender=None, request=None, **kwargs)#

This is the primary interface method for the invitation backend. This method should be referenced from your invitation form or view and if you need to customize what happens when a user is invited, this is where to do it.

Usage example in a form class:

class AccountUserAddForm(OrganizationUserAddForm):

    class Meta:
        model = OrganizationUser

    def save(self, *args, **kwargs):
        try:
            user = get_user_model().objects.get(email__iexact=self.cleaned_data['email'])
        except get_user_model().MultipleObjectsReturned:
            raise forms.ValidationError("This email address has been used multiple times.")
        except get_user_model().DoesNotExist:
            user = invitation_backend().invite_by_email(
                    self.cleaned_data['email'],
                    **{'domain': get_current_site(self.request),
                        'organization': self.organization})

        return OrganizationUser.objects.create(user=user,
                organization=self.organization)

Note

As the example shows, the invitation backend does not associate the individual user with the organization account, it only creates the user so it can be associated in addition to sending the invitation.

Use additional keyword arguments passed via **kwargs to include contextual information in the invitation, such as what account the user is being invited to join. By default the invitation template requires domain details as per the Django Sites framework so you can provide either a Site object, or craft the domain kwarg as follows:

domain={ “name”: “My Site”, “domain”: “www.example.com” }

InvitationBackend.activate_view(request, user_id, token)#

This method is a view for activating a user account via a unique link sent via email. The view ensures the token matches a user and is valid, that the user is unregistered, and that the user’s entered data is valid (e.g. password, names). User entered data is validated against the form_class.

The view then ensures the user’s OrganizationUser connections are activated, logs the user in with the entered credentials and redirects to the success URL.