django-hunger Documentation

Contents:

Quickstart

Installation and Basic Configuration

  • Install django-hunger using pip or easy_install.

  • Add hunger to INSTALLED_APPS in settings.py.

  • Add hunger.middleware.BetaMiddleware to MIDDLEWARE_CLASSES.

  • Add url(r'hunger', include('hunger.urls')) to your urlconf.

  • List views that all users may see at any time regardless of beta status in the setting HUNGER_ALWAYS_ALLOW_VIEWS and HUNGER_ALWAYS_ALLOW_MODULES. The views setting accepts views by function name or urlpattern name, while the modules accepts a string module name where all included views are always allowed. Typically, you at least want to let people register, login, and recover password, so include the auth urls:

    HUNGER_ALWAYS_ALLOW_MODULES = [
        'django.contrib.auth.views'
    ]
    
  • Create template hunger/not_in_beta.html, which is the page a user is redirected to when trying to access protected content when not in the beta.

  • Create template hunger/verified.html, which is the page after the user successfully has joined and verified their in-beta status.

  • Create template hunger/invalid.html, which is the page a user sees when they try to use a code but it is invalid. It could be a code that doesn’t exist or one that has run out of invites.

  • [Optional] Create template hunger/invite_sent.html, which is the page a user sees after sending invites to other people. You don’t need this if you only want to allow admins and staff to send invites.

  • Create the email template hunger/invite_email.[html/txt] and email subject template hunger/invite_email_subject.txt. These templates are rendered like Django templates with a simple context described in hunger/email.py. To ensure the best user experience, you should provide both the html and txt email templates. Example versions of these templates are in example/example/templates/hunger/.

Advanced Configuration

The basic configuration basically involves creating a bunch of static templates for various pre-configured views. For a more advanced configuration, you can let hunger use your own urls, views, and templates using custom redirect settings. All redirect targets must be valid targets for the built-in django.shortcuts.redirect function.

  • HUNGER_REDIRECT for users accessing protected content while not in the beta.
  • HUNGER_VERIFIED_REDIRECT for the page a user sees after successfully joining and verifying in-beta status.
  • HUNGER_INVITE_SENT_REDIRECT for the page a user sees after sending invites to others.
  • HUNGER_EMAIL_TEMPLATES_DIR for a different directory holding the invite email templates.
  • HUNGER_EMAIL_INVITE_FUNCTION for a different function to call when sending email invites. Takes precedence over HUNGER_EMAIL_TEMPLATES_DIR.

Integration with django_templated_email

If django_templated_email is installed, you can use a customized *.email template for beta invites.

And create the following template:

<project_dir>/templates/hunger/invite_email.email

User Flow

Cases

  1. User is unregistered
    • Can only visit views listed in HUNGER_ALWAYS_ALLOW_VIEWS or views in modules listed in HUNGER_ALWAYS_ALLOW_MODULES. The views list may refer to the view by the view’s function name or urlpattern name.
    • All other urls redirect to HUNGER_REDIRECT.
    • If registration view is listed above, then the user can register for an account that doesn’t yet have beta access.
    • If invited by a friend by receiving an email with a beta invite link, then the code is stored in a cookie. When the user registers, then they are automatically placed into the beta.
    • If registering via a public beta code, the code is similarly placed in a cookie, where later registration will place the user automatically in the beta and the invitation code count decrements by 1.
  2. User is registered but not in beta
    • An admin can invite that specific user to the beta through the Django admin interface.
    • The user can be invited by another beta who has beta access, provided that the inviter has enough invitations to send the invitation. The user clicks a link.
    • The user can join the beta themselves by using a public beta code as long as the code has enough uses left.
    • Upon being verified as in-beta, the user is redirected to HUNGER_VERIFIED_REDIRECT.
  3. User is registered and in beta
    • An admin can dispense invitations so that users can invite their friends.
    • Invitations in hand, the user invites friends via either email or their username if applicable.
    • Otherwise, allow user to invite friends at-will.

Trying the Example App

Clone the repo and run the included example django project:

git clone git://github.com/joshuakarjala/django-hunger.git
cd django-hunger/example
pip install -r requirements.txt
python manage.py syncdb
python manage.py runserver

Guide

The example app utilizes a basic configuration with django-registration for verifying emails. Therefore the list of views in HUNGER_ALWAYS_ALLOW_VIEWS utlizes the registration_* views instead of django.contrib.auth.views for registration.

Note that the email backend being used in the example is the console backend, meaning that all emails are printed to the console.

Once the example project is running, registering an ordinary user will result in the creation of the account + activation through email. After registration, the standard user does not have beta access and will be restricted.

To grant beta access to the created user, simply sign into the admin site at /admin/, click on Invitations, and invite the invitation corresponding to the registered user via the admin actions menu.

Signing in as the original user will result in being able to access protected beta content.

Upgrading to Version 2

Version 2 of Hunger is very different from v1. In v1 of the app, the private beta phase was a pre-registration phase, meaning that it operated by limiting access to registration until a user is invited to the beta. In v2, the private beta becase a post-registration phase, meaning that all users are allowed to register, but limiting access to the rest of the site.

Due to the drastic differences between the two versions, there will be no upgrade path between the two versions. However, for all future upgrades, South migrations will be provided.

Overview

  • Three ways to get into the beta.

    1. Users self-signup for the beta. An admin can choose to invite them at any time.
    2. An admin can grant in-beta users with a limited number of invites to invite their friends.
    3. An admin can create a limited number public beta code that anybody can use to join the beta. Useful for press releases.
  • Hunger is a post-registration app, meaning the intended behavior is to let users sign up freely, but restrict the rest of the site to beta participants. This makes it easy to integrate with social login and user management apps.

  • Email as the method of choice for communication. Emails are used to send people their invites.

  • Flexible design with many entry points for customization of default behavior.

  • TODO: Tracking and user analytics for the beta phase. Want to know which users are the most excited about your site? Find out by analyzing the invite graph.

Quickstart

To get started, see Quickstart.

Indices and tables