Author: [email protected]
Date: Mon Jan 26 02:21:04 2009
New Revision: 91
Added:
trunk/docs/
trunk/docs/customizing.txt
trunk/docs/index.txt
trunk/docs/install.txt
trunk/docs/usage.txt
Modified:
trunk/README
Log:
adding documentation
Modified: trunk/README
==============================================================================
--- trunk/README (original)
+++ trunk/README Mon Jan 26 02:21:04 2009
@@ -1,4 +1,6 @@
User-to-user messaging app for Django
=====================================
-This is a basic messaging application for the django web-framework.
\ No newline at end of file
+This is a basic messaging application for the django web-framework, please
+see the /docs/ directory for more information.
+
Added: trunk/docs/customizing.txt
==============================================================================
--- (empty file)
+++ trunk/docs/customizing.txt Mon Jan 26 02:21:04 2009
@@ -0,0 +1,98 @@
+.. _ref-messages-customization:
+
+===========================
+Customizing django-messages
+===========================
+
+There are multiple levels at which you can customize django-messages
without
+altering the code directly.
+
+
+Templates
+---------
+
+Django-messages comes with a set of built-in templates which you can use.
+If these templates don't fit your project you can override any or all of
them
+by putting files with the same filenames in one the directories listes in
+``TEMPLATES_DIRS`` in your ``settings.py``.
+
+Django-messages uses the following templates:
+
+* :file:`messages/base.html` - A base template from which all the following
+ templates inherit. Maybe it's enough to customize this template for your
+ project.
+* :file:`messages/compose.html` - This template is rendered, when a user
+ composes a new messages.
+* :file:`messages/inbox.html` - This template lists the users inbox.
+* :file:`messages/new_messages.html` - This template is used to construct
the
+ notification mail sent to a user, whenever a new message is received.
+* :file:`messages/outbox.html` - This template lists the users outbox aka
sent
+ messages.
+* :file:`messages/trash.html` - This template lists the users trash.
+* :file:`messages/view.html` - This template renders a single message with
all
+ details.
+
+Additionally django-message provides a set of template for
django-notification.
+These template can be found in :file:`messages/templates/notification/` and
+can also be overwritten in one of your project's ``TEMPLATE_DIRS``.
+
+
+URL-conf
+--------
+
+If you want to further customize how django-messages works it is possible
to
+write your own url-conf instead of including ``messages.urls`` in your
+root url-conf. This not only allows changing the url structure but also
allows
+modifying the kwargs passed to the views and therefore modifying some
behaviour.
+
+Please note: If you provide your own url-conf, or urlpatterns directly
embedded
+in your root url-conf, you shouldn't include ``messages.urls``.
+
+Three common customizations are described in more detail below.
+
+
+Modifying template names
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If overwriting templates in your project's ``TEMPLATE_DIRS`` does not
provide
+enough freedom, you can change the names of the used templates by providing
+a `template_name` keyword argument to the views. Every view which renders a
+template accepts this keyword-argument.
+
+If you want to change the template the ``inbox`` view uses to
``my_inbox.html``
+instead of the default ``messages/inbox.html`` you can use this line in
your
+own url-conf::
+
+ url(r'^inbox/$', inbox, {'template_name': 'my_inbox.html',},
name='messages_inbox'),
+
+
+Modifying form classes
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to use your own form for composing messages, for example to add
+new features, you can simply pass the form-class to the views via kwargs.
+Every view which renders a form accepts a `form_class` keyword argument to
+specify the form-class.
+
+If you want to use Your own ``MyComposeForm`` you can pass it to the view
by
+using a line like the following in your own url-conf::
+
+ from somewhere import MyComposeForm
+ ...
+ url(r'^compose/$', compose, {'form_class': MyComposeForm,},
name='messages_compose'),
+
+
+Modifying success urls
+~~~~~~~~~~~~~~~~~~~~~~
+
+All views, which will redirect the user after a successfull action accept a
+`success_url` keyword argument to specify the destination url. The
``delete``
+and ``undelete`` views will additionally check if a ``next`` parameter is
+provided in the querystring appended to the url.
+
+If you don't want to append the next target to the url, or want to change
+the redirecting behaviour of other views, you can pass a ``success_url``
+parameter in your own url-conf, for example like this::
+
+ url(r'^delete/(?P<message_id>[\d]+)/$', delete,
{'success_url': '/profile/',}, name='messages_delete'),
+
Added: trunk/docs/index.txt
==============================================================================
--- (empty file)
+++ trunk/docs/index.txt Mon Jan 26 02:21:04 2009
@@ -0,0 +1,26 @@
+===============
+django-messages
+===============
+
+``messages`` is a Django app which provides a user-to-user messaging
system.
+Django-messages enables your users to send private messages to each other.
It
+provides a basic set of functionality you would expect from such a system.
+Every user has an inbox, an Outbox and a Trash. Messages can be composed
and
+there is an easy url-based approach to preloading the compose-form with the
+recipient user, which makes it extremly easy to put "send xyz a message"
links
+on profile pages.
+
+Currently django-messages comes with these translations:
+
+* de
+* fr
+* es_AR
+* pl
+* es
+* pt_BR
+
+.. toctree::
+
+ install
+ usage
+ customizing
Added: trunk/docs/install.txt
==============================================================================
--- (empty file)
+++ trunk/docs/install.txt Mon Jan 26 02:21:04 2009
@@ -0,0 +1,90 @@
+.. _ref-messages-install:
+
+==========================
+Installing django-messages
+==========================
+
+Basically all you have to do is get the ``messages`` folder somewhere on
the
+Python path. There are multiple ways to achive this.
+
+Quickstart
+----------
+
+If you already downloaded the package change into the ``django-messages``
+directory and run::
+
+ python setup.py install
+
+Otherwise you will find more information in the remainder of this document.
+
+Django-messages is available via PyPi, so the following command will
download
+and install django-messages on your system in one step::
+
+ easy_install django-messages
+
+If you prefer using pip, you may achieve the same result by running::
+
+ pip install django-messages
+
+
+Download
+---------
+
+You will always find and download the latest packaged version at:
+http://code.google.com/p/django-messages/downloads/list
+
+If you prefer to use the current developement version to get earlier
access to
+new features you can checkout the code from the SVN repository::
+
+ svn checkout http://django-messages.googlecode.com/svn/trunk/
django-messages
+
+
+Install
+-------
+
+If you downloaded the tar-ball extract it with (change the version number
if
+required)::
+
+ tar -xcvf django-messages-0.4.tar.gz
+
+After extracting the tar-ball or checking out the code from the repository,
+change into the ``django-messages`` directory and install the code::
+
+ cd django-messages
+ python setup.py install
+
+
+Manual Install
+--------------
+
+Instead of using ``setup.py install`` it is also possible to copy or
symlink
+the ``messages`` folder inside the toplevel ``django-messages`` folder to
+your Python path. This will be enough to make djano-messages available to
your
+system.
+
+
+Dependencies
+------------
+
+Django-messages has no external dependencies except for Django. Starting
with
+version 0.3 Django 1.0 or later is required. If you have to use Django
0.96.x
+you might still use version 0.2 (unsupported).
+
+Django-messages has some features which may use an external app if it is
+present in the current Django project. Please note, that these apps have to
+be listed in ``INSTALLED_APPS`` to be used by django-messages.
+
+* If you use `django-notification`_ django-messages will use it for sending
+ notifications to users about new messages instead of using the built-in
+ mechanism
+
+* If `django-mailer`_ is used the built-in messages sending code will use
it
+ instead of the django built-in ``send_mail`` function.
+
+Please note that we try to support Python 2.4, but as we develop
django-messages
+on Python 2.5 sometimes code might slip in which breaks Python 2.4
compatibility.
+This can be considered a bug and you can help us by reporting the
incompytibility.
+
+
+.. _`django-notification`: http://code.google.com/p/django-notification/
+.. _`django-mailer`: http://code.google.com/p/django-mailer/
Added: trunk/docs/usage.txt
==============================================================================
--- (empty file)
+++ trunk/docs/usage.txt Mon Jan 26 02:21:04 2009
@@ -0,0 +1,50 @@
+=====================
+Using django-messages
+=====================
+
+To enable django-messages in your Django project make sure it is
+:ref:`installed <ref-messages-install>`. You can check if django-messages
was
+successfully installed by opening a python shell and running::
+
+ >>> import messages
+ >>>
+
+If no error occured, you can assumed that the app was installed correctly.
+
+
+Edit settings
+-------------
+
+The next step is to add ``messsages`` to the ``INSTALLED_APPS`` setting::
+
+ INSTALLED_APPS = (
+ ...
+ 'messages',
+ ...
+ )
+
+
+Add urls
+--------
+
+To make django-messages available to your users you should include the
+bunlded url-conf in your root url-conf. One example would be to edit
+your main ``urls.py`` and add a line like this::
+
+ urlpatterns = patterns(''
+ ...
+ (r'^messages/', include('messages.urls')),
+ ...
+ )
+
+
+Templates
+---------
+
+Django-messages provides some simple default templates which will get you
+started quick. The templates make the assumption that a base template with
+the name ``base.html`` exists which defines a block ``content`` and a block
+``sidebar``. If this is not the case, or the template don't fit due to
other
+concerns, it's very easy to provide to your own templates. Please see the
+:ref:`customization docs <ref-messages-customization>` fore more details.
+
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"pinax-updates" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/pinax-updates?hl=en
-~----------~----~----~----~------~----~------~--~---
