From e9dcf7ca0142a381bf5005bb30d35fcda0fc5e49 Mon Sep 17 00:00:00 2001 From: Andy Chosak Date: Wed, 13 Mar 2024 11:33:00 -0400 Subject: [PATCH] Documentation updates --- docs/extending/rich_text_internals.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/extending/rich_text_internals.md b/docs/extending/rich_text_internals.md index de7dbf2581..a11340e1a8 100644 --- a/docs/extending/rich_text_internals.md +++ b/docs/extending/rich_text_internals.md @@ -118,11 +118,16 @@ You can create custom rewrite handlers to support your own new `linktype` and `e For example, ``PageLinkHandler.get_instance`` might receive ``{'id': 123}`` and return the instance of the Wagtail ``Page`` class with ID 123. + This method should raise an exception if the provided attributes cannot be used to retrieve a + Django model instance, for example if the provided ``id`` attribute is invalid. + If left undefined, a default implementation of this method will query the ``id`` model field on the class returned by ``get_model`` using the provided ``id`` attribute; this can be overridden in your own handlers should you want to use some other model field. .. method:: get_many(attrs_list) Optional. The classmethod ``get_many`` method works similarly to ``get_instance`` but instead takes a list of attribute dictionaries and returns a list of Django model instances. + + Any instances that cannot be retrieved will be represented by ``None`` in the returned list. ``` Below is an example custom rewrite handler that implements some of these methods to add support for rich text linking to user email addresses. It supports the conversion of rich text tags like `` to valid HTML like ``. This example assumes that equivalent front-end functionality has been added to allow users to insert these kinds of links into their rich text editor.