Встраиваемое содержимое

Rich text

Встроенный редактор rich text Wagtail имеет значок «медиа», который позволяет размещать встраиваемые элементы в rich text. Вам не нужно ничего делать, чтобы активировать это; просто убедитесь, что содержимое поля rich text передаётся через фильтр |richtext в шаблоне, так как это вызывает модуль встраивания для получения и вложения кода встраивания.

EmbedBlock Тип блока StreamField

Тип блока EmbedBlock позволяет размещать встраиваемые элементы в StreamField.

Аргументы max_width и max_height отправляются поставщику при получении кода встраивания.

Например:

from wagtail.embeds.blocks import EmbedBlock

class MyStreamField(blocks.StreamBlock):
    ...

    embed = EmbedBlock(max_width=800, max_height=400)

{% embed %} тег

Синтаксис: {% embed <url> [max_width=<max width>] %}

Вы можете вложить встраиваемые элементы в шаблон, передав URL-адрес и необязательный аргумент max_width тегу {% embed %}.

Аргумент max_width отправляется поставщику при получении кода встраивания.

{% load wagtailembeds_tags %}

{# Embed a YouTube video #}
{% embed 'https://www.youtube.com/watch?v=Ffu-2jEdLPw' %}

{# This tag can also take the URL from a variable #}
{% embed page.video_url %}

Из Python

Вы также можете вызвать внутреннюю функцию get_embed, которая принимает строку URL и возвращает объект Embed (см. документацию модели ниже). Она также принимает необязательный ключевой аргумент max_width, который отправляется поставщику при получении кода встраивания.

from wagtail.embeds.embeds import get_embed
from wagtail.embeds.exceptions import EmbedException

try:
    embed = get_embed('https://www.youtube.com/watch?v=Ffu-2jEdLPw')

    print(embed.html)
except EmbedException:
    # Cannot find embed
    pass

oEmbed (по умолчанию)

Поисковик встраивания по умолчанию получает код встраивания напрямую от поставщика контента с помощью протокола oEmbed. Wagtail имеет встроенный список поставщиков, все из которых включены по умолчанию. Вы можете найти этот список поставщиков по следующей ссылке:

https://github.com/wagtail/wagtail/blob/main/wagtail/embeds/oembed_providers.py

from wagtail.embeds.oembed_providers import youtube, vimeo

# Add a custom provider
# Your custom provider must support oEmbed for this to work. You should be
# able to find these details in the provider's documentation.
# - 'endpoint' is the URL of the oEmbed endpoint that Wagtail will call
# - 'urls' specifies which patterns
my_custom_provider = {
    'endpoint': 'https://customvideosite.com/oembed',
    'urls': [
        '^http(?:s)?://(?:www\\.)?customvideosite\\.com/[^#?/]+/videos/.+$',
    ]
}

WAGTAILEMBEDS_FINDERS = [
    {
        'class': 'wagtail.embeds.finders.oembed',
        'providers': [youtube, vimeo, my_custom_provider],
    }
]

from wagtail.embeds.oembed_providers import youtube


WAGTAILEMBEDS_FINDERS = [
    # Fetches YouTube videos but puts ``?scheme=https`` in the GET parameters
    # when calling YouTube's oEmbed endpoint
    {
        'class': 'wagtail.embeds.finders.oembed',
        'providers': [youtube],
        'options': {'scheme': 'https'}
    },

    # Handles all other oEmbed providers the default way
    {
        'class': 'wagtail.embeds.finders.oembed',
    }
]

Facebook и Instagram

Начиная с октября 2020 года, Facebook прекратил поддержку своих публичных API oEmbed. Если вы хотите встроить записи Facebook или Instagram на свой сайт, вам необходимо использовать новые аутентифицированные API. Для этого вам нужно создать учётную запись разработчика Facebook и создать приложение Facebook, которое включает в себя продукт «oEmbed». Инструкции по созданию необходимого приложения содержатся в разделах требований к документации Facebook и Instagram.

Начиная с июня 2021 года, продукт «oEmbed» был заменён функцией «oEmbed Read». Для встраивания записей Facebook и Instagram ваше приложение должно активировать функцию «oEmbed Read». Кроме того, приложение должно быть проверено и одобрено Facebook. Вы можете найти объявление в изменениях API.

Приложения, которые активировали продукт oEmbed до 8 июня 2021 года, должны активировать функцию oEmbed Read и пройти проверку своего приложения до 7 сентября 2021 года.

После того, как у вас будут токены доступа к вашему приложению (ID приложения и секрет приложения), добавьте поисковики Facebook и/или Instagram в свою настройку WAGTAILEMBEDS_FINDERS и настройте их с помощью ID приложения и секрета приложения из вашего приложения:

WAGTAILEMBEDS_FINDERS = [
    {
        'class': 'wagtail.embeds.finders.facebook',
        'app_id': 'YOUR FACEBOOK APP_ID HERE',
        'app_secret': 'YOUR FACEBOOK APP_SECRET HERE',
    },
    {
        'class': 'wagtail.embeds.finders.instagram',
        'app_id': 'YOUR INSTAGRAM APP_ID HERE',
        'app_secret': 'YOUR INSTAGRAM APP_SECRET HERE',
    },

    # Handles all other oEmbed providers the default way
    {
        'class': 'wagtail.embeds.finders.oembed',
    }
]

По умолчанию встраиваемые элементы Facebook и Instagram включают в себя некоторые JavaScript-скрипты, необходимые для их полного отображения. В некоторых случаях это может быть нежелательно — например, если у вас есть несколько встраиваемых элементов Facebook, это приведёт к нескольким тегам script. Передав 'omitscript': True в конфигурацию, вы можете указать, что эти теги script должны быть опущены из HTML встраиваемого элемента. Обратите внимание, что вам затем придётся самостоятельно позаботиться о загрузке этого скрипта.

Embed.ly

Embed.ly — платная услуга, которая также может предоставлять встраиваемые элементы для сайтов, не реализующих протокол oEmbed.

Они также предоставляют некоторые полезные функции, такие как обеспечение единообразного вида встраиваемых элементов и общий API для воспроизведения видео, что полезно, если ваш сайт позволяет размещать видео на разных поставщиках, и вам нужно реализовать пользовательские элементы управления для них.

Wagtail имеет встроенную поддержку получения встраиваемых элементов от Embed.ly. Для его использования сначала установите пакет Python Embedly python package.

Теперь добавьте поисковик встраивания в вашу настройку WAGTAILEMBEDS_FINDERS, использующий класс wagtail.embeds.finders.oembed и передайте ему свой API-ключ:

WAGTAILEMBEDS_FINDERS = [
    {
        'class': 'wagtail.embeds.finders.embedly',
        'key': 'YOUR EMBED.LY KEY HERE'
    }
]

Пользовательские классы поисковиков встраивания

Для полного контроля вы можете создать пользовательский класс поисковика.

Вот примерный класс поисковика, который можно использовать в качестве шаблона; обратите внимание на документацию к методам для подробностей о том, что делает каждый метод:

from wagtail.embeds.finders.base import EmbedFinder


class ExampleFinder(EmbedFinder):
    def __init__(self, **options):
        pass

    def accept(self, url):
        """
        Returns True if this finder knows how to fetch an embed for the URL.

        This should not have any side effects (no requests to external servers)
        """
        pass

    def find_embed(self, url, max_width=None):
        """
        Takes a URL and max width and returns a dictionary of information about the
        content to be used for embedding it on the site.

        This is the part that may make requests to external APIs.
        """
        # TODO: Perform the request

        return {
            'title': "Title of the content",
            'author_name': "Author name",
            'provider_name': "Provider name (such as YouTube, Vimeo, etc)",
            'type': "Either 'photo', 'video', 'link' or 'rich'",
            'thumbnail_url': "URL to thumbnail image",
            'width': width_in_pixels,
            'height': height_in_pixels,
            'html': "<h2>The Embed HTML</h2>",
        }

После того, как вы реализовали все эти методы, вам нужно просто добавить его в настройку WAGTAILEMBEDS_FINDERS:

WAGTAILEMBEDS_FINDERS = [
    {
        'class': 'path.to.your.finder.class.here',
        # Any other options will be passed as kwargs to the __init__ method
    }
]

Удаление встраиваемых элементов

Пока ваша конфигурация встраиваемых элементов не сломана, удаление элементов в модели Embed должно быть абсолютно безопасным. Wagtail автоматически перезаполнит записи, используемые на сайте.

Это может быть полезно, если вы переключились с oEmbed на Embedly или наоборот, поскольку код встраивания, который они генерируют, может незначительно отличаться и привести к несоответствию на вашем сайте.