django-mptt/django-mptt — pull request #225 by pstch (2012-12-06 13:04:19+00:00)
Title: Instance methods and template filters for partial path computing

These commits modifies ``get_ascendants()`` and ``get_descendants()`` by adding an optional argument and adds one template filter, ``nodes_up_to`` related to vertical tree traversal and path computing.

The arguments, up_to and down_to, added to respectively ``get_ascendants()`` and ``get_descendants()`` methods allows to limit the lookup depth. For ``get_ascendants()``, only the items up to that level will be returned, and for ``get_descendants()``, only the items down to that level.

We also add a simple template filter, ``nodes_up_to``, that allows to filter a list of ascendants up to a certain level, because of this : in most cases, when the path of a MPTT model needs to be displayed, this is up to the root. However in some cases (e.g. list of a child's descendants), this may be displayed up to that child.

The ``nodes_down_to`` template filter was not written because I could not find any use case for it : Because this is a filter, it does not access the data itself, and cannot use the ``up_to``/``down_to`` arguments for ``get_ascendants()``and ``get_descendants()``. When listing descendants down to a certain level, getting extra data can be a huge waste, while when listing ascendants up to a certain level, getting extra data won't be such a huge waste.

Furthermore, ascendants are already fully loaded somewhere on the page : running a filtered ``get_ascendants()`` query to avoid extra queries would in fact make an useless query. This is why I made this a template filter and not a template tag.

Note: the standard use case for this filter is to chain it with the ``make_path`` filter