Merge branch 'master' of github.com:torchbox/wagtail

docs/core_components/pages/advanced_topics/routable_page_mixin.rst

@@ -4,7 +4,7 @@
 Embedding URL configuration in Pages
 ====================================
 
-.. versionadded:: 0.5
+.. versionadded:: 0.6
 
 The ``RoutablePageMixin`` mixin provides a convenient way for a page to respond on multiple sub-URLs with different views. For example, a blog section on a site might provide several different types of index page at URLs like ``/blog/2013/06/``, ``/blog/authors/bob/``, ``/blog/tagged/python/``, all served by the same ``BlogIndex`` page.
 
@@ -68,16 +68,18 @@ The ``RoutablePageMixin`` class
 
             from wagtail.wagtailcore.models import Page
 
+
             class MyPage(RoutablePageMixin, Page):
                 subpage_urls = (
-                    url(r'^$', 'serve', name='main'),
+                    url(r'^$', 'main', name='main'),
                     url(r'^archive/$', 'archive', name='archive'),
+                    url(r'^archive/(?P<year>[0-9]{4})/$', 'archive', name='archive'),
                 )
 
-                def serve(self, request):
+                def main(self, request):
                     ...
 
-                def archive(self, request):
+                def archive(self, request, year=None):
                     ...
 
     .. automethod:: resolve_subpage
@@ -86,7 +88,7 @@ The ``RoutablePageMixin`` class
 
         .. code-block:: python
 
-            view, args, kwargs = page.resolve_subpage('/past/')
+            view, args, kwargs = page.resolve_subpage('/archive/')
             response = view(request, *args, **kwargs)
 
     .. automethod:: reverse_subpage
@@ -95,7 +97,7 @@ The ``RoutablePageMixin`` class
 
         .. code-block:: python
 
-            url = page.url + page.reverse_subpage('events_for_year', args=('2014', ))
+            url = page.url + page.reverse_subpage('archive', kwargs={'year': '2014'})
 
 
  .. _routablepageurl_template_tag:
@@ -103,8 +105,6 @@ The ``RoutablePageMixin`` class
 The ``routablepageurl`` template tag
 ====================================
 
-.. versionadded:: 0.6
-
 .. currentmodule:: wagtail.contrib.wagtailroutablepage.templatetags.wagtailroutablepage_tags
 .. autofunction:: routablepageurl
 

docs/core_components/pages/creating_pages.rst

@@ -147,3 +147,50 @@ In addition to the model fields provided, ``Page`` has many properties and metho
         Defines which template file should be used to render the login form for Protected pages using this model. This overrides the default, defined using ``PASSWORD_REQUIRED_TEMPLATE`` in your settings. See :ref:`private_pages`
 
 
+Tips
+~~~~
+
+Friendly model names
+--------------------
+
+Make your model names more friendly to users of Wagtail using Django's internal ``Meta`` class with a ``verbose_name`` e.g
+
+.. code-block:: python
+    
+    class HomePage(Page):
+        ...
+
+        class Meta:
+            verbose_name = "Homepage"
+
+When users are given a choice of pages to create, the list of page types is generated by splitting your model names on each of their capital letters. Thus a ``HomePage`` model would be named "Home Page" which is a little clumsy. ``verbose_name`` as in the example above, would change this to read "Homepage" which is slightly more conventional.
+
+The above example also ensures the name of the 
+
+Helpful model descriptions
+--------------------------
+
+As your site becomes more complex users may require some prompting in deciding which content type to use when creating a new page. Developers can add a description to their Models by extending Django's internal model ``Meta`` class.
+
+Insert the following once at the top of your ``models.py``:
+
+.. code-block:: python
+
+    import django.db.models.options as options
+    options.DEFAULT_NAMES = options.DEFAULT_NAMES + ('description',)
+     
+
+Then for each model as necessary, add a description option to the model ``Meta`` class
+
+
+.. code-block:: python
+
+    class HomePage(Page):
+        ...
+        
+        class Meta:
+            description = "The top level homepage for your site"
+            verbose_name = "Homepage"
+
+
+(This method can be used to extend the Model Meta class in various ways however Wagtail only supports the addition of a ``description`` option).

docs/core_components/pages/editing_api.rst

@@ -1,6 +1,6 @@
 .. _editing-api:
 
-Defining models with the Editing API
+Displaying fields with the Editing API
 ====================================
 
 .. note::

docs/core_components/pages/writing_templates.rst

@@ -112,13 +112,16 @@ For example:
     <!-- or a square thumbnail: -->
     {% image self.photo fill-80x80 %}
 
-In the above syntax ``[image]`` is the Django object refering to the image. If your page model defined a field called "photo" then ``[image]`` would probably be ``self.photo``. The ``[resize-rule]`` defines how the image is to be resized when inserted into the page; various resizing methods are supported, to cater for different usage cases (e.g. lead images that span the whole width of the page, or thumbnails to be cropped to a fixed size).
+In the above syntax example ``[image]`` is the Django object refering to the image. If your page model defined a field called "photo" then ``[image]`` would probably be ``self.photo``. The ``[resize-rule]`` defines how the image is to be resized when inserted into the page; various resizing methods are supported, to cater for different usage cases (e.g. lead images that span the whole width of the page, or thumbnails to be cropped to a fixed size).
 
 Note that a space separates ``[image]`` and ``[resize-rule]``, but the resize rule must not contain spaces.
 
+
 The available resizing methods are:
 
+
 .. glossary::
+
     ``max`` 
         (takes two dimensions)
 
@@ -182,6 +185,7 @@ The available resizing methods are:
         Leaves the image at its original size - no resizing is performed.
 
 
+
 .. Note::
     Wagtail does not allow deforming or stretching images. Image dimension ratios will always be kept. Wagtail also *does not support upscaling*. Small images forced to appear at larger sizes will "max out" at their their native dimensions.
 
@@ -218,6 +222,15 @@ Wagtail can assign the image data to another variable using Django's ``as`` synt
         height="{{ tmp_photo.height }}" alt="{{ tmp_photo.alt }}" class="my-custom-class" />
         
 
+This syntax exposes the underlying image "Rendition" (``tmp_photo``) to the developer. A "Rendition" contains just the information specific to the way you've requested to format the image i.e dimensions and source URL.
+
+If your site defines a custom image model using ``AbstractImage``, then any additional fields you add to an image e.g a copyright holder, are **not** part of the image *rendition*, they're part of the image *model*. 
+
+Therefore in the above example, if you'd added the field ``foo`` to your AbstractImage you'd access it using ``{{ self.photo.foo }}`` not ``{{ tmp_photo.foo }}``. 
+
+(Due to the links in the database between renditions and their parent image, you could also access it as ``{{ tmp_photo.image.foo }}`` but this is clearly confusing.)
+
+
 .. Note::      
     The image property used for the ``src`` attribute is actually ``image.url``, not ``image.src``.