.. _section_urls:

Url for a section
=================

Sections will appear in the ``urlpatterns`` based on the ``url``, ``name`` and
``parent`` it has on itself; and depending on some of the
:ref:`options <section_configure_url>` it has.

The ``url`` and ``name`` attributes are assigned when the section is created
, and ``parent`` is assigned implicityly when you add
:ref:`children <section_children>` to a section.

.. _section_url_interpretation:

How the url is interpreted
--------------------------

The url for each section is built when the urlpatterns are created
and are generated by concatenating the urls from the lineage of parent sections
to the section we're adding a url for.

If there is no parents and our section's ``url`` is None
then it is replaced with '.*'.

If there are no parents and our section's ``url`` is an empty string
then it is replaced with '^$'.

Otherwise, all duplicate slashes are remove
, it is prefixed with a '^' and forced to end with '/$'.

If you set ``catch_all`` to False, then it won't append the url with
a ``/`` or ``$``

.. _section_configure_url:

Section url options
-------------------

You can affect how the section is added via an
`include <https://docs.djangoproject.com/en/dev/ref/urls/#django.conf.urls.include>`_
via the ``app_name`` and ``namespace`` options into "section.configure"

See the :ref:`Splitter section <section_include>` for when that would happen.

Configure also provides the ``match`` option which will make that
section appear as a named regex group in the url:

.. code-block:: python

    # This section here has configured match to "blah"
    Section(r'\d+').configure(match="blah")

So for this section, it's url part will look like:

.. code-block:: python

    r"(?P<blah>\d+)"

.. note:: You can see what url part a section will have by doing:

  .. code-block:: python

    >>> from cwf.sections import Section
    >>> from cwf.sections.pattern_list import PatternList
    >>> section = Section("\d+").configure(match="blah")
    >>> PatternList(section).url_part()
    r'(?P<blah>\d+)'

Ommitting a section from urlpatterns
++++++++++++++++++++++++++++++++++++

A section will be ommitted entirely from the urlpatterns if it has no
configured :ref:`view <section_view_target>` but all it's children will still
appear in the urlpatterns.

For example:

.. code-block:: python

    from cwf.sections import Section

    section = Section().configure(module="webthing.views")

    numbers = section.add('numbers')
    numbers.add("one").configure(target="one")
    numbers.add("two").configure(target="two")

    urlpatterns = section.patterns()

Is equivalent to:

.. code-block:: python

    from django.conf.urls import patterns

    urlpatterns = patterns(''
        , (r'^numbers/one/$', 'webthing.views.one')
        , (r'^numbers/two/$', 'webthing.views.two')
        )