README

此插件包实现了在 XMLBlock 内容对象属性内容中检测文件下载链接的解决方案，并显示用户可以使用以打开文件文档的文档辅助应用程序。

版本

• BC 文档阅读器当前版本为 0.1.6

• 上次重大更新：2015 年 5 月 20 日

版权

• BC 文档阅读器版权所有 1999 - 2015 Brookins 咨询公司和 2013 - 2015 Think Creative

• 查看：COPYRIGHT.md 了解有关版权和许可证条款的更多信息

许可证

BC 文档阅读器采用 GNU 通用公共许可证。

完整的许可证协议包含在 LICENSE 文件中。

BC 文档阅读器是免费软件：您可以根据自由软件基金会发布的 GNU 通用公共许可证的条款重新分发和/或修改它，许可证版本为 2 或您选择的更高版本。

BC 文档阅读器以希望它将是有用的目的进行分发，但没有任何保证；甚至没有隐含的适销性或特定用途适用性的保证。有关详细信息，请参阅 GNU 通用公共许可证。

GNU GPL 在某些条件下授予您使用、修改和重新分发 BC 文档阅读器的权利。GNU GPL 许可证随软件一起分发，请参阅 doc/LICENSE 文件。

它也可在 https://gnu.ac.cn/licenses/gpl.txt 上找到

您应该已经收到与 BC 文档阅读器一起的 GNU 通用公共许可证副本，位于 doc/LICENSE 中。如果没有，请参阅 https://gnu.ac.cn/licenses/。

根据 GNU GPL 许可证使用 BC 文档阅读器是免费的（作为自由）。

有关更多信息或疑问，请联系： license@brookinsconsulting.com

要求

使用 BC 文档阅读器扩展需要以下要求

eZ Publish 版本

• 确保您使用 eZ Publish 版本 5.x（必需）或更高版本。

• 与 eZ Publish 社区项目 2013.11 设计和测试

PHP 版本

• 确保您有 PHP 5.x 或更高版本。

功能

Twig 操作符

此解决方案提供以下 twig 过滤器和函数

• Twig 过滤器：bc_document_reader - 在模板覆盖中使用，用于检测配置为检测的下载文件链接（通过 yaml 选项）以及通过传递的 twig 过滤器 url 参数输入检测到的链接。

• Twig 函数：bc_document_readers - 显示配置为检测的下载文件链接的文档阅读器列表，这些链接在当前页面内容对象的 XML BLock 属性内容中被检测到。

• Twig 过滤器：bc_file_size - 与内容/下载文件下载嵌入模板一起使用，以显示嵌入文件的大小。此 twig 过滤器直接基于 ezplatform6.0-alpha1 默认提供的 ez_file_size。这种复制是为了在 eZ Publish 平台 5.x 的旧版本中引入相同的功能支持。

服务

• 辅助检测内容和模板中文件下载链接的服务

依赖关系

• 此解决方案在任何方面都不依赖于eZ Publish Legacy

• 分页数据的持久存储和文档阅读器文件链接扩展

• 分页数据变量的底层持久存储由BcPageData包提供。

  • 如果您通过composer安装，此依赖项将自动安装

用例需求

本解决方案旨在满足客户网站对文档可访问性的共同需求。

可能没有具体标准要求本解决方案的所有部分，但它是我们在构建基于Web的文档管理解决方案时应该认真考虑遵循的最佳实践的一部分。

ADA / 第508节合规性

这些标准更具体地描述了使链接文档本身可访问的内容（这不在我们的控制范围内，而是在客户手中），其余部分是最佳实践，但不一定是“必需的”。

第508节标准/合规性要求侧重于使文档本身可访问的标准（这通常不在我们的控制范围内，而是在客户手中）。

虽然第508节标准/合规性要求没有具体提及或要求以下所有项目，但我们发现以下最佳实践（不一定是“必需的”）有助于创建更易于使用的文档管理和阅读的Web用户体验。

