kopia lustrzana https://github.com/wagtail/wagtail
Convert StreamField reference to proper class definition markup
Matt Westcott
Matt Westcott
rodzic
37c2326150
commit
f3e33f849f
|
|
@ -3,36 +3,36 @@
|
|||
StreamField reference
|
||||
=====================
|
||||
|
||||
StreamField
|
||||
-----------
|
||||
.. class:: wagtail.core.fields.StreamField(blocks, blank=False, min_num=None, max_num=None, block_counts=None)
|
||||
|
||||
``wagtail.core.fields.StreamField``
|
||||
A model field for representing long-form content as a sequence of content blocks of various types. See :ref:`streamfield`.
|
||||
|
||||
A model field for representing long-form content as a sequence of content blocks of various types.
|
||||
:param blocks: A list of block types, passed as either a list of ``(name, block_definition)`` tuples or a ``StreamBlock`` instance.
|
||||
:param blank: When false (the default), at least one block must be provided for the field to be considered valid.
|
||||
:param min_num: Minimum number of sub-blocks that the stream must have.
|
||||
:param max_num: Maximum number of sub-blocks that the stream may have.
|
||||
:param block_counts: Specifies the minimum and maximum number of each block type, as a dictionary mapping block names to dicts with (optional) ``min_num`` and ``max_num`` fields.
|
||||
|
||||
Accepts a list of block types, passed as either a list of ``(name, block_type)`` tuples or a ``StreamBlock`` instance. Also accepts the following optional keyword arguments:
|
||||
.. code-block:: python
|
||||
|
||||
``blank`` (default: ``False``)
|
||||
When false, at least one block must be provided for the field to be considered valid.
|
||||
body = StreamField([
|
||||
('heading', blocks.CharBlock(form_classname="full title")),
|
||||
('paragraph', blocks.RichTextBlock()),
|
||||
('image', ImageChooserBlock()),
|
||||
], block_counts={
|
||||
'heading': {'min_num': 1},
|
||||
'image': {'max_num': 5},
|
||||
})
|
||||
|
||||
``min_num``
|
||||
Minimum number of sub-blocks that the stream must have.
|
||||
.. versionadded:: 2.13
|
||||
|
||||
``max_num``
|
||||
Maximum number of sub-blocks that the stream may have.
|
||||
|
||||
``block_counts``
|
||||
Specifies the minimum and maximum number of each block type, as a dictionary mapping block names to dicts with (optional) ``min_num`` and ``max_num`` fields.
|
||||
|
||||
.. versionadded:: 2.13
|
||||
|
||||
The ``min_num``, ``max_num`` and ``block_counts`` arguments were added. Previously, these were only available on the ``StreamBlock`` definition.
|
||||
The ``min_num``, ``max_num`` and ``block_counts`` arguments were added. Previously, these were only available on the ``StreamBlock`` definition.
|
||||
|
||||
|
||||
Block types
|
||||
-----------
|
||||
Block options
|
||||
-------------
|
||||
|
||||
All block types accept the following optional keyword arguments:
|
||||
All block definitions accept the following optional keyword arguments:
|
||||
|
||||
``default``
|
||||
The default value that a new 'empty' block should receive.
|
||||
|
|
@ -49,472 +49,442 @@ All block types accept the following optional keyword arguments:
|
|||
``group``
|
||||
The group used to categorize this block, i.e. any blocks with the same group name will be shown together in the editor interface with the group name as a heading.
|
||||
|
||||
CharBlock
|
||||
~~~~~~~~~
|
||||
|
||||
``wagtail.core.blocks.CharBlock``
|
||||
Field block types
|
||||
-----------------
|
||||
|
||||
A single-line text input. The following keyword arguments are accepted:
|
||||
.. class:: wagtail.core.blocks.CharBlock
|
||||
|
||||
``required`` (default: True)
|
||||
If true, the field cannot be left blank.
|
||||
A single-line text input. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
``max_length``, ``min_length``
|
||||
Ensures that the string is at most or at least the given length.
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param max_length: The maximum allowed length of the field.
|
||||
:param min_length: The minimum allowed length of the field.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
``help_text``
|
||||
Help text to display alongside the field.
|
||||
.. versionchanged:: 2.11
|
||||
|
||||
``validators``
|
||||
A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
The ``class`` attribute was previously set via the keyword argument ``classname``.
|
||||
|
||||
``form_classname``
|
||||
A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
.. versionchanged:: 2.11
|
||||
.. class:: wagtail.core.blocks.TextBlock
|
||||
|
||||
The ``class`` attribute was previously set via the keyword argument ``classname``.
|
||||
A multi-line text input. As with ``CharBlock``, the following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param max_length: The maximum allowed length of the field.
|
||||
:param min_length: The minimum allowed length of the field.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
TextBlock
|
||||
~~~~~~~~~
|
||||
|
||||
``wagtail.core.blocks.TextBlock``
|
||||
.. class:: wagtail.core.blocks.EmailBlock
|
||||
|
||||
A multi-line text input. As with ``CharBlock``, the keyword arguments ``required`` (default: True), ``max_length``, ``min_length``, ``help_text``, ``validators`` and ``form_classname`` are accepted.
|
||||
A single-line email input that validates that the value is a valid e-mail address. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
EmailBlock
|
||||
~~~~~~~~~~
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
``wagtail.core.blocks.EmailBlock``
|
||||
|
||||
A single-line email input that validates that the email is a valid Email Address. The keyword arguments ``required`` (default: True), ``help_text``, ``validators`` and ``form_classname`` are accepted.
|
||||
.. class:: wagtail.core.blocks.IntegerBlock
|
||||
|
||||
For an example of ``EmailBlock`` in use, see :ref:`streamfield_personblock_example`
|
||||
A single-line integer input that validates that the value is a valid whole number. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
IntegerBlock
|
||||
~~~~~~~~~~~~
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param max_value: The maximum allowed numeric value of the field.
|
||||
:param min_value: The minimum allowed numeric value of the field.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
``wagtail.core.blocks.IntegerBlock``
|
||||
|
||||
A single-line integer input that validates that the integer is a valid whole number. The keyword arguments ``required`` (default: True), ``max_value``, ``min_value``, ``help_text``, ``validators`` and ``form_classname`` are accepted.
|
||||
.. class:: wagtail.core.blocks.FloatBlock
|
||||
|
||||
For an example of ``IntegerBlock`` in use, see :ref:`streamfield_personblock_example`
|
||||
A single-line Float input that validates that the value is a valid floating point number. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
FloatBlock
|
||||
~~~~~~~~~~
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param max_value: The maximum allowed numeric value of the field.
|
||||
:param min_value: The minimum allowed numeric value of the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
``wagtail.core.blocks.FloatBlock``
|
||||
|
||||
A single-line Float input that validates that the value is a valid floating point number. The keyword arguments ``required`` (default: True), ``max_value``, ``min_value``, ``validators`` and ``form_classname`` are accepted.
|
||||
.. class:: wagtail.core.blocks.DecimalBlock
|
||||
|
||||
DecimalBlock
|
||||
~~~~~~~~~~~~
|
||||
A single-line decimal input that validates that the value is a valid decimal number. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
``wagtail.core.blocks.DecimalBlock``
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param max_value: The maximum allowed numeric value of the field.
|
||||
:param min_value: The minimum allowed numeric value of the field.
|
||||
:param max_digits: The maximum number of digits allowed in the number. This number must be greater than or equal to ``decimal_places``.
|
||||
:param decimal_places: The number of decimal places to store with the number.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
A single-line decimal input that validates that the value is a valid decimal number. The keyword arguments ``required`` (default: True), ``help_text``, ``max_value``, ``min_value``, ``max_digits``, ``decimal_places``, ``validators`` and ``form_classname`` are accepted.
|
||||
|
||||
For an example of ``DecimalBlock`` in use, see :ref:`streamfield_personblock_example`
|
||||
.. class:: wagtail.core.blocks.RegexBlock
|
||||
|
||||
RegexBlock
|
||||
~~~~~~~~~~
|
||||
A single-line text input that validates a string against a regular expression. The regular expression used for validation must be supplied as the first argument, or as the keyword argument ``regex``.
|
||||
|
||||
``wagtail.core.blocks.RegexBlock``
|
||||
.. code-block:: python
|
||||
|
||||
A single-line text input that validates a string against a regex expression. The regular expression used for validation must be supplied as the first argument, or as the keyword argument ``regex``. To customise the message text used to indicate a validation error, pass a dictionary as the keyword argument ``error_messages`` containing either or both of the keys ``required`` (for the message shown on an empty value) or ``invalid`` (for the message shown on a non-matching value):
|
||||
blocks.RegexBlock(regex=r'^[0-9]{3}$', error_messages={
|
||||
'invalid': "Not a valid library card number."
|
||||
})
|
||||
|
||||
.. code-block:: python
|
||||
The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
blocks.RegexBlock(regex=r'^[0-9]{3}$', error_messages={
|
||||
'invalid': "Not a valid library card number."
|
||||
})
|
||||
:param regex: Regular expression to validate against.
|
||||
:param error_messages: Dictionary of error messages, containing either or both of the keys ``required`` (for the message shown on an empty value) or ``invalid`` (for the message shown on a non-matching value).
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param max_length: The maximum allowed length of the field.
|
||||
:param min_length: The minimum allowed length of the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
The keyword arguments ``regex``, ``error_messages``, ``help_text``, ``required`` (default: True), ``max_length``, ``min_length``, ``validators`` and ``form_classname`` are accepted.
|
||||
|
||||
URLBlock
|
||||
~~~~~~~~
|
||||
.. class:: wagtail.core.blocks.URLBlock
|
||||
|
||||
``wagtail.core.blocks.URLBlock``
|
||||
A single-line text input that validates that the string is a valid URL. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
A single-line text input that validates that the string is a valid URL. The keyword arguments ``required`` (default: True), ``max_length``, ``min_length``, ``help_text``, ``validators`` and ``form_classname`` are accepted.
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param max_length: The maximum allowed length of the field.
|
||||
:param min_length: The minimum allowed length of the field.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
BooleanBlock
|
||||
~~~~~~~~~~~~
|
||||
|
||||
``wagtail.core.blocks.BooleanBlock``
|
||||
.. class:: wagtail.core.blocks.BooleanBlock
|
||||
|
||||
A checkbox. The keyword arguments ``required``, ``help_text`` and ``form_classname`` are accepted. As with Django's ``BooleanField``, a value of ``required=True`` (the default) indicates that the checkbox must be ticked in order to proceed. For a checkbox that can be ticked or unticked, you must explicitly pass in ``required=False``.
|
||||
A checkbox. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
DateBlock
|
||||
~~~~~~~~~
|
||||
:param required: If true (the default), the checkbox must be ticked to proceed. As with Django's ``BooleanField``, a checkbox that can be left ticked or unticked must be explicitly denoted with ``required=False``.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
``wagtail.core.blocks.DateBlock``
|
||||
|
||||
A date picker. The keyword arguments ``required`` (default: True), ``help_text``, ``validators``, ``form_classname`` and ``format`` are accepted.
|
||||
.. class:: wagtail.core.blocks.DateBlock
|
||||
|
||||
``format`` (default: None)
|
||||
Date format. This must be one of the recognised formats listed in the `DATE_INPUT_FORMATS <https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DATE_INPUT_FORMATS>`_ setting. If not specified Wagtail will use ``WAGTAIL_DATE_FORMAT`` setting with fallback to '%Y-%m-%d'.
|
||||
A date picker. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
TimeBlock
|
||||
~~~~~~~~~
|
||||
:param format: Date format. This must be one of the recognised formats listed in the `DATE_INPUT_FORMATS <https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DATE_INPUT_FORMATS>`_ setting. If not specified Wagtail will use the ``WAGTAIL_DATE_FORMAT`` setting with fallback to '%Y-%m-%d'.
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
``wagtail.core.blocks.TimeBlock``
|
||||
|
||||
A time picker. The keyword arguments ``required`` (default: True), ``help_text``, ``validators`` and ``form_classname`` are accepted.
|
||||
.. class:: wagtail.core.blocks.TimeBlock
|
||||
|
||||
DateTimeBlock
|
||||
~~~~~~~~~~~~~
|
||||
A time picker. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
``wagtail.core.blocks.DateTimeBlock``
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
A combined date / time picker. The keyword arguments ``required`` (default: True), ``help_text``, ``format``, ``validators`` and ``form_classname`` are accepted.
|
||||
|
||||
``format`` (default: None)
|
||||
Date format. This must be one of the recognised formats listed in the `DATETIME_INPUT_FORMATS <https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DATETIME_INPUT_FORMATS>`_ setting. If not specified Wagtail will use ``WAGTAIL_DATETIME_FORMAT`` setting with fallback to '%Y-%m-%d %H:%M'.
|
||||
.. class:: wagtail.core.blocks.DateTimeBlock
|
||||
|
||||
RichTextBlock
|
||||
~~~~~~~~~~~~~
|
||||
A combined date / time picker. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
``wagtail.core.blocks.RichTextBlock``
|
||||
:param format: Date/time format. This must be one of the recognised formats listed in the `DATETIME_INPUT_FORMATS <https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DATETIME_INPUT_FORMATS>`_ setting. If not specified Wagtail will use the ``WAGTAIL_DATETIME_FORMAT`` setting with fallback to '%Y-%m-%d %H:%M'.
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
A WYSIWYG editor for creating formatted text including links, bold / italics etc. The keyword arguments ``required`` (default: True), ``help_text``, ``validators``, ``form_classname``, ``editor`` and ``features`` are accepted.
|
||||
|
||||
``editor`` (default: ``default``)
|
||||
The rich text editor to be used (see :ref:`WAGTAILADMIN_RICH_TEXT_EDITORS`).
|
||||
.. class:: wagtail.core.blocks.RichTextBlock
|
||||
|
||||
``features`` (default: None)
|
||||
Specify the set of features allowed (see :ref:`rich_text_features`).
|
||||
A WYSIWYG editor for creating formatted text including links, bold / italics etc. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
:param editor: The rich text editor to be used (see :ref:`WAGTAILADMIN_RICH_TEXT_EDITORS`).
|
||||
:param features: Specifies the set of features allowed (see :ref:`rich_text_features`).
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
RawHTMLBlock
|
||||
~~~~~~~~~~~~
|
||||
|
||||
``wagtail.core.blocks.RawHTMLBlock``
|
||||
.. class:: wagtail.core.blocks.RawHTMLBlock
|
||||
|
||||
A text area for entering raw HTML which will be rendered unescaped in the page output. The keyword arguments ``required`` (default: True), ``max_length``, ``min_length``, ``help_text``, ``validators`` and ``form_classname`` are accepted.
|
||||
A text area for entering raw HTML which will be rendered unescaped in the page output. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
.. WARNING::
|
||||
When this block is in use, there is nothing to prevent editors from inserting malicious scripts into the page, including scripts that would allow the editor to acquire administrator privileges when another administrator views the page. Do not use this block unless your editors are fully trusted.
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param max_length: The maximum allowed length of the field.
|
||||
:param min_length: The minimum allowed length of the field.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
BlockQuoteBlock
|
||||
~~~~~~~~~~~~~~~
|
||||
.. WARNING::
|
||||
When this block is in use, there is nothing to prevent editors from inserting malicious scripts into the page, including scripts that would allow the editor to acquire administrator privileges when another administrator views the page. Do not use this block unless your editors are fully trusted.
|
||||
|
||||
``wagtail.core.blocks.BlockQuoteBlock``
|
||||
|
||||
A text field, the contents of which will be wrapped in an HTML `<blockquote>` tag pair. The keyword arguments ``required`` (default: True), ``max_length``, ``min_length``, ``help_text``, ``validators`` and ``form_classname`` are accepted.
|
||||
.. class:: wagtail.core.blocks.BlockQuoteBlock
|
||||
|
||||
A text field, the contents of which will be wrapped in an HTML `<blockquote>` tag pair in the page output. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
ChoiceBlock
|
||||
~~~~~~~~~~~
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param max_length: The maximum allowed length of the field.
|
||||
:param min_length: The minimum allowed length of the field.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
``wagtail.core.blocks.ChoiceBlock``
|
||||
|
||||
A dropdown select box for choosing from a list of choices. The following keyword arguments are accepted:
|
||||
.. class:: wagtail.core.blocks.ChoiceBlock
|
||||
|
||||
``choices``
|
||||
A list of choices, in any format accepted by Django's :attr:`~django.db.models.Field.choices` parameter for model fields, or a callable returning such a list.
|
||||
A dropdown select box for choosing one item from a list of choices. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
``required`` (default: True)
|
||||
If true, the field cannot be left blank.
|
||||
:param choices: A list of choices, in any format accepted by Django's :attr:`~django.db.models.Field.choices` parameter for model fields, or a callable returning such a list.
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param widget: The form widget to render the field with (see `Django Widgets <https://docs.djangoproject.com/en/stable/ref/forms/widgets/>`__).
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
``help_text``
|
||||
Help text to display alongside the field.
|
||||
``ChoiceBlock`` can also be subclassed to produce a reusable block with the same list of choices everywhere it is used. For example, a block definition such as:
|
||||
|
||||
``validators``
|
||||
A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
.. code-block:: python
|
||||
|
||||
``form_classname``
|
||||
A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
blocks.ChoiceBlock(choices=[
|
||||
('tea', 'Tea'),
|
||||
('coffee', 'Coffee'),
|
||||
], icon='cup')
|
||||
|
||||
``widget``
|
||||
The form widget to render the field with (see `Django Widgets <https://docs.djangoproject.com/en/stable/ref/forms/widgets/>`__).
|
||||
|
||||
``ChoiceBlock`` can also be subclassed to produce a reusable block with the same list of choices everywhere it is used. For example, a block definition such as:
|
||||
could be rewritten as a subclass of ChoiceBlock:
|
||||
|
||||
.. code-block:: python
|
||||
.. code-block:: python
|
||||
|
||||
blocks.ChoiceBlock(choices=[
|
||||
('tea', 'Tea'),
|
||||
('coffee', 'Coffee'),
|
||||
], icon='cup')
|
||||
class DrinksChoiceBlock(blocks.ChoiceBlock):
|
||||
choices = [
|
||||
('tea', 'Tea'),
|
||||
('coffee', 'Coffee'),
|
||||
]
|
||||
|
||||
class Meta:
|
||||
icon = 'cup'
|
||||
|
||||
could be rewritten as a subclass of ChoiceBlock:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class DrinksChoiceBlock(blocks.ChoiceBlock):
|
||||
choices = [
|
||||
('tea', 'Tea'),
|
||||
('coffee', 'Coffee'),
|
||||
]
|
||||
|
||||
class Meta:
|
||||
icon = 'cup'
|
||||
|
||||
|
||||
``StreamField`` definitions can then refer to ``DrinksChoiceBlock()`` in place of the full ``ChoiceBlock`` definition. Note that this only works when ``choices`` is a fixed list, not a callable.
|
||||
``StreamField`` definitions can then refer to ``DrinksChoiceBlock()`` in place of the full ``ChoiceBlock`` definition. Note that this only works when ``choices`` is a fixed list, not a callable.
|
||||
|
||||
|
||||
.. _streamfield_multiplechoiceblock:
|
||||
|
||||
MultipleChoiceBlock
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
.. class:: wagtail.core.blocks.MultipleChoiceBlock
|
||||
|
||||
``wagtail.core.blocks.MultipleChoiceBlock``
|
||||
A select box for choosing multiple items from a list of choices. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
A multiple select box for choosing from a list of choices. The following keyword arguments are accepted:
|
||||
|
||||
``choices``
|
||||
A list of choices, in any format accepted by Django's :attr:`~django.db.models.Field.choices` parameter for model fields, or a callable returning such a list.
|
||||
|
||||
``required`` (default: True)
|
||||
If true, the field cannot be left blank.
|
||||
|
||||
``help_text``
|
||||
Help text to display alongside the field.
|
||||
|
||||
``validators``
|
||||
A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
|
||||
``form_classname``
|
||||
A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
``widget``
|
||||
The form widget to render the field with (see `Django Widgets <https://docs.djangoproject.com/en/stable/ref/forms/widgets/>`__).
|
||||
:param choices: A list of choices, in any format accepted by Django's :attr:`~django.db.models.Field.choices` parameter for model fields, or a callable returning such a list.
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
:param widget: The form widget to render the field with (see `Django Widgets <https://docs.djangoproject.com/en/stable/ref/forms/widgets/>`__).
|
||||
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
|
||||
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
|
||||
|
||||
|
||||
PageChooserBlock
|
||||
~~~~~~~~~~~~~~~~
|
||||
.. class:: wagtail.core.blocks.PageChooserBlock
|
||||
|
||||
``wagtail.core.blocks.PageChooserBlock``
|
||||
A control for selecting a page object, using Wagtail's page browser. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
A control for selecting a page object, using Wagtail's page browser. The following keyword arguments are accepted:
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param page_type: Restrict choices to one or more specific page types; by default, any page type may be selected. Can be specified as a page model class, model name (as a string), or a list or tuple of these.
|
||||
:param can_choose_root: Defaults to false. If true, the editor can choose the tree root as a page. Normally this would be undesirable, since the tree root is never a usable page, but in some specialised cases it may be appropriate. For example, a block providing a feed of related articles could use a PageChooserBlock to select which subsection of the site articles will be taken from, with the root corresponding to 'everywhere'.
|
||||
|
||||
``required`` (default: True)
|
||||
If true, the field cannot be left blank.
|
||||
|
||||
``page_type`` (default: Page)
|
||||
Restrict choices to one or more specific page types. Accepts a page model class, model name (as a string), or a list or tuple of these.
|
||||
.. class:: wagtail.documents.blocks.DocumentChooserBlock
|
||||
|
||||
``can_choose_root`` (default: False)
|
||||
If true, the editor can choose the tree root as a page. Normally this would be undesirable, since the tree root is never a usable page, but in some specialised cases it may be appropriate. For example, a block providing a feed of related articles could use a PageChooserBlock to select which subsection of the site articles will be taken from, with the root corresponding to 'everywhere'.
|
||||
A control to allow the editor to select an existing document object, or upload a new one. The following additional keyword argument is accepted:
|
||||
|
||||
DocumentChooserBlock
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
|
||||
``wagtail.documents.blocks.DocumentChooserBlock``
|
||||
|
||||
A control to allow the editor to select an existing document object, or upload a new one. The keyword argument ``required`` (default: True) is accepted.
|
||||
.. class:: wagtail.images.blocks.ImageChooserBlock
|
||||
|
||||
ImageChooserBlock
|
||||
~~~~~~~~~~~~~~~~~
|
||||
A control to allow the editor to select an existing image, or upload a new one. The following additional keyword argument is accepted:
|
||||
|
||||
``wagtail.images.blocks.ImageChooserBlock``
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
|
||||
A control to allow the editor to select an existing image, or upload a new one. The keyword argument ``required`` (default: True) is accepted.
|
||||
|
||||
SnippetChooserBlock
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
.. class:: wagtail.snippets.blocks.SnippetChooserBlock
|
||||
|
||||
``wagtail.snippets.blocks.SnippetChooserBlock``
|
||||
A control to allow the editor to select a snippet object. Requires one positional argument: the snippet class to choose from. The following additional keyword argument is accepted:
|
||||
|
||||
A control to allow the editor to select a snippet object. Requires one positional argument: the snippet class to choose from. The keyword argument ``required`` (default: True) is accepted.
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
|
||||
EmbedBlock
|
||||
~~~~~~~~~~
|
||||
|
||||
``wagtail.embeds.blocks.EmbedBlock``
|
||||
.. class:: wagtail.embeds.blocks.EmbedBlock
|
||||
|
||||
A field for the editor to enter a URL to a media item (such as a YouTube video) to appear as embedded media on the page. The keyword arguments ``required`` (default: True), ``max_length``, ``min_length`` and ``help_text`` are accepted.
|
||||
A field for the editor to enter a URL to a media item (such as a YouTube video) to appear as embedded media on the page. The following keyword arguments are accepted in addition to the standard ones:
|
||||
|
||||
:param required: If true (the default), the field cannot be left blank.
|
||||
:param max_length: The maximum allowed length of the field.
|
||||
:param min_length: The minimum allowed length of the field.
|
||||
:param help_text: Help text to display alongside the field.
|
||||
|
||||
|
||||
Structural block types
|
||||
----------------------
|
||||
|
||||
.. _streamfield_staticblock:
|
||||
|
||||
StaticBlock
|
||||
~~~~~~~~~~~
|
||||
.. class:: wagtail.core.blocks.StaticBlock
|
||||
|
||||
``wagtail.core.blocks.StaticBlock``
|
||||
A block which doesn't have any fields, thus passes no particular values to its template during rendering. This can be useful if you need the editor to be able to insert some content which is always the same or doesn't need to be configured within the page editor, such as an address, embed code from third-party services, or more complex pieces of code if the template uses template tags. The following additional keyword argument is accepted:
|
||||
|
||||
A block which doesn't have any fields, thus passes no particular values to its template during rendering. This can be useful if you need the editor to be able to insert some content which is always the same or doesn't need to be configured within the page editor, such as an address, embed code from third-party services, or more complex pieces of code if the template uses template tags.
|
||||
:param admin_text: A text string to display in the admin when this block is used. By default, some default text (which contains the ``label`` keyword argument if you pass it) will be displayed in the editor interface, so that the block doesn't look empty, but this can be customised by passing ``admin_text``:
|
||||
|
||||
By default, some default text (which contains the ``label`` keyword argument if you pass it) will be displayed in the editor interface, so that the block doesn't look empty. But you can also customise it entirely by passing a text string as the ``admin_text`` keyword argument instead:
|
||||
.. code-block:: python
|
||||
|
||||
.. code-block:: python
|
||||
blocks.StaticBlock(
|
||||
admin_text='Latest posts: no configuration needed.',
|
||||
# or admin_text=mark_safe('<b>Latest posts</b>: no configuration needed.'),
|
||||
template='latest_posts.html')
|
||||
|
||||
blocks.StaticBlock(
|
||||
admin_text='Latest posts: no configuration needed.',
|
||||
# or admin_text=mark_safe('<b>Latest posts</b>: no configuration needed.'),
|
||||
template='latest_posts.html')
|
||||
``StaticBlock`` can also be subclassed to produce a reusable block with the same configuration everywhere it is used:
|
||||
|
||||
``StaticBlock`` can also be subclassed to produce a reusable block with the same configuration everywhere it is used:
|
||||
.. code-block:: python
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class LatestPostsStaticBlock(blocks.StaticBlock):
|
||||
class Meta:
|
||||
icon = 'user'
|
||||
label = 'Latest posts'
|
||||
admin_text = '{label}: configured elsewhere'.format(label=label)
|
||||
template = 'latest_posts.html'
|
||||
|
||||
StructBlock
|
||||
~~~~~~~~~~~
|
||||
|
||||
``wagtail.core.blocks.StructBlock``
|
||||
|
||||
A block consisting of a fixed group of sub-blocks to be displayed together. Takes a list of ``(name, block_definition)`` tuples as its first argument:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
('person', blocks.StructBlock([
|
||||
('first_name', blocks.CharBlock()),
|
||||
('surname', blocks.CharBlock()),
|
||||
('photo', ImageChooserBlock(required=False)),
|
||||
('biography', blocks.RichTextBlock()),
|
||||
], icon='user'))
|
||||
class LatestPostsStaticBlock(blocks.StaticBlock):
|
||||
class Meta:
|
||||
icon = 'user'
|
||||
label = 'Latest posts'
|
||||
admin_text = '{label}: configured elsewhere'.format(label=label)
|
||||
template = 'latest_posts.html'
|
||||
|
||||
|
||||
Alternatively, the list of sub-blocks can be provided in a subclass of StructBlock:
|
||||
.. class:: wagtail.core.blocks.StructBlock
|
||||
|
||||
.. code-block:: python
|
||||
A block consisting of a fixed group of sub-blocks to be displayed together. Takes a list of ``(name, block_definition)`` tuples as its first argument:
|
||||
|
||||
class PersonBlock(blocks.StructBlock):
|
||||
first_name = blocks.CharBlock()
|
||||
surname = blocks.CharBlock()
|
||||
photo = ImageChooserBlock(required=False)
|
||||
biography = blocks.RichTextBlock()
|
||||
.. code-block:: python
|
||||
|
||||
class Meta:
|
||||
icon = 'user'
|
||||
('person', blocks.StructBlock([
|
||||
('first_name', blocks.CharBlock()),
|
||||
('surname', blocks.CharBlock()),
|
||||
('photo', ImageChooserBlock(required=False)),
|
||||
('biography', blocks.RichTextBlock()),
|
||||
], icon='user'))
|
||||
|
||||
|
||||
The ``Meta`` class supports the properties ``default``, ``label``, ``icon`` and ``template``, which have the same meanings as when they are passed to the block's constructor.
|
||||
Alternatively, StructBlock can be subclassed to specify a reusable set of sub-blocks:
|
||||
|
||||
This defines ``PersonBlock()`` as a block type that can be re-used as many times as you like within your model definitions:
|
||||
.. code-block:: python
|
||||
|
||||
.. code-block:: python
|
||||
class PersonBlock(blocks.StructBlock):
|
||||
first_name = blocks.CharBlock()
|
||||
surname = blocks.CharBlock()
|
||||
photo = ImageChooserBlock(required=False)
|
||||
biography = blocks.RichTextBlock()
|
||||
|
||||
body = StreamField([
|
||||
('heading', blocks.CharBlock(form_classname="full title")),
|
||||
('paragraph', blocks.RichTextBlock()),
|
||||
('image', ImageChooserBlock()),
|
||||
('person', PersonBlock()),
|
||||
])
|
||||
|
||||
Further options are available for customising the display of a ``StructBlock`` within the page editor - see :ref:`custom_editing_interfaces_for_structblock`.
|
||||
|
||||
You can also customise how the value of a ``StructBlock`` is prepared for using in templates - see :ref:`custom_value_class_for_structblock`.
|
||||
class Meta:
|
||||
icon = 'user'
|
||||
|
||||
|
||||
The ``Meta`` class supports the properties ``default``, ``label``, ``icon`` and ``template``, which have the same meanings as when they are passed to the block's constructor.
|
||||
|
||||
ListBlock
|
||||
~~~~~~~~~
|
||||
This defines ``PersonBlock()`` as a block type for use in StreamField definitions:
|
||||
|
||||
``wagtail.core.blocks.ListBlock``
|
||||
.. code-block:: python
|
||||
|
||||
A block consisting of many sub-blocks, all of the same type. The editor can add an unlimited number of sub-blocks, and re-order and delete them. Takes the definition of the sub-block as its first argument:
|
||||
body = StreamField([
|
||||
('heading', blocks.CharBlock(form_classname="full title")),
|
||||
('paragraph', blocks.RichTextBlock()),
|
||||
('image', ImageChooserBlock()),
|
||||
('person', PersonBlock()),
|
||||
])
|
||||
|
||||
.. code-block:: python
|
||||
The following additional options are available as either keyword arguments or Meta class attributes:
|
||||
|
||||
('ingredients_list', blocks.ListBlock(blocks.CharBlock(label="Ingredient")))
|
||||
:param form_classname: An HTML ``class`` attribute to set on the root element of this block as displayed in the editing interface. Defaults to ``struct-block``; note that the admin interface has CSS styles defined on this class, so it is advised to include ``struct-block`` in this value when overriding. See :ref:`custom_editing_interfaces_for_structblock`.
|
||||
:param form_template: Path to a Django template to use to render this block's form. See :ref:`custom_editing_interfaces_for_structblock`.
|
||||
:param value_class: A subclass of ``wagtail.core.blocks.StructValue`` to use as the type of returned values for this block. See :ref:`custom_value_class_for_structblock`.
|
||||
|
||||
|
||||
Any block type is valid as the sub-block type, including structural types:
|
||||
.. class:: wagtail.core.blocks.ListBlock
|
||||
|
||||
.. code-block:: python
|
||||
A block consisting of many sub-blocks, all of the same type. The editor can add an unlimited number of sub-blocks, and re-order and delete them. Takes the definition of the sub-block as its first argument:
|
||||
|
||||
('ingredients_list', blocks.ListBlock(blocks.StructBlock([
|
||||
('ingredient', blocks.CharBlock()),
|
||||
('amount', blocks.CharBlock(required=False)),
|
||||
])))
|
||||
.. code-block:: python
|
||||
|
||||
To customise the class name of a ``ListBlock`` as it appears in the page editor, you can specify a ``form_classname`` attribute as a keyword argument to the ``ListBlock`` constructor:
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 4
|
||||
|
||||
('ingredients_list', blocks.ListBlock(blocks.StructBlock([
|
||||
('ingredient', blocks.CharBlock()),
|
||||
('amount', blocks.CharBlock(required=False)),
|
||||
]), form_classname='ingredients-list'))
|
||||
|
||||
Alternatively, you can add ``form_classname`` in a subclass's ``Meta``:
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 6
|
||||
|
||||
class IngredientsListBlock(blocks.ListBlock):
|
||||
ingredient = blocks.CharBlock()
|
||||
amount = blocks.CharBlock(required=False)
|
||||
|
||||
class Meta:
|
||||
form_classname = 'ingredients-list'
|
||||
('ingredients_list', blocks.ListBlock(blocks.CharBlock(label="Ingredient")))
|
||||
|
||||
|
||||
StreamBlock
|
||||
~~~~~~~~~~~
|
||||
Any block type is valid as the sub-block type, including structural types:
|
||||
|
||||
``wagtail.core.blocks.StreamBlock``
|
||||
.. code-block:: python
|
||||
|
||||
A block consisting of a sequence of sub-blocks of different types, which can be mixed and reordered at will. Used as the overall mechanism of the StreamField itself, but can also be nested or used within other structural block types. Takes a list of ``(name, block_definition)`` tuples as its first argument:
|
||||
('ingredients_list', blocks.ListBlock(blocks.StructBlock([
|
||||
('ingredient', blocks.CharBlock()),
|
||||
('amount', blocks.CharBlock(required=False)),
|
||||
])))
|
||||
|
||||
.. code-block:: python
|
||||
The following additional option is available as either a keyword argument or a Meta class attribute:
|
||||
|
||||
('carousel', blocks.StreamBlock(
|
||||
[
|
||||
('image', ImageChooserBlock()),
|
||||
('quotation', blocks.StructBlock([
|
||||
('text', blocks.TextBlock()),
|
||||
('author', blocks.CharBlock()),
|
||||
])),
|
||||
('video', EmbedBlock()),
|
||||
],
|
||||
icon='cogs'
|
||||
))
|
||||
:param form_classname: An HTML ``class`` attribute to set on the root element of this block as displayed in the editing interface.
|
||||
|
||||
|
||||
As with StructBlock, the list of sub-blocks can also be provided as a subclass of StreamBlock:
|
||||
.. class:: wagtail.core.blocks.StreamBlock
|
||||
|
||||
.. code-block:: python
|
||||
A block consisting of a sequence of sub-blocks of different types, which can be mixed and reordered at will. Used as the overall mechanism of the StreamField itself, but can also be nested or used within other structural block types. Takes a list of ``(name, block_definition)`` tuples as its first argument:
|
||||
|
||||
class CarouselBlock(blocks.StreamBlock):
|
||||
image = ImageChooserBlock()
|
||||
quotation = blocks.StructBlock([
|
||||
('text', blocks.TextBlock()),
|
||||
('author', blocks.CharBlock()),
|
||||
])
|
||||
video = EmbedBlock()
|
||||
.. code-block:: python
|
||||
|
||||
class Meta:
|
||||
icon='cogs'
|
||||
('carousel', blocks.StreamBlock(
|
||||
[
|
||||
('image', ImageChooserBlock()),
|
||||
('quotation', blocks.StructBlock([
|
||||
('text', blocks.TextBlock()),
|
||||
('author', blocks.CharBlock()),
|
||||
])),
|
||||
('video', EmbedBlock()),
|
||||
],
|
||||
icon='cogs'
|
||||
))
|
||||
|
||||
.. _streamfield_top_level_streamblock:
|
||||
|
||||
Since ``StreamField`` accepts an instance of ``StreamBlock`` as a parameter, in place of a list of block types, this makes it possible to re-use a common set of block types without repeating definitions:
|
||||
As with StructBlock, the list of sub-blocks can also be provided as a subclass of StreamBlock:
|
||||
|
||||
.. code-block:: python
|
||||
.. code-block:: python
|
||||
|
||||
class HomePage(Page):
|
||||
carousel = StreamField(CarouselBlock(max_num=10, block_counts={'video': {'max_num': 2}}))
|
||||
class CarouselBlock(blocks.StreamBlock):
|
||||
image = ImageChooserBlock()
|
||||
quotation = blocks.StructBlock([
|
||||
('text', blocks.TextBlock()),
|
||||
('author', blocks.CharBlock()),
|
||||
])
|
||||
video = EmbedBlock()
|
||||
|
||||
``StreamBlock`` accepts the following options as either keyword arguments or ``Meta`` properties:
|
||||
class Meta:
|
||||
icon='cogs'
|
||||
|
||||
``required`` (default: True)
|
||||
If true, at least one sub-block must be supplied. This is ignored when using the ``StreamBlock`` as the top-level block of a StreamField; in this case the StreamField's ``blank`` property is respected instead.
|
||||
.. _streamfield_top_level_streamblock:
|
||||
|
||||
``min_num``
|
||||
Minimum number of sub-blocks that the stream must have.
|
||||
Since ``StreamField`` accepts an instance of ``StreamBlock`` as a parameter, in place of a list of block types, this makes it possible to re-use a common set of block types without repeating definitions:
|
||||
|
||||
``max_num``
|
||||
Maximum number of sub-blocks that the stream may have.
|
||||
.. code-block:: python
|
||||
|
||||
``block_counts``
|
||||
Specifies the minimum and maximum number of each block type, as a dictionary mapping block names to dicts with (optional) ``min_num`` and ``max_num`` fields.
|
||||
class HomePage(Page):
|
||||
carousel = StreamField(CarouselBlock(max_num=10, block_counts={'video': {'max_num': 2}}))
|
||||
|
||||
``form_classname``
|
||||
Customise the class name added to a ``StreamBlock`` form in the page editor.
|
||||
``StreamBlock`` accepts the following additional options as either keyword arguments or ``Meta`` properties:
|
||||
|
||||
:param required: If true (the default), at least one sub-block must be supplied. This is ignored when using the ``StreamBlock`` as the top-level block of a StreamField; in this case the StreamField's ``blank`` property is respected instead.
|
||||
:param min_num: Minimum number of sub-blocks that the stream must have.
|
||||
:param max_num: Maximum number of sub-blocks that the stream may have.
|
||||
:param block_counts: Specifies the minimum and maximum number of each block type, as a dictionary mapping block names to dicts with (optional) ``min_num`` and ``max_num`` fields.
|
||||
:param form_classname: An HTML ``class`` attribute to set on the root element of this block as displayed in the editing interface.
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 4
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue