Patrick Samson committed cbaa2d9

updated for the version 2.0.0 to come

  • Participants
  • Parent commits 7db4321

Comments (0)

Files changed (9)

+== API ==
+For an easier usage of the application from other applications in the project,
+an API is provided.
+=== pm_broadcast() ===
+Broadcast a message to multiple Users.
+For an easier cleanup, all these messages are directly marked as archived and deleted on the sender side.
+Arguments: (sender, recipients, subject, body='', skip_notification=False)
+=== pm_write() ===
+Write a message to a User.
+Contrary to pm_broadcast(), the message is archived and/or deleted on the sender side only if requested.
+Arguments: (sender, recipient, subject, body='', skip_notification=False, auto_archive=False, auto_delete=False)
+=== Arguments ===
+* {{{auto_archive}}}: to mark the message as archived on the sender side
+* {{{auto_delete}}}: to mark the message as deleted on the sender side
+* {{{body}}}: the contents of the message
+* {{{recipient}}}: a User instance
+* {{{recipients}}}: a list or tuple of User instances, or a single User instance
+* {{{sender}}}: a User instance
+* {{{skip_notification}}}: if the normal notification event is not wished
+* {{{subject}}}: the subject of the message
+=== Example ===
+Suppose an application managing Event objects. Whenever a new Event is generated,
+you want to broadcast an announcement to Users who have subscribed
+to be informed of the availability of such a kind of Event.
+Code sample:
+from postman.api import pm_broadcast
+events = Event.objects.filter(...)
+for e in events:
+	pm_broadcast(
+		recipients=e.subscribers,
+		subject='New {0} at Our School: {1}'.format(e.type, e.title),
+		body=e.description)
+<-//[[Management Commands|Previous]]// //[[Home]]// //[[Frequently Asked Questions|Next]]//->
-<a href="{% url postman_write username %}">write to {{ username }}</a>
+<a href="{% url 'postman_write' username %}">write to {{ username }}</a>
 Separate multiple usernames with a {{{:}}} character.
-<a href="{% url postman_write 'adm1:adm2:adm3' %}">write to admins</a>
+<a href="{% url 'postman_write' 'adm1:adm2:adm3' %}">write to admins</a>
 === Prefilled fields ===
-<a href="{% url postman_write %}?subject=details request&body=give me details about ...">
+<a href="{% url 'postman_write' %}?subject=details request&body=give me details about ...">
 ask for details
     exchange_filter = staticmethod(my_exchange_filter)
-== Auto-complete field ===
+=== Auto-complete field ===
 An auto-complete functionality may be useful on the recipients field.
 To activate the option, set at least the {{{arg_default}}} key in the
-{{{POSTMAN_AUTOCOMPLETER_APP}}} dictionary.  If the default ajax_select application is used,
+{{{POSTMAN_AUTOCOMPLETER_APP}}} dictionary.  If the default {{{ajax_select}}} application is used,
 define a matching entry in the {{{AJAX_LOOKUP_CHANNELS}}} dictionary.
+**In case of version 1.1.4/5 of django-ajax-selects:**
 Support for multiple recipients is not turned on by default by django-ajax-selects.
-To allow this capability, you have to pass the option {{{multiple: true}}}.
+To allow this capability, you have to pass the option {{{multiple: true}}} to jquery-plugin-autocomplete.
 Make your own templates, based on these two files, given as implementation examples:
-* postman/templates/autocomplete_postman_multiple.html
-* postman/templates/autocomplete_postman_single.html
+* postman/templates/autocomplete_postman_multiple_as1-1.html
+* postman/templates/autocomplete_postman_single_as1-1.html
-These examples include a correction necessary for the support of the 'multiple' option
-(in version 1.1.4 of django-ajax-selects).
+These examples include a correction necessary for the support of the 'multiple' option.
+**In case of version 1.2.x of django-ajax-selects:**
+Refer to the installation guide of this application, in particular the use of AJAX_SELECT_BOOTSTRAP
+Support for multiple recipients is not as simple as an option: see the examples in the
+[[|jQuery UI demos]].
+The directory {{{postman/templates/}}} doesn't currently provide any examples for this version.
 ==== Customization ====

-<-//[[Management Commands|Previous]]// //[[Home]]//
+<-//[[API|Previous]]// //[[Home]]//
 This is an application for [[|Django]]-powered websites.
 Available translations are:
-|Arabic - ar [9%.....]                                  |German - de [..57%...]
-|Chinese - zn_CN [.....100%] (到Gene Woo感谢)              |Italian - it [.....94%] (Grazie a Yohan Boniface)
+|Arabic - ar [9%.....]                                  |German - de [.....100%] (Dankeschön an 'lonelycowboy')
+|Chinese - zh_CN [.....100%] (到Gene Woo感谢)              |Italian - it [.....94%] (Grazie a Yohan Boniface)
+|Chinese - zh_TW [.....100%] (到Leonard Huang感谢)         |Persian - fa_IR [....87%.]
 |Danish - da [.32%....]                                 |Polish - pl [....86%.]
 |Dutch - nl [..51%...]                                  |Russian - ru [.....100%] (спасибо Vasiliy Korchagin)
 |French - fr [.....100%] (Langue de l'auteur)           |Spanish - es [.....97%] (Gracias a Erik Rivera)
    * [[Features]]
    * [[Tags and Filters]]
    * [[Management Commands]]
-   * [[Posting from other Django Apps]]
+   * [[API]]
    * [[Frequently Asked Questions]]

 It can be run directly or better as a nightly cron job.
-<-//[[Tags and Filters|Previous]]// //[[Home]]// //[[Frequently Asked Questions|Next]]//->
+<-//[[Tags and Filters|Previous]]// //[[Home]]// //[[API|Next]]//->

 Parties should be notified of these events:
-* when a message is rejected
-* when a message or a reply is received
+* when a message is rejected (sender)
+* when a message or a reply is received (recipient)
 === For visitors ===
 Some extra context variables are passed in the call to the notifier application
 and so are available in the templates:
-* {{{message}}}: the Message instance
-* {{{action}}}: 'rejection' or 'acceptance'
+* {{{pm_message}}}: the Message instance
+* {{{pm_action}}}: 'rejection' or 'acceptance'
 If no notifier application is used, an email is sent, using these templates:

-== Postman Messaging via Other Apps ==
-It is possible for other apps in the same Django project to post messages through Postman, either with or without accompanying emails being sent. For example, let's say you have an Events app in your project, and new Event records have a set of known recipients as User objects. The trick is to save one Postman Message() model instance for each intended recipient.  In the view code of your events app, do something like:
-from postman.models import Message
-from postman.models import STATUS_PENDING, STATUS_ACCEPTED
-events = Event.objects.filter(foo=bar)
-  for e in events:
-    recips = User.objects.filter(foo=bar)
-    for r in recips:
-      # Create Postman message
-      msg = Message()
-      msg.subject = 'New %s at Our School: %s' % (e.type, e.title)
-      msg.body = e.description
-      msg.sender =
-      msg.recipient = r
-      msg.moderation_status = STATUS_ACCEPTED # Delivers a Postman internal message.  
-      msg.notify_users(STATUS_PENDING,is_auto_moderated=True) # Remove line to skip sending email
-This is just an example - modify to suit your needs of course.

 You may use it as it is with a CSS design of yours, re-use it or extend some parts of it,
 or only view it as an example.
+You may need to adjust some templates to match your version of Django.
+Permute the comment tags for the lines denoted by the marks: {# dj v1.x #} in:
+* base_write.html
+In case you run a Django 1.2 version, perform these additional steps for any template:
+* Remove {% load url from future %}
+* Change any {% url 'XX' %} to {% url XX %}
 Relations between templates:
     |_ view.html
-If the django-ajax-selects application is used, the following URLs are referenced by this set:
+If the autocomplete application is django-ajax-selects in version 1.1.4 or 1.1.5, the following URLs are referenced by this set:
-* {% admin_media_prefix %}js/jquery.min.js
-* {{ MEDIA_URL }}js/jquery.autocomplete.min.js
-* {{ MEDIA_URL }}css/jquery.autocomplete.css
-* {{ MEDIA_URL }}css/indicator.gif
+* js/jquery.min.js
+* js/jquery.autocomplete.min.js
+* css/jquery.autocomplete.css
+* css/indicator.gif
+You may have to adjust the path prefix with your version of Django:
+{{ MEDIA_URL }} or {{ STATIC_URL }} or {% admin_media_prefix %} or {% static '... %} or {% static 'admin/... %}.
+These files are part of the requirements of django-ajax-selects version 1.1.x and
+it's up to you to make them accessible in your project (they are not provided by the django-postman app).
 The {{{postman/base.html}}} template extends a {{{base.html}}} site template,
 in which some blocks are expected:
 * content: in <html><body>, to put the page contents
 * postman_menu: in <html><body>, to put a navigation menu
-==== Medias ====
+==== Static Files ====
 A CSS file is provided with the application, for the Admin site: {{{postman/css/admin.css}}}.
 It is not mandatory but makes the display more confortable.
-The file is provided under {{{postman/medias/}}}. It's up to you to make it visible to the URL resolver.
+The file is provided under {{{postman/static/}}}.
+For Django 1.3+, just follow the instructions related to the staticfiles app.
+For Django 1.2:
+It's up to you to make it visible to the URL resolver.
 For example:
-* In a production environment, set /<MEDIA_URL>/postman/ as a symlink to <Postman_module>/medias/postman/
+* Rename the path to {{{postman/medias/}}}
+* In a production environment, set /<MEDIA_ROOT>/postman/ as a symlink to <Postman_module>/medias/postman/
 * In a development environment (django's runserver), you can put in the URLconf, something like:
 ('^' + settings.MEDIA_URL.strip('/') + r'/(?P<path>postman/.*)$', 'django.views.static.serve',
     {'document_root': os.path.join(imp.find_module('postman')[1], 'medias')}),
 See also [[Views]] for the stylesheets of views.
-<a href="{% url postman_reply reply_to_pk %}?next={{ next_url|urlencode }}">Reply</a>
+<a href="{% url 'postman_reply' reply_to_pk %}?next={{ next_url|urlencode }}">Reply</a>
 === reply formatters ===