• 指向文档直接下载的链接应包括文档标题，或明确描述所链接的文档。

• 所有链接，包括但不限于文档直接下载链接，都应遵守所有一般第508节标准。

  • 链接的大小应根据设备可读。

  • 链接应遵守颜色对比标准。

• 当合适时，文档直接下载链接应显示相关的mime-type图标和文件大小。

• 包含文档直接下载链接的页面还应显示指向相应文档阅读器（例如Adobe Acrobat）的适当下载页面的链接，如果可能，在页面底部打开文档。

• 与文档链接（例如文档缩略图）相关的任何图像（或任何非文本元素）都必须包括简洁描述该元素所传达内容的“alt”文本。

• 避免在页面结构中将冗余链接相邻放置（例如，如果缩略图图像链接到文档，然后是标准文本链接到同一文档，则两者都应尽可能包裹在单个<a>元素中）。

有关“美国残疾人法案和第508节合规性”的更多信息，请访问http://www.section508.gov。

安装

通过Composer安装Bundle

从您的项目根目录运行以下命令以安装包

bash$ composer require brookinsconsulting/bcdocumentreaderbundle dev-master;

Bundle激活

在文件ezpublish/EzPublishKernel.php中use语句的底部，添加以下行。

use BrookinsConsulting\BcPageDataBundle\BcPageDataBundle;
use BrookinsConsulting\BcDocumentReaderBundle\BcDocumentReaderBundle;

