pinax-referrals

To install pinax-referrals, use pip to install the package, add it to your INSTALLED_APPS, configure the middleware, and include the URLs in your project's URL configuration.

1. Install the package:

   pip install pinax-referrals

2. Update INSTALLED_APPS:

   INSTALLED_APPS = [
       # other apps
       "pinax.referrals",
   ]

3. Configure Middleware: Add pinax.referrals.middleware.SessionJumpingMiddleware to your MIDDLEWARE setting. It must be placed after django.contrib.auth.middleware.AuthenticationMiddleware to correctly link users who register/authenticate after clicking a referral link.

   MIDDLEWARE = [
       # other middleware
       "django.contrib.auth.middleware.AuthenticationMiddleware",
       "pinax.referrals.middleware.SessionJumpingMiddleware",
   ]

4. Include URLs: Add pinax.referrals.urls to your urlpatterns using a namespace.

   urlpatterns = [
       # other urls
       url(r"^referrals/", include("pinax.referrals.urls", namespace="pinax_referrals")),
   ]

Modify the default behavior of pinax-referrals using the following settings:

create_referral

Use this tag to render a form that allows users to generate a referral link. The form is designed for AJAX submission and returns JSON.

Usage:

{% load pinax_referrals_tags %}

{# To link to a specific object: #}
{% create_referral object.get_absolute_url object %}

{# To link to a specific URL: #}
{% url my_named_url as myurl %}
{% create_referral myurl %}

Recommended JavaScript (using jquery.form):

$(function () {
    $('form.referral').each(function(i, e) {
        var form = $(e);
        var options = {
            dataType: "json",
            success: function(data) {
                form.html('<input type="text" value="' + data.url + '" />');
                form.find("input[type=text]").select();
            }
        };
        form.ajaxForm(options);
    });
});

referral_responses

An assignment tag that sets a context variable to a queryset of all responses for all referrals owned by a specific user, ordered by creation date.

Usage:

{% load pinax_referrals_tags %}
{% referral_responses user as responses %}

{% for response in responses %}
    {# response is a ReferralResponse object #}
{% endfor %}

action_display filter

Converts a response action code into user-friendly text based on the PINAX_REFERRALS_ACTION_DISPLAY setting.

Usage:

{% load pinax_referrals_tags %}
<p>{{ response.action|action_display }}</p>

Use Referral.record_response to track specific actions taken by a user after they have interacted with a referral link. This method checks the current request (user or session) for existing referral responses and records the new action.

Parameters:

• request: The current HTTP request.
• action: A string label for the action being performed.
• target (optional): A keyword argument to associate the response with a specific object (using a generic foreign key).

Returns:

• A ReferralResponse object if a response was recorded.
• None if the user/session has no previously recorded referral context.

Example: Recording a specific site action:

from pinax.referrals.models import Referral

def my_view(request, **kwargs):
    # Records the action 'SOME_ACTION' for the current user/session
    referral_response = Referral.record_response(request, "SOME_ACTION")
    
    # Recording an action associated with a specific object
    referral_response_with_target = Referral.record_response(
        request, 
        "SOME_ACTION", 
        target=some_object
    )

The Referral.create factory method creates a new referral instance. It can be used directly for custom integrations, such as automatically assigning a referral code to a user upon signup.

Parameters:

• redirect_to (required): The URL where the user should be redirected.
• user (optional): The user associated with the referral. If omitted, it is recorded as None.
• label (optional): A keyword argument to allow users to manage multiple referrals by giving them names.

Example: Assigning a referral to a user profile via a signal:

from pinax.referrals.models import Referral
from django.urls import reverse

# Inside a signal receiver or similar logic
referral = Referral.create(
    user=profile.user,
    redirect_to=reverse("home")
)
profile.referral = referral
profile.save()

Template Usage: To display the referral URL in a template:

{{ user.get_profile.referral.url }}

Dynamic Redirection: You can append a redirect_to query parameter to the referral URL at runtime to change the destination:

{{ user.get_profile.referral.url }}?redirect_to=/special/