From: Patrick Samson <pk.samson@gmail.com>
Date: Mon, 13 Aug 2012 20:11:31 +0000 (+0200)
Subject: Updated the documentation ; Added a CHANGELOG file
X-Git-Tag: 2.0.0~6
X-Git-Url: https://git.parisson.com/?a=commitdiff_plain;h=98c0acbb3c9f18a394e30c6de3529eca5fe18461;p=django-postman.git

Updated the documentation ; Added a CHANGELOG file
---

diff --git a/CHANGELOG b/CHANGELOG
new file mode 100644
index 0000000..d024c13
--- /dev/null
+++ b/CHANGELOG
@@ -0,0 +1,37 @@
+========================
+Django Postman changelog
+========================
+
+Version 2.0.0, August 2012
+--------------------------
+* Add an API.
+* Rename the extra context variables passed to the notifier app to avoid name clash:
+	pm_message and pm_action
+* More adjustments for Django 1.4.
+* Change medias/ to static/ for conformance with django 1.3.
+* Adjustments for integration with version 1.2.x of django-ajax-selects, in addition to 1.1.x:
+ - Rename autocomplete_postman_*.html as autocomplete_postman_*_as1-1.html
+	to make clear that they are for django-*a*jax-*s*elects app version 1.1.x.
+ - Replace the template variable 'is_autocompleted' (a boolean) by 'autocompleter_app'
+	(a dictionary with keys: 'is_active', 'name' and 'version').
+* Add this CHANGELOG file.
+
+Version 1.2.0, March 2012
+-------------------------
+* Improve the or_me filter, in relation with issue #5.
+* Improve the autopagination performance.
+* First adjustments for Django 1.4.
+
+Version 1.1.0, January 2012
+---------------------------
+* Add POSTMAN_DISABLE_USER_EMAILING.
+* No need for an immediate rejection notification for a User.
+* Add an ordering criteria.
+
+Version 1.0.1, January 2011
+---------------------------
+* Fix issue #1.
+
+Version 1.0.0, January 2011
+---------------------------
+* Initial release.
\ No newline at end of file
diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 0000000..c51c1a2
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,49 @@
+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(
+            sender=e.author,
+            recipients=e.subscribers,
+            subject='New {0} at Our School: {1}'.format(e.type, e.title),
+            body=e.description)
diff --git a/docs/features.rst b/docs/features.rst
index 1b690dd..59904c1 100644
--- a/docs/features.rst
+++ b/docs/features.rst
@@ -8,13 +8,13 @@ In the pages of your site, you can put links containing the recipient name(s).
 
 Example::
 
-    <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.
 
 Example::
 
-    <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
 ----------------
@@ -23,7 +23,7 @@ You may prefill the contents of some fields by providing a query string in the l
 
 Example::
 
-    <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
     </a>
 
@@ -211,18 +211,29 @@ Example::
         'arg_default': 'postman_users',
     }
 
-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``.
+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 jquery-plugin-autocomplete.
 
 .. _`django-ajax-selects`: http://code.google.com/p/django-ajax-selects/
 
-Make your own templates, based on these two files, given as implementation examples:
+	Make your own templates, based on these two files, given as implementation examples:
+
+	* :file:`postman/templates/autocomplete_postman_multiple_as1-1.html`
+	* :file:`postman/templates/autocomplete_postman_single_as1-1.html`
+
+	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
+	and AJAX_SELECT_INLINES.
+	Support for multiple recipients is not as simple as an option: see the examples in the `jQuery UI demos`_.
 
-* :file:`postman/templates/autocomplete_postman_multiple.html`
-* :file:`postman/templates/autocomplete_postman_single.html`
+.. _`jQuery UI demos`: http://jqueryui.com/demos/autocomplete/multiple-remote.html
 
-These examples include a correction necessary for the support of the 'multiple' option
-(in version 1.1.4 of django-ajax-selects).
+	The directory `postman/templates/` doesn't currently provide any examples for this version.
 
 Customization
 ~~~~~~~~~~~~~
diff --git a/docs/index.rst b/docs/index.rst
index b8edc64..1e01d2d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -97,6 +97,7 @@ Contents:
    features
    tags-filters
    management
+   api
    faq
 
 Indices and tables
diff --git a/docs/management.rst b/docs/management.rst
index ba715f4..a966a92 100644
--- a/docs/management.rst
+++ b/docs/management.rst
@@ -24,7 +24,7 @@ A management command is provided for this purpose:
 
 It can be run as a cron job or directly.
 
-A :option:`--days` option can be used to specify the minimal number of days a message/conversation
+The :option:`--days` option can be used to specify the minimal number of days a message/conversation
 must have been marked for deletion.
 Default value is 30 days.
 
diff --git a/docs/notification.rst b/docs/notification.rst
index 5be2980..76f68d3 100644
--- a/docs/notification.rst
+++ b/docs/notification.rst
@@ -3,8 +3,8 @@ Notification
 
 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:
 
@@ -38,8 +38,8 @@ If a notifier application is configured (see :ref:`optional_settings`), the foll
 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:
 
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 2d9ba34..320066b 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -135,6 +135,16 @@ A complete set of working templates is provided with the application.
 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::
 
     base.html
@@ -148,12 +158,18 @@ Relations between templates::
     |  |_ reply.html
     |_ 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 :file:`postman/base.html` template extends a :file:`base.html` site template,
 in which some blocks are expected:
@@ -163,20 +179,26 @@ 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: :file:`postman/css/admin.css`.
 It is not obligatory but makes the display more confortable.
 
-The file is provided under :file:`postman/medias/`. It's up to you to make it visible to the URL resolver.
+The file is provided under :file:`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:
+	For example:
 
-* In a production environment, set :file:`/<MEDIA_URL>/postman/` as a symlink to :file:`<Postman_module>/medias/postman/`
-* In a development environment (django's runserver), you can put in the URLconf, something like::
+	* Rename the path to :file:`postman/medias/`
+	* In a production environment, set :file:`/<MEDIA_ROOT>/postman/` as a symlink to :file:`<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')}),
+		('^' + 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 :ref:`styles` for the stylesheets of views.
 
diff --git a/docs/views.rst b/docs/views.rst
index 8d4ae32..c981125 100644
--- a/docs/views.rst
+++ b/docs/views.rst
@@ -77,7 +77,7 @@ Example::
 
 Example::
 
-    <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
 ----------------