Встроенное содержимое

Wagtail поддерживает генерацию кода вставки из URL-адресов к содержимому на внешних поставщиках, таких как YouTube или Twitter. По умолчанию Wagtail будет извлекать код вставки непосредственно с сайта соответствующего поставщика с использованием протокола oEmbed.

Wagtail имеет встроенный список наиболее распространённых поставщиков, и этот список можно изменить с помощью настроек. Wagtail также поддерживает извлечение кода вставки с помощью Embedly и пользовательских поисковиков вставки.

Вставка содержимого на ваш сайт

Модуль вставки Wagtail должен работать прямо из коробки для большинства поставщиков. Вы можете использовать любой из следующих методов для вызова модуля:

Текстовый редактор

Стандартный текстовый редактор Wagtail имеет значок «медиа», который позволяет вставлять вставки в текстовый редактор. Вам ничего не нужно делать, чтобы включить эту возможность; просто убедитесь, что содержимое текстового поля передаётся через фильтр |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

Настройка поисковиков вставки

Поисковики вставки — это модули в Wagtail, ответственные за создание кода вставки из URL-адреса.

Поисковики вставки настраиваются с помощью настройки WAGTAILEMBEDS_FINDERS. Это список конфигураций поисковиков, которые выполняются по очереди, пока один из них успешно не вернёт вставку:

Настройка по умолчанию:

WAGTAILEMBEDS_FINDERS = [
    {
        'class': 'wagtail.embeds.finders.oembed'
    }
]

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

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

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

Настройка списка поставщиков

Можно ограничить используемых поставщиков, указав список поставщиков в конфигурации поисковика.

Например, эта настройка позволит вставлять контент только с Vimeo и YouTube. Она также добавляет пользовательского поставщика:

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],
    }
]

Настройка отдельного поставщика

Несколько поисковиков могут быть объединены друг за другом. Это может использоваться для настройки конфигурации одного поставщика без влияния на другие.

Например, так можно настроить YouTube на возврат видео в HTTPS (что необходимо явно сделать для YouTube):

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 Developer и приложения Facebook, которое включает oEmbed Product. Инструкции по созданию необходимого приложения находятся в разделах требований документации Facebook и Instagram.

По состоянию на июнь 2021 года функция oEmbed Product была заменена функцией oEmbed Read. Для вставки постов Facebook и Instagram ваше приложение должно активировать функцию oEmbed Read. Кроме того, приложение должно быть проверено и одобрено Facebook. Об этом можно узнать в журнале изменений API.

Приложения, которые активировали продукт oEmbed до 8 июня 2021 года, должны активировать функцию чтения oEmbed и проверить своё приложение до 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, это приведёт к нескольким тегам скрипта. Передавая 'omitscript': True в настройку, вы можете указать, что эти теги скрипта должны быть исключены из 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 (eg. 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

Удаление вставок

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

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