armstrong.apps.embeds 0.9

功能

• 单个嵌入，多种关系！始终了解您使用的外部内容和使用引用的数量。

• 元数据！访问外部内容的元数据。比纯iframe嵌入代码更有用。

• 模块化后端！通过标准接口获取元数据和嵌入代码，访问各种内容提供者API。

• 可定制模板！表示与数据分离。让外部内容看起来适合您的网站。

• 单个嵌入，多种用途！为每种用例创建模板。视频可以用作标题、缩略图、带标题的信用、画廊等。

• 统一的视觉外观！每种内容类型共享模板。无论来源如何，视频内容都可以以标准格式呈现。

• 自动后端分配！只需一步即可编程嵌入。我们只需要URL。

• 管理员预览！在保存之前检查响应数据。看起来奇怪？切换后端并再次预览。

• 响应缓存！不必担心第三方API失败。响应将无限期缓存。

• 检查新数据！从管理员处查看是否有新数据可用，而无需对其进行任何承诺。

• 鸟瞰图！汇总您通常如何以及使用哪些类型的外部内容的信息。

安装和配置

支持Django 1.3、1.4、1.5、1.6、1.7在Python 2.6和2.7上。（尽管如果您使用Django 1.3，请确保使用django-model-utils<1.4。）

1. pip安装armstrong.apps.embeds

2. [可选] 如果您计划使用resize_iframe模板过滤器，请执行pip install lxml

3. [可选] 如果您想使用ArmLayout来渲染模板，请执行pip install armstrong.core.arm_layout

4. 将armstrong.apps.embeds添加到您的INSTALLED_APPS

5. 安装数据库模式

   • Django 1.7+ 使用manage.py migrate

   • 以前的Django使用manage.py syncdb或（如果您使用South，则使用manage.py migrate）

6. 将提供的后端加载到您的数据库中。（这不是作为初始固定数据提供的，这样您就可以在不担心syncdb将恢复初始版本的情况下进行编辑。）

manage.py loaddata embed_backends.json

7. 如果您使用的是Embedly后端，请将您的API密钥添加到settings.py

EMBEDLY_KEY = 'your key'

日志记录：此组件使用armstrong.apps.embeds记录器发出日志语句。

用法

对四个模型的快速概述——

EmbedType和Provider实际上除了规范化数据库和提供快速执行聚合查询的方法之外，并没有做任何事情。EmbedType基于四个oEmbed类型，尽管在实践中您可能还会有一个第五个error类型（这是可以接受的）。

后端是前端模型的实际代码，用于连接第三方API以获取外部内容URL的响应数据。最初从 fixtures 数据文件中加载它们最为简单，但请随意自定义。只需不要更改 slug 即可，这是模型映射到其代码后端的方式。 regex 和 priority 是设计来更改的。这就是您将如何自定义自动分配行为。Embedly 后端将处理 YouTube，但假设您已经编写了一个更针对 YouTube 的后端–通过选择正则表达式和更高的优先级将其添加到数据库中。

嵌入 是基石。创建一个新的嵌入对象只需要一个 url。后端将通过正则表达式匹配 URL 并根据最高优先级选择匹配的后端来自动分配。自动分配只是一个方便的功能，用于加快嵌入的创建。您也可以在对象创建时或之后手动分配后端。模型上的其他每个字段都是后端提供的元数据。请将它们视为只读。那么，您如何获取响应？您如何获取实际信息？

响应对象–

embed_obj.update_response() 将从后端检索响应并在响应有效且不同时分配它，然后返回 True。如果响应无效或相同，则不进行分配并返回 False。如果您想获取响应对象本身，请使用 embed_obj.get_response()。

embed_obj.response 是访问响应数据的方式。这将是一个 BaseResponse 对象的子类，具有一组标准属性。在 API 出现问题、没有返回数据、404 等情况下，is_valid() 将为 False。当响应是新鲜的时，is_fresh() 将为 True。它用于区分数据库缓存的响应数据，您可能可以忽略它。 type 和 provider 是 EmbedType 和 Provider 模型对象。 _data 存储实际的原始响应（JSON 格式）。目标是永远不直接访问它。相反，每个后端/API 都通过继承 BaseResponse 类来子类化，并根据需要对原始数据进行解析以生成标准属性。这样，无论它是 YouTube 还是 Vimeo，都可以以相同的方式访问对象并共享模板。这些属性在没有任何内容可用时返回空字符串，因此是 模板安全 的。当前数据属性包括

