.. _ref-profiles-reference:

=========
Reference
=========

This document covers various components of ``pinax.apps.profiles``.


Named URLs
==========

The named URLs in this app should enable the use of of the ``{% url %}``
template tag as well as ``reverse`` lookups in your project code without having
to know the implementation details of this app.


profile_username_autocomplete
-----------------------------

An AJAX call back URL to the ``pinax.apps.autocomplete_app.views.username_autocomplete_friends``
app that looks up and provides a list of data to the jQuery autocomplete_
plugin.

See :ref:`autocomplete app usage documentation <ref-autocomplete_app-gettingstarted-usage>`.


profile_list
------------

Upon GET request, this url will render a template named ``profiles/profiles.html``
by default with a list of users in context ordered by either ``date_joined`` descending
or by ``username`` ascending.  This is further optionally limited with case-insensitive
search against the ``username`` field if the query parameter ``search_terms`` is
provided.  Likewise, the ordering defaults to ``date_joined`` descending which can
be overridden by supplying the query parameter ``order`` with the value of ``name``.

Examples:

.. code-block:: html

	<a href="{% url profile_list %}?search_terms=beth&order=name">Show "beth" Users</a>

This would result in the ``users`` context variable limited to users such as
*Beth, Bethany, Marybeth* and would be ordered alphabetically by their username.

The value of ``order`` and ``search_terms`` are also passed to the template as
context variables.


profile_detail
--------------

This url will render a template named ``profiles/profile.html`` by
default with ``is_me`` and ``other_user`` as context variables where ``is_me``
is a boolean that indicates whether or not ``other_user`` is the same as the
authenticated user making the request.

:keyword arguments: The username for the profile to view that matches ``(?P<username>[\w\._-]+)``


profile_edit
------------

This url, when POSTed to will process the variables through a
``pinax.apps.profiles.forms.ProfileForm`` instance, otherwise it will
process a GET request by rendering ``profiles/profile_edit.html`` by
default for regular requests and ``profiles/profile_edit_facebox.html``
for ajax calls.  It renders both of these templates with an instance of the
``pinax.apps.profiles.ProfileForm`` as ``profile_form`` and an instance of
``pinax.apps.profiles.models.Profile`` as ``profile``.


Templates
=========

Templates should be placed in an ``profiles/`` folder at the root of one of
your template search paths.


profiles.html
-------------

:context: ``users``, ``order``, ``search_terms``


profile.html
------------

:context: ``is_me``, ``is_friend``, ``is_following``, ``other_user``, ``other_friends``, ``invite_form``, ``previous_invitations_to``, ``previous_invitations_from``


profile_edit.html
-----------------

:context: ``profile``, ``profile_form``


profile_edit_facebox.html
-------------------------

:context: ``profile``, ``profile_form``


Modules
=======


``pinax.apps.profiles.admin``
-----------------------------

.. automodule:: pinax.apps.profiles.admin
   :members:
   :undoc-members:


``pinax.apps.profiles.forms``
-----------------------------

.. automodule:: pinax.apps.profiles.forms
   :members:
   :undoc-members:


``pinax.apps.profiles.models``
------------------------------

.. automodule:: pinax.apps.profiles.models
   :members:
   :undoc-members:


``pinax.apps.profiles.templatetags.profile_tags``
-------------------------------------------------

.. automodule:: pinax.apps.profiles.templatetags.profile_tags
   :members:
   :undoc-members:


``pinax.apps.profiles.views``
-----------------------------

.. automodule:: pinax.apps.profiles.views
   :members:
   :undoc-members:


.. _autocomplete: http://docs.jquery.com/Plugins/Autocomplete