<commit_before>
=====
Usage
=====

Integrating notification support into your app is a simple three-step process.

  * create your notice types
  * create your notice templates
  * send notifications

Creating Notice Types
=====================

You need to call ``create_notice_type(label, display, description)`` once to
create the notice types for your application in the database. ``label`` is just
the internal shortname that will be used for the type, ``display`` is what the
user will see as the name of the notification type and `description` is a
short description.

For example::

    notification.create_notice_type("friends_invite", "Invitation Received", "you have received an invitation")

One good way to automatically do this notice type creation is in a
``management.py`` file for your app, attached to the syncdb signal.
Here is an example::

    from django.conf import settings

    if "notification" in settings.INSTALLED_APPS:
        from notification.models import create_notice_type
    
        def create_notice_types(app, created_models, verbosity, **kwargs):
            create_notice_type("friends_invite", "Invitation Received", "you have received an invitation")
            create_notice_type("friends_accept", "Acceptance Received", "an invitation you sent has been accepted")
    
        signals.post_syncdb.connect(create_notice_types, sender=notification)
    else:
        print "Skipping creation of NoticeTypes as notification app not found"

Notice that the code is wrapped in a conditional claus so if
django-notification is not installed, your app will proceed anyway.


Notification templates
======================

There are four different templates that can to be written for the actual content of the notices:

  * ``short.txt`` is a very short, text-only version of the notice (suitable for things like email subjects)
  * ``full.txt`` is a longer, text-only version of the notice (suitable for things like email bodies)
  * ``notice.html`` is a short, html version of the notice, displayed in a user's notice list on the website
  * ``full.html`` is a long, html version of the notice (not currently used for anything)

Each of these should be put in a directory on the template path called ``notification/<notice_type_label>/<template_name>``.
If any of these are missing, a default would be used. In practice, ``notice.html`` and ``full.txt`` should be provided at a minimum.

For example, ``notification/friends_invite/notice.html`` might contain::
    
    {% load i18n %}{% url invitations as invitation_page %}{% url profile_detail username=invitation.from_user.username as user_url %}
    {% blocktrans with invitation.from_user as invitation_from_user %}<a href="{{ user_url }}">{{ invitation_from_user }}</a> has requested to add you as a friend (see <a href="{{ invitation_page }}">invitations</a>){% endblocktrans %}
<commit_msg>Fixes a typo in the docs<commit_after>
=====
Usage
=====

Integrating notification support into your app is a simple three-step process.

  * create your notice types
  * create your notice templates
  * send notifications

Creating Notice Types
=====================

You need to call ``create_notice_type(label, display, description)`` once to
create the notice types for your application in the database. ``label`` is just
the internal shortname that will be used for the type, ``display`` is what the
user will see as the name of the notification type and `description` is a
short description.

For example::

    notification.create_notice_type("friends_invite", "Invitation Received", "you have received an invitation")

One good way to automatically do this notice type creation is in a
``management.py`` file for your app, attached to the syncdb signal.
Here is an example::

    from django.conf import settings

    if "notification" in settings.INSTALLED_APPS:
        from notification.models import create_notice_type
    
        def create_notice_types(app, created_models, verbosity, **kwargs):
            create_notice_type("friends_invite", "Invitation Received", "you have received an invitation")
            create_notice_type("friends_accept", "Acceptance Received", "an invitation you sent has been accepted")
    
        signals.post_syncdb.connect(create_notice_types, sender=notification)
    else:
        print "Skipping creation of NoticeTypes as notification app not found"

Notice that the code is wrapped in a conditional clause so if
django-notification is not installed, your app will proceed anyway.

Notification templates
======================

There are four different templates that can to be written for the actual content of the notices:

  * ``short.txt`` is a very short, text-only version of the notice (suitable for things like email subjects)
  * ``full.txt`` is a longer, text-only version of the notice (suitable for things like email bodies)
  * ``notice.html`` is a short, html version of the notice, displayed in a user's notice list on the website
  * ``full.html`` is a long, html version of the notice (not currently used for anything)

Each of these should be put in a directory on the template path called ``notification/<notice_type_label>/<template_name>``.
If any of these are missing, a default would be used. In practice, ``notice.html`` and ``full.txt`` should be provided at a minimum.

For example, ``notification/friends_invite/notice.html`` might contain::
    
    {% load i18n %}{% url invitations as invitation_page %}{% url profile_detail username=invitation.from_user.username as user_url %}
    {% blocktrans with invitation.from_user as invitation_from_user %}<a href="{{ user_url }}">{{ invitation_from_user }}</a> has requested to add you as a friend (see <a href="{{ invitation_page }}">invitations</a>){% endblocktrans %}

{'fraction_non_alphanumeric': 0.0959779043673399, 'fraction_numerical': 0.0006904885206283445, 'mean_word_length': 4.533906399235912, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2170553', 'n_tokens_mistral': 1511, 'n_tokens_neox': 1460, 'n_words': 691}