kopia lustrzana https://github.com/wagtail/wagtail
306 wiersze
14 KiB
ReStructuredText
306 wiersze
14 KiB
ReStructuredText
==========================================
|
|
Wagtail 1.0 release notes - IN DEVELOPMENT
|
|
==========================================
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 1
|
|
|
|
|
|
What's changed
|
|
==============
|
|
|
|
StreamField - a field type for freeform content
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
StreamField provides an editing model for freeform content such as blog posts and news stories, allowing diverse content types such as text, images, headings, video and more specialised types such as maps and charts to be mixed in any order. See :ref:`streamfield`.
|
|
|
|
|
|
Wagtail API - A RESTful API for your Wagtail site
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When installed, the new Wagtail API module provides a RESTful web API to your
|
|
Wagtail site. You can use this for accessing your raw field content for your
|
|
sites pages, images and documents in JSON format. See :doc:`/contrib/api/index`
|
|
|
|
|
|
MySQL support
|
|
~~~~~~~~~~~~~
|
|
|
|
Wagtail now officially supports MySQL as a database backend.
|
|
|
|
|
|
Minor changes
|
|
~~~~~~~~~~~~~
|
|
|
|
* Dropped Django 1.6 support
|
|
* Dropped Python 2.6 and 3.2 support
|
|
* Dropped Elasticsearch 0.90.x support
|
|
|
|
|
|
Core
|
|
----
|
|
|
|
* Added validation to prevent pages being created with only whitespace characters in their title fields
|
|
* The Page model now records the date/time that a page was first published, as the field ``first_published_at``
|
|
* Increased the maximum length of a page slug from 50 to 255 characters
|
|
* Added hooks ``register_rich_text_embed_handler`` and ``register_rich_text_link_handler`` for customising link / embed handling within rich text fields
|
|
|
|
|
|
Admin
|
|
-----
|
|
|
|
**UI**
|
|
|
|
* Improvements to the layout of the left-hand menu footer
|
|
* Menu items of custom apps are now highlighted when being used
|
|
* Added thousands separator for counters on dashboard
|
|
* Added contextual links to admin notification messages
|
|
* When copying pages, it is now possible to specify a place to copy to
|
|
* Added pagination to the snippets listing and chooser
|
|
* Page / document / image / snippet choosers now include a link to edit the chosen item
|
|
* Plain text fields in the page editor now use auto-expanding text areas
|
|
* Added "Add child page" button to admin userbar
|
|
|
|
|
|
**Page editor**
|
|
|
|
* Javascript includes in the admin backend have been moved to the HTML header, to accommodate form widgets that render inline scripts that depend on libraries such as jQuery
|
|
* The external link chooser in rich text areas now accepts URLs of the form '/some/local/path', to allow linking to non-Wagtail-controlled URLs within the local site
|
|
* Bare text entered in rich text areas is now automatically wrapped in a paragraph element
|
|
|
|
|
|
**Edit handlers API**
|
|
|
|
* ``FieldPanel`` now accepts an optional ``widget`` parameter to override the field's default form widget
|
|
* Page model fields without a ``FieldPanel`` are no longer displayed in the form
|
|
* No longer need to specify the base model on ``InlinePanel`` definitions
|
|
* Page classes can specify an edit_handler property to override the default Content / Promote / Settings tabbed interface
|
|
|
|
|
|
**Other admin changes**
|
|
|
|
* SCSS files in wagtailadmin now use absolute imports, to permit overriding by user stylesheets
|
|
* Removed the dependency on ``LOGIN_URL`` and ``LOGIN_REDIRECT_URL`` settings
|
|
* Password reset view names namespaced to wagtailadmin
|
|
* Removed the need to add permission check on admin views (now automated)
|
|
* Reversing ``django.contrib.auth.admin.login`` will no longer lead to Wagtails login view (making it easier to have front end views)
|
|
* Added cache-control headers to all admin views. This allows Varnish/Squid/CDN to run on vanilla settings in front of a Wagtail site
|
|
* Date / time pickers now consistently use times without seconds, to prevent Javascript behaviour glitches when focusing / unfocusing fields
|
|
* Added hook ``construct_homepage_summary_items`` for customising the site summary panel on the admin homepage
|
|
* Renamed the ``construct_wagtail_edit_bird`` hook to ``construct_wagtail_userbar``
|
|
|
|
|
|
|
|
Project template
|
|
----------------
|
|
|
|
* The Vagrantfile now listens on port 8000
|
|
* Removed ``LOGIN_URL`` and ``LOGIN_REDIRECT_URL`` settings (as Wagtail no longer requires these)
|
|
* Removed example Celery configuration from ``production.py`` and ``requirements.txt``
|
|
|
|
|
|
Search
|
|
------
|
|
|
|
* Search view accepts "page" GET parameter in line with pagination
|
|
|
|
|
|
Bug fixes
|
|
~~~~~~~~~
|
|
|
|
* The ``document_served`` signal now correctly passes the Document class as ``sender`` and the document as ``instance``
|
|
* Image edit page no longer throws ``OSError`` when the original image is missing
|
|
* Users are no longer logged out on changing password when SessionAuthenticationMiddleware is in use
|
|
|
|
|
|
Upgrade considerations
|
|
======================
|
|
|
|
Support for older Django/Python/Elasticsearch versions dropped
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This release drops support for Django 1.6, Python 2.6/3.2 and Elasticsearch 0.90.x. Please make sure these are updated before upgrading.
|
|
|
|
If you are upgrading from Elasticsearch 0.90.x, you may also need to update the ``elasticsearch`` pip package to a version greater than ``1.0`` as well.
|
|
|
|
Upgrading from the external ``wagtailapi`` module.
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you were previously using the external ``wagtailapi`` module, it is important to note these two backwards-incompatible changes.
|
|
|
|
**1. Representation of foreign keys has changed**
|
|
|
|
Foreign keys were previously represented by just the value of their primary key.
|
|
For example::
|
|
|
|
"feed_image": 1
|
|
|
|
This has now been changed to add some ``meta`` information::
|
|
|
|
"feed_image": {
|
|
"id": 1,
|
|
"meta": {
|
|
"type": "wagtailimages.Image",
|
|
"detail_url": "http://api.example.com/api/v1/images/1/"
|
|
}
|
|
}
|
|
|
|
|
|
**2. On the page detail view, the "parent" field has been moved out of meta**
|
|
|
|
Previously, there was a "parent" field in the "meta" section on the page detail
|
|
view::
|
|
|
|
{
|
|
"id": 10,
|
|
"meta": {
|
|
"type": "demo.BlogPage",
|
|
"parent": 2
|
|
},
|
|
|
|
...
|
|
}
|
|
|
|
|
|
This has now been moved to the top level. Also, the above change to how foreign
|
|
keys are represented applies to this field too::
|
|
|
|
{
|
|
"id": 10,
|
|
"meta": {
|
|
"type": "demo.BlogPage"
|
|
},
|
|
"parent": {
|
|
"id": 2,
|
|
"meta": {
|
|
"type": "demo.BlogIndexPage"
|
|
}
|
|
}
|
|
|
|
...
|
|
}
|
|
|
|
|
|
|
|
``InlinePanel`` definitions no longer need to specify the base model
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
In previous versions of Wagtail, inline child blocks on a page or snippet were defined using a declaration like::
|
|
|
|
InlinePanel(HomePage, 'carousel_items', label="Carousel items")
|
|
|
|
It is no longer necessary to pass the base model as a parameter, so this declaration should be changed to::
|
|
|
|
InlinePanel('carousel_items', label="Carousel items")
|
|
|
|
The old format is now deprecated; all existing ``InlinePanel`` declarations should be updated to the new format.
|
|
|
|
Celery no longer automatically used for sending notification emails
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Previously, Wagtail would try to use Celery whenever the ``djcelery`` module was
|
|
installed, even if Celery wasn't actually set up. This could cause a very hard
|
|
to track down problem where notification emails would not be sent so this
|
|
functionality has now been removed.
|
|
|
|
If you would like to keep using Celery for sending notification emails, have a
|
|
look at: `django-celery-email <https://pypi.python.org/pypi/django-celery-email>`_
|
|
|
|
You no longer need ``LOGIN_URL`` and ``LOGIN_REDIRECT_URL`` to point to Wagtail admin.
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you are upgrading from an older version of Wagtail, you probably want to remove these from your project settings.
|
|
|
|
Prevously, these two settings needed to be set to ``wagtailadmin_login`` and ``wagtailadmin_dashboard``
|
|
respectively or Wagtail would become very tricky to log in to. This is no longer the case and Wagtail
|
|
should work fine without them.
|
|
|
|
Login/Password reset views renamed
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
It was previously possible to reverse the Wagtail login using django.contrib.auth.views.login.
|
|
This is no longer possible. Update any references to ``wagtailadmin_login``.
|
|
|
|
Password reset view name has changed from ``password_reset`` to ``wagtailadmin_password_reset``.
|
|
|
|
Javascript includes in admin backend have been moved
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To improve compatibility with third-party form widgets, pages within the Wagtail admin backend now output their Javascript includes in the HTML header, rather than at the end of the page. If your project extends the admin backend (through the ``register_admin_menu_item`` hook, for example) you will need to ensure that all associated Javascript code runs correctly from the new location. In particular, any code that accesses HTML elements will need to be contained in an 'onload' handler (e.g. jQuery's ``$(document).ready()``).
|
|
|
|
EditHandler internal API has changed
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
While it is not an official Wagtail API, it has been possible for Wagtail site implementers to define their own ``EditHandler`` subclasses for use in panel definitions, to customise the behaviour of the page / snippet editing forms. If you have made use of this facility, you will need to update your custom EditHandlers, as this mechanism has been refactored (to allow EditHandler classes to keep a persistent reference to their corresponding model). If you have only used Wagtail's built-in panel types (``FieldPanel``, ``InlinePanel``, ``PageChooserPanel`` and so on), you are unaffected by this change.
|
|
|
|
Previously, functions like ``FieldPanel`` acted as 'factory' functions, where a call such as ``FieldPanel('title')`` constructed and returned an ``EditHandler`` subclass tailored to work on a 'title' field. These functions now return an object with a ``bind_to_model`` method instead; the EditHandler subclass can be obtained by calling this with the model class as a parameter. As a guide to updating your custom EditHandler code, you may wish to refer to `the relevant change to the Wagtail codebase <https://github.com/torchbox/wagtail/commit/121c01c7f7db6087a985fa8dc9957bc78b9f6a6a>`_.
|
|
|
|
chooser_panel templates are obsolete
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you have added your own custom admin views to the Wagtail admin (e.g. through the ``register_admin_urls`` hook), you may have used one of the following template includes to incorporate a chooser element for pages, documents, images or snippets into your forms:
|
|
|
|
- ``wagtailadmin/edit_handlers/chooser_panel.html``
|
|
- ``wagtailadmin/edit_handlers/page_chooser_panel.html``
|
|
- ``wagtaildocs/edit_handlers/document_chooser_panel.html``
|
|
- ``wagtailimages/edit_handlers/image_chooser_panel.html``
|
|
- ``wagtailsnippets/edit_handlers/snippet_chooser_panel.html``
|
|
|
|
All of these templates are now deprecated. Wagtail now provides a set of Django form widgets for this purpose - ``AdminPageChooser``, ``AdminDocumentChooser``, ``AdminImageChooser`` and ``AdminSnippetChooser`` - which can be used in place of the ``HiddenInput`` widget that these form fields were previously using. The field can then be rendered using the regular ``wagtailadmin/shared/field.html`` or ``wagtailadmin/shared/field_as_li.html`` template.
|
|
|
|
``document_served`` signal arguments have changed
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Previously, the ``document_served`` signal (which is fired whenever a user downloads a document) passed the document instance as the ``sender``. This has now been changed to correspond the behaviour of Django's built-in signals; ``sender`` is now the ``Document`` class, and the document instance is passed as the argument ``instance``. Any existing signal listeners that expect to receive the document instance in ``sender`` must now be updated to check the ``instance`` argument instead.
|
|
|
|
Custom image models must specify an ``admin_form_fields`` list
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Previously, the forms for creating and editing images followed Django's default behaviour of showing all fields defined on the model; this would include any custom fields specific to your project that you defined by subclassing ``AbstractImage`` and setting ``WAGTAILIMAGES_IMAGE_MODEL``. This behaviour is risky as it may lead to fields being unintentionally exposed to the user, and so Django has deprecated this, for removal in Django 1.8. Accordingly, if you create your own custom subclass of ``AbstractImage``, you must now provide an ``admin_form_fields`` property, listing the fields that should appear on the image creation / editing form - for example::
|
|
|
|
from wagtail.wagtailimages.models import AbstractImage, Image
|
|
|
|
class MyImage(AbstractImage):
|
|
photographer = models.CharField(max_length=255)
|
|
has_legal_approval = models.BooleanField()
|
|
|
|
admin_form_fields = Image.admin_form_fields + ['photographer']
|
|
|
|
Customising the tabbed interface
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Wagtail organises panels into three tabs: 'Content', 'Promote' and 'Settings'. Depending on the requirements of your site, you may wish to customise this for specific page types - for example, adding an additional tab for sidebar content. This can be done by specifying an ``edit_handler`` property on the page model. For example:
|
|
|
|
.. code-block:: python
|
|
|
|
from wagtail.wagtailadmin.edit_handlers import TabbedInterface, ObjectList
|
|
|
|
class BlogPage(Page):
|
|
# field definitions omitted
|
|
|
|
BlogPage.content_panels = [
|
|
FieldPanel('title', classname="full title"),
|
|
FieldPanel('date'),
|
|
FieldPanel('body', classname="full"),
|
|
]
|
|
BlogPage.sidebar_content_panels = [
|
|
SnippetChooserPanel('advert', Advert),
|
|
InlinePanel('related_links', label="Related links"),
|
|
]
|
|
|
|
BlogPage.edit_handler = TabbedInterface([
|
|
ObjectList(BlogPage.content_panels, heading='Content'),
|
|
ObjectList(BlogPage.sidebar_content_panels, heading='Sidebar content'),
|
|
ObjectList(BlogPage.promote_panels, heading='Promote'),
|
|
ObjectList(BlogPage.settings_panels, heading='Settings', classname="settings"),
|
|
])
|
|
|
|
``construct_wagtail_edit_bird`` hook has been renamed
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Previously you could customize the Wagtail userbar using the ``construct_wagtail_edit_bird`` hook.
|
|
The hook has been renamed to ``construct_wagtail_userbar``.
|
|
|
|
The old hook is now deprecated; all existing ``construct_wagtail_edit_bird`` declarations should be updated to the new hook.
|