• 标题

• 作者名称

• 作者链接

• 图片链接

• 图片高度

• 图片宽度

• 渲染

渲染 可能是最重要的；这是内容提供者提供的嵌入内容的完整表达式。对于 Twitter，这是带有 JavaScript 小部件的 blockquote，它将动态地将推文加载到 iframe 中。对于 YouTube 和 Vimeo，这是视频播放器。无论服务如何设计其内容以进行嵌入，这将是它。

image_xxx 的含义取决于内容。对于视频，这将是在视频播放之前显示的静态图像。对于 SlideShare，它是演示文稿的第一张幻灯片。对于 Flickr，它是缩略图。值得注意的是，我们不知道图片的大小，因此如果您在模板中使用它，请考虑使用属性或 CSS 修复图像标签的尺寸。

后端–

Embedly 是一种元嵌入服务。他们知道如何处理超过 250 家内容提供商，以提供一组标准化的元数据。具体来说，这个后端通过他们的 embedly-python 库使用他们的“嵌入”服务。它提供了巨大的好处，但确实需要一个账户。幸运的是，有一个相当合理的免费层。在安装部分中提到了使用此功能所需的配置。

Twitter 是一个简单的包装器，用于通过 Twitter 的 JavaScript 小部件加载推文。它不执行任何 API 或网络调用，因此不提供任何关于 URL 的元数据。它能做的唯一一件事就是像复制粘贴嵌入代码一样嵌入推文。

默认 只重复提供的 URL。这是一个什么也做不了的通用选项。

模板–

假设您想在您的网站上显示嵌入内容，您将在这一部分花费最多的开发者时间。这不仅仅关乎照片和视频的外观。现在您不仅有了“嵌入代码”的访问权限——现在您有了元数据——您可以用多种方式使用相同的嵌入。例如，一张照片可以作为小图标的预览，一个小图像，一个带有标题的较大图像用于封面艺术，一个故事中的缩略图，它可以展开为带有归属的模态全尺寸版本。无论您想要什么。由于响应对象具有标准接口，所以即使不知道照片是从哪里来的，也不会影响。Instagram 和 TwitPic 的行为相同。

注意：这种供应商冷漠的概念取决于 EmbedType。我们只能将相同类型的处理方式相同，或者对所有嵌入回退到某种通用方式。如果供应商或后端报告一个 Flickr URL 为“链接”类型，即使我们知道在内心深处它是一个“照片”，它也不会使用特定于照片的模板。

现在我们来举一些例子。由于 ArmLayout 是为此目的而设计的，我们将使用它。它提供了一个 render_model 模板标签，它接受一个对象和一个模板名称，然后从最具体到最不具体查找该模板。ArmLayout 使用 get_layout_template_name() 进行查找，AppsEmbeds 则扩展了它，使其还可以查找特定于类型的模板。

render_model embed_obj 'full' 对于 photo 类型将按以下顺序查找

• layout/embeds/embedtype/photo/full.html

• layout/embeds/embed/full.html

因此，要显示嵌入对象为“预览”，只需创建以下文件。每种内容类型都可以自定义“预览”的含义。（可能是一个小缩略图或截断的简介文本。）

• layout/embeds/embedtype/photo/preview.html

• layout/embeds/embedtype/video/preview.html

• layout/embeds/embedtype/link/preview.html

• layout/embeds/embedtype/rich/preview.html

• layout/embeds/embed/preview.html

“封面艺术”是另一种显示嵌入的方式。（可能是一个较大的图像，以及标题和作者归属。）

• layout/embeds/embedtype/photo/lead_art.html

• layout/embeds/embedtype/video/lead_art.html

• layout/embeds/embedtype/link/lead_art.html

