From ad222ffb18f3e2af7760ca66ee59d6089c8604ac Mon Sep 17 00:00:00 2001 From: Karl Hobley Date: Thu, 14 May 2015 21:51:49 +0100 Subject: [PATCH] Restructured basic panels docs --- docs/reference/pages/editing_api.rst | 58 ++++++++++++++++++++++++---- 1 file changed, 51 insertions(+), 7 deletions(-) diff --git a/docs/reference/pages/editing_api.rst b/docs/reference/pages/editing_api.rst index bdd1d27a9d..408c4e53ed 100644 --- a/docs/reference/pages/editing_api.rst +++ b/docs/reference/pages/editing_api.rst @@ -20,18 +20,62 @@ A "panel" is the basic editing block in Wagtail. Wagtail will automatically pick There are four basic types of panels: - ``FieldPanel( field_name, classname=None, widget=None )`` - This is the panel used for basic Django field types. ``field_name`` is the name of the class property used in your model definition. ``classname`` is a string of optional CSS classes given to the panel which are used in formatting and scripted interactivity. By default, panels are formatted as inset fields. The CSS class ``full`` can be used to format the panel so it covers the full width of the Wagtail page editor. The CSS class ``title`` can be used to mark a field as the source for auto-generated slug strings. The optional ``widget`` parameter allows you to specify a `django form widget`_ to use instead of the default widget for this field type. +.. module:: wagtail.wagtailadmin.edit_handers + +FieldPanel +---------- + +.. class:: FieldPanel(field_name, classname=None, widget=None) + + This is the panel used for basic Django field types. + + .. attribute:: FieldPanel.field_name + + This is the name of the class property used in your model definition. + + .. attribute:: FieldPanel.classname + + This is a string of optional CSS classes given to the panel which are used in formatting and scripted interactivity. By default, panels are formatted as inset fields. + + The CSS class ``full`` can be used to format the panel so it covers the full width of the Wagtail page editor. + + The CSS class ``title`` can be used to mark a field as the source for auto-generated slug strings. + + .. attribute:: FieldPanel.widget (optional) + + This parameter allows you to specify a `django form widget`_ to use instead of the default widget for this field type. .. _django form widget: https://docs.djangoproject.com/en/dev/ref/forms/widgets/ - ``MultiFieldPanel( children, heading="", classname=None )`` - This panel condenses several ``FieldPanel`` s or choosers, from a list or tuple, under a single ``heading`` string. +MultiFieldPanel +--------------- - ``InlinePanel( relation_name, panels=None, classname=None, label='', help_text='' )`` - This panel allows for the creation of a "cluster" of related objects over a join to a separate model, such as a list of related links or slides to an image carousel. This is a very powerful, but tricky feature which will take some space to cover, so we'll skip over it for now. For a full explanation on the usage of ``InlinePanel``, see :ref:`inline_panels`. +.. class:: MultiFieldPanel(children, heading="", classname=None) + + This panel condenses several ``FieldPanel`` s or choosers, from a ``list`` or ``tuple``, under a single ``heading`` string. + + .. attribute:: MultiFieldPanel.children + + A ``list`` or ``tuple`` of child panels + + .. attribute:: MultiFieldPanel.heading + + A heading for the fields + +InlinePanel +----------- + +.. class:: InlinePanel(relation_name, panels=None, classname=None, label='', help_text='') + + This panel allows for the creation of a "cluster" of related objects over a join to a separate model, such as a list of related links or slides to an image carousel. + + This is a very powerful, but tricky feature which will take some space to cover, so we'll skip over it for now. For a full explanation on the usage of ``InlinePanel``, see :ref:`inline_panels`. + +FieldRowPanel +------------- + +.. class:: FieldRowPanel(children, classname=None) - ``FieldRowPanel( children, classname=None )`` This panel is purely aesthetic. It creates a columnar layout in the editing interface, where each of the child Panels appears alongside each other rather than below. Use of FieldRowPanel particularly helps reduce the "snow-blindness" effect of seeing so many fields on the page, for complex models. It also improves the perceived association between fields of a similar nature. For example if you created a model representing an "Event" which had a starting date and ending date, it may be intuitive to find the start and end date on the same "row". FieldRowPanel should be used in combination with ``col*`` classnames added to each of the child Panels of the FieldRowPanel. The Wagtail editing interface is layed out using a grid system, in which the maximum width of the editor is 12 columns wide. Classes ``col1``-``col12`` can be applied to each child of a FieldRowPanel. The class ``col3`` will ensure that field appears 3 columns wide or a quarter the width. ``col4`` would cause the field to be 4 columns wide, or a third the width.