在文件ezpublish/EzPublishKernel.php的registerBundles方法中，将以下内容添加到$bundles = array(变量定义中。

// Brookins Consulting : BcDocumentReaderBundle Requirements
new BrookinsConsulting\BcPageDataBundle\BcPageDataBundle(),
new BrookinsConsulting\BcDocumentReaderBundle\BcDocumentReaderBundle()

Bundle资产安装

建议（为了内置功能正常工作）在安装和激活包之后安装包资产。

以下是安装包资产的一个示例

php -d memory_limit=-1 ezpublish/console assets:install --relative --symlink web

Bundle样式安装

建议（为了按设计正常工作）在您的pagelayout模板中安装包样式的包含。

为已配置为提供scss的站点安装Bundle样式

此解决方案默认使用scss为其样式表，而不是纯css，并期望您的安装的assetic config.yml已启用assetic样式表过滤器“compass,cssrewrite”。

编辑您的pagelayout twig模板，并在样式表包含中添加bundle的styles.scss。

{% stylesheets filter="compass,cssrewrite"
    "@YourCustomBundle/Resources/public/scss/styles.scss"
    "@BcDocumentReaderBundle/Resources/public/scss/styles.scss"
%}

您还希望确保Ruby和Compass都已安装并可用，因为它们由assetic用于将scss转换为css。

您可以通过多种方式安装 Ruby 和 Compass。在运行 assetic:dump 命令并测试网站对这些工具的使用之前，请确保它们可以通过命令行访问。

建议（为了使内置功能按预期工作）在安装 pagelayout 模板中包含的 bundle 样式后，再导出 bundle 资产。

以下是导出 bundle 资产的示例

php -d memory_limit=-1 ezpublish/console assetic:dump --env=dev web

为尚未配置为提供 scss 的网站安装 Bundle 样式

此解决方案默认使用scss为其样式表，而不是纯css，并期望您的安装的assetic config.yml已启用assetic样式表过滤器“compass,cssrewrite”。

在 eZ Publish 平台 / eZ Platform 的默认安装中，您可以自己通过以下更改来启用这些要求。

启用 assetic 样式表过滤器 compass 和 cssrewrite

编辑您的 ezpublish/config.yml 文件并做出以下更改

# Assetic Configuration
assetic:
    debug:          %kernel.debug%
    use_controller: true
# snip (to avoid confusion)
    filters:
        cssrewrite: ~
        compass: ~

具体来说，您必须将这些行添加到您的 assetic 配置中，保存所有配置更改并清除所有缓存

# Assetic Configuration
# snip (to avoid confusion)
    filters:
        cssrewrite: ~
        compass: ~

确保 Ruby 和 Compass 已安装且可用

Ruby 和 Compass 用于将 scss 转换为 css。您可以通过多种方式安装 Ruby 和 Compass。在测试网站对这些工具的使用之前，请确保它们可以通过命令行访问。

为尚未配置为提供 scss 的网站安装 scss 样式模板代码

编辑您的 pagelayout.html.twig 模板或 page_head_style.html.twig 模板，并在现有仅包含 css 的样式表调用 之后 添加 bundle 的 styles.scss 调用

{% stylesheets
    '@eZDemoBundle/Resources/public/css/bootstrap.css'
    '@eZDemoBundle/Resources/public/css/responsive.css'
    '@eZDemoBundle/Resources/public/css/video.css'
    '@BCPageLayoutOverrideTestBundle/Resources/public/css/override.css'
%}
    <link rel="stylesheet" type="text/css" href="{{ asset_url }}"/>
{% endstylesheets %}

{% stylesheets filter="compass,cssrewrite"
    '@BcDocumentReaderBundle/Resources/public/scss/styles.scss'
%}
    <link rel="stylesheet" type="text/css" href="{{ asset_url }}"/>
{% endstylesheets %}

上述示例来自 eZ Publish 平台 Demo Bundle 的默认安装（2014.11）。

建议（为了使内置功能按预期工作）在安装 pagelayout 模板中包含的 bundle 样式后，再导出 bundle 资产。

以下是导出 bundle 资产的示例

php -d memory_limit=-1 ezpublish/console assetic:dump --env=dev web

Bundle 文档辅助 Twig 函数安装

编辑您的 pagelayout twig 模板并添加以下 bc_document_readers twig 函数代码

{# START INSTALL THIS CODE: BC Document Reader : Display Document Reader Helper Application Download Links #}
{{ include('BcDocumentReaderBundle:parts:reader_links.html.twig', {}) }}
{# END INSTALL THIS CODE: BC Document Reader #}

以下是一个基本的使用示例

<div id="main-content" class="{% if is_homepage is not defined %}panel-light-blue subpage{% endif %}" >
    {% if is_homepage is not defined %}
    <div class="container">
    {% endif %}

    {% block content %}
        {% if module_result %}
            {# we are in a legacy rendered module #}
            {{ module_result.content|raw }}
        {% endif %}
    {% endblock %}

    {# START INSTALL THIS CODE: BC Document Reader : Display Document Reader Helper Application Download Links #}
    {{ include('BcDocumentReaderBundle:parts:reader_links.html.twig', {}) }}
    {# END INSTALL THIS CODE: BC Document Reader #}

    {% if is_homepage is not defined %}
    </div>
    {% endif %}
</div>

清除缓存

清除 eZ Publish 平台 / eZ platform 缓存（必需）。

php ezpublish/console cache:clear;

模板自定义

自定义模板覆盖 Twig 过滤器安装

如果您需要在自定义模板覆盖（可能用于自定义内容类型）中使用 bc_document_reader twig 过滤器，只需将模板内容的 URL 字符串值传递给过滤器，即可检测文件 / 文档类型。

媒体类型 / 文件类型自定义

支持的文件扩展名和媒体类型

请查阅 Resources/config/documentreader.yml 和 Resources/config/mimetypes.yml 以获取默认检测到的文件扩展名和媒体类型。

如果您希望支持更多文件扩展名和媒体类型，只需将它们添加到 yaml 设置中并清除所有缓存（必需）。

注意避免重复的媒体类型

对于每个文档读取器辅助应用程序组设置，只能有一个媒体类型。

如果设置中已经存在媒体类型，不要添加重复的，因为这会引起严重问题。

相反，只需将额外的文件扩展名添加到现有的文档读取器辅助应用程序组设置中。

向现有媒体类型文档读取器辅助应用程序组设置添加新的文件扩展名。

检测额外的自定义文件扩展名和媒体类型

示例

首先编辑 bundle 设置选项文件 Resources/config/mimeptypes.yml 并搜索您希望为添加文件扩展名支持而添加的媒体类型。

在本例中，我们正在添加对默认情况下不支持 .zipx 文件的检测支持。

由于已经存在 application/zip 媒体类型的设置，您只需添加额外的扩展名。

以下是所需添加/更改的清晰示例。

之前

- { type: "CompressedWin", mimeType: "application/zip", extensions: [ zip ] }

之后

- { type: "CompressedWin", mimeType: "application/zip", extensions: [ zip, zipx ] }

保存您的 yaml 设置添加并清除所有缓存（必需）。

向现有文档读取器辅助应用程序组映射中的现有设置添加新的文件扩展名和媒体类型

示例

首先编辑 bundle 设置选项文件 Resources/config/mimeptypes.yml 并搜索您希望为添加文件扩展名支持而添加的媒体类型。

在本例中，我们正在添加对默认情况下不支持 .cab 文件的检测支持。

由于尚未设置application/vnd.ms-cab-compressed mimetypes，您只需添加完整的设置定义。

以下是所需添加/更改的清晰示例。

添加以下设置行

helper_mime_map:
# Snip (Feel free to place the following line any position below the helper_mime_map: line
- { type: "CompressedWin", mimeType: "application/vnd.ms-cab-compressed", extensions: [ cab ] }

保存您的 yaml 设置添加并清除所有缓存（必需）。

默认情况下，添加上述设置将显示压缩Win文档读取器辅助应用程序，“WinRar（适用于Windows）”。

在新的文档读取器辅助应用程序组映射中添加一个新文件扩展名和 mimetypes，该 mimetypes 不在默认设置中。

示例

首先编辑 bundle 设置选项文件 Resources/config/mimeptypes.yml 并搜索您希望为添加文件扩展名支持而添加的媒体类型。

在此示例中，我们正在添加对默认情况下不受支持的.ogg音频文件的支持。

由于尚未设置audio/ogg mimetypes，您只需添加完整的设置定义。

以下是所需添加/更改的清晰示例。

添加以下设置行

helper_mime_map:
# Snip (Feel free to place the following line any position below the helper_mime_map: line
- { type: "WindowsVlc", mimeType: "audio/ogg", extensions: [ ogg, opus, oga, spx ] }

保存您的 yaml 设置添加。

第二次编辑捆绑设置选项文件 Resources/config/documentreaders.yml 并添加以下文档读取器辅助设置

以下是所需添加/更改的清晰示例。

添加以下设置行

helpers:
    WindowsVlc:
        name: VLC Media File
        viewer_name: VLC Media Player
        viewer_url: http://get.videolan.org/vlc/2.2.1/win32/vlc-2.2.1-win32.exe
        icon: audio
        icon_image: mimetypes/sound.png

保存您的 yaml 设置添加并清除所有缓存（必需）。

默认情况下，添加上述设置将显示WindowsVlc文档读取器辅助应用程序，“Vlc（适用于Windows）”。

用法

默认情况下，该解决方案在正确安装后配置为虚拟工作。

测试

该解决方案在正确安装和配置后配置为工作。

只需导航到包含一个或多个xmlblock属性的内容对象节点。如果 xmlblock 属性内容包含对 pdf、zip、rar、mp3 等文件的链接，则在您的用户 siteaccess 中加载此页面。如果没有，则使用管理员添加一些默认支持的文件类型链接，并在您的用户 siteaccess 中查看节点。

故障排除

阅读常见问题解答

一些问题比其他问题更常见。最常见的问题列在doc/FAQ.md

支持

如果您发现此文档或常见问题解答中没有处理的问题，您可以通过支持系统联系 Brookins Consulting：http://brookinsconsulting.com/contact