• layout/embeds/embedtype/rich/lead_art.html

• layout/embeds/embed/lead_art.html

省略特定类型的模板文件，ArmLayout 将使用层次结构中下一个更通用的文件。

还有一个 default.html 模板用于响应无效或缺失时的回退。（此模板名称可以通过 embed_obj.fallback_template_name 进行自定义。）如果没有响应，则不会在正常/预期模板中显示任何数据。回退可以提供更有用的输出和视觉参考，表明某些事情不正常。

模板标签/过滤器（需要 lxml）–

resize_iframe 是一个模板过滤器，它限制了 iframes 的宽度，因为意外嵌入一个很大的 iframe 可能会破坏布局的外观。它只会缩小大的 iframes；它不会改变已指定大小（或更小）的 iframes。

常见用法

{{ object.response.render|resize_iframe:645|safe }}

在这个例子中，如果render属性包含带有iframe的代码，并且任何一个或所有这些iframe的宽度超过645px，iframe的宽度将被更改为645px，相应地高度会缩小。

限制

内容提供商服务条款–

您嵌入内容的服务可能有其使用指南和限制。请注意并遵守这些规定。重新设计或修改展示方式，或仅使用元数据的部分可能违反他们的服务条款。更改或重复使用内容也可能不尊重内容创作者，也不真诚。请尊重创作者和尊重服务。

发布内容–

嵌入的内容已经发布；它来自其他某个网站。这里重要的是我们如何使用和整合外部内容到我们自己的作品中。Armstrong是一个新闻室和内容发布平台。典型情况是记者和编辑撰写、草稿、校对和发布。内容受到关注，完成之前不会发布。AppsEmbeds也是如此。普遍的假设是有人正在查看嵌入内容——可能不是原始响应数据——但肯定是对其外观的最终结果（即模板如何呈现）。如果外观不正确，则不会发布。

很可能有一天您会遇到一个内容提供商，其响应不符合预期的格式。很难预测这些事情，但希望有人正在查看内容并会注意到。

自定义API查询–

许多API为其提供的响应提供定制。它们可能允许您指定最大宽度和最大高度、文本对齐、本地化、回调、透明模式或单词长度截断。AppsEmbeds主要是因为无法做出这些假设而不进行任何此类操作。AppsEmbeds以默认形式为您提供原始数据，并遵循“定制后”的方法。

resize_iframe是这方面的例子。您可能希望有一个200px的iframe用于预览，以及在文章正文中用于同一嵌入内容的800px iframe。在API调用中设置maxwidth=200、缓存并在此后遇到更大的尺寸用例是不合适的。

最终，API使用可能是一件棘手的事情。在AppsEmbeds范式内，最佳行动方案是定制或创建适合您使用的API和可能要查询的参数的后端和/或响应类。如果您有更好的想法或令人惊叹的后端，请提出拉取请求！

指向同一内容的不同URL–

目前无法确定多个URL是否指向同一内容。这两个YouTube链接将创建两个不同的嵌入对象

https://www.youtube.com/watch?v=12345
https://www.youtube.com/watch?v=12345&feature=player_embedded

贡献

开发在GitHub上完成。欢迎参与！

• 发现了一个错误？在GitHub Issues中提交。尽可能提供详细的信息，并确保列出特定的组件，因为我们使用集中式、跨项目的错误跟踪器。

• 测试？pip install tox然后运行tox

• 有代码要提交？复制仓库，在主题分支上合并您的更改，并创建一个pull request。armstrong.dev包提供用于测试、覆盖和South迁移的工具，以及使用此组件的设置轻松运行完整的Django环境。

• 有疑问、需要帮助、讨论？请使用我们的Google Group邮件列表。

项目状态

Armstrong 是一个开源新闻平台，任何组织都可以免费使用。它是德克萨斯论坛（Texas Tribune）和调查报道中心（The Center for Investigative Reporting）以及约翰·S·和詹姆斯·L·奈特基金会（John S. and James L. Knight Foundation）资助的合作成果。Armstrong 可以作为一个完整的包以及单个独立组件提供。