diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 5ac174a88f..e8ca73f87a 100644 --- a/CHANGELOG.txt +++ b/CHANGELOG.txt @@ -14,6 +14,7 @@ Changelog * Fix: Correctly handle `date` objects on `human_readable_date` template tag (Jhonatan Lopes) * Docs: Add contributing development documentation on how to work with a fork of Wagtail (Nix Asteri, Dan Braghis) * Docs: Make sure the settings panel is listed in tabbed interface examples (Tibor Leupold) + * Docs: Update multiple pages in the reference sections and multiple page names to their US spelling instead of UK spelling (Victoria Poromon) * Maintenance: Move RichText HTML whitelist parser to use the faster, built in `html.parser` (Jake Howard) * Maintenance: Remove duplicate 'path' in default_exclude_fields_in_copy (Ramchandra Shahi Thakuri) * Maintenance: Update unit tests to always use the faster, built in `html.parser` & remove `html5lib` dependency (Jake Howard) diff --git a/docs/advanced_topics/deploying.md b/docs/advanced_topics/deploying.md index 29381ca5ec..4bb421304d 100644 --- a/docs/advanced_topics/deploying.md +++ b/docs/advanced_topics/deploying.md @@ -60,7 +60,7 @@ The django-storages Amazon S3 backends (`storages.backends.s3boto.S3BotoStorage` ### Cache -Wagtail is designed to leverage Django's [cache framework](inv:django#topics/cache) when available to accelerate page loads. The cache is especially useful for the Wagtail admin, which can't take advantage of conventional CDN caching. +Wagtail is designed to take adavantage of Django's [cache framework](inv:django#topics/cache) when available to accelerate page loads. The cache is especially useful for the Wagtail admin, which can't take advantage of conventional CDN caching. Wagtail supports any of Django's cache backend, however we recommend against using one tied to the specific process or environment Django is running (eg `FileBasedCache` or `LocMemCache`). diff --git a/docs/contributing/ui_guidelines.md b/docs/contributing/ui_guidelines.md index ea420d367d..5d32ac1893 100644 --- a/docs/contributing/ui_guidelines.md +++ b/docs/contributing/ui_guidelines.md @@ -166,7 +166,7 @@ When adding or updating an icon, 1. Run it through [SVGO](https://jakearchibald.github.io/svgomg/) with appropriate compression settings. 2. Manually remove any unnecessary attributes. Set the `viewBox` attribute, and remove `width` and `height` attributes. 3. Manually add its `id` attribute with a prefix of `icon-` and the icon name matching the file name. Keep the icon as named from its source if possible. -4. Add or preserve licensing information as a HTML comment starting with an exclamation mark: ``. For Font Awesome, we want: ``. For example, ``. +4. Add or preserve licensing information as an HTML comment starting with an exclamation mark: ``. For Font Awesome, we want: ``. For example, ``. 5. Add the icon to Wagtail’s own implementation of the `register_icons` hook, in alphabetical order. 6. Go to the styleguide and copy the Wagtail icons table according to instructions in the template, pasting the result in `wagtail_icons_table.txt`. 7. If the icon requires [right-to-left mirroring](https://rtlstyling.com/posts/rtl-styling#bidirectional-icons), add the `class="icon--directional"` attribute. diff --git a/docs/extending/adding_reports.md b/docs/extending/adding_reports.md index e59e3cba40..9163c7c14f 100644 --- a/docs/extending/adding_reports.md +++ b/docs/extending/adding_reports.md @@ -19,7 +19,7 @@ class UnpublishedChangesReportView(PageReportView): ## Defining your report -The most important attributes and methods to customise to define your report are: +The most important attributes and methods to customize to define your report are: ```{eval-rst} .. method:: get_queryset(self) @@ -88,7 +88,7 @@ and specific type of any pages. For our example, we might want to know when the (dictionary) A dictionary of any fields/attributes in ``list_export`` for which you wish to manually specify a heading for the spreadsheet -column, and their headings. If unspecified, the heading will be taken from the field ``verbose_name`` if applicable, and the +column and their headings. If unspecified, the heading will be taken from the field ``verbose_name`` if applicable, and the attribute string otherwise. For our example, ``last_published_at`` will automatically get a heading of ``"Last Published At"``, but a simple "Last Published" looks neater. We'll add that by setting ``export_headings``: diff --git a/docs/extending/admin_views.md b/docs/extending/admin_views.md index a39b2704c3..df1c1d260e 100644 --- a/docs/extending/admin_views.md +++ b/docs/extending/admin_views.md @@ -102,7 +102,7 @@ Now create a `templates/wagtailcalendar/` folder within the `wagtailcalendar` ap {% endblock %} ``` -Here we are overriding three of the blocks defined in the base template: `titletag` (which sets the content of the HTML `` tag), `extra_css` (which allows us to provide additional CSS styles specific to this page), and `content` (for the main content area of the page). We're also including the standard header bar component, and setting a title and icon. For a list of the recognised icon identifiers, see the [style guide](styleguide). +Here we are overriding three of the blocks defined in the base template: `titletag` (which sets the content of the HTML `<title>` tag), `extra_css` (which allows us to provide additional CSS styles specific to this page), and `content` (for the main content area of the page). We're also including the standard header bar component, and setting a title and icon. For a list of the recognized icon identifiers, see the [style guide](styleguide). Revisiting `/admin/calendar/` will now show the calendar within the Wagtail admin page furniture. @@ -192,7 +192,7 @@ The calendar will now be visible at the URL `/admin/calendar/month/`. ![A single calender month](../_static/images/adminviews_calendarmonth.png) -Finally we can alter our `wagtail_hooks.py` to include a group of custom menu items. This is similar to adding a single item but involves importing two more classes, `Menu` and `SubmenuMenuItem`. +Finally, we can alter our `wagtail_hooks.py` to include a group of custom menu items. This is similar to adding a single item but involves importing two more classes, `Menu` and `SubmenuMenuItem`. ```{code-block} python :emphasize-lines: 3,20-25 @@ -254,7 +254,7 @@ class CalendarViewSet(ViewSet): # This can be accessed at `/admin/calendar/` # and reverse-resolved with the name `calendar:index`. # This first URL will be used for the menu item, but it can be - # customised by overriding the `menu_url` property. + # customized by overriding the `menu_url` property. path('', index, name='index'), # This can be accessed at `/admin/calendar/month/` @@ -275,7 +275,7 @@ def register_viewset(): Compared to the previous example with the two separate hooks, this will result in a single menu item "Calendar" that takes you to the `/admin/calendar/` URL. The second URL will not have its own menu item, but it will still be accessible at `/admin/calendar/month/`. This is useful for grouping related views together, that may not necessarily need their own menu items. -For further customisations, refer to the {class}`~wagtail.admin.viewsets.base.ViewSet` documentation. +For further customizations, refer to the {class}`~wagtail.admin.viewsets.base.ViewSet` documentation. (using_base_viewsetgroup)= @@ -307,4 +307,4 @@ def register_viewset(): This will result in a top-level menu item "Agenda" with the two viewsets' menu items as sub-items, e.g. "Calendar" and "Events". -For further customisations, refer to the {class}`~wagtail.admin.viewsets.base.ViewSetGroup` documentation. +For further customizations, refer to the {class}`~wagtail.admin.viewsets.base.ViewSetGroup` documentation. diff --git a/docs/extending/audit_log.md b/docs/extending/audit_log.md index 8e9ca5450d..08392aef6c 100644 --- a/docs/extending/audit_log.md +++ b/docs/extending/audit_log.md @@ -7,7 +7,7 @@ Wagtail provides a mechanism to log actions performed on its objects. Common act The Wagtail admin uses the action log entries to provide a site-wide and page-specific history of changes. It uses a registry of 'actions' that provide additional context for the logged action. -The audit log-driven Page history replaces the revisions list page, but provides a filter for revision-specific entries. +The audit log-driven Page history replaces the revisions list page but provides a filter for revision-specific entries. ```{note} The audit log does not replace revisions. @@ -21,7 +21,7 @@ The `wagtail.log_actions.log` function can be used to add logging to your own co Adds an entry to the audit log. :param instance: The model instance that the action is performed on - :param action: The code name for the action being performed. This can be one of the names listed below, or a custom action defined through the :ref:`register_log_actions` hook. + :param action: The code name for the action being performed. This can be one of the names listed below or a custom action defined through the :ref:`register_log_actions` hook. :param user: Optional - the user initiating the action. For actions logged within an admin view, this defaults to the logged-in user. :param uuid: Optional - log entries given the same UUID indicates that they occurred as part of the same user action (for example a page being immediately published on creation). :param title: The string representation, of the instance being logged. By default, Wagtail will attempt to use the instance's ``str`` representation or ``get_admin_display_title`` for page objects. @@ -62,7 +62,7 @@ When adding logging, you need to log the action or actions that happen to the ob | `wagtail.publish` | The page was published | | `wagtail.publish.schedule` | The draft is scheduled for publishing | | `wagtail.publish.scheduled` | Draft published via `publish_scheduled` management command | -| `wagtail.schedule.cancel` | Draft scheduled for publishing cancelled via "Cancel scheduled publish" | +| `wagtail.schedule.cancel` | Draft scheduled for publishing canceled via "Cancel scheduled publish" | | `wagtail.unpublish` | The page was unpublished | | `wagtail.unpublish.scheduled` | Page unpublished via `publish_scheduled` management command | | `wagtail.lock` | Page was locked | @@ -80,7 +80,7 @@ When adding logging, you need to log the action or actions that happen to the ob | `wagtail.workflow.approve` | The draft was approved at a Workflow Task | | `wagtail.workflow.reject` | The draft was rejected, and changes were requested at a Workflow Task | | `wagtail.workflow.resume` | The draft was resubmitted to the workflow | -| `wagtail.workflow.cancel` | The workflow was cancelled | +| `wagtail.workflow.cancel` | The workflow was canceled | ## Log context diff --git a/docs/extending/custom_account_settings.md b/docs/extending/custom_account_settings.md index 695475ff19..24cba55077 100644 --- a/docs/extending/custom_account_settings.md +++ b/docs/extending/custom_account_settings.md @@ -1,13 +1,13 @@ (custom_account_settings)= -# Customising the user account settings form +# Customizing the user account settings form -This document describes how to customise the user account settings form that can be found by clicking "Account settings" +This document describes how to customize the user account settings form which can be found by clicking "Account settings" at the bottom of the main menu. ## Adding new panels -Each panel on this form is a separate model form which can operate on an instance of either the user model, or the {class}`wagtail.users.models.UserProfile`. +Each panel on this form is a separate model form that can operate on an instance of either the user model, or the {class}`wagtail.users.models.UserProfile`. ### Basic example @@ -113,7 +113,7 @@ class CustomSettingsPanel(BaseSettingsPanel): - `title` - The display name of the title - `order` - The order of the tab. The builtin Wagtail tabs start at `100` and increase by `100` for each tab -## Customising the template +## Customizing the template You can provide a custom template for the panel by specifying a template name: diff --git a/docs/extending/custom_bulk_actions.md b/docs/extending/custom_bulk_actions.md index 2db625a7cb..dd5bb28975 100644 --- a/docs/extending/custom_bulk_actions.md +++ b/docs/extending/custom_bulk_actions.md @@ -136,7 +136,7 @@ def check_perm(self, obj): return obj.has_perm('some_perm') # returns True or False ``` -The success message shown on the admin can be customised by overriding the `get_success_message` method. +The success message shown on the admin can be customized by overriding the `get_success_message` method. ```python def get_success_message(self, num_parent_objects, num_child_objects): diff --git a/docs/extending/custom_tasks.md b/docs/extending/custom_tasks.md index f2ba75ab3d..48b7f76645 100644 --- a/docs/extending/custom_tasks.md +++ b/docs/extending/custom_tasks.md @@ -122,7 +122,7 @@ class UserApprovalTask(Task): ## Customising behaviour -Both `Task` and `TaskState` have a number of methods that can be overridden to implement custom behaviour. Here are some of the most useful: +Both `Task` and `TaskState` have a number of methods that can be overridden to implement custom behavior. Here are some of the most useful: `Task.user_can_access_editor(obj, user)`, `Task.user_can_lock(obj, user)`, `Task.user_can_unlock(obj, user)`: @@ -174,7 +174,7 @@ Returns the name of a custom template to be used in rendering the data entry mod This performs the actions specified in `Task.get_actions(obj, user)`: it is passed an action name, for example, `approve`, and the relevant task state. By default, it calls `approve` and `reject` methods on the task state when the corresponding action names are passed through. Any additional data entered in a modal (see `get_form_for_action` and `get_actions`) is supplied as kwargs. -For example, let's say we wanted to add an additional option: cancelling the entire workflow: +For example, let's say we wanted to add an additional option: canceling the entire workflow: ```python def on_action(self, task_state, user, action_name): @@ -186,7 +186,7 @@ def on_action(self, task_state, user, action_name): `Task.get_task_states_user_can_moderate(user, **kwargs)`: -This returns a QuerySet of `TaskStates` (or subclasses) the given user can moderate - this is currently used to select objects to display on the user's dashboard. +This returns a QuerySet of `TaskStates` (or subclasses) that the given user can moderate - this is currently used to select objects to display on the user's dashboard. For example: @@ -215,7 +215,7 @@ def get_description(cls): Wagtail's notifications are sent by `wagtail.admin.mail.Notifier` subclasses: callables intended to be connected to a signal. -By default, email notifications are sent upon workflow submission, approval and rejection, and upon submission to a group approval task. +By default, email notifications are sent upon workflow submission, approval, and rejection, and upon submission to a group approval task. As an example, we'll add email notifications for when our new task is started. @@ -237,7 +237,7 @@ class BaseUserApprovalTaskStateEmailNotifier(EmailNotificationMixin, Notifier): def can_handle(self, instance, **kwargs): if super().can_handle(instance, **kwargs) and isinstance(instance.task.specific, UserApprovalTask): - # Don't send notifications if a Task has been cancelled and then resumed - when object was updated to a new revision + # Don't send notifications if a Task has been canceled and then resumed - when object was updated to a new revision return not TaskState.objects.filter(workflow_state=instance.workflow_state, task=instance.task, status=TaskState.STATUS_CANCELLED).exists() return False diff --git a/docs/extending/customising_group_views.md b/docs/extending/customizing_group_views.md similarity index 87% rename from docs/extending/customising_group_views.md rename to docs/extending/customizing_group_views.md index 3e56d16737..4b0a0f7e33 100644 --- a/docs/extending/customising_group_views.md +++ b/docs/extending/customizing_group_views.md @@ -1,12 +1,12 @@ -(customising_group_views)= +(customizing_group_views)= -# Customising group edit/create views +# Customizing group edit/create views -The views for managing groups within the app are collected into a 'viewset' class, which acts as a single point of reference for all shared components of those views, such as forms. By subclassing the viewset, it is possible to override those components and customise the behaviour of the group management interface. +The views for managing groups within the app are collected into a 'viewset' class, which acts as a single point of reference for all shared components of those views, such as forms. By subclassing the viewset, it is possible to override those components and customize the behavior of the group management interface. ## Custom edit/create forms -This example shows how to customise forms on the 'edit group' and 'create group' views in the Wagtail admin. +This example shows how to customize forms on the 'edit group' and 'create group' views in the Wagtail admin. Let's say you need to connect Active Directory groups with Django groups. We create a model for Active Directory groups as follows: @@ -107,11 +107,11 @@ INSTALLED_APPS = [ ] ``` -(customising_group_views_permissions_order)= +(customizing_group_views_permissions_order)= -## Customising the group editor permissions ordering +## Customizing the group editor permissions ordering -The order that object types appear in the group editor's "Object permissions" and "Other permissions" sections can be configured by registering that order in one or more `AppConfig` definitions. The order value is typically an integer between 0 and 999, although this is not enforced. +The order in which object types appear in the group editor's "Object permissions" and "Other permissions" sections can be configured by registering that order in one or more `AppConfig` definitions. The order value is typically an integer between 0 and 999, although this is not enforced. ```python from django.apps import AppConfig diff --git a/docs/extending/extending_client_side.md b/docs/extending/extending_client_side.md index 29d9310c57..fbf0c4e5c9 100644 --- a/docs/extending/extending_client_side.md +++ b/docs/extending/extending_client_side.md @@ -1,15 +1,15 @@ (extending_client_side)= -# Extending client-side behaviour +# Extending client-side behavior -Many kinds of common customisations can be done without reaching into JavaScript, but depending on what parts of the client-side interaction you want to leverage or customise, you may need to employ React, Stimulus, or plain (vanilla) JS. +Many kinds of common customizations can be done without reaching into JavaScript, but depending on what parts of the client-side interaction you want to leverage or customize, you may need to employ React, Stimulus, or plain (vanilla) JS. [React](https://reactjs.org/) is used for more complex parts of Wagtail, such as the sidebar, commenting system, and the Draftail rich-text editor. For basic JavaScript-driven interaction, Wagtail is migrating towards [Stimulus](https://stimulus.hotwired.dev/). -You don't need to know or use these libraries to add your custom behaviour to elements, and in many cases, simple JavaScript will work fine, but Stimulus is the recommended approach for more complex use cases. +You don't need to know or use these libraries to add your custom behavior to elements, and in many cases, simple JavaScript will work fine, but Stimulus is the recommended approach for more complex use cases. -You don't need to have Node.js tooling running for your custom Wagtail installation for many customisations built on these libraries, but in some cases, such as building packages, it may make more complex development easier. +You don't need to have Node.js tooling running for your custom Wagtail installation for many customizations built on these libraries, but in some cases, such as building packages, it may make more complex development easier. ```{note} Avoid using jQuery and undocumented jQuery plugins, as they will be removed in a future version of Wagtail. @@ -33,13 +33,13 @@ These will ensure the added files are used in the admin after the core JavaScrip ## Extending with DOM events -When approaching client-side customisations or adopting new components, try to keep the implementation simple first, you may not need any knowledge of Stimulus, React, JavaScript Modules or a build system to achieve your goals. +When approaching client-side customizations or adopting new components, try to keep the implementation simple first, you may not need any knowledge of Stimulus, React, JavaScript Modules, or a build system to achieve your goals. -The simplest way to attach behaviour to the browser is via [DOM Events](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events) and plain (vanilla) JavaScript. +The simplest way to attach behavior to the browser is via [DOM Events](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events) and plain (vanilla) JavaScript. ### Wagtail's custom DOM events -Wagtail supports some custom behaviour via listening or dispatching custom DOM events. +Wagtail supports some custom behavior via listening or dispatching custom DOM events. - See [Images title generation on upload](images_title_generation_on_upload). - See [Documents title generation on upload](docs_title_generation_on_upload). @@ -51,7 +51,7 @@ Wagtail supports some custom behaviour via listening or dispatching custom DOM e Wagtail uses [Stimulus](https://stimulus.hotwired.dev/) as a way to provide lightweight client-side interactivity or custom JavaScript widgets within the admin interface. -The key benefit of using Stimulus is that your code can avoid the need for manual initialisation when widgets appear dynamically, such as within modals, `InlinePanel`, or `StreamField` panels. +The key benefit of using Stimulus is that your code can avoid the need for manual initialization when widgets appear dynamically, such as within modals, `InlinePanel`, or `StreamField` panels. The [Stimulus handbook](https://stimulus.hotwired.dev/handbook/introduction) is the best source on how to work with and understand Stimulus. @@ -211,7 +211,7 @@ You should be able to see that on your Blog Pages, the introduction field will n For more complex widgets we can now integrate additional libraries whenever the widget appears in the rendered HTML, either on initial load or dynamically without the need for any inline `script` elements. -In this example we will build a color picker widget using the [Coloris](https://coloris.js.org/) JavaScript library with support for custom widget options. +In this example, we will build a color picker widget using the [Coloris](https://coloris.js.org/) JavaScript library with support for custom widget options. First, let's start with the HTML, building on the [Django widgets](inv:django#ref/forms/widgets) system that Wagtail supports for `FieldPanel` and `FieldBlock`. Using the `build_attrs` method, we build up the appropriate Stimulus data attributes to support common data structures being passed into the controller. @@ -346,7 +346,7 @@ You may want to avoid bundling Stimulus with your JavaScript output and treat th ## Extending with React -To customise or extend the [React](https://reactjs.org/) components, you may need to use React too, as well as other related libraries. +To customize or extend the [React](https://reactjs.org/) components, you may need to use React too, as well as other related libraries. To make this easier, Wagtail exposes its React-related dependencies as global variables within the admin. Here are the available packages: diff --git a/docs/extending/extending_draftail.md b/docs/extending/extending_draftail.md index a60dfef352..3eff344862 100644 --- a/docs/extending/extending_draftail.md +++ b/docs/extending/extending_draftail.md @@ -35,7 +35,7 @@ def register_mark_feature(features): 'type': type_, 'label': '☆', 'description': 'Mark', - # This isn’t even required – Draftail has predefined styles for MARK. + # This isn’t even required – Draftail has predefined styles for MARK. # 'style': {'textDecoration': 'line-through'}, } @@ -67,7 +67,7 @@ These steps will always be the same for all Draftail plugins. The important part For detailed configuration options, head over to the [Draftail documentation](https://www.draftail.org/docs/formatting-options) to see all of the details. Here are some parts worth highlighting about controls: - The `type` is the only mandatory piece of information. -- To display the control in the toolbar, combine `icon`, `label` and `description`. +- To display the control in the toolbar, combine `icon`, `label`, and `description`. - `icon` is an icon name [registered in the Wagtail icon library](../../advanced_topics/icons) - for example, `'icon': 'user',`. It can also be an array of strings, to use SVG paths, or SVG symbol references for example `'icon': ['M100 100 H 900 V 900 H 100 Z'],`. The paths need to be set for a 1024x1024 viewbox. ### Creating new inline styles @@ -143,7 +143,7 @@ Here are the main requirements to create a new entity feature: - The editor plugin must define a `source`: a React component responsible for creating new entity instances in the editor, using the Draft.js API. - The editor plugin also needs a `decorator` (for inline entities) or `block` (for block entities): a React component responsible for displaying entity instances within the editor. - Like for inline styles and blocks, set up the to/from DB conversion. -- The conversion usually is more involved, since entities contain data that needs to be serialised to HTML. +- The conversion usually is more involved, since entities contain data that needs to be serialized to HTML. To write the React components, Wagtail exposes its own React, Draft.js, and Draftail dependencies as global variables. Read more about this in [extending client-side React components](extending_client_side_react). To go further, please look at the [Draftail documentation](https://www.draftail.org/docs/formatting-options) as well as the [Draft.js exporter documentation](https://github.com/springload/draftjs_exporter). @@ -303,7 +303,7 @@ This is a straightforward React component. It does not use JSX since we do not w Finally, we register the JS components of our plugin: ```javascript -// Register the plugin directly on script execution so the editor loads it when initialising. +// Register the plugin directly on script execution so the editor loads it when initializing. window.draftail.registerPlugin({ type: 'STOCK', source: StockSource, @@ -339,10 +339,10 @@ Custom block entities can also be created (have a look at the separate [Draftail ## Other editor extensions -Draftail has additional APIs for more complex customisations: +Draftail has additional APIs for more complex customizations: - **Controls** – To add arbitrary UI elements to editor toolbars. -- **Decorators** – For arbitrary text decorations / highlighting. +- **Decorators** – For arbitrary text decorations/highlighting. - **Plugins** – For direct access to all Draft.js APIs. ### Custom toolbar controls @@ -418,7 +418,7 @@ The [decorators API](https://www.draftail.org/docs/decorators) is how Draftail / There are two important considerations when using this API: - Order matters: only one decorator can render per character in the editor. This includes any entities that are rendered as decorations. -- For performance reasons, Draft.js only re-renders decorators that are on the currently-focused line of text. +- For performance reasons, Draft.js only re-renders decorators that are on the currently focused line of text. Here is an example with highlighting of problematic punctuation – first, registering the editor feature in a `wagtail_hooks.py`: @@ -478,7 +478,7 @@ window.draftail.registerPlugin({ This is an advanced feature. Please carefully consider whether you really need this. ``` -Draftail supports plugins following the [Draft.js Plugins](https://www.draft-js-plugins.com/) architecture. Such plugins are the most advanced and powerful type of extension for the editor, offering customisation capabilities equal to what would be possible with a custom Draft.js editor. +Draftail supports plugins following the [Draft.js Plugins](https://www.draft-js-plugins.com/) architecture. Such plugins are the most advanced and powerful type of extension for the editor, offering customization capabilities equal to what would be possible with a custom Draft.js editor. A common scenario where this API can help is to add bespoke copy-paste processing. Here is a simple example, automatically converting URL anchor hash references to links. First, let’s register the extension in Python: @@ -544,8 +544,8 @@ window.draftail.registerPlugin(anchorifyPlugin, 'plugins'); ## Integration of the Draftail widgets -To further customise how the Draftail widgets are integrated into the UI, there are additional extension points for CSS and JS: +To further customize how the Draftail widgets are integrated into the UI, there are additional extension points for CSS and JS: -- In JavaScript, use the `[data-draftail-input]` attribute selector to target the input which contains the data, and `[data-draftail-editor-wrapper]` for the element which wraps the editor. +- In JavaScript, use the `[data-draftail-input]` attribute selector to target the input that contains the data, and `[data-draftail-editor-wrapper]` for the element that wraps the editor. - The editor instance is bound to the input field for imperative access. Use `document.querySelector('[data-draftail-input]').draftailEditor`. - In CSS, use the classes prefixed with `Draftail-`. diff --git a/docs/extending/forms.md b/docs/extending/forms.md index 8abd99bbd9..9694fc36e5 100644 --- a/docs/extending/forms.md +++ b/docs/extending/forms.md @@ -66,10 +66,10 @@ See [](/reference/pages/panels) for the set of panel types provided by Wagtail. A view performs the following steps to render a model form through the panels mechanism: -- The top-level panel object for the model is retrieved. Usually this is done by looking up the model's `edit_handler` property and falling back on an `ObjectList` consisting of children given by the model's `panels` property. However, it may come from elsewhere - for example, snippets can define their panels via the `SnippetViewSet` class. +- The top-level panel object for the model is retrieved. Usually, this is done by looking up the model's `edit_handler` property and falling back on an `ObjectList` consisting of children given by the model's `panels` property. However, it may come from elsewhere - for example, snippets can define their panels via the `SnippetViewSet` class. - If the `PanelsGroup`s permissions do not allow a user to see this panel, then nothing more will be done. - This can be modified using the `permission` keyword argument, see examples of this usage in [](customising_the_tabbed_interface) and [](panels_permissions). -- The view calls `bind_to_model` on the top-level panel, passing the model class, and this returns a clone of the panel with a `model` property. As part of this process the `on_model_bound` method is invoked on each child panel, to allow it to perform additional initialisation that requires access to the model (for example, this is where `FieldPanel` retrieves the model field definition). +- The view calls `bind_to_model` on the top-level panel, passing the model class, and this returns a clone of the panel with a `model` property. As part of this process, the `on_model_bound` method is invoked on each child panel, to allow it to perform additional initialization that requires access to the model (for example, this is where `FieldPanel` retrieves the model field definition). - The view then calls `get_form_class` on the top-level panel to retrieve a ModelForm subclass that can be used to edit the model. This proceeds as follows: - Retrieve a base form class from the model's `base_form_class` property, falling back on `wagtail.admin.forms.WagtailAdminModelForm` - Call `get_form_options` on each child panel - which returns a dictionary of properties including `fields` and `widgets` - and merge the results into a single dictionary diff --git a/docs/extending/generic_views.md b/docs/extending/generic_views.md index 66ca0b3bd7..0ab692b385 100644 --- a/docs/extending/generic_views.md +++ b/docs/extending/generic_views.md @@ -55,7 +55,7 @@ def register_viewset(): return person_viewset ``` -The viewset can be further customised by overriding other attributes and methods. +The viewset can be further customized by overriding other attributes and methods. ### Icon @@ -69,9 +69,9 @@ The {attr}`~.ViewSet.url_prefix` and {attr}`~.ViewSet.url_namespace` properties ### Menu item -By default, registering a `ModelViewSet` will not register a main menu item. To add a menu item, set {attr}`~.ViewSet.add_to_admin_menu` to `True`. Alternatively, if you want to add the menu item inside the "Settings" menu, you can set {attr}`~.ViewSet.add_to_settings_menu` to `True`. Unless {attr}`~.ViewSet.menu_icon` is specified, the menu will use the same {attr}`~.ViewSet.icon` used for the views. The {attr}`~.ViewSet.menu_url` property can be overridden to customise the menu item's link, which defaults to the listing view for the model. +By default, registering a `ModelViewSet` will not register a main menu item. To add a menu item, set {attr}`~.ViewSet.add_to_admin_menu` to `True`. Alternatively, if you want to add the menu item inside the "Settings" menu, you can set {attr}`~.ViewSet.add_to_settings_menu` to `True`. Unless {attr}`~.ViewSet.menu_icon` is specified, the menu will use the same {attr}`~.ViewSet.icon` used for the views. The {attr}`~.ViewSet.menu_url` property can be overridden to customize the menu item's link, which defaults to the listing view for the model. -Unless specified, the menu item will be labelled after the model's verbose name. You can customise the menu item's label, name, and order by setting the {attr}`~.ViewSet.menu_label`, {attr}`~.ViewSet.menu_name`, and {attr}`~.ViewSet.menu_order` attributes respectively. If you would like to customise the `MenuItem` instance completely, you could override the {meth}`~.ViewSet.get_menu_item` method. +Unless specified, the menu item will be labeled after the model's verbose name. You can customize the menu item's label, name, and order by setting the {attr}`~.ViewSet.menu_label`, {attr}`~.ViewSet.menu_name`, and {attr}`~.ViewSet.menu_order` attributes respectively. If you would like to customize the `MenuItem` instance completely, you could override the {meth}`~.ViewSet.get_menu_item` method. You can group multiple `ModelViewSet`s' menu items inside a single top-level menu item using the {class}`~wagtail.admin.viewsets.model.ModelViewSetGroup` class. It is similar to `ViewSetGroup`, except it takes the {attr}`~django.db.models.Options.app_label` of the first viewset's model as the default {attr}`~.ViewSetGroup.menu_label`. Refer to [the examples for `ViewSetGroup`](using_base_viewsetgroup) for more details. @@ -79,13 +79,13 @@ You can group multiple `ModelViewSet`s' menu items inside a single top-level men ### Listing view -The {attr}`~ModelViewSet.list_display` attribute can be set to specify the columns shown on the listing view. To customise the number of items to be displayed per page, you can set the {attr}`~ModelViewSet.list_per_page` attribute. Additionally, the {attr}`~ModelViewSet.ordering` attribute can be used to override the `default_ordering` configured in the listing view. +The {attr}`~ModelViewSet.list_display` attribute can be set to specify the columns shown on the listing view. To customize the number of items to be displayed per page, you can set the {attr}`~ModelViewSet.list_per_page` attribute. Additionally, the {attr}`~ModelViewSet.ordering` attribute can be used to override the `default_ordering` configured in the listing view. You can add the ability to filter the listing view by defining a {attr}`~ModelViewSet.list_filter` attribute and specifying the list of fields to filter. Wagtail uses the django-filter package under the hood, and this attribute will be passed as django-filter's `FilterSet.Meta.fields` attribute. This means you can also pass a dictionary that maps the field name to a list of lookups. -If you would like to make further customisations to the filtering mechanism, you can also use a custom `wagtail.admin.filters.WagtailFilterSet` subclass by overriding the {attr}`~ModelViewSet.filterset_class` attribute. The `list_filter` attribute is ignored if `filterset_class` is set. For more details, refer to [django-filter's documentation](https://django-filter.readthedocs.io/en/stable/guide/usage.html#the-filter). +If you would like to make further customizations to the filtering mechanism, you can also use a custom `wagtail.admin.filters.WagtailFilterSet` subclass by overriding the {attr}`~ModelViewSet.filterset_class` attribute. The `list_filter` attribute is ignored if `filterset_class` is set. For more details, refer to [django-filter's documentation](https://django-filter.readthedocs.io/en/stable/guide/usage.html#the-filter). -You can add the ability to export the listing view to a spreadsheet by setting the {attr}`~ModelViewSet.list_export` attribute to specify the columns to be exported. The {attr}`~ModelViewSet.export_filename` attribute can be used to customise the file name of the exported spreadsheet. +You can add the ability to export the listing view to a spreadsheet by setting the {attr}`~ModelViewSet.list_export` attribute to specify the columns to be exported. The {attr}`~ModelViewSet.export_filename` attribute can be used to customize the file name of the exported spreadsheet. (modelviewset_create_edit)= @@ -93,7 +93,7 @@ You can add the ability to export the listing view to a spreadsheet by setting t You can define a `panels` or `edit_handler` attribute on the `ModelViewSet` or your Django model to use Wagtail's panels mechanism. For more details, see [](forms_panels_overview). -If neither `panels` nor `edit_handler` is defined and the {meth}`~ModelViewSet.get_edit_handler` method is not overridden, the form will be rendered as a plain Django form. You can customise the form by setting the {attr}`~ModelViewSet.form_fields` attribute to specify the fields to be shown on the form. Alternatively, you can set the {attr}`~ModelViewSet.exclude_form_fields` attribute to specify the fields to be excluded from the form. If panels are not used, you must define `form_fields` or `exclude_form_fields`, unless {meth}`~ModelViewSet.get_form_class` is overridden. +If neither `panels` nor `edit_handler` is defined and the {meth}`~ModelViewSet.get_edit_handler` method is not overridden, the form will be rendered as a plain Django form. You can customize the form by setting the {attr}`~ModelViewSet.form_fields` attribute to specify the fields to be shown on the form. Alternatively, you can set the {attr}`~ModelViewSet.exclude_form_fields` attribute to specify the fields to be excluded from the form. If panels are not used, you must define `form_fields` or `exclude_form_fields`, unless {meth}`~ModelViewSet.get_form_class` is overridden. (modelviewset_copy)= @@ -115,7 +115,7 @@ The inspect view is disabled by default, as it's not often useful for most model When inspect view is enabled, an 'Inspect' button will automatically appear for each row on the listing view, which takes you to a view that shows a list of field values for that particular instance. -By default, all 'concrete' fields (where the field value is stored as a column in the database table for your model) will be shown. You can customise what values are displayed by specifying the {attr}`~ModelViewSet.inspect_view_fields` or the {attr}`~ModelViewSet.inspect_view_fields_exclude` attributes on your `ModelViewSet` class. +By default, all 'concrete' fields (where the field value is stored as a column in the database table for your model) will be shown. You can customize what values are displayed by specifying the {attr}`~ModelViewSet.inspect_view_fields` or the {attr}`~ModelViewSet.inspect_view_fields_exclude` attributes on your `ModelViewSet` class. (modelviewset_templates)= @@ -129,21 +129,21 @@ If {attr}`~ModelViewSet.template_prefix` is set, Wagtail will look for the views To override the template used by the `IndexView` for example, you could create a new `index.html` template and put it in one of those locations. For example, given `custom/campaign` as the `template_prefix` and a `Shirt` model in a `merch` app, you could add your custom template as `templates/custom/campaign/merch/shirt/index.html`. -For some common views, Wagtail also allows you to override the template used by overriding the `{view_name}_template_name` property on the viewset. The following is a list of customisation points for the views: +For some common views, Wagtail also allows you to override the template used by overriding the `{view_name}_template_name` property on the viewset. The following is a list of customization points for the views: - `IndexView`: `index.html` or {attr}`~ModelViewSet.index_template_name` - - For the results fragment used in AJAX responses (e.g. when searching), customise `index_results.html` or {attr}`~ModelViewSet.index_results_template_name` + - For the results fragment used in AJAX responses (e.g. when searching), customize `index_results.html` or {attr}`~ModelViewSet.index_results_template_name` - `CreateView`: `create.html` or {attr}`~ModelViewSet.create_template_name` - `EditView`: `edit.html` or {attr}`~ModelViewSet.edit_template_name` - `DeleteView`: `delete.html` or {attr}`~ModelViewSet.delete_template_name` - `HistoryView`: `history.html` or {attr}`~ModelViewSet.history_template_name` - `InspectView`: `inspect.html` or {attr}`~ModelViewSet.inspect_template_name` -### Other customisations +### Other customizations By default, the model registered with a `ModelViewSet` will also be registered to the [reference index](managing_the_reference_index). You can turn off this behavior by setting {attr}`~ModelViewSet.add_to_reference_index` to `False`. -Various additional attributes are available to customise the viewset - see the {class}`ModelViewSet` documentation. +Various additional attributes are available to customize the viewset - see the {class}`ModelViewSet` documentation. (chooserviewset)= @@ -207,7 +207,7 @@ PersonChooserBlock = person_chooser_viewset.get_block_class( Chooser viewsets provide a mechanism for limiting the options displayed in the chooser according to another input field on the calling page. For example, suppose the person model has a country field - we can then set up a page model with a country dropdown and a person chooser, where an editor first selects a country from the dropdown and then opens the person chooser to be presented with a list of people from that country. -To set this up, define a `url_filter_parameters` attribute on the ChooserViewSet. This specifies a list of URL parameters that will be recognised for filtering the results - whenever these are passed in the URL, a `filter` clause on the correspondingly-named field will be applied to the queryset. These parameters should also be listed in the `preserve_url_parameters` attribute, so that they are preserved in the URL when navigating through the chooser (such as when following pagination links). The following definition will allow the person chooser to be filtered by country: +To set this up, define a `url_filter_parameters` attribute on the ChooserViewSet. This specifies a list of URL parameters that will be recognized for filtering the results - whenever these are passed in the URL, a `filter` clause on the correspondingly-named field will be applied to the queryset. These parameters should also be listed in the `preserve_url_parameters` attribute, so that they are preserved in the URL when navigating through the chooser (such as when following pagination links). The following definition will allow the person chooser to be filtered by country: ```python class PersonChooserViewSet(ChooserViewSet): diff --git a/docs/extending/index.md b/docs/extending/index.md index ad7aaec1ce..a394a92520 100644 --- a/docs/extending/index.md +++ b/docs/extending/index.md @@ -16,7 +16,7 @@ adding_reports custom_tasks audit_log custom_account_settings -customising_group_views +customizing_group_views custom_image_filters extending_client_side rich_text_internals diff --git a/docs/extending/rich_text_internals.md b/docs/extending/rich_text_internals.md index 67b51e8591..c26e5ba4ba 100644 --- a/docs/extending/rich_text_internals.md +++ b/docs/extending/rich_text_internals.md @@ -52,7 +52,7 @@ Again, the `embedtype` attribute identifies a rule that shall be used to rewrite A number of additional constraints apply to `<a linktype="...">` and `<embed embedtype="..." />` tags, to allow the conversion to be performed efficiently via string replacement: - The tag name and attributes must be lower-case -- Attribute values must be quoted with double-quotes +- Attribute values must be quoted with double quotes - `embed` elements must use XML self-closing tag syntax (those that end in `/>` instead of a closing `</embed>` tag) - The only HTML entities permitted in attribute values are `<`, `>`, `&` and `"` @@ -205,9 +205,9 @@ It is possible to create your own rich text editor implementation. At minimum, a Typically, a rich text widget also receives a `features` list, passed from either `RichTextField` / `RichTextBlock` or the `features` option in `WAGTAILADMIN_RICH_TEXT_EDITORS`, which defines the features available in that instance of the editor (see [rich text features](rich_text_features)). To opt in to supporting features, set the attribute `accepts_features = True` on your widget class; the widget constructor will then receive the feature list as a keyword argument `features`. -There is a standard set of recognised feature identifiers as listed under [rich text features](rich_text_features), but this is not a definitive list; feature identifiers are only defined by convention, and it is up to each editor widget to determine which features it will recognise, and adapt its behaviour accordingly. Individual editor widgets might implement fewer or more features than the default set, either as built-in functionality or through a plugin mechanism if the editor widget has one. +There is a standard set of recognized feature identifiers as listed under [rich text features](rich_text_features), but this is not a definitive list; feature identifiers are only defined by convention, and it is up to each editor widget to determine which features it will recognize, and adapt its behavior accordingly. Individual editor widgets might implement fewer or more features than the default set, either as built-in functionality or through a plugin mechanism if the editor widget has one. -For example, a third-party Wagtail extension might introduce `table` as a new rich text feature, and provide implementations for the Draftail editor (which provides a plugin mechanism). In this case, the third-party extension will not be aware of your custom editor widget, and so the widget will not know how to handle the `table` feature identifier. Editor widgets should silently ignore any feature identifiers that they do not recognise. +For example, a third-party Wagtail extension might introduce `table` as a new rich text feature, and provide implementations for the Draftail editor (which provides a plugin mechanism). In this case, the third-party extension will not be aware of your custom editor widget, and so the widget will not know how to handle the `table` feature identifier. Editor widgets should silently ignore any feature identifiers that they do not recognize. The `default_features` attribute of the feature registry is a list of feature identifiers to be used whenever an explicit feature list has not been given in `RichTextField` / `RichTextBlock` or `WAGTAILADMIN_RICH_TEXT_EDITORS`. This list can be modified within the `register_rich_text_features` hook to make new features enabled by default, and retrieved by calling `get_default_features()`. @@ -241,7 +241,7 @@ class CustomRichTextArea(widgets.TextArea): ```{eval-rst} .. method:: FeatureRegistry.register_editor_plugin(editor_name, feature_name, plugin_definition) -Rich text editors often provide a plugin mechanism to allow extending the editor with new functionality. The ``register_editor_plugin`` method provides a standardised way for ``register_rich_text_features`` hooks to define plugins to be pulled into the editor when a given rich text feature is enabled. +Rich text editors often provide a plugin mechanism to allow extending the editor with new functionality. The ``register_editor_plugin`` method provides a standardized way for ``register_rich_text_features`` hooks to define plugins to be pulled into the editor when a given rich text feature is enabled. ``register_editor_plugin`` is passed an editor name (a string uniquely identifying the editor widget - Wagtail uses the identifier ``draftail`` for the built-in editor), a feature identifier, and a plugin definition object. This object is specific to the editor widget and can be any arbitrary value, but will typically include a :doc:`Django form media <django:topics/forms/media>` definition referencing the plugin's JavaScript code - which will then be merged into the editor widget's own media definition - along with any relevant configuration options to be passed when instantiating the editor. @@ -262,7 +262,7 @@ Wagtail provides two utility classes, `wagtail.admin.rich_text.converters.conten Both classes accept a `features` list as an argument to their constructor and implement two methods, `from_database_format(data)` which converts Wagtail rich text data to the editor's format, and `to_database_format(data)` which converts editor data to Wagtail rich text format. -As with editor plugins, the behaviour of a converter class can vary according to the feature list passed to it. In particular, it can apply whitelisting rules to ensure that the output only contains HTML elements corresponding to the currently active feature set. The feature registry provides a `register_converter_rule` method to allow `register_rich_text_features` hooks to define conversion rules that will be activated when a given feature is enabled. +As with editor plugins, the behavior of a converter class can vary according to the feature list passed to it. In particular, it can apply whitelisting rules to ensure that the output only contains HTML elements corresponding to the currently active feature set. The feature registry provides a `register_converter_rule` method to allow `register_rich_text_features` hooks to define conversion rules that will be activated when a given feature is enabled. ```{eval-rst} .. method:: FeatureRegistry.register_converter_rule(converter_name, feature_name, rule_definition) diff --git a/docs/reference/contrib/forms/customisation.md b/docs/reference/contrib/forms/customization.md similarity index 94% rename from docs/reference/contrib/forms/customisation.md rename to docs/reference/contrib/forms/customization.md index b4c28ab358..95a5104023 100644 --- a/docs/reference/contrib/forms/customisation.md +++ b/docs/reference/contrib/forms/customization.md @@ -1,4 +1,6 @@ -# Form builder customisation +(form_builder_customization)= + +# Form builder customization For a basic usage example see [form builder usage](form_builder_usage). @@ -268,10 +270,10 @@ Your template should look like this: <input type="submit"> </form> {% else %} - <div>You can fill in the from only one time.</div> + <div>You can fill in the form only one time.</div> {% endif %} {% else %} - <div>To fill in the form, you must to log in.</div> + <div>To fill in the form, you must log in.</div> {% endif %} </body> </html> @@ -322,7 +324,7 @@ class FormPage(AbstractEmailForm): Implements a simple multi-step form. Stores each step into a session. - When the last step was submitted correctly, saves whole form into a DB. + When the last step is submitted correctly, saves the whole form into a DB. """ session_key_data = 'form_data-%s' % self.pk @@ -340,7 +342,7 @@ class FormPage(AbstractEmailForm): if request.method == 'POST': # The first step will be submitted with step_number == 2, - # so we need to get a form from previous step + # so we need to get a form from the previous step # Edge case - submission of the last step prev_step = step if is_last_step else paginator.page(step.previous_page_number()) @@ -460,7 +462,7 @@ class FormPage(AbstractEmailForm): context = super().get_context(request, *args, **kwargs) # If you need to show results only on landing page, - # you may need check request.method + # You may need to check request.method results = dict() # Get information about form fields @@ -535,7 +537,7 @@ You can also show the results on the landing page. You can override the `render_landing_page` method on your `FormPage` to change what is rendered when a form submits. -In this example below we have added a `thank_you_page` field that enables custom redirects after a form submits to the selected page. +In the example below we have added a `thank_you_page` field that enables custom redirects after a form submits to the selected page. When overriding the `render_landing_page` method, we check if there is a linked `thank_you_page` and then redirect to it if it exists. @@ -586,7 +588,7 @@ class FormPage(AbstractEmailForm): ## Customise form submissions listing in Wagtail Admin -The Admin listing of form submissions can be customised by setting the attribute `submissions_list_view_class` on your FormPage model. +The Admin listing of form submissions can be customized by setting the attribute `submissions_list_view_class` on your FormPage model. The list view class must be a subclass of `SubmissionsListView` from `wagtail.contrib.forms.views`, which is a child class of Django's class based {class}`~django.views.generic.list.ListView`. @@ -614,7 +616,7 @@ class FormField(AbstractFormField): class FormPage(AbstractEmailForm): - """Form Page with customised submissions listing view""" + """Form Page with customized submissions listing view""" # set custom view class as class attribute submissions_list_view_class = CustomSubmissionsListView @@ -630,7 +632,7 @@ class FormPage(AbstractEmailForm): First, make the new field type available in the page editor by changing your `FormField` model. - Create a new set of choices which includes the original `FORM_FIELD_CHOICES` along with new field types you want to make available. -- Each choice must contain a unique key and a human readable name of the field, for example `('slug', 'URL Slug')` +- Each choice must contain a unique key and a human-readable name of the field, for example `('slug', 'URL Slug')` - Override the `field_type` field in your `FormField` model with `choices` attribute using these choices. - You will need to run `./manage.py makemigrations` and `./manage.py migrate` after this step. @@ -653,7 +655,7 @@ from wagtail.contrib.forms.models import ( class FormField(AbstractFormField): - # extend the built in field type choices + # extend the built-in field type choices # our field type key will be 'ipaddress' CHOICES = FORM_FIELD_CHOICES + (('ipaddress', 'IP Address'),) @@ -709,7 +711,7 @@ class FormPage(AbstractEmailForm): # Get the original content (string) email_content = super().render_email(form) - # Add a title (not part of original method) + # Add a title (not part of the original method) title = '{}: {}'.format('Form', self.title) content = [title, '', email_content, ''] @@ -764,11 +766,11 @@ class FormPage(AbstractEmailForm): ## Custom `clean_name` generation -- Each time a new `FormField` is added a `clean_name` also gets generated based on the user entered `label`. -- `AbstractFormField` has a method `get_field_clean_name` to convert the label into a HTML valid `lower_snake_case` ASCII string using the [AnyAscii](https://pypi.org/project/anyascii/) library which can be overridden to generate a custom conversion. +- Each time a new `FormField` is added a `clean_name` also gets generated based on the user-entered `label`. +- `AbstractFormField` has a method `get_field_clean_name` to convert the label into an HTML-valid `lower_snake_case` ASCII string using the [AnyAscii](https://pypi.org/project/anyascii/) library which can be overridden to generate a custom conversion. - The resolved `clean_name` is also used as the form field name in rendered HTML forms. - Ensure that any conversion will be unique enough to not create conflicts within your `FormPage` instance. -- This method gets called on creation of new fields only and as such will not have access to its own `Page` or `pk`. This does not get called when labels are edited as modifying the `clean_name` after any form responses are submitted will mean those field responses will not be retrieved. +- This method gets called on the creation of new fields only and as such will not have access to its own `Page` or `pk`. This does not get called when labels are edited as modifying the `clean_name` after any form responses are submitted will mean those field responses will not be retrieved. - This method gets called for form previews and also validation of duplicate labels. ```python @@ -798,7 +800,7 @@ class FormPage(AbstractEmailForm): ## Using `FormMixin` or `EmailFormMixin` to use with other `Page` subclasses -If you need to add form behaviour while extending an additional class, you can use the base mixins instead of the abstract models. +If you need to add form behavior while extending an additional class, you can use the base mixins instead of the abstract models. ```python from wagtail.models import Page diff --git a/docs/reference/contrib/forms/index.md b/docs/reference/contrib/forms/index.md index e967e5a5a6..15de941ae4 100644 --- a/docs/reference/contrib/forms/index.md +++ b/docs/reference/contrib/forms/index.md @@ -5,7 +5,7 @@ The `wagtailforms` module allows you to set up single-page forms, such as a 'Contact us' form, as pages of a Wagtail site. It provides a set of base models that site implementers can extend to create their own `FormPage` type with their own site-specific templates. Once a page type has been set up in this way, editors can build forms within the usual page editor, consisting of any number of fields. Form submissions are stored for later retrieval through a new 'Forms' section within the Wagtail admin interface; in addition, they can be optionally e-mailed to an address specified by the editor. ```{note} -**wagtailforms is not a replacement for** [Django's form support](inv:django#topics/forms/index). It is designed as a way for page authors to build general-purpose data collection forms without having to write code. If you intend to build a form that assigns specific behaviour to individual fields (such as creating user accounts), or needs a custom HTML layout, you will almost certainly be better served by a standard Django form, where the fields are fixed in code rather than defined on-the-fly by a page author. See the [wagtail-form-example project](https://github.com/gasman/wagtail-form-example/commits/master) for an example of integrating a Django form into a Wagtail page. +**wagtailforms is not a replacement for** [Django's form support](inv:django#topics/forms/index). It is designed as a way for page authors to build general-purpose data collection forms without having to write code. If you intend to build a form that assigns specific behavior to individual fields (such as creating user accounts), or needs a custom HTML layout, you will almost certainly be better served by a standard Django form, where the fields are fixed in code rather than defined on-the-fly by a page author. See the [wagtail-form-example project](https://github.com/gasman/wagtail-form-example/commits/master) for an example of integrating a Django form into a Wagtail page. ``` (form_builder_usage)= @@ -58,9 +58,9 @@ class FormPage(AbstractEmailForm): `AbstractEmailForm` defines the fields `to_address`, `from_address` and `subject`, and expects `form_fields` to be defined. Any additional fields are treated as ordinary page content - note that `FormPage` is responsible for serving both the form page itself and the landing page after submission, so the model definition should include all necessary content fields for both of those views. -Date and datetime values in a form response will be formatted with the [SHORT_DATE_FORMAT](https://docs.djangoproject.com/en/stable/ref/settings/#short-date-format) and [SHORT_DATETIME_FORMAT](https://docs.djangoproject.com/en/stable/ref/settings/#short-datetime-format) respectively. (see [](form_builder_render_email) for how to customise the email content). +Date and datetime values in a form response will be formatted with the [SHORT_DATE_FORMAT](https://docs.djangoproject.com/en/stable/ref/settings/#short-date-format) and [SHORT_DATETIME_FORMAT](https://docs.djangoproject.com/en/stable/ref/settings/#short-datetime-format) respectively. (see [](form_builder_render_email) for how to customize the email content). -If you do not want your form page type to offer form-to-email functionality, you can inherit from AbstractForm instead of `AbstractEmailForm`, and omit the `to_address`, `from_address` and `subject` fields from the `content_panels` definition. +If you do not want your form page type to offer form-to-email functionality, you can inherit from AbstractForm instead of `AbstractEmailForm`, and omit the `to_address`, `from_address`, and `subject` fields from the `content_panels` definition. You now need to create two templates named `form_page.html` and `form_page_landing.html` (where `form_page` is the underscore-formatted version of the class name). `form_page.html` differs from a standard Wagtail template in that it is passed a variable `form`, containing a Django `Form` object, in addition to the usual `page` variable. A very basic template for the form would thus be: @@ -110,5 +110,5 @@ class FormPage(AbstractEmailForm): maxdepth: 1 titlesonly: --- -customisation +customization ``` diff --git a/docs/reference/contrib/settings.md b/docs/reference/contrib/settings.md index cde8d29692..6f60229024 100644 --- a/docs/reference/contrib/settings.md +++ b/docs/reference/contrib/settings.md @@ -1,9 +1,9 @@ # Settings The `wagtail.contrib.settings` module allows you to define models that hold -settings which are either common across all site records, or specific to each site. +settings which are either common across all site records or specific to each site. -Settings are editable by administrators within the Wagtail admin, and can be +Settings are editable by administrators within the Wagtail admin and can be accessed in code as well as in templates. ## Installation @@ -84,7 +84,7 @@ class SiteSpecificImportantPages(BaseSiteSetting): ] ``` -You can also customise the edit handlers [like you would do for `Page` model](customising_the_tabbed_interface) with a custom `edit_handler` attribute: +You can also customize the edit handlers [like you would do for `Page` model](customising_the_tabbed_interface) with a custom `edit_handler` attribute: ```python from wagtail.admin.panels import TabbedInterface, ObjectList @@ -295,7 +295,7 @@ Or, alternately, using the `set` tag: For models with foreign key relationships to other objects (for example pages), which are very often needed to output values in templates, you can set -the `select_related` attribute on your model to have Wagtail utilise +the `select_related` attribute on your model to have Wagtail utilize Django's [QuerySet.select_related()](https://docs.djangoproject.com/en/stable/ref/models/querysets/#select-related) method to fetch the settings object and related objects in a single query. With this, the initial query is more complex, but you will be able to diff --git a/docs/reference/contrib/simple_translation.md b/docs/reference/contrib/simple_translation.md index 733cec5fae..5c41392b93 100644 --- a/docs/reference/contrib/simple_translation.md +++ b/docs/reference/contrib/simple_translation.md @@ -28,7 +28,7 @@ Run `python manage.py migrate` to create the necessary permissions. In the Wagtail admin, go to settings and give some users or groups the "Can submit translations" permission. -## Page tree synchronisation +## Page tree synchronization Depending on your use case, it may be useful to keep the page trees in sync between different locales. diff --git a/docs/reference/contrib/sitemaps.md b/docs/reference/contrib/sitemaps.md index 334136d34e..01e441f9e2 100644 --- a/docs/reference/contrib/sitemaps.md +++ b/docs/reference/contrib/sitemaps.md @@ -13,7 +13,7 @@ during the sitemap generation you will have to use the views from the provided by Django (`django.contrib.sitemaps.views`). The usage of these views is otherwise identical, which means that -customisation and caching of the sitemaps are done using the default Django +customization and caching of the sitemaps are done using the default Django patterns. See the Django documentation for in-depth information. ``` @@ -85,7 +85,7 @@ Find out more about [working with Sites](site_model_ref). ### URLs The `Page` class defines a `get_sitemap_urls` method which you can -override to customise sitemaps per `Page` instance. This method must accept +override to customize sitemaps per `Page` instance. This method must accept a request object and return a list of dictionaries, one dictionary per URL entry in the sitemap. You can exclude pages from the sitemap by returning an empty list. diff --git a/docs/reference/contrib/table_block.md b/docs/reference/contrib/table_block.md index adda7f3f90..ba037295f5 100644 --- a/docs/reference/contrib/table_block.md +++ b/docs/reference/contrib/table_block.md @@ -99,7 +99,7 @@ Every key in the `table_options` dictionary maps to a [handsontable](https://han - [contextMenu](https://handsontable.com/docs/6.2.2/Options.html#contextMenu) - Enables or disables the Handsontable right-click menu. By default this is set to `True`. Alternatively you can provide a list or a dictionary with [specific options](https://handsontable.com/docs/6.2.2/demo-context-menu.html#page-specific). - [editor](https://handsontable.com/docs/6.2.2/Options.html#editor) - Defines the editor used for table cells. The default setting is text. - [stretchH](https://handsontable.com/docs/6.2.2/Options.html#stretchH) - Sets the default horizontal resizing of tables. Options include, 'none', 'last', and 'all'. By default TableBlock uses 'all' for the even resizing of columns. -- [height](https://handsontable.com/docs/6.2.2/Options.html#height) - The default height of the grid. By default TableBlock sets the height to `108` for the optimal appearance of new tables in the editor. This is optimised for tables with `startRows` set to `3`. If you change the number of `startRows` in the configuration, you might need to change the `height` setting to improve the default appearance in the editor. +- [height](https://handsontable.com/docs/6.2.2/Options.html#height) - The default height of the grid. By default TableBlock sets the height to `108` for the optimal appearance of new tables in the editor. This is optimized for tables with `startRows` set to `3`. If you change the number of `startRows` in the configuration, you might need to change the `height` setting to improve the default appearance in the editor. - [language](https://handsontable.com/docs/6.2.2/Options.html#language) - The default language setting. By default TableBlock tries to get the language from `django.utils.translation.get_language`. If needed, this setting can be overridden here. - [renderer](https://handsontable.com/docs/6.2.2/Options.html#renderer) - The default setting Handsontable uses to render the content of table cells. - [autoColumnSize](https://handsontable.com/docs/6.2.2/Options.html#autoColumnSize) - Enables or disables the `autoColumnSize` plugin. The TableBlock default setting is `False`. diff --git a/docs/reference/contrib/typed_table_block.md b/docs/reference/contrib/typed_table_block.md index 60e5d2b6d2..522fc9f9b8 100644 --- a/docs/reference/contrib/typed_table_block.md +++ b/docs/reference/contrib/typed_table_block.md @@ -76,7 +76,7 @@ Or: ## Custom validation -As with other blocks, validation logic on `TypedTableBlock` can be customised by overriding the `clean` method (see [](streamfield_validation)). Raising a `ValidationError` exception from this method will attach the error message to the table as a whole. To attach errors to individual cells, the exception class `wagtail.contrib.typed_table_block.blocks.TypedTableBlockValidationError` can be used - in addition to the standard `non_block_errors` argument, this accepts a `cell_errors` argument consisting of a nested dict structure where the outer keys are row indexes and the inner keys are column indexes. For example: +As with other blocks, validation logic on `TypedTableBlock` can be customized by overriding the `clean` method (see [](streamfield_validation)). Raising a `ValidationError` exception from this method will attach the error message to the table as a whole. To attach errors to individual cells, the exception class `wagtail.contrib.typed_table_block.blocks.TypedTableBlockValidationError` can be used - in addition to the standard `non_block_errors` argument, this accepts a `cell_errors` argument consisting of a nested dict structure where the outer keys are row indexes and the inner keys are column indexes. For example: ```python from django.core.exceptions import ValidationError diff --git a/docs/reference/hooks.md b/docs/reference/hooks.md index 9732930072..4f37b67ce7 100644 --- a/docs/reference/hooks.md +++ b/docs/reference/hooks.md @@ -5,8 +5,8 @@ On loading, Wagtail will search for any app with the file `wagtail_hooks.py` and execute the contents. This provides a way to register your own functions to execute at certain points in Wagtail's execution, such as when a page is saved or when the main menu is constructed. ```{note} -Hooks are typically used to customise the view-level behaviour of the Wagtail admin and front-end. -For customisations that only deal with model-level behaviour - such as calling an external service when a page or document is added - it is often better to use [Django's signal mechanism](inv:django#topics/signals) (see also: [Wagtail signals](signals)), as these are not dependent on a user taking a particular path through the admin interface. +Hooks are typically used to customize the view-level behavior of the Wagtail admin and front-end. +For customizations that only deal with model-level behavior - such as calling an external service when a page or document is added - it is often better to use [Django's signal mechanism](inv:django#topics/signals) (see also: [Wagtail signals](signals)), as these are not dependent on a user taking a particular path through the admin interface. ``` Registering functions with a Wagtail hook is done through the `@hooks.register` decorator: @@ -104,13 +104,13 @@ depth: 1 ## Admin modules -Hooks for building new areas of the admin interface (alongside pages, images, documents and so on). +Hooks for building new areas of the admin interface (alongside pages, images, documents, and so on). (construct_homepage_panels)= ### `construct_homepage_panels` -Add or remove panels from the Wagtail admin homepage. The callable passed into this hook should take a `request` object and a list of panel objects, and should modify this list in-place as required. Panel objects are [](template_components) with an additional `order` property, an integer that determines the panel's position in the final ordered list. The default panels use integers between `100` and `300`. +Add or remove panels from the Wagtail admin homepage. The callable passed into this hook should take a `request` object and a list of panel objects and should modify this list in place as required. Panel objects are [](template_components) with an additional `order` property, an integer that determines the panel's position in the final ordered list. The default panels use integers between `100` and `300`. ```python from django.utils.safestring import mark_safe @@ -137,7 +137,7 @@ def add_another_welcome_panel(request, panels): ### `construct_homepage_summary_items` -Add or remove items from the 'site summary' bar on the admin homepage (which shows the number of pages and other object that exist on the site). The callable passed into this hook should take a `request` object and a list of summary item objects, and should modify this list in-place as required. Summary item objects are instances of `wagtail.admin.site_summary.SummaryItem`, which extends [the Component class](creating_template_components) with the following additional methods and properties: +Add or remove items from the 'site summary' bar on the admin homepage (which shows the number of pages and other object that exist on the site). The callable passed into this hook should take a `request` object and a list of summary item objects and should modify this list in-place as required. Summary item objects are instances of `wagtail.admin.site_summary.SummaryItem`, which extends [the Component class](creating_template_components) with the following additional methods and properties: ```{eval-rst} .. method:: SummaryItem(request) @@ -172,7 +172,7 @@ def hide_explorer_menu_item_from_frank(request, menu_items): ### `describe_collection_contents` -Called when Wagtail needs to find out what objects exist in a collection, if any. Currently this happens on the confirmation before deleting a collection, to ensure that non-empty collections cannot be deleted. The callable passed to this hook will receive a `collection` object, and should return either `None` (to indicate no objects in this collection), or a dict containing the following keys: +Called when Wagtail needs to find out what objects exist in a collection, if any. Currently, this happens on the confirmation before deleting a collection, to ensure that non-empty collections cannot be deleted. The callable passed to this hook will receive a `collection` object, and should return either `None` (to indicate no objects in this collection), or a dict containing the following keys: - `count` - A numeric count of items in this collection - `count_text` - A human-readable string describing the number of items in this collection, such as "3 documents". (Sites with multi-language support should return a translatable string here, most likely using the `django.utils.translation.ngettext` function.) @@ -221,7 +221,7 @@ More details about the options that are available can be found at [](custom_acco Add an item to the "More actions" tab on the "Account" page within the Wagtail admin. The callable for this hook should return a dict with the keys -`url`, `label` and `help_text`. For example: +`url`, `label`, and `help_text`. For example: ```python from django.urls import reverse @@ -245,11 +245,11 @@ Add an item to the Wagtail admin menu. The callable passed to this hook must ret - `name` - an internal name used to identify the menu item; defaults to the slugified form of the label. - `icon_name` - icon to display against the menu item; no defaults, optional, but should be set for top-level menu items so they can be identified when collapsed. - `classname` - additional classes applied to the link. -- `order` - an integer which determines the item's position in the menu. +- `order` - an integer that determines the item's position in the menu. For menu items that are only available to superusers, the subclass `wagtail.admin.menu.AdminOnlyMenuItem` can be used in place of `MenuItem`. -`MenuItem` can be further subclassed to customise its initialisation or conditionally show or hide the item for specific requests (for example, to apply permission checks); see the source code (`wagtail/admin/menu.py`) for details. +`MenuItem` can be further subclassed to customize its initialization or conditionally show or hide the item for specific requests (for example, to apply permission checks); see the source code (`wagtail/admin/menu.py`) for details. ```python from django.urls import reverse @@ -356,7 +356,7 @@ As `construct_main_menu`, but modifies the 'Help' sub-menu rather than the top-l ### `register_admin_search_area` -Add an item to the Wagtail admin search "Other Searches". Behaviour of this hook is similar to `register_admin_menu_item`. The callable passed to this hook must return an instance of `wagtail.admin.search.SearchArea`. New items can be constructed from the `SearchArea` class by passing the following parameters: +Add an item to the Wagtail admin search "Other Searches". The behavior of this hook is similar to `register_admin_menu_item`. The callable passed to this hook must return an instance of `wagtail.admin.search.SearchArea`. New items can be constructed from the `SearchArea` class by passing the following parameters: - `label` - text displayed in the "Other Searches" option box. - `name` - an internal name used to identify the search option; defaults to the slugified form of the label. @@ -370,7 +370,7 @@ Setting the URL can be achieved using reverse() on the target search page. The G A template tag, `search_other` is provided by the `wagtailadmin_tags` template module. This tag takes a single, optional parameter, `current`, which allows you to specify the `name` of the search option currently active. If the parameter is not given, the hook defaults to a reverse lookup of the page's URL for comparison against the `url` parameter. -`SearchArea` can be subclassed to customise the HTML output, specify JavaScript files required by the option, or conditionally show or hide the item for specific requests (for example, to apply permission checks); see the source code (`wagtail/admin/search.py`) for details. +`SearchArea` can be subclassed to customize the HTML output, specify JavaScript files required by the option, or conditionally show or hide the item for specific requests (for example, to apply permission checks); see the source code (`wagtail/admin/search.py`) for details. ```python from django.urls import reverse @@ -425,7 +425,7 @@ def user_listing_external_profile(context, user): ### `filter_form_submissions_for_user` -Allows access to form submissions to be customised on a per-user, per-form basis. +Allows access to form submissions to be customized on a per-user, per-form basis. This hook takes two parameters: @@ -450,13 +450,13 @@ def construct_forms_for_user(user, queryset): ## Editor interface -Hooks for customising the editing interface for pages and snippets. +Hooks for customizing the editing interface for pages and snippets. (register_rich_text_features)= ### `register_rich_text_features` -Rich text fields in Wagtail work with a list of 'feature' identifiers that determine which editing controls are available in the editor, and which elements are allowed in the output; for example, a rich text field defined as `RichTextField(features=['h2', 'h3', 'bold', 'italic', 'link'])` would allow headings, bold / italic formatting and links, but not (for example) bullet lists or images. The `register_rich_text_features` hook allows new feature identifiers to be defined - see [](rich_text_features) for details. +Rich text fields in Wagtail work with a list of 'feature' identifiers that determine which editing controls are available in the editor, and which elements are allowed in the output; for example, a rich text field defined as `RichTextField(features=['h2', 'h3', 'bold', 'italic', 'link'])` would allow headings, bold / italic formatting, and links, but not (for example) bullet lists or images. The `register_rich_text_features` hook allows new feature identifiers to be defined - see [](rich_text_features) for details. (insert_global_admin_css)= @@ -562,7 +562,7 @@ The `priority` argument controls the order the buttons are displayed in the drop ## Editor workflow -Hooks for customising the way users are directed through the process of creating page content. +Hooks for customizing the way users are directed through the process of creating page content. (after_create_page)= @@ -622,7 +622,7 @@ def before_create_page(request, parent_page, page_class): ### `after_delete_page` -Do something after a `Page` object is deleted. Uses the same behaviour as `after_create_page`. +Do something after a `Page` object is deleted. Uses the same behavior as `after_create_page`. (before_delete_page)= @@ -630,7 +630,7 @@ Do something after a `Page` object is deleted. Uses the same behaviour as `after Called at the beginning of the "delete page" view passing in the request and the page object. -Uses the same behaviour as `before_create_page`, is is run both for both `GET` and `POST` requests. +Uses the same behavior as `before_create_page`, and is run for both `GET` and `POST` requests. ```python from django.shortcuts import redirect @@ -655,7 +655,7 @@ def before_delete_page(request, page): ### `after_edit_page` -Do something with a `Page` object after it has been updated. Uses the same behaviour as `after_create_page`. +Do something with a `Page` object after it has been updated. Uses the same behavior as `after_create_page`. (before_edit_page)= @@ -663,7 +663,7 @@ Do something with a `Page` object after it has been updated. Uses the same behav Called at the beginning of the "edit page" view passing in the request and the page object. -Uses the same behaviour as `before_create_page`. +Uses the same behavior as `before_create_page`. (after_publish_page)= @@ -701,7 +701,7 @@ The function does not have to return anything, but if an object with a `status_c ### `after_copy_page` -Do something with a `Page` object after it has been copied passing in the request, page object and the new copied page. Uses the same behaviour as `after_create_page`. +Do something with a `Page` object after it has been copied passing in the request, page object, and the new copied page. Uses the same behavior as `after_create_page`. (before_copy_page)= @@ -709,21 +709,21 @@ Do something with a `Page` object after it has been copied passing in the reques Called at the beginning of the "copy page" view passing in the request and the page object. -Uses the same behaviour as `before_create_page`. +Uses the same behavior as `before_create_page`. (after_move_page)= ### `after_move_page` -Do something with a `Page` object after it has been moved passing in the request and page object. Uses the same behaviour as `after_create_page`. +Do something with a `Page` object after it has been moved passing in the request and page object. Uses the same behavior as `after_create_page`. (before_move_page)= ### `before_move_page` -Called at the beginning of the "move page" view passing in the request, the page object and the destination page object. +Called at the beginning of the "move page" view passing in the request, the page object, and the destination page object. -Uses the same behaviour as `before_create_page`. +Uses the same behavior as `before_create_page`. (before_convert_alias_page)= @@ -762,17 +762,17 @@ We recommend they are non-aliased, direct translations of the pages from the fun ### `register_page_action_menu_item` -Add an item to the popup menu of actions on the page creation and edit views. The callable passed to this hook must return an instance of `wagtail.admin.action_menu.ActionMenuItem`. `ActionMenuItem` is a subclass of [Component](creating_template_components) and so the rendering of the menu item can be customised through `template_name`, `get_context_data`, `render_html` and `Media`. In addition, the following attributes and methods are available to be overridden: +Add an item to the popup menu of actions on the page creation and edit views. The callable passed to this hook must return an instance of `wagtail.admin.action_menu.ActionMenuItem`. `ActionMenuItem` is a subclass of [Component](creating_template_components) and so the rendering of the menu item can be customized through `template_name`, `get_context_data`, `render_html`, and `Media`. In addition, the following attributes and methods are available to be overridden: -- `order` - an integer (default 100) which determines the item's position in the menu. Can also be passed as a keyword argument to the object constructor. The lowest-numbered item in this sequence will be selected as the default menu item; as standard, this is "Save draft" (which has an `order` of 0). +- `order` - an integer (default 100) that determines the item's position in the menu. Can also be passed as a keyword argument to the object constructor. The lowest-numbered item in this sequence will be selected as the default menu item; as standard, this is "Save draft" (which has an `order` of 0). - `label` - the displayed text of the menu item -- `get_url` - a method which returns a URL for the menu item to link to; by default, returns `None` which causes the menu item to behave as a form submit button instead +- `get_url` - a method that returns a URL for the menu item to link to; by default, returns `None` which causes the menu item to behave as a form submit button instead - `name` - value of the `name` attribute of the submit button, if no URL is specified - `icon_name` - icon to display against the menu item - `classname` - a `class` attribute value to add to the button element -- `is_shown` - a method which returns a boolean indicating whether the menu item should be shown; by default, true except when editing a locked page +- `is_shown` - a method that returns a boolean indicating whether the menu item should be shown; by default, true except when editing a locked page -The `get_url`, `is_shown`, `get_context_data` and `render_html` methods all accept a context dictionary containing the following fields: +The `get_url`, `is_shown`, `get_context_data`, and `render_html` methods all accept a context dictionary containing the following fields: - `view` - name of the current view: `'create'`, `'edit'` or `'revisions_revert'` - `page` - for `view` = `'edit'` or `'revisions_revert'`, the page being edited @@ -808,7 +808,7 @@ def remove_submit_to_moderator_option(menu_items, request, context): menu_items[:] = [item for item in menu_items if item.name != 'action-submit'] ``` -The `construct_page_action_menu` hook is called after the menu items have been sorted by their order attributes, and so setting a menu item's order will have no effect at this point. Instead, items can be reordered by changing their position in the list, with the first item being selected as the default action. For example, to change the default action to Publish: +The `construct_page_action_menu` hook is called after the menu items have been sorted by their order attributes, so setting a menu item's order will have no effect at this point. Instead, items can be reordered by changing their position in the list, with the first item being selected as the default action. For example, to change the default action to Publish: ```python @hooks.register('construct_page_action_menu') @@ -842,7 +842,7 @@ def add_puppy_link_item(request, items): ## Admin workflow -Hooks for customising the way admins are directed through the process of editing users. +Hooks for customizing the way admins are directed through the process of editing users. (after_create_user)= @@ -889,7 +889,7 @@ def do_before_create_user(request): ### `after_delete_user` -Do something after a `User` object is deleted. Uses the same behaviour as `after_create_user`. +Do something after a `User` object is deleted. Uses the same behavior as `after_create_user`. (before_delete_user)= @@ -897,13 +897,13 @@ Do something after a `User` object is deleted. Uses the same behaviour as `after Called at the beginning of the "delete user" view passing in the request and the user object. -Uses the same behaviour as `before_create_user`. +Uses the same behavior as `before_create_user`. (after_edit_user)= ### `after_edit_user` -Do something with a `User` object after it has been updated. Uses the same behaviour as `after_create_user`. +Do something with a `User` object after it has been updated. Uses the same behavior as `after_create_user`. (before_edit_user)= @@ -911,7 +911,7 @@ Do something with a `User` object after it has been updated. Uses the same behav Called at the beginning of the "edit user" view passing in the request and the user object. -Uses the same behaviour as `before_create_user`. +Uses the same behavior as `before_create_user`. ## Choosers @@ -919,7 +919,7 @@ Uses the same behaviour as `before_create_user`. ### `construct_page_chooser_queryset` -Called when rendering the page chooser view, to allow the page listing QuerySet to be customised. The callable passed into the hook will receive the current page QuerySet and the request object, and must return a Page QuerySet (either the original one, or a new one). +Called when rendering the page chooser view, to allow the page listing QuerySet to be customized. The callable passed into the hook will receive the current page QuerySet and the request object, and must return a Page QuerySet (either the original one or a new one). ```python from wagtail import hooks @@ -936,7 +936,7 @@ def show_my_pages_only(pages, request): ### `construct_document_chooser_queryset` -Called when rendering the document chooser view, to allow the document listing QuerySet to be customised. The callable passed into the hook will receive the current document QuerySet and the request object, and must return a Document QuerySet (either the original one, or a new one). +Called when rendering the document chooser view, to allow the document listing QuerySet to be customized. The callable passed into the hook will receive the current document QuerySet and the request object, and must return a Document QuerySet (either the original one or a new one). ```python from wagtail import hooks @@ -953,7 +953,7 @@ def show_my_uploaded_documents_only(documents, request): ### `construct_image_chooser_queryset` -Called when rendering the image chooser view, to allow the image listing QuerySet to be customised. The callable passed into the hook will receive the current image QuerySet and the request object, and must return an Image QuerySet (either the original one, or a new one). +Called when rendering the image chooser view, to allow the image listing QuerySet to be customized. The callable passed into the hook will receive the current image QuerySet and the request object, and must return an Image QuerySet (either the original one or a new one). ```python from wagtail import hooks @@ -972,7 +972,7 @@ def show_my_uploaded_images_only(images, request): ### `construct_explorer_page_queryset` -Called when rendering the page explorer view, to allow the page listing QuerySet to be customised. The callable passed into the hook will receive the parent page object, the current page QuerySet, and the request object, and must return a Page QuerySet (either the original one, or a new one). +Called when rendering the page explorer view, to allow the page listing QuerySet to be customized. The callable passed into the hook will receive the parent page object, the current page QuerySet, and the request object, and must return a Page QuerySet (either the original one or a new one). ```python from wagtail import hooks @@ -1010,7 +1010,7 @@ The arguments passed to the hook are as follows: - `page` - the page object to generate the button for - `user` - the logged-in user -- `next_url` - the URL that the linked action should redirect back to on completion of the action, if the view supports it +- `next_url` - the URL that the linked action should redirect back to on completion of the action if the view supports it The `priority` argument controls the order the buttons are displayed in. Buttons are ordered from low to high priority, so a button with `priority=10` will be displayed before a button with `priority=20`. @@ -1038,7 +1038,7 @@ The arguments passed to the hook are as follows: - `page` - the page object to generate the button for - `user` - the logged-in user -- `next_url` - the URL that the linked action should redirect back to on completion of the action, if the view supports it +- `next_url` - the URL that the linked action should redirect back to on completion of the action if the view supports it The `priority` argument controls the order the buttons are displayed in the dropdown. Buttons are ordered from low to high priority, so a button with `priority=10` will be displayed before a button with `priority=60`. @@ -1046,7 +1046,7 @@ The `priority` argument controls the order the buttons are displayed in the drop The admin widgets also provide `ButtonWithDropdownFromHook`, which allows you to define a custom hook for generating a dropdown menu that gets attached to your button. -Creating a button with a dropdown menu involves two steps. Firstly, you add your button to the `register_page_listing_buttons` hook, just like the example above. +Creating a button with a dropdown menu involves two steps. Firstly, you add your button to the `register_page_listing_buttons` hook, just like in the example above. Secondly, you register a new hook that yields the contents of the dropdown menu. This example shows how Wagtail's default admin dropdown is implemented. You can also see how to register buttons conditionally, in this case by testing the user's permission with `page.permissions_for_user`: @@ -1076,7 +1076,7 @@ def page_custom_listing_more_buttons(page, user, next_url=None): yield wagtailadmin_widgets.Button('Unpublish', reverse('wagtailadmin_pages:unpublish', args=[page.id]), priority=40) ``` -The template for the dropdown button can be customised by overriding `wagtailadmin/pages/listing/_button_with_dropdown.html`. Make sure to leave the dropdown UI component itself as-is. +The template for the dropdown button can be customized by overriding `wagtailadmin/pages/listing/_button_with_dropdown.html`. Make sure to leave the dropdown UI component itself as-is. (construct_page_listing_buttons)= @@ -1203,7 +1203,7 @@ def before_snippet_delete(request, instances): if request.method == 'POST': for instance in instances: - # Override the deletion behaviour + # Override the deletion behavior instance.delete() return HttpResponse(f"{total} snippets have been deleted", content_type="text/plain") @@ -1214,17 +1214,19 @@ def before_snippet_delete(request, instances): ### `register_snippet_action_menu_item` Add an item to the popup menu of actions on the snippet creation and edit views. -The callable passed to this hook receives the snippet's model class as an argument, and must return an instance of `wagtail.snippets.action_menu.ActionMenuItem`. `ActionMenuItem` is a subclass of [Component](creating_template_components) and so the rendering of the menu item can be customised through `template_name`, `get_context_data`, `render_html` and `Media`. In addition, the following attributes and methods are available to be overridden: + +The callable passed to this hook receives the snippet's model class as an argument, and must return an instance of `wagtail.snippets.action_menu. +ActionMenuItem`. `ActionMenuItem` is a subclass of [Component](creating_template_components) and so the rendering of the menu item can be customized through `template_name`, `get_context_data`, `render_html` and `Media`. In addition, the following attributes and methods are available to be overridden: - `order` - an integer (default 100) which determines the item's position in the menu. Can also be passed as a keyword argument to the object constructor. The lowest-numbered item in this sequence will be selected as the default menu item; as standard, this is "Save draft" (which has an `order` of 0). - `label` - the displayed text of the menu item -- `get_url` - a method which returns a URL for the menu item to link to; by default, returns `None` which causes the menu item to behave as a form submit button instead +- `get_url` - a method that returns a URL for the menu item to link to; by default, returns `None` which causes the menu item to behave as a form submit button instead - `name` - value of the `name` attribute of the submit button if no URL is specified - `icon_name` - icon to display against the menu item - `classname` - a `class` attribute value to add to the button element -- `is_shown` - a method which returns a boolean indicating whether the menu item should be shown; by default, true except when editing a locked page +- `is_shown` - a method that returns a boolean indicating whether the menu item should be shown; by default, true except when editing a locked page -The `get_url`, `is_shown`, `get_context_data` and `render_html` methods all accept a context dictionary containing the following fields: +The `get_url`, `is_shown`, `get_context_data`, and `render_html` methods all accept a context dictionary containing the following fields: - `view` - name of the current view: `'create'` or `'edit'` - `model` - the snippet's model class @@ -1253,7 +1255,7 @@ def register_guacamole_menu_item(model): ### `construct_snippet_action_menu` Modify the final list of action menu items on the snippet creation and edit views. -The callable passed to this hook receives a list of `ActionMenuItem` objects, a request object and a context dictionary as per `register_snippet_action_menu_item`, and should modify the list of menu items in-place. +The callable passed to this hook receives a list of `ActionMenuItem` objects, a request object, and a context dictionary as per `register_snippet_action_menu_item`, and should modify the list of menu items in-place. ```python @hooks.register('construct_snippet_action_menu') @@ -1261,7 +1263,7 @@ def remove_delete_option(menu_items, request, context): menu_items[:] = [item for item in menu_items if item.name != 'delete'] ``` -The `construct_snippet_action_menu` hook is called after the menu items have been sorted by their order attributes, and so setting a menu item's order will have no effect at this point. Instead, items can be reordered by changing their position in the list, with the first item being selected as the default action. For example, to change the default action to Delete: +The `construct_snippet_action_menu` hook is called after the menu items have been sorted by their order attributes, so setting a menu item's order will have no effect at this point. Instead, items can be reordered by changing their position in the list, with the first item being selected as the default action. For example, to change the default action to Delete: ```python @hooks.register('construct_snippet_action_menu') @@ -1298,7 +1300,7 @@ The arguments passed to the hook are as follows: - `snippet` - the snippet object to generate the button for - `user` - the user who is viewing the snippets listing -- `next_url` - the URL that the linked action should redirect back to on completion of the action, if the view supports it +- `next_url` - the URL that the linked action should redirect back to on completion of the action if the view supports it The `priority` argument controls the order the buttons are displayed in. Buttons are ordered from low to high priority, so a button with `priority=10` will be displayed before a button with `priority=20`. @@ -1316,7 +1318,7 @@ def remove_snippet_listing_button_item(buttons, snippet, user): ## Bulk actions -Hooks for registering and customising bulk actions. See [](custom_bulk_actions) on how to write custom bulk actions. +Hooks for registering and customizing bulk actions. See [](custom_bulk_actions) on how to write custom bulk actions. (register_bulk_action)= diff --git a/docs/reference/jinja2.md b/docs/reference/jinja2.md index 5f81903758..7b81e74be0 100644 --- a/docs/reference/jinja2.md +++ b/docs/reference/jinja2.md @@ -197,7 +197,7 @@ Allows to pass template context (by default) to the StreamField template. See [StreamField template rendering](streamfield_template_rendering) for more information. ```{note} -The ``{% include_block %}`` tag is designed to closely follow the syntax and behaviour +The ``{% include_block %}`` tag is designed to closely follow the syntax and behavior of Jinja's ``{% include %}``, so it does not implement the Django version's feature of only passing specified variables into the context. ``` diff --git a/docs/reference/management_commands.md b/docs/reference/management_commands.md index 372dc2a96e..668cfaf7db 100644 --- a/docs/reference/management_commands.md +++ b/docs/reference/management_commands.md @@ -10,7 +10,7 @@ ./manage.py publish_scheduled ``` -This command publishes, updates or unpublishes objects that have had these actions scheduled by an editor. We recommend running this command once an hour. +This command publishes, updates, or unpublishes objects that have had these actions scheduled by an editor. We recommend running this command once an hour. (fixtree)= @@ -129,7 +129,7 @@ An alias for the `update_index` command that can be used when another installed ./manage.py rebuild_references_index ``` -This command populates the table that tracks cross-references between objects, used for the usage reports on images, documents and snippets. This table is updated automatically saving objects, but it is recommended to run this command periodically to ensure that the data remains consistent. +This command populates the table that tracks cross-references between objects, used for the usage reports on images, documents, and snippets. This table is updated automatically saving objects, but it is recommended to run this command periodically to ensure that the data remains consistent. ### Silencing the command @@ -145,7 +145,7 @@ python manage.py rebuild_references_index --verbosity 0 ./manage.py show_references_index ``` -Displays a summary of the contents of the references index. This shows the number of objects indexed against each model type, and can be useful to identify which models are being indexed without rebuilding the index itself. +Displays a summary of the contents of the references index. This shows the number of objects indexed against each model type and can be useful to identify which models are being indexed without rebuilding the index itself. (wagtail_update_image_renditions)= @@ -156,9 +156,9 @@ Displays a summary of the contents of the references index. This shows the numbe ``` This command provides the ability to regenerate image renditions. -This is useful if you have deployed to a server where the image renditions have not yet been generated or you have changed the underlying image rendition behaviour and need to ensure all renditions are created again. +This is useful if you have deployed to a server where the image renditions have not yet been generated or you have changed the underlying image rendition behavior and need to ensure all renditions are created again. -This does not remove rendition images that are unused, this can be done by clearing the folder using `rm -rf` or similar, once this is done you can then use the management command to generate the renditions. +This does not remove unused rendition images, this can be done by clearing the folder using `rm -rf` or similar, once this is done you can then use the management command to generate the renditions. Options: diff --git a/docs/reference/pages/index.md b/docs/reference/pages/index.md index 1ad68619bb..89e606db15 100644 --- a/docs/reference/pages/index.md +++ b/docs/reference/pages/index.md @@ -2,7 +2,7 @@ Wagtail requires a little careful setup to define the types of content that you want to present through your website. The basic unit of content in Wagtail is the :class:`~wagtail.models.Page`, and all of your page-level content will inherit basic webpage-related properties from it. But for the most part, you will be defining content yourself, through the construction of Django models using Wagtail's `Page` as a base. -Wagtail organises content created from your models in a tree, which can have any structure and combination of model objects in it. Wagtail doesn't prescribe ways to organise and interrelate your content, but here we've sketched out some strategies for organising your models. +Wagtail organizes content created from your models in a tree, which can have any structure and combination of model objects in it. Wagtail doesn't prescribe ways to organize and interrelate your content, but here we've sketched out some strategies for organizing your models. The presentation of your content, the actual webpages, includes the normal use of the Django template system. We'll cover additional functionality that Wagtail provides at the template level later on. diff --git a/docs/reference/pages/model_recipes.md b/docs/reference/pages/model_recipes.md index af88533879..ae3603441a 100644 --- a/docs/reference/pages/model_recipes.md +++ b/docs/reference/pages/model_recipes.md @@ -31,7 +31,7 @@ class EventPage(Page): return super().serve(request) ``` -{meth}`~wagtail.models.Page.serve` takes a Django request object and returns a Django response object. Wagtail returns a `TemplateResponse` object with the template and context which it generates, which allows middleware to function as intended, so keep in mind that a simpler response object like a `HttpResponse` will not receive these benefits. +{meth}`~wagtail.models.Page.serve` takes a Django request object and returns a Django response object. Wagtail returns a `TemplateResponse` object with the template and context that it generates, which allows middleware to function as intended, so keep in mind that a simpler response object like a `HttpResponse` will not receive these benefits. With this strategy, you could use Django or Python utilities to render your model in JSON or XML or any other format you'd like. @@ -75,7 +75,7 @@ class Page(...): raise Http404 ``` -{meth}`~wagtail.models.Page.route` takes the current object (`self`), the `request` object, and a list of the remaining `path_components` from the request URL. It either continues delegating routing by calling {meth}`~wagtail.models.Page.route` again on one of its children in the Wagtail tree, or ends the routing process by returning a `RouteResult` object or raising a 404 error. +{meth}`~wagtail.models.Page.route` takes the current object (`self`), the `request` object, and a list of the remaining `path_components` from the request URL. It either continues delegating routing by calling {meth}`~wagtail.models.Page.route` again on one of its children in the Wagtail tree or ends the routing process by returning a `RouteResult` object or raising a 404 error. The `RouteResult` object (defined in wagtail.url_routing) encapsulates all the information Wagtail needs to call a page's {meth}`~wagtail.models.Page.serve` method and return a final response: this information consists of the page object, and any additional `args`/`kwargs` to be passed to {meth}`~wagtail.models.Page.serve`. @@ -227,11 +227,11 @@ class BlogPage(Page): tags = ClusterTaggableManager(through='demo.TaggedBlog', blank=True) ``` -Within the admin, the tag field will automatically recognise the custom tag model being used, and will offer autocomplete suggestions taken from that tag model. +Within the admin, the tag field will automatically recognize the custom tag model being used and will offer autocomplete suggestions taken from that tag model. ### Disabling free tagging -By default, tag fields work on a "free tagging" basis: editors can enter anything into the field, and upon saving, any tag text not recognised as an existing tag will be created automatically. To disable this behaviour, and only allow editors to enter tags that already exist in the database, custom tag models accept a `free_tagging = False` option: +By default, tag fields work on a "free tagging" basis: editors can enter anything into the field, and upon saving, any tag text not recognized as an existing tag will be created automatically. To disable this behavior, and only allow editors to enter tags that already exist in the database, custom tag models accept a `free_tagging = False` option: ```python from taggit.models import TagBase @@ -250,11 +250,11 @@ Here we have registered `BlogTag` as a snippet, to provide an interface for admi ### Managing tags as snippets -In order to manage all the tags used in a project, you can register the `Tag` model as a snippet to be managed via the Wagtail admin. This will allow you to have a tag admin interface within the main menu in which you can add, edit or delete your tags. +To manage all the tags used in a project, you can register the `Tag` model as a snippet to be managed via the Wagtail admin. This will allow you to have a tag admin interface within the main menu in which you can add, edit or delete your tags. Tags that are removed from a content don't get deleted from the `Tag` model and will still be shown in typeahead tag completion. So having a tag interface is a great way to completely get rid of tags you don't need. -To add the tag interface, add the following block of code to a `wagtail_hooks.py` file within any your project’s apps: +To add the tag interface, add the following block of code to a `wagtail_hooks.py` file within any of your project’s apps: ```python from wagtail.admin.panels import FieldPanel @@ -276,4 +276,4 @@ class TagsSnippetViewSet(SnippetViewSet): register_snippet(TagsSnippetViewSet) ``` -A `Tag` model has a `name` and `slug` required fields. If you decide to add a tag, it is recommended to only display the `name` field panel as the slug field is autofilled when the `name` field is filled and you don't need to enter the same name in both the fields. +A `Tag` model has a `name` and `slug` required fields. If you decide to add a tag, it is recommended to only display the `name` field panel as the slug field is automatically populated when the `name` field is filled and you don't need to enter the same name in both fields. diff --git a/docs/reference/pages/model_reference.md b/docs/reference/pages/model_reference.md index 39beba447f..61392a2266 100644 --- a/docs/reference/pages/model_reference.md +++ b/docs/reference/pages/model_reference.md @@ -335,8 +335,8 @@ See also [django-treebeard](https://django-treebeard.readthedocs.io/en/latest/in .. attribute:: base_form_class - The form class used as a base for editing Pages of this type in the Wagtail page editor. - This attribute can be set on a model to customise the Page editor form. + The form class is used as a base for editing Pages of this type in the Wagtail page editor. + This attribute can be set on a model to customize the Page editor form. Forms must be a subclass of :class:`~wagtail.admin.forms.WagtailAdminPageForm`. See :ref:`custom_edit_handler_forms` for more information. @@ -370,7 +370,7 @@ The {meth}`~wagtail.models.Site.find_for_request` function returns the Site obje (text) - This is the hostname of the site, excluding the scheme, port and path. + This is the hostname of the site, excluding the scheme, port, and path. For example: ``www.mysite.com`` @@ -439,15 +439,15 @@ Wagtail will initially set up one `Locale` to act as the default language for al This first locale will automatically pick the value from `WAGTAIL_CONTENT_LANGUAGES` that most closely matches the site primary language code defined in `LANGUAGE_CODE`. If the primary language code is changed later, Wagtail will **not** automatically create a new `Locale` record or update an existing one. -Before internationalisation is enabled, all pages use this primary `Locale` record. -This is to satisfy the database constraints, and makes it easier to switch internationalisation on at a later date. +Before internationalization is enabled, all pages use this primary `Locale` record. +This is to satisfy the database constraints and make it easier to switch internationalization on at a later date. ### Changing `WAGTAIL_CONTENT_LANGUAGES` Languages can be added or removed from `WAGTAIL_CONTENT_LANGUAGES` over time. Before removing an option from `WAGTAIL_CONTENT_LANGUAGES`, it's important that the `Locale` -record is updated to a use a different content language or is deleted. +record is updated to use a different content language or is deleted. Any `Locale` instances that have invalid content languages are automatically filtered out from all database queries making them unable to be edited or viewed. @@ -502,7 +502,7 @@ Pages already include this mixin, so there is no need to add it. This is shared with all translations of that instance so can be used for querying translations. ``` -The `translation_key` and `locale` fields have a unique key constraint to prevent the object being translated into a language more than once. +The `translation_key` and `locale` fields have a unique key constraint to prevent the object from being translated into a language more than once. ```{note} This is currently enforced via {attr}`~django.db.models.Options.unique_together` in `TranslatableMixin.Meta`, but may be replaced with a {class}`~django.db.models.UniqueConstraint` in `TranslatableMixin.Meta.constraints` in the future. @@ -572,7 +572,7 @@ Pages already include this mixin, so there is no need to add it. (foreign key to :class:`~wagtail.models.Revision`) - This points to the latest revision created for the object. This reference is stored in the database for performance optimisation. + This points to the latest revision created for the object. This reference is stored in the database for performance optimization. ``` ### Methods and properties @@ -870,7 +870,7 @@ You can use the [`purge_revisions`](purge_revisions) command to delete old revis ## `Workflow` -Workflows represent sequences of tasks which must be approved for an action to be performed on an object - typically publication. +Workflows represent sequences of tasks that must be approved for an action to be performed on an object - typically publication. ### Database fields @@ -999,7 +999,7 @@ Workflow states represent the status of a started workflow on an object. ## `Task` -Tasks represent stages in a workflow which must be approved for the workflow to complete successfully. +Tasks represent stages in a workflow that must be approved for the workflow to complete successfully. ### Database fields @@ -1118,19 +1118,19 @@ Task states store state information about the progress of a task on a particular (date/time) - When this task state was cancelled, rejected, or approved. + When this task state was canceled, rejected, or approved. .. attribute:: finished_by (foreign key to user model) - The user who completed (cancelled, rejected, approved) the task. + The user who completed (canceled, rejected, approved) the task. .. attribute:: comment (text) - A text comment, typically added by a user when the task is completed. + A text comment is typically added by a user when the task is completed. ``` ### Methods and properties @@ -1266,7 +1266,7 @@ An abstract base class that represents a record of an action performed on an obj (dict) The JSON representation of any additional details for each action. - For example source page id and title when copying from a page. Or workflow id/name and next step id/name on a workflow transition + For example, source page id and title when copying from a page. Or workflow id/name and next step id/name on a workflow transition .. attribute:: timestamp @@ -1278,7 +1278,7 @@ An abstract base class that represents a record of an action performed on an obj (boolean) - A boolean that can set to ``True`` when the content has changed. + A boolean that can be set to ``True`` when the content has changed. .. attribute:: deleted diff --git a/docs/reference/pages/panels.md b/docs/reference/pages/panels.md index bbab0b2c48..d7f6f919e2 100644 --- a/docs/reference/pages/panels.md +++ b/docs/reference/pages/panels.md @@ -4,7 +4,7 @@ ## Built-in Fields and Choosers -Wagtail's panel mechanism automatically recognises Django model fields and provides them with an appropriate widget for input. You can use it by defining the field in your Django model as normal and passing the field name into +Wagtail's panel mechanism automatically recognizes Django model fields and provides them with an appropriate widget for input. You can use it by defining the field in your Django model as normal and passing the field name into [`FieldPanel`](wagtail.admin.panels.FieldPanel) (or a suitable panel type) when defining your panels. Here are some built-in panel types that you can use in your panel definitions. These are all subclasses of the base [`Panel`](wagtail.admin.panels.Panel) class, and unless otherwise noted, they accept all of `Panel`'s parameters in addition to their own. @@ -21,7 +21,7 @@ Here are some built-in panel types that you can use in your panel definitions. T ```{eval-rst} .. autoclass:: FieldPanel - This is the panel to use for basic Django model field types. It provides a default icon and heading based on the model field definition, but they can be customised by passing additional arguments to the constructor. For more details, see :ref:`customising_panels`. + This is the panel to use for basic Django model field types. It provides a default icon and heading based on the model field definition, but they can be customized by passing additional arguments to the constructor. For more details, see :ref:`customising_panels`. .. attribute:: FieldPanel.field_name @@ -33,7 +33,7 @@ Here are some built-in panel types that you can use in your panel definitions. T .. attribute:: FieldPanel.disable_comments (optional) - This allows you to prevent a field level comment button showing for this panel if set to ``True``. See `Create and edit comments <https://guide.wagtail.org/en-latest/how-to-guides/manage-pages/#create-and-edit-comments>`_. + This allows you to prevent a field-level comment button from showing for this panel if set to ``True``. See `Create and edit comments <https://guide.wagtail.org/en-latest/how-to-guides/manage-pages/#create-and-edit-comments>`_. .. attribute:: FieldPanel.permission (optional) @@ -45,7 +45,7 @@ Here are some built-in panel types that you can use in your panel definitions. T For most field types, the field value will be rendered in the form for editors to see (along with field's label and help text), but no form inputs will be displayed, and the form will ignore attempts to change the value in POST data. For example by injecting a hidden input into the form HTML before submitting. - By default, field values from ``StreamField`` or ``RichTextField`` are redacted to prevent rendering of potentially insecure HTML mid-form. You can change this behaviour for custom panel types by overriding ``Panel.format_value_for_display()``. + By default, field values from ``StreamField`` or ``RichTextField`` are redacted to prevent rendering of potentially insecure HTML mid-form. You can change this behavior for custom panel types by overriding ``Panel.format_value_for_display()``. .. attribute:: FieldPanel.attrs (optional) @@ -83,7 +83,7 @@ Here are some built-in panel types that you can use in your panel definitions. T ```{eval-rst} .. class:: InlinePanel(relation_name, panels=None, label='', min_num=None, max_num=None, **kwargs) - 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. For a full explanation on the usage of ``InlinePanel``, see :ref:`inline_models`. To save space, you can :ref:`collapse the panel by default <collapsible>`. + 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. For a full explanation of the usage of ``InlinePanel``, see :ref:`inline_models`. To save space, you can :ref:`collapse the panel by default <collapsible>`. .. attribute:: InlinePanel.relation_name @@ -135,7 +135,7 @@ class BlogPage(Page): ] ``` -Using the JavaScript as follows. +Using JavaScript is as follows. ```javascript // static/js/inline-panel.js @@ -201,7 +201,7 @@ The `MultipleChooserPanel` definition on `BlogPage` would be: This panel 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". + The 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". By default, the panel is divided into equal-width columns, but this can be overridden by adding ``col*`` class names to each of the child Panels of the FieldRowPanel. The Wagtail editing interface is laid out using a grid system. Classes ``col1``-``col12`` can be applied to each child of a FieldRowPanel to define how many columns they span out of the total number of columns. When grid items add up to 12 columns, 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. @@ -243,7 +243,7 @@ The `MultipleChooserPanel` definition on `BlogPage` would be: ```{eval-rst} .. autoclass:: PageChooserPanel - While ``FieldPanel`` also supports ``ForeignKey`` to :class:`~wagtail.models.Page` models, you can explicitly use ``PageChooserPanel`` to allow ``Page``-specific customisations. + While ``FieldPanel`` also supports ``ForeignKey`` to :class:`~wagtail.models.Page` models, you can explicitly use ``PageChooserPanel`` to allow ``Page``-specific customizations. .. code-block:: python @@ -270,7 +270,7 @@ The `MultipleChooserPanel` definition on `BlogPage` would be: PageChooserPanel('related_page', ['demo.PublisherPage', 'demo.AuthorPage']) - Passing ``can_choose_root=True`` will allow the editor to 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 page with an automatic "related articles" feed could use a ``PageChooserPanel`` to select which subsection articles will be taken from, with the root corresponding to 'everywhere'. + Passing ``can_choose_root=True`` will allow the editor to choose the tree root as a page. Normally this would be undesirable since the tree root is never a usable page, but in some specialized cases it may be appropriate; for example, a page with an automatic "related articles" feed could use a ``PageChooserPanel`` to select which subsection articles will be taken from, with the root corresponding to 'everywhere'. ``` ### FormSubmissionsPanel @@ -304,15 +304,15 @@ The `MultipleChooserPanel` definition on `BlogPage` would be: .. autoclass:: TitleFieldPanel - This is the panel to use for Page title fields or main titles on other models. It provides a default classname, placeholder and widget attributes to enable the automatic sync with the slug field in the form. Many of these defaults can be customised by passing additional arguments to the constructor. All the same `FieldPanel` arguments are supported including a custom widget. For more details, see :ref:`customising_panels`. + This is the panel to use for Page title fields or main titles on other models. It provides a default classname, placeholder, and widget attributes to enable the automatic sync with the slug field in the form. Many of these defaults can be customized by passing additional arguments to the constructor. All the same `FieldPanel` arguments are supported including a custom widget. For more details, see :ref:`customising_panels`. ``` (customising_panels)= -## Panel customisation +## Panel customization -By adding extra parameters to your panel/field definitions, you can control much of how your fields will display in the Wagtail page editing interface. Wagtail's page editing interface takes much of its behaviour from Django's admin, so you may find many options for customisation covered there. +By adding extra parameters to your panel/field definitions, you can control much of how your fields will display in the Wagtail page editing interface. Wagtail's page editing interface takes much of its behavior from Django's admin, so you may find many options for customisation covered there. (See [Django model field reference](inv:django#ref/models/fields)). (customising_panel_icons)= @@ -327,7 +327,7 @@ Use the `heading` argument to the panel constructor to set the panel's heading. ### CSS classes -Use the `classname` argument to the panel constructor to add CSS classes to the panel. The class will be applied to the HTML `<section>` element of the panel. This can be used to add extra styling to the panel or to control its behaviour. +Use the `classname` argument to the panel constructor to add CSS classes to the panel. The class will be applied to the HTML `<section>` element of the panel. This can be used to add extra styling to the panel or to control its behavior. The `title` class can be used to make the input stand out with a bigger font size and weight. @@ -350,13 +350,13 @@ The `collapsed` class will load the editor page with the panel collapsed under i ### Help text -Use the `help_text` argument to the panel constructor to customise the help text to be displayed above the input. If unset for `FieldPanel`s, it will be set automatically using the form field's `help_text` (taken in turn from a model field's `help_text`). +Use the `help_text` argument to the panel constructor to customize the help text to be displayed above the input. If unset for `FieldPanel`s, it will be set automatically using the form field's `help_text` (taken in turn from a model field's `help_text`). ### Placeholder text By default, Wagtail uses the field's label as placeholder text. To change it, pass to the `FieldPanel` a widget with a placeholder attribute set to your desired text. You can select widgets from [Django's form widgets](inv:django#ref/forms/widgets), or any of the Wagtail's widgets found in `wagtail.admin.widgets`. -For example, to customise placeholders for a `Book` snippet model: +For example, to customize placeholders for a `Book` snippet model: ```python # models.py @@ -368,7 +368,7 @@ class Book(models.Model): release_date = models.DateField() price = models.DecimalField(max_digits=5, decimal_places=2) - # you can create them separately + # You can create them separately title_widget = forms.TextInput( attrs = { 'placeholder': 'Enter Full Title' @@ -427,7 +427,7 @@ In this example, 'notes' will be visible to all editors, 'cost' and 'details' wi Use the `attrs` parameter to add custom attributes to the HTML element of the panel. This allows you to specify additional attributes, such as `data-*` attributes. The `attrs` parameter accepts a dictionary where the keys are the attribute names and these will be rendered in the same way as Django's widget {attr}`~django.forms.Widget.attrs` where `True` and `False` will be treated as HTML5 boolean attributes. -For example, you can use the `attrs` parameter to integrate your Stimulus controller to the panel: +For example, you can use the `attrs` parameter to integrate your Stimulus controller into the panel: ```python content_panels = [ diff --git a/docs/reference/pages/theory.md b/docs/reference/pages/theory.md index 546c40f62b..c203bcee72 100644 --- a/docs/reference/pages/theory.md +++ b/docs/reference/pages/theory.md @@ -18,7 +18,7 @@ As a web developer, though, you probably already have a good understanding of tr winter-wrap-up/ ``` -The Wagtail admin interface uses the tree to organise content for editing, letting you navigate up and down levels in the tree through its Explorer menu. This method of organisation is a good place to start in thinking about your own Wagtail models. +The Wagtail admin interface uses the tree to organize content for editing, letting you navigate up and down levels in the tree through its Explorer menu. This method of organization is a good place to start in thinking about your own Wagtail models. ### Nodes and Leaves @@ -26,7 +26,7 @@ It might be handy to think of the `Page`-derived models you want to create as be #### Nodes -Parent nodes on the Wagtail tree probably want to organise and display a browse-able index of their descendants. A blog, for instance, needs a way to show a list of individual posts. +Parent nodes on the Wagtail tree probably want to organize and display a browseable index of their descendants. A blog, for instance, needs a way to show a list of individual posts. A Parent node could provide its own function returning its descendant objects. @@ -34,7 +34,7 @@ A Parent node could provide its own function returning its descendant objects. class EventPageIndex(Page): # ... def events(self): - # Get list of live event pages that are descendants of this page + # Get the list of live event pages that are descendants of this page events = EventPage.objects.live().descendant_of(self) # Filter events list to get ones that are either @@ -47,11 +47,11 @@ class EventPageIndex(Page): return events ``` -This example makes sure to limit the returned objects to pieces of content which make sense, specifically ones which have been published through Wagtail's admin interface (`live()`) and are children of this node (`descendant_of(self)`). By setting a `subpage_types` class property in your model, you can specify which models are allowed to be set as children, and by setting a `parent_page_types` class property, you can specify which models are allowed to be parents of this page model. Wagtail will allow any `Page`-derived model by default. Regardless, it's smart for a parent model to provide an index filtered to make sense. +This example makes sure to limit the returned objects to pieces of content that make sense, specifically ones that have been published through Wagtail's admin interface (`live()`) and are children of this node (`descendant_of(self)`). By setting a `subpage_types` class property in your model, you can specify which models are allowed to be set as children, and by setting a `parent_page_types` class property, you can specify which models are allowed to be parents of this page model. Wagtail will allow any `Page`-derived model by default. Regardless, it's smart for a parent model to provide an index filtered to make sense. #### Leaves -Leaves are the pieces of content itself, a page which is consumable, and might just consist of a bunch of properties. A blog page leaf might have some body text and an image. A person page leaf might have a photo, a name, and an address. +Leaves are the pieces of content itself, a consumable page, and might just consist of a bunch of properties. A blog page leaf might have some body text and an image. A person's page leaf might have a photo, a name, and an address. It might be helpful for a leaf to provide a way to back up along the tree to a parent, such as in the case of breadcrumbs navigation. The tree might also be deep enough that a leaf's parent won't be included in general site navigation. @@ -61,7 +61,7 @@ The model for the leaf could provide a function that traverses the tree in the o class EventPage(Page): # ... def event_index(self): - # Find closest ancestor which is an event index + # Find the closest ancestor which is an event index return self.get_ancestors().type(EventIndexPage).last() ``` @@ -69,7 +69,7 @@ If defined, `subpage_types` and `parent_page_types` will also limit the parent m #### Other Relationships -Your `Page`-derived models might have other interrelationships which extend the basic Wagtail tree or depart from it entirely. You could provide functions to navigate between siblings, such as a "Next Post" link on a blog page (`post->post->post`). It might make sense for subtrees to interrelate, such as in a discussion forum (`forum->post->replies`) Skipping across the hierarchy might make sense, too, as all objects of a certain model class might interrelate regardless of their ancestors (`events = EventPage.objects.all`). It's largely up to the models to define their interrelations, the possibilities are really endless. +Your `Page`-derived models might have other interrelationships that extend the basic Wagtail tree or depart from it entirely. You could provide functions to navigate between siblings, such as a "Next Post" link on a blog page (`post->post->post`). It might make sense for subtrees to interrelate, such as in a discussion forum (`forum->post->replies`) Skipping across the hierarchy might make sense, too, as all objects of a certain model class might interrelate regardless of their ancestors (`events = EventPage.objects.all`). It's largely up to the models to define their interrelations, the possibilities are endless. (anatomy_of_a_wagtail_request)= @@ -85,32 +85,32 @@ For going beyond the basics of model definition and interrelation, it might help 6. `serve()` finds a template to pass it to using `get_template()` 7. A response object is returned by `serve()` and Django responds to the requester. -You can apply custom behaviour to this process by overriding `Page` class methods such as `route()` and `serve()` in your own models. For examples, see [Recipes](page_model_recipes). +You can apply custom behavior to this process by overriding `Page` class methods such as `route()` and `serve()` in your own models. For examples, see [Recipes](page_model_recipes). (scheduled_publishing)= ## Scheduled Publishing Page publishing can be scheduled through the _Set schedule_ feature in the _Status_ side panel of the _Edit_ page. This allows you to set up initial page publishing or a page update in advance. -In order for pages to go live at the scheduled time, you should set up the [publish_scheduled](publish_scheduled) management command. +For pages to go live at the scheduled time, you should set up the [publish_scheduled](publish_scheduled) management command. The basic workflow is as follows: - Scheduling is done by setting the _go-live at_ field of the page and clicking _Publish_. - Scheduling a revision for a page that is not currently live means that page will go live when the scheduled time comes. -- Scheduling a revision for a page that is already live means that revision will be published when the time comes. +- Scheduling a revision for a page that is already live means that the revision will be published when the time comes. - If the page has a scheduled revision and you set another revision to publish immediately (i.e. clicking _Publish_ with the _go-live at_ field unset), the scheduled revision will be unscheduled. - If the page has a scheduled revision and you schedule another revision to publish (i.e. clicking _Publish_ with the _go-live at_ field set), the existing scheduled revision will be unscheduled and the new revision will be scheduled instead. Note that you have to click _Publish_ after setting the _go-live at_ field for the revision to be scheduled. Saving a draft revision with the _go-live at_ field without clicking _Publish_ will not schedule it to be published. -The _History_ view for a given page will show which revision is scheduled and when it is scheduled for. A scheduled revision in the list will also provide an _Unschedule_ button to cancel it. +The _History_ view for a given page will show which revision is scheduled and when it is scheduled. A scheduled revision in the list will also provide an _Unschedule_ button to cancel it. In addition to scheduling a page to be published, it is also possible to schedule a page to be unpublished by setting the _expire at_ field. However, unlike with publishing, the unpublishing schedule is applied to the live page instance rather than a specific revision. This means that any change to the _expire at_ field will only be effective once the associated revision is published (i.e. when the changes are applied to the live instance). To illustrate: - Scheduling is done by setting the _expire at_ field of the page and clicking _Publish_. If the _go-live at_ field is also set, then the unpublishing schedule will only be applied after the revision goes live. - Consider a live page that is scheduled to be unpublished on e.g. 14 June. Then sometime before the schedule, consider that a new revision is scheduled to be published on a date that's **earlier** than the unpublishing schedule, e.g. 9 June. When the new revision goes live on 9 June, the _expire at_ field contained in the new revision will replace the existing unpublishing schedule. This means: - - If the new revision contains a different _expire at_ field (e.g. 17 June), the new revision will go live on 9 June and the page will not be unpublished on 14 June but it will be unpublished on 17 June. + - If the new revision contains a different _expire at_ field (e.g. 17 June), the new revision will go live on 9 June and the page will not be unpublished on 14 June but will be unpublished on 17 June. - If the new revision has the _expire at_ field unset, the new revision will go live on 9 June and the unpublishing schedule will be unset, thus the page will not be unpublished. - Consider another live page that is scheduled to be unpublished on e.g. 14 June. Then sometime before the schedule, consider that a new revision is scheduled to be published on a date that's **later** than the unpublishing schedule, e.g. 21 June. The new revision will not take effect until it goes live on 21 June, so the page will still be unpublished on 14 June. This means: - If the new revision contains a different _expire at_ field (e.g. 25 June), the page will be unpublished on 14 June, the new revision will go live on 21 June and the page will be unpublished again on 25 June. diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 0f8645dd61..3e82b4a487 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -70,17 +70,17 @@ WAGTAILSEARCH_HITS_MAX_AGE = 14 Set the number of days (default 7) that search query logs are kept for; these are used to identify popular search terms for [promoted search results](editors_picks). Queries older than this will be removed by the [](searchpromotions_garbage_collect) command. -## Internationalisation +## Internationalization -Wagtail supports internationalisation of content by maintaining separate trees of pages for each language. +Wagtail supports the internationalization of content by maintaining separate trees of pages for each language. -For a guide on how to enable internationalisation on your site, see the [configuration guide](enabling_internationalisation). +For a guide on how to enable internationalization on your site, see the [configuration guide](enabling_internationalisation). ### `WAGTAIL_I18N_ENABLED` (boolean, default `False`) -When set to `True`, Wagtail's internationalisation features will be enabled: +When set to `True`, Wagtail's internationalization features will be enabled: ```python WAGTAIL_I18N_ENABLED = True @@ -107,7 +107,7 @@ Each item in the list is a 2-tuple containing a language code and a display name The language code can either be a language code on its own (such as `en`, `fr`), or it can include a region code (such as `en-gb`, `fr-fr`). You can mix the two formats if you only need to localize in some regions but not others. -This setting follows the same structure of Django's `LANGUAGES` setting, so they can both be set to the same value: +This setting follows the same structure as Django's `LANGUAGES` setting, so they can both be set to the same value: ```python LANGUAGES = WAGTAIL_CONTENT_LANGUAGES = [ @@ -145,8 +145,8 @@ Note that all languages that exist in ``WAGTAIL_CONTENT_LANGUAGES`` must also ex ## Embeds -Wagtail supports generating embed code from URLs to content on an external providers such as Youtube or Twitter. By default, Wagtail will fetch the embed code directly from the relevant provider's site using the oEmbed protocol. -Wagtail has a builtin list of the most common providers. +Wagtail supports generating embed code from URLs to content on external providers such as YouTube or X (formerly Twitter). By default, Wagtail will fetch the embed code directly from the relevant provider's site using the oEmbed protocol. +Wagtail has a built-in list of the most common providers. The embeds fetching can be fully configured using the `WAGTAILEMBEDS_FINDERS` setting. This is fully documented in [](configuring_embed_finders). @@ -188,10 +188,10 @@ WAGTAILADMIN_RICH_TEXT_EDITORS = { } ``` -Customise the behaviour of rich text fields. By default, `RichTextField` and `RichTextBlock` use the configuration given under the `'default'` key, but this can be overridden on a per-field basis through the `editor` keyword argument, for example `body = RichTextField(editor='secondary')`. Within each configuration block, the following fields are recognised: +Customize the behavior of rich text fields. By default, `RichTextField` and `RichTextBlock` use the configuration given under the `'default'` key, but this can be overridden on a per-field basis through the `editor` keyword argument, for example `body = RichTextField(editor='secondary')`. Within each configuration block, the following fields are recognized: - `WIDGET`: The rich text widget implementation to use. Wagtail provides `wagtail.admin.rich_text.DraftailRichTextArea` (a modern extensible editor which enforces well-structured markup). Other widgets may be provided by third-party packages. -- `OPTIONS`: Configuration options to pass to the widget. Recognised options are widget-specific, but `DraftailRichTextArea` accept a `features` list indicating the active rich text features (see [](rich_text_features)). +- `OPTIONS`: Configuration options to pass to the widget. Recognized options are widget-specific, but `DraftailRichTextArea` accepts a `features` list indicating the active rich text features (see [](rich_text_features)). If a `'default'` editor is not specified, rich text fields that do not specify an `editor` argument will use the Draftail editor with the default feature set enabled. @@ -203,7 +203,7 @@ If a `'default'` editor is not specified, rich text fields that do not specify a WAGTAILADMIN_EXTERNAL_LINK_CONVERSION = 'exact' ``` -Customise Wagtail's behaviour when an internal page url is entered in the external link chooser. Possible values for this setting are `'all'`, `'exact'`, `'confirm`, or `''`. The default, `'all'`, means that Wagtail will automatically convert submitted urls that exactly match page urls to the corresponding internal links. If the url is an inexact match - for example, the submitted url has query parameters - then Wagtail will confirm the conversion with the user. `'exact'` means that any inexact matches will be left as external urls, and the confirmation step will be skipped. `'confirm'` means that every link conversion will be confirmed with the user, even if the match is exact. `''` means that Wagtail will not attempt to convert any urls entered to internal page links. +Customize Wagtail's behavior when an internal page url is entered in the external link chooser. Possible values for this setting are `'all'`, `'exact'`, `'confirm`, or `''`. The default, `'all'`, means that Wagtail will automatically convert submitted urls that exactly match page urls to the corresponding internal links. If the url is an inexact match - for example, the submitted url has query parameters - then Wagtail will confirm the conversion with the user. `'exact'` means that any inexact matches will be left as external urls, and the confirmation step will be skipped. `'confirm'` means that every link conversion will be confirmed with the user, even if the match is exact. `''` means that Wagtail will not attempt to convert any urls entered to internal page links. ### `WAGTAIL_DATE_FORMAT`, `WAGTAIL_DATETIME_FORMAT`, `WAGTAIL_TIME_FORMAT` @@ -213,7 +213,7 @@ WAGTAIL_DATETIME_FORMAT = '%d.%m.%Y. %H:%M' WAGTAIL_TIME_FORMAT = '%H:%M' ``` -Specifies the date, time and datetime format to be used in input fields in the Wagtail admin. The format is specified in [Python datetime module syntax](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior), and must be one of the recognised formats listed in the `DATE_INPUT_FORMATS`, `TIME_INPUT_FORMATS`, or `DATETIME_INPUT_FORMATS` setting respectively (see [DATE_INPUT_FORMATS](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DATE_INPUT_FORMATS)). +Specifies the date, time, and datetime format to be used in input fields in the Wagtail admin. The format is specified in [Python datetime module syntax](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior) and must be one of the recognized formats listed in the `DATE_INPUT_FORMATS`, `TIME_INPUT_FORMATS`, or `DATETIME_INPUT_FORMATS` setting respectively (see [DATE_INPUT_FORMATS](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-DATE_INPUT_FORMATS)). ## Page editing @@ -243,7 +243,7 @@ WAGTAIL_AUTO_UPDATE_PREVIEW = True ``` When enabled, the preview panel in the page editor is automatically updated on each change. If set to `False`, a refresh button will be shown and the preview is only updated when the button is clicked. -This behaviour is enabled by default. +This behavior is enabled by default. To completely disable the preview panel, set [preview modes](wagtail.models.Page.preview_modes) to be empty on your model `preview_modes = []`. @@ -253,7 +253,7 @@ To completely disable the preview panel, set [preview modes](wagtail.models.Page WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL = 500 ``` -The interval (in milliseconds) to check for changes made in the page editor before updating the preview. The default value is `500`. +The interval (in milliseconds) is to check for changes made in the page editor before updating the preview. The default value is `500`. (wagtailadmin_global_edit_lock)= @@ -394,11 +394,11 @@ WAGTAILDOCS_SERVE_METHOD = 'redirect' Determines how document downloads will be linked to and served. Normally, requests for documents are sent through a Django view, to perform privacy checks (see [Collection Privacy settings](https://guide.wagtail.org/en-latest/how-to-guides/manage-collections/#privacy-settings)) and potentially other housekeeping tasks such as hit counting. To fully protect against users bypassing this check, it needs to happen in the same request where the document is served; however, this incurs a performance hit as the document then needs to be served by the Django server. In particular, this cancels out much of the benefit of hosting documents on external storage, such as S3 or a CDN. -For this reason, Wagtail provides a number of serving methods which trade some of the strictness of the permission check for performance: +For this reason, Wagtail provides several serving methods that trade some of the strictness of the permission check for performance: - `'direct'` - links to documents point directly to the URL provided by the underlying storage, bypassing the Django view that provides the permission check. This is most useful when deploying sites as fully static HTML (for example using [wagtail-bakery](https://github.com/wagtail/wagtail-bakery) or [Gatsby](https://www.gatsbyjs.org/)). -- `'redirect'` - links to documents point to a Django view which will check the user's permission; if successful, it will redirect to the URL provided by the underlying storage to allow the document to be downloaded. This is most suitable for remote storage backends such as S3, as it allows the document to be served independently of the Django server. Note that if a user is able to guess the latter URL, they will be able to bypass the permission check; some storage backends may provide configuration options to generate a random or short-lived URL to mitigate this. -- `'serve_view'` - links to documents point to a Django view which both checks the user's permission, and serves the document. Serving will be handled by [django-sendfile](https://github.com/johnsensible/django-sendfile), if this is installed and supported by your server configuration, or as a streaming response from Django if not. When using this method, it is recommended that you configure your webserver to _disallow_ serving documents directly from their location under `MEDIA_ROOT`, as this would provide a way to bypass the permission check. +- `'redirect'` - links to documents point to a Django view which will check the user's permission; if successful, it will redirect to the URL provided by the underlying storage to allow the document to be downloaded. This is most suitable for remote storage backends such as S3, as it allows the document to be served independently of the Django server. Note that if a user can guess the latter URL, they will be able to bypass the permission check; some storage backends may provide configuration options to generate a random or short-lived URL to mitigate this. +- `'serve_view'` - links to documents point to a Django view which both checks the user's permission and serves the document. Serving will be handled by [django-sendfile](https://github.com/johnsensible/django-sendfile), if this is installed and supported by your server configuration, or as a streaming response from Django if not. When using this method, it is recommended that you configure your webserver to _disallow_ serving documents directly from their location under `MEDIA_ROOT`, as this would provide a way to bypass the permission check. If `WAGTAILDOCS_SERVE_METHOD` is unspecified or set to `None`, the default method is `'redirect'` when a remote storage backend is in use (one that exposes a URL but not a local filesystem path), and `'serve_view'` otherwise. Finally, some storage backends may not expose a URL at all; in this case, serving will proceed as for `'serve_view'`. @@ -470,7 +470,7 @@ This specifies whether password fields are shown when creating or editing users WAGTAILUSERS_PASSWORD_REQUIRED = True ``` -This specifies whether password is a required field when creating a new user. True by default; ignored if `WAGTAILUSERS_PASSWORD_ENABLED` is false. If this is set to False, and the password field is left blank when creating a user, then that user will have no usable password; in order to log in, they will have to reset their password (if `WAGTAIL_PASSWORD_RESET_ENABLED` is True) or use an alternative authentication system such as LDAP (if one is set up). +This specifies whether password is a required field when creating a new user. True by default; ignored if `WAGTAILUSERS_PASSWORD_ENABLED` is false. If this is set to False, and the password field is left blank when creating a user, then that user will have no usable password; to log in, they will have to reset their password (if `WAGTAIL_PASSWORD_RESET_ENABLED` is True) or use an alternative authentication system such as LDAP (if one is set up). ### `WAGTAIL_EMAIL_MANAGEMENT_ENABLED` @@ -536,7 +536,7 @@ Allows the default `LoginForm` to be extended with extra fields. WAGTAILADMIN_LOGIN_URL = 'http://example.com/login/' ``` -This specifies the URL to redirect to when a user attempts to access a Wagtail admin page without being logged in. If omitted, Wagtail will fall back to using the standard login view (typically `/admin/login/`). +This specifies the URL to redirect when a user attempts to access a Wagtail admin page without being logged in. If omitted, Wagtail will fall back to using the standard login view (typically `/admin/login/`). ## User preferences @@ -554,12 +554,12 @@ If a user has not uploaded a profile picture, Wagtail will look for an avatar li ### `WAGTAIL_USER_TIME_ZONES` -Logged-in users can choose their current time zone for the admin interface in the account settings. If is no time zone selected by the user, then `TIME_ZONE` will be used. +Logged-in users can choose their current time zone for the admin interface in the account settings. If there is no time zone selected by the user, then `TIME_ZONE` will be used. (Note that time zones are only applied to datetime fields, not to plain time or date fields. This is a Django design decision.) The list of time zones is by default the common_timezones list from pytz. It is possible to override this list via the `WAGTAIL_USER_TIME_ZONES` setting. -If there is zero or one time zone permitted, the account settings form will be hidden. +If there is zero or one-time zone permitted, the account settings form will be hidden. ```python WAGTAIL_USER_TIME_ZONES = ['America/Chicago', 'Australia/Sydney', 'Europe/Rome'] @@ -620,7 +620,7 @@ WAGTAIL_ENABLE_UPDATE_CHECK = True For admins only, Wagtail performs a check on the dashboard to see if newer releases are available. This also provides the Wagtail team with the hostname of your Wagtail site. If you'd rather not receive update notifications, or if you'd like your site to remain unknown, you can disable it with this setting. -If admins should only be informed of new long term support (LTS) versions, then set this setting to `"lts"` (the setting is case-insensitive). +If admins should only be informed of new long-term support (LTS) versions, then set this setting to `"lts"` (the setting is case-insensitive). (wagtail_enable_whats_new_banner)= @@ -630,7 +630,7 @@ If admins should only be informed of new long term support (LTS) versions, then WAGTAIL_ENABLE_WHATS_NEW_BANNER = True ``` -For new releases, Wagtail may show a notification banner on the dashboard that helps users learn more about the UI changes and new features in the release. Users are able to dismiss this banner, which will hide it until the next release. If you'd rather not show these banners, you can disable it with this setting. +For new releases, Wagtail may show a notification banner on the dashboard that helps users learn more about the UI changes and new features in the release. Users can dismiss this banner, which will hide it until the next release. If you'd rather not show these banners, you can disable it with this setting. ## Frontend authentication @@ -652,7 +652,7 @@ As above, but for password restrictions on documents. For more details, see the ### `WAGTAIL_FRONTEND_LOGIN_TEMPLATE` -The basic login page can be customised with a custom template. +The basic login page can be customized with a custom template. ```python WAGTAIL_FRONTEND_LOGIN_TEMPLATE = 'myapp/login.html' @@ -775,7 +775,7 @@ For full documentation on frontend cache invalidation, including these settings, } ``` -See documentation linked above for full options available. +See the documentation linked above for the full options available. ```{note} ``WAGTAILFRONTENDCACHE_LOCATION`` is no longer the preferred way to set the cache location, instead set the ``LOCATION`` within the ``WAGTAILFRONTENDCACHE`` item. @@ -787,7 +787,7 @@ See documentation linked above for full options available. WAGTAILFRONTENDCACHE_LANGUAGES = [l[0] for l in settings.LANGUAGES] ``` -Default is an empty list, must be a list of languages to also purge the urls for each language of a purging url. This setting needs `settings.USE_I18N` to be `True` to work. +Default is an empty list, there must be a list of languages to also purge the urls for each language of a purging url. This setting needs `settings.USE_I18N` to be `True` to work. ## Redirects @@ -797,7 +797,7 @@ Default is an empty list, must be a list of languages to also purge the urls for WAGTAIL_REDIRECTS_FILE_STORAGE = 'tmp_file' ``` -By default the redirect importer keeps track of the uploaded file as a temp file, but on certain environments (load balanced/cloud environments), you cannot keep a shared file between environments. For those cases you can use the built-in cache to store the file instead. +By default the redirect importer keeps track of the uploaded file as a temp file, but on certain environments (load balanced/cloud environments), you cannot keep a shared file between environments. For those cases, you can use the built-in cache to store the file instead. ```python WAGTAIL_REDIRECTS_FILE_STORAGE = 'cache' diff --git a/docs/reference/signals.md b/docs/reference/signals.md index 11df187ae2..7f30a1bc0f 100644 --- a/docs/reference/signals.md +++ b/docs/reference/signals.md @@ -152,11 +152,11 @@ This signal is emitted from a `WorkflowState` when a page's workflow completes s ## workflow_cancelled -This signal is emitted from a `WorkflowState` when a page's workflow is cancelled +This signal is emitted from a `WorkflowState` when a page's workflow is canceled - `sender` - `WorkflowState` - `instance` - The specific `WorkflowState` instance. -- `user` - The user who cancelled the workflow +- `user` - The user who canceled the workflow - `kwargs` - Any other arguments passed to `workflow_cancelled.send()` ## task_submitted @@ -188,9 +188,9 @@ This signal is emitted from a `TaskState` when a page's task is approved ## task_cancelled -This signal is emitted from a `TaskState` when a page's task is cancelled. +This signal is emitted from a `TaskState` when a page's task is canceled. - `sender` - `TaskState` - `instance` - The specific `TaskState` instance. -- `user` - The user who cancelled the task +- `user` - The user who canceled the task - `kwargs` - Any other arguments passed to `task_cancelled.send()` diff --git a/docs/reference/streamfield/blocks.md b/docs/reference/streamfield/blocks.md index c3f2af16f9..2c000cc00a 100644 --- a/docs/reference/streamfield/blocks.md +++ b/docs/reference/streamfield/blocks.md @@ -50,7 +50,7 @@ All block definitions accept the following optional keyword arguments: - `template` - The path to a Django template that will be used to render this block on the front end. See [Template rendering](streamfield_template_rendering) - `group` - - The group used to categorise this block. Any blocks with the same group name will be shown together in the editor interface with the group name as a heading. + - The group used to categorize this block. Any blocks with the same group name will be shown together in the editor interface with the group name as a heading. (field_block_types)= @@ -194,7 +194,7 @@ All block definitions accept the following optional keyword arguments: A date picker. The following keyword arguments are accepted in addition to the standard ones: - :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 format: Date format. This must be one of the recognized 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/>`__). @@ -215,9 +215,9 @@ All block definitions accept the following optional keyword arguments: .. autoclass:: wagtail.blocks.DateTimeBlock :show-inheritance: - A combined date / time picker. The following keyword arguments are accepted in addition to the standard ones: + A combined date/time picker. The following keyword arguments are accepted in addition to the standard ones: - :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 format: Date/time format. This must be one of the recognized 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/>`__). @@ -334,7 +334,7 @@ All block definitions accept the following optional keyword arguments: :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'. + :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 specialized 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'. .. autoclass:: wagtail.documents.blocks.DocumentChooserBlock @@ -381,9 +381,9 @@ All block definitions accept the following optional keyword arguments: .. autoclass:: wagtail.blocks.StaticBlock :show-inheritance: - 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 that 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: - :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``: + :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 customized by passing ``admin_text``: .. code-block:: python @@ -459,7 +459,7 @@ All block definitions accept the following optional keyword arguments: :param value_class: A subclass of ``wagtail.blocks.StructValue`` to use as the type of returned values for this block. See :ref:`custom_value_class_for_structblock`. :param search_index: If false (default true), the content of this block will not be indexed for searching. :param label_format: - Determines the label shown when the block is collapsed in the editing interface. By default, the value of the first sub-block in the StructBlock is shown, but this can be customised by setting a string here with block names contained in braces - for example ``label_format = "Profile for {first_name} {surname}"`` + Determines the label shown when the block is collapsed in the editing interface. By default, the value of the first sub-block in the StructBlock is shown, but this can be customized by setting a string here with block names contained in braces - for example ``label_format = "Profile for {first_name} {surname}"`` .. autoclass:: wagtail.blocks.ListBlock @@ -494,7 +494,7 @@ All block definitions accept the following optional keyword arguments: :param form_classname: An HTML ``class`` attribute to set on the root element of this block as displayed in the editing interface. :param min_num: Minimum number of sub-blocks that the list must have. :param max_num: Maximum number of sub-blocks that the list may have. - :param search_index: If false (default true) , the content of this block will not be indexed for searching. + :param search_index: If false (default true), the content of this block will not be indexed for searching. :param collapsed: When true, all sub-blocks are initially collapsed. @@ -547,7 +547,7 @@ All block definitions accept the following optional keyword arguments: ``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 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 search_index: If false (default true), the content of this block will not be indexed for searching. diff --git a/docs/reference/streamfield/widget_api.md b/docs/reference/streamfield/widget_api.md index 07e289c123..4d7117baf1 100644 --- a/docs/reference/streamfield/widget_api.md +++ b/docs/reference/streamfield/widget_api.md @@ -2,7 +2,7 @@ # Form widget client-side API -In order for the StreamField editing interface to dynamically create form fields, any Django form widgets used within StreamField blocks must have an accompanying JavaScript implementation, defining how the widget is rendered client-side and populated with data, and how to extract data from that field. Wagtail provides this implementation for widgets inheriting from `django.forms.widgets.Input`, `django.forms.Textarea`, `django.forms.Select` and `django.forms.RadioSelect`. For any other widget types, or ones which require custom client-side behaviour, you will need to provide your own implementation. +For the StreamField editing interface to dynamically create form fields, any Django form widgets used within StreamField blocks must have an accompanying JavaScript implementation, defining how the widget is rendered client-side and populated with data, and how to extract data from that field. Wagtail provides this implementation for widgets inheriting from `django.forms.widgets.Input`, `django.forms.Textarea`, `django.forms.Select` and `django.forms.RadioSelect`. For any other widget types, or ones that require custom client-side behavior, you will need to provide your own implementation. This implementation can be driven by [Stimulus](extending_client_side_stimulus) or for deeper integrations you can leverage telepath. @@ -41,7 +41,7 @@ The JavaScript object associated with a widget instance should provide a single ```{eval-rst} .. js:function:: render(placeholder, name, id, initialState) - Render a copy of this widget into the current page, and perform any initialisation required. + Render a copy of this widget into the current page, and perform any initialization required. :param placeholder: An HTML DOM element to be replaced by the widget's HTML. :param name: A string to be used as the ``name`` attribute on the input element. For widgets that use multiple input elements (and have server-side logic for collating them back into a final value), this can be treated as a prefix, with further elements delimited by dashes. (For example, if ``name`` is ``'person-0'``, the widget may create elements with names ``person-0-first_name`` and ``person-0-surname`` without risking collisions with other field names on the form.) diff --git a/docs/releases/1.9.rst b/docs/releases/1.9.rst index 7c1c9efd28..a2b17264ff 100644 --- a/docs/releases/1.9.rst +++ b/docs/releases/1.9.rst @@ -55,7 +55,7 @@ Other features * View live / draft links in the admin now consistently open in a new window (Marco Fucci) * ``ChoiceBlock`` now omits the blank option if the block is required and has a default value (Andreas Nüßlein) * The ``add_subpage`` view now maintains a ``next`` URL parameter to specify where to redirect to after completing page creation (Robert Rollins) -* The ``wagtailforms`` module now allows to define custom form submission model, add custom data to CSV export and some other customisations. See :doc:`/reference/contrib/forms/customisation` (Mikalai Radchuk) +* The ``wagtailforms`` module now allows to define custom form submission model, add custom data to CSV export and some other customisations. See :doc:`/reference/contrib/forms/customization` (Mikalai Radchuk) * The Webpack configuration is now in a subfolder to declutter the project root, and uses environment-specific configurations for smaller bundles in production and easier debugging in development (Janneke Janssen, Thibaud Colas) * Added page titles to title text on action buttons in the explorer, for improved accessibility (Matt Westcott) diff --git a/docs/releases/2.14.rst b/docs/releases/2.14.rst index c83ef90abd..88c98aa5f4 100644 --- a/docs/releases/2.14.rst +++ b/docs/releases/2.14.rst @@ -16,7 +16,7 @@ New features ~~~~~~~~~~~~ * Added ``ancestor_of`` API filter. See :ref:`apiv2_filter_by_tree_position`. (Jaap Roes) - * Added support for customising group management views. See :ref:`customising_group_views`. (Jan Seifert) + * Added support for customising group management views. See :ref:`customizing_group_views`. (Jan Seifert) * Added ``full_url`` property to image renditions (Shreyash Srivastava) * Added locale selector when choosing translatable snippets (Karl Hobley) * Added ``WAGTAIL_WORKFLOW_ENABLED`` setting for enabling / disabling moderation workflows globally (Matt Westcott) diff --git a/docs/releases/5.1.md b/docs/releases/5.1.md index f4a5c0faba..2434209fa2 100644 --- a/docs/releases/5.1.md +++ b/docs/releases/5.1.md @@ -84,7 +84,7 @@ We have made a number of improvements to snippets as part of [RFC 85: Snippets p * Return filters from `parse_query_string` as a `QueryDict` to support multiple values (Aman Pandey) * Explicitly specify `MenuItem.name` for all admin menu and submenu items (Justin Koestinger) * Add oEmbed provider patterns for YouTube Shorts (e.g. [https://www.youtube.com/shorts/nX84KctJtG0](https://www.youtube.com/shorts/nX84KctJtG0)) and YouTube Live URLs (valnuro, Fabien Le Frapper) - * Add a predictable default ordering of the "Object/Other permissions" in the Group Editing view, allow this [ordering to be customised](customising_group_views_permissions_order) (Daniel Kirkham) + * Add a predictable default ordering of the "Object/Other permissions" in the Group Editing view, allow this [ordering to be customised](customizing_group_views_permissions_order) (Daniel Kirkham) * Implement a new design for chooser buttons with better accessibility (Thibaud Colas) * Add [`AbstractImage.get_renditions()`](image_renditions_multiple) for efficient generation of multiple renditions (Andy Babic) * Phone numbers entered via a link chooser will now have any spaces stripped out, ensuring a valid `href="tel:..."` attribute (Sahil Jangra) @@ -266,7 +266,7 @@ During the deprecation period, the `permission_type` field will still be availab The ordering for "Object permissions" and "Other permissions" now follows a predictable order equivalent to Django's default `Model` ordering. This will be different to the previous indeterminate ordering. -The default ordering is now `["content_type__app_label", "content_type__model"]`. See [](customising_group_views_permissions_order) for details on how to customise this order. +The default ordering is now `["content_type__app_label", "content_type__model"]`. See [](customizing_group_views_permissions_order) for details on how to customise this order. ### JSON-timestamps stored in `ModelLogEntry` and `PageLogEntry` are now ISO-formatted and UTC diff --git a/docs/releases/5.2.md b/docs/releases/5.2.md index 98b2e2968c..9752d77101 100644 --- a/docs/releases/5.2.md +++ b/docs/releases/5.2.md @@ -306,7 +306,7 @@ Models that are registered with a `ModelViewSet` now have reference index tracki ### Groups `IndexView.results_template_name` renamed from `results.html` to `index_results.html` -The `IndexView`'s `results_template_name` attribute in the `GroupViewSet` has been renamed from `wagtailusers/groups/results.html` to `wagtailusers/groups/index_results.html` for consistency with the other viewsets. If you have customised or extended the template, e.g. for [](customising_group_views), you will need to rename it to match the new name. +The `IndexView`'s `results_template_name` attribute in the `GroupViewSet` has been renamed from `wagtailusers/groups/results.html` to `wagtailusers/groups/index_results.html` for consistency with the other viewsets. If you have customised or extended the template, e.g. for [](customizing_group_views), you will need to rename it to match the new name. ### `construct_snippet_listing_buttons` hook no longer accepts a `context` argument diff --git a/docs/releases/6.1.md b/docs/releases/6.1.md index 85e498b2de..f5a115bc97 100644 --- a/docs/releases/6.1.md +++ b/docs/releases/6.1.md @@ -31,6 +31,7 @@ depth: 1 * Add contributing development documentation on how to work with a fork of Wagtail (Nix Asteri, Dan Braghis) * Make sure the settings panel is listed in tabbed interface examples (Tibor Leupold) + * Update multiple pages in the reference sections and multiple page names to their US spelling instead of UK spelling (Victoria Poromon) ### Maintenance diff --git a/docs/topics/snippets/customising.md b/docs/topics/snippets/customizing.md similarity index 100% rename from docs/topics/snippets/customising.md rename to docs/topics/snippets/customizing.md diff --git a/docs/topics/snippets/index.md b/docs/topics/snippets/index.md index fddaa83210..8a10d321c6 100644 --- a/docs/topics/snippets/index.md +++ b/docs/topics/snippets/index.md @@ -13,5 +13,5 @@ maxdepth: 2 registering rendering features -customising +customizing ``` diff --git a/wagtail/models/collections.py b/wagtail/models/collections.py index 0aa1c4af35..99bf0ffd0d 100644 --- a/wagtail/models/collections.py +++ b/wagtail/models/collections.py @@ -90,7 +90,7 @@ class Collection(MP_Node): Renders this Collection's name as a formatted string that displays its hierarchical depth via indentation. If indentation_start_depth is supplied, the Collection's depth is rendered relative to that depth. indentation_start_depth defaults to 2, the depth of the first non-Root Collection. - Pass html=True to get a HTML representation, instead of the default plain-text. + Pass html=True to get an HTML representation, instead of the default plain-text. Example text output: " ↳ Pies" Example HTML output: "    ↳ Pies" diff --git a/wagtail/test/testapp/models.py b/wagtail/test/testapp/models.py index f0ac00fe34..4ff07c90e3 100644 --- a/wagtail/test/testapp/models.py +++ b/wagtail/test/testapp/models.py @@ -556,7 +556,7 @@ class FormPage(AbstractEmailForm): # This is redundant (SubmissionsListView is the default view class), but importing # SubmissionsListView in this models.py helps us to confirm that this recipe - # https://docs.wagtail.org/en/stable/reference/contrib/forms/customisation.html#customise-form-submissions-listing-in-wagtail-admin + # https://docs.wagtail.org/en/stable/reference/contrib/forms/customization.html#customise-form-submissions-listing-in-wagtail-admin # works without triggering circular dependency issues - # see https://github.com/wagtail/wagtail/issues/6265 submissions_list_view_class = SubmissionsListView