Updated the documentation ; Added a CHANGELOG file

diff --git a/CHANGELOG b/CHANGELOG
new file mode 100644 (file)
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 (file)
index 0000000..c51c1a2
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,49 @@
+API\r
+===\r
+\r
+For an easier usage of the application from other applications in the project,\r
+an API is provided.\r
+\r
+pm_broadcast()\r
+--------------\r
+Broadcast a message to multiple Users.\r
+\r
+For an easier cleanup, all these messages are directly marked as archived and deleted on the sender side.\r
+\r
+Arguments: (sender, recipients, subject, body='', skip_notification=False)\r
+\r
+pm_write()\r
+----------\r
+Write a message to a User.\r
+\r
+Contrary to pm_broadcast(), the message is archived and/or deleted on the sender side only if requested.\r
+\r
+Arguments: (sender, recipient, subject, body='', skip_notification=False, auto_archive=False, auto_delete=False)\r
+\r
+Arguments\r
+---------\r
+* ``auto_archive``: to mark the message as archived on the sender side\r
+* ``auto_delete``: to mark the message as deleted on the sender side\r
+* ``body``: the contents of the message\r
+* ``recipient``: a User instance\r
+* ``recipients``: a list or tuple of User instances, or a single User instance\r
+* ``sender``: a User instance\r
+* ``skip_notification``: if the normal notification event is not wished\r
+* ``subject``: the subject of the message\r
+\r
+Example\r
+-------\r
+Suppose an application managing Event objects. Whenever a new Event is generated,\r
+you want to broadcast an announcement to Users who have subscribed\r
+to be informed of the availability of such a kind of Event.\r
+\r
+Code sample::\r
+\r
+    from postman.api import pm_broadcast\r
+    events = Event.objects.filter(...)\r
+    for e in events:\r
+        pm_broadcast(\r
+            sender=e.author,\r
+            recipients=e.subscribers,\r
+            subject='New {0} at Our School: {1}'.format(e.type, e.title),\r
+            body=e.description)\r

diff --git a/docs/features.rst b/docs/features.rst
index 1b690dd2949413892336a39e77548e5fe5e10689..59904c1232c578c394f60ce20d9bde934612b578 100644 (file)
--- 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).
 \r
 Example::\r
 \r
-    <a href="{% url postman_write username %}">write to {{ username }}</a>\r
+    <a href="{% url 'postman_write' username %}">write to {{ username }}</a>\r
 \r
 Separate multiple usernames with a ``:`` character.\r
 \r
 Example::\r
 \r
-    <a href="{% url postman_write 'adm1:adm2:adm3' %}">write to admins</a>\r
+    <a href="{% url 'postman_write' 'adm1:adm2:adm3' %}">write to admins</a>\r
 \r
 Prefilled fields\r
 ----------------\r
@@ -23,7 +23,7 @@ You may prefill the contents of some fields by providing a query string in the l
 \r
 Example::\r
 \r
-    <a href="{% url postman_write %}?subject=details request&body=give me details about ...">\r
+    <a href="{% url 'postman_write' %}?subject=details request&body=give me details about ...">\r
     ask for details\r
     </a>\r
 \r
@@ -211,18 +211,29 @@ Example::
         'arg_default': 'postman_users',\r
     }\r
 \r
-Support for multiple recipients is not turned on by default by `django-ajax-selects`_.\r
-To allow this capability, you have to pass the option ``multiple: true``.\r
+In case of version 1.1.4/5 of django-ajax-selects:\r
+\r
+       Support for multiple recipients is not turned on by default by `django-ajax-selects`_.\r
+       To allow this capability, you have to pass the option ``multiple: true`` to jquery-plugin-autocomplete.\r
 \r
 .. _`django-ajax-selects`: http://code.google.com/p/django-ajax-selects/\r
 \r
-Make your own templates, based on these two files, given as implementation examples:\r
+       Make your own templates, based on these two files, given as implementation examples:\r
+\r
+       * :file:`postman/templates/autocomplete_postman_multiple_as1-1.html`\r
+       * :file:`postman/templates/autocomplete_postman_single_as1-1.html`\r
+\r
+       These examples include a correction necessary for the support of the 'multiple' option.\r
+\r
+In case of version 1.2.x of django-ajax-selects:\r
+\r
+       Refer to the installation guide of this application, in particular the use of AJAX_SELECT_BOOTSTRAP\r
+       and AJAX_SELECT_INLINES.\r
+       Support for multiple recipients is not as simple as an option: see the examples in the `jQuery UI demos`_.\r
 \r
-* :file:`postman/templates/autocomplete_postman_multiple.html`\r
-* :file:`postman/templates/autocomplete_postman_single.html`\r
+.. _`jQuery UI demos`: http://jqueryui.com/demos/autocomplete/multiple-remote.html\r
 \r
-These examples include a correction necessary for the support of the 'multiple' option\r
-(in version 1.1.4 of django-ajax-selects).\r
+       The directory `postman/templates/` doesn't currently provide any examples for this version.\r
 \r
 Customization\r
 ~~~~~~~~~~~~~\r

diff --git a/docs/index.rst b/docs/index.rst
index b8edc64e568e93b36b78384cb60e6e49ee9a3fe4..1e01d2d7b58348a5160d6925964b12819c2d907e 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -97,6 +97,7 @@ Contents:
    features\r
    tags-filters\r
    management\r
+   api\r
    faq\r
 \r
 Indices and tables\r

diff --git a/docs/management.rst b/docs/management.rst
index ba715f46f93b9dc1677c4db6d77ab0d6ae951ee2..a966a924066e79e35f6ec18197a890381a06aefc 100644 (file)
--- a/docs/management.rst
+++ b/docs/management.rst
@@ -24,7 +24,7 @@ A management command is provided for this purpose:
 \r
 It can be run as a cron job or directly.\r
 \r
-A :option:`--days` option can be used to specify the minimal number of days a message/conversation\r
+The :option:`--days` option can be used to specify the minimal number of days a message/conversation\r
 must have been marked for deletion.\r
 Default value is 30 days.\r
 \r

diff --git a/docs/notification.rst b/docs/notification.rst
index 5be29800adc2ad59c1ba0244b2880ff724ca9032..76f68d3c01f85406f358bb43cfb13699c65c364c 100644 (file)
--- a/docs/notification.rst
+++ b/docs/notification.rst
@@ -3,8 +3,8 @@ Notification
 \r
 Parties should be notified of these events:\r
 \r
-* when a message is rejected\r
-* when a message or a reply is received\r
+* when a message is rejected (sender)\r
+* when a message or a reply is received (recipient)\r
 \r
 .. _for_visitors:\r
 \r
@@ -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\r
 and so are available in the templates:\r
 \r
-* ``message``: the Message instance\r
-* ``action``: 'rejection' or 'acceptance'\r
+* ``pm_message``: the Message instance\r
+* ``pm_action``: 'rejection' or 'acceptance'\r
 \r
 If no notifier application is used, an email is sent, using these templates:\r
 \r

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 2d9ba3491bfb53a1fa359a3bed0dc9f521177421..320066bb3090e71aef0393a9f3cbcac4d03724bf 100644 (file)
--- 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,\r
 or only view it as an example.\r
 \r
+You may need to adjust some templates to match your version of Django.\r
+Permute the comment tags for the lines denoted by the marks: {# dj v1.x #} in:\r
+\r
+* base_write.html\r
+\r
+In case you run a Django 1.2 version, perform these additional steps for any template:\r
+\r
+* Remove {% load url from future %}\r
+* Change any {% url 'XX' %} to {% url XX %}\r
+\r
 Relations between templates::\r
 \r
     base.html\r
@@ -148,12 +158,18 @@ Relations between templates::
     |  |_ reply.html\r
     |_ view.html\r
 \r
-If the django-ajax-selects application is used, the following URLs are referenced by this set:\r
+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:\r
 \r
-* {% admin_media_prefix %}js/jquery.min.js\r
-* {{ MEDIA_URL }}js/jquery.autocomplete.min.js\r
-* {{ MEDIA_URL }}css/jquery.autocomplete.css\r
-* {{ MEDIA_URL }}css/indicator.gif\r
+* js/jquery.min.js\r
+* js/jquery.autocomplete.min.js\r
+* css/jquery.autocomplete.css\r
+* css/indicator.gif\r
+\r
+You may have to adjust the path prefix with your version of Django:\r
+{{ MEDIA_URL }} or {{ STATIC_URL }} or {% admin_media_prefix %} or {% static '... %} or {% static 'admin/... %}.\r
+\r
+These files are part of the requirements of django-ajax-selects version 1.1.x and\r
+it's up to you to make them accessible in your project (they are not provided by the django-postman app).\r
 \r
 The :file:`postman/base.html` template extends a :file:`base.html` site template,\r
 in which some blocks are expected:\r
@@ -163,20 +179,26 @@ in which some blocks are expected:
 * content: in <html><body>, to put the page contents\r
 * postman_menu: in <html><body>, to put a navigation menu\r
 \r
-Medias\r
-~~~~~~\r
+Static Files\r
+~~~~~~~~~~~~\r
 A CSS file is provided with the application, for the Admin site: :file:`postman/css/admin.css`.\r
 It is not obligatory but makes the display more confortable.\r
 \r
-The file is provided under :file:`postman/medias/`. It's up to you to make it visible to the URL resolver.\r
+The file is provided under :file:`postman/static/`.\r
+\r
+For Django 1.3+, just follow the instructions related to the staticfiles app.\r
+\r
+For Django 1.2:\r
+       It's up to you to make it visible to the URL resolver.\r
 \r
-For example:\r
+       For example:\r
 \r
-* In a production environment, set :file:`/<MEDIA_URL>/postman/` as a symlink to :file:`<Postman_module>/medias/postman/`\r
-* In a development environment (django's runserver), you can put in the URLconf, something like::\r
+       * Rename the path to :file:`postman/medias/`\r
+       * In a production environment, set :file:`/<MEDIA_ROOT>/postman/` as a symlink to :file:`<Postman_module>/medias/postman/`\r
+       * In a development environment (django's runserver), you can put in the URLconf, something like::\r
 \r
-    ('^' + settings.MEDIA_URL.strip('/') + r'/(?P<path>postman/.*)$', 'django.views.static.serve',\r
-        {'document_root': os.path.join(imp.find_module('postman')[1], 'medias')}),\r
+               ('^' + settings.MEDIA_URL.strip('/') + r'/(?P<path>postman/.*)$', 'django.views.static.serve',\r
+                       {'document_root': os.path.join(imp.find_module('postman')[1], 'medias')}),\r
 \r
 See also :ref:`styles` for the stylesheets of views.\r
 \r

diff --git a/docs/views.rst b/docs/views.rst
index 8d4ae32c424f9c67d668c10aa16f796a6daab16d..c9811250997a20b0126655c8961910877f5aca83 100644 (file)
--- a/docs/views.rst
+++ b/docs/views.rst
@@ -77,7 +77,7 @@ Example::
 \r
 Example::\r
 \r
-    <a href="{% url postman_reply reply_to_pk %}?next={{ next_url|urlencode }}">Reply</a>\r
+    <a href="{% url 'postman_reply' reply_to_pk %}?next={{ next_url|urlencode }}">Reply</a>\r
 \r
 reply formatters\r
 ----------------\r