Oracle APEX 系列文章16:AOP - PDF报表打印新选择

英文原文链接:Configuring AOP as Print Server in Oracle APEX 20.1

在 Oracle APEX 20.1 中将 AOP 配置为打印服务器

Oracle Application Express(APEX)20.1 的新功能之一,就是与 APEX Office Print(AOP)的集成。

在这篇文章中,将介绍这种集成的含义以及如何在 APEX 20.1 中设置和使用 AOP。

Oracle APEX 中的后台打印/报表导出

Oracle APEX 3.0 引入了将报告区域导出为PDF的功能 - 本质上是打印报告。它是声明式定义的,并且可用于所有报告区域。您可以查看和打印带有在每个页面上重复的页面标题和页脚,以及与各种页面大小正确匹配的内容的报告。为此,可使用外部定义的报告服务器将报告数据转换为PDF格式。在早期,此外部报表服务器是 Oracle BI Publisher 或外部 Apache FOP 服务器。后来,当 ORDS 出现时,FOP服务器作为选件包括在内。

我相信外部 Apache FOP 并没有被广泛使用,因为它太复杂,无法简单地设置。有能力支付(巨大的)许可证或已经在公司中拥有许可证的人使用 Oracle BI Publisher。以我的经验,ORDS是使用最多的打印服务器。 但是,在ORDS 18.4发行说明中,宣布将弃用内置FOP服务器,而在ORDS 19.4中,FOP更是被完全放弃。

这意味着人们需要使用旧版本的ORDS或使用其他版本…

关于 APEX Office Print(AOP)

APEX Office Print(AOP)已有5年多历史了,它使从 Oracle APEX 导出和打印报告变得更加容易且成本可控。根据您在Word,Excel,Powerpoint,HTML和Text中创建的模板,AOP会将来自APEX区域的数据,数据库中的数据甚至外部数据与已定义输出格式的模板(例如PDF或任何模板格式)合并。在过去的几年中,AOP广受欢迎,并已成为 Oracle APEX 项目的首选打印引擎。

去年,Oracle宣布他们将直接在 Oracle APEX 中集成 APEX Office Print (AOP) ,而现在已在 APEX 20.1 版本中正式实现。在这一次版本迭代中,AOP 替代了 FOP 服务器,在将来的 Oracle APEX 版本中,则计划支持更多的 AOP 特性。

在 Oracle APEX 20.1 中配置 AOP

要将 AOP 配置为打印服务器,请登录到 INTERNAL 工作区并转到 Instance Settings

单击 Report Printing,然后选择 APEX Office Print 作为打印服务器:

填写运行 AOP Server 的主机地址。AOP支持运行在AOP云中,或者本地部署AOP Server。您可以在 www.apexofficeprint.com 上免费订阅AOP打印服务,也可以下载后进行本地部署。

在APEX 20.1中,只能在实例级别上配置打印服务器。在未来的APEX 20.2版本中,将能够在工作空间(Workspace)级别上覆盖这些设置。这意味着您将有能力为不同的项目使用不同的AOP服务器或云帐户,增加更多的灵活性。

在 Oracle APEX 20.1 中使用 AOP

要查看实际运行中的AOP集成,可以转到任何经典报表(Classic Report)或交互式报表(Interactive Report),然后单击“打印”“下载到PDF”链接。

经典报表(Classic Report)中的“打印”链接:

输出将如下所示:

您可以在“区域”“打印属性”中自定义输出:

单击交互式报告(Interactive Report)中的“操作”>“下载”>“PDF”时,您具有相同的功能

这是 AOP 在 Oracle APEX 中的最基本功能,它模仿了提供的 ORDS、BI Publisher 或外部FOP服务器。

实际上,APEX Office Print 可以做得更多。AOP 可以完全按照您在屏幕上看到的方式打印一个或多个 Interactive Reports,包括突出显示、分段显示、过滤器等。它还可以将 IR、IG 和 Classic Reports 结合在一起,甚至在您提供的自定义模板中将图表全部组合在一起。

如果需要此功能,则需要使用 AOP插件AOP PL/SQL API,就像在 APEX 20.1 之前一样,您可以从 www.apexofficeprint.com 网站下载该文件。

强烈建议您安装AOP Sample App,它展示了 AOP 在过去5年中获得的所有功能。在每个页面上,您都可以查看示例的构建方式以及使用的模板。

第1步:下载 AOP 安装包

访问 AOP 官网,点击Downloads链接,根据实际情况下载安装包。

下载并解压后,目录结构如下:

第2步:安装 AOP

安装 AOP PL/SQL API:

登录到您希望使用 AOP 的 APEX 工作空间(Workspace),待安装的组件如下:

  • AOP PL/SQL API
  • AOP 插件(3个)
  • AOP 示例应用

这里假设您已安装了 APEX 自带的示例应用 Sample Database packaged application,希望在这个应用里使用 AOP 的打印功能。

导航到 SQL Workshop -> SQL Scripts -> Upload,选择 aop_db_pkg.sql 进行上传(您可以在db目录下找到它).

aop_db_pkg.sql 文件会安装 AOP 所需的数据库表、PL/SQL包、同义词等。

别忘了点击运行按钮以便执行刚刚上传的sql文件。

确保选择了正确的数据库schema。

运行完毕后,效果如下图所示:

如果您在创建同义词时遇到了 ORA-01031 insufficient privileges 错误,联系DBA让他授予您的数据库schema相应权限(CREATE SYNONYM)。

安装 AOP 插件:

AOP 包含了3个插件,您可以选择只用 AOP 的 PL/SQL API 来与 AOP 进行交互,但因为您需要与 APEX 配合使用,所以您还会用到 动态行为插件过程处理插件内容转换插件,这些插件可以处理所有的 PL/SQL 调用,您只需告诉 AOP 到哪里找到合适的模板和数据即可。

  • AOP 动态行为插件:这个插件应该用得是最多的,也是最简单和最稳定的。
  • AOP 过程处理插件:这个插件仅用在特定的场景,比如:在页面加载前用模式窗口显示 PDF 内容,或者您需要在调用 AOP 打印功能之前提交并保存数据。
  • AOP 内容转换插件:这个插件被用来将任意类型的文件转换成 PDF 格式,而无需依赖模板,这也是它唯一的用处。

导航到 Shared Components -> Plug-ins,点击 Import 按钮.

选择 dynamic_action_plugin_be_apexrnd_aop_da.sql 文件(位于安装包的apex目录下),文件类型 选项选择 Plug-in字符集 选择 Unicode UTF-8,点击若干次 下一步 按钮完成插件导入。

一旦安装完毕,您将来到 Component Settings 页面,以便对当前插件做进一步设置。

重复上述步骤,完成另外两个插件(process_type_plugin_be_apexrnd_aop.sqldynamic_action_plugin_be_apexrnd_aop_convert_da.sql)的导入。

第3步:AOP 插件设置

首先配置 APEX Office Print (AOP) - DA [Plug-in] 插件。

这里唯一需要修改的就是 API Key。如果您采用本地化部署(On Premises),则无需设置 API Key。您可以登陆 AOP 官网 后,在 AOP Dashboard 中找到属于您的 API Key

对于另外两个插件,同样设置 API Key

好了,如果您采用 AOP Free Cloud 的方式使用 AOP,以上设置就足够了。

以下是更多有关插件的设置:

  • AOP URL: 这个 url 指向 AOP 服务器。如果您选择使用 AOP Cloud,保留默认值(http://api.apexofficeprint.com/)即可。如果您选择了本地化部署(On-Premises),请确保提供了正确的您的服务器地址。当使用 HTTPS 时,请确保您已经往数据库wallet中添加了必要的证书。有关这部分介绍,可以查看我们官网的相关文档。
  • AOP Failover URL (仅适用于本地化部署): 可选配置,可以指向您的备用 AOP 服务器,一旦主实例出现故障,备用服务器将提供服务。如果您选择的是 AOP Cloud 的方式,无需设置此项。

  • AOP Mode (仅适用于AOP Cloud): AOP 可以运行在生产模式(Production Mode),生产模式下,打印报表时会相应地扣减您账户中的信用点;您也可以使用开发模式(Development Mode),开发模式下不会扣减任何信用点,唯一的差别是打印的报告中会带有水印。您可以利用一个名为AOP_MODE的内置 item 动态设置 AOP 的运行模式。

  • Debug: 启用这一选项将强制 AOP 捕获发送到 AOP 服务器端的 JSON 内容,这一选项对您分析问题时将会特别有用。

    • 当该选项被设置为 Local 时:您的报表将下载为 JSON 格式,这将让您有机会分析具体问题所在。你也可以将问题描述及 JSON 文件发送给 support@apexofficeprint.com 以便获得进一步的支持。
    • 当该选项被设置为 Remote 时:将适用于 AOP Cloud 方式。您可以从 AOP Dashboard 中找到对应的 JSON 文件,进而进行进一步分析。
    • 您可以使用一个名为 AOP_DEBUG 的内置 item 来动态设置 Debug 模式。
  • Converter: 为了能够将文档转换成 PDF 格式,AOP 需要使用外部转换器(Converter),AOP 使用 LibreOffice 作为默认转换器。如果您选择本地化部署,可以添加其他第三方转换器,比如:AbiWord, Aspose, 或者其他转换器。

  • Use settings defined in package: 您可以编写 PL/SQL 包来设置 AOP 插件,这也让您可以很方便地在多个环境(开发、测试、生产)中安装部署 AOP 插件。
  • Log Package: AOP 内置支持日志功能。为了启用日志,您需要执行 ALTER PACKAGE aop_api19_pkg COMPILE PLSQL_CCFLAGS = 'logger_on:TRUE';。一旦编译成功,您可以通过指定全局变量 g_logger_enabled 来启用/关闭 debug 信息。您可以指定您自己的 debug 存储过程,所有的日志请求将被发送给 aop_api_pkg.plsql_call_to_aop

AOP做的第一件事就是调用 start_request,最后一件事是调用 stop_request. 您可以在AOP Sample APP中找到更多关于 aop_log_pkg 的例子。

第4步:AOP 使用

这里以APEX自带的Sample Database Application为例,假设我们已经完成了上述设置。打开page 4,这个页面包含一个互动报表(Interactive Report)。

切换到页面编辑模式

Order Region 下创建一个叫 PRINT 的按钮。

按钮属性配置如下:

  • Button Name: PRINT
  • Label: Print
  • Button Position: Right of Interactive Report Search Bar
  • Button Template: Icon
  • Icon: fa-print
  • Action: Defined by Dynamic Action

在按钮上添加动态行为。

选择 APEX Office Print (AOP) - DA [Plug-in] 插件作为展示选项。

Template Type 选项选择 AOP Template,这样 AOP 将生成一个通用模板,以便后续您可以进一步编辑。

Data Type 选项设置为 Region(s): Classic Report, Interactive Report/Grid, SVG, Canvas, HTML, Other,并且将 Region Static Id(s) 设置成 orders_ir(这个 static id 将被AOP用来获取该region的元数据,以便生成需要在屏幕上显示的数据)。

注:这里的这个 region static id 可以在您的 Interactive ReportAdvanced 属性中找到。

对于 Affected Elements 属性报错,可以简单地通过以下设置解决。

保存页面并运行它,您将看到刚刚添加的打印按钮。

点击打印按钮,将打开一个Word默认模板,您可以基于该模板进行自定义设置。

AOP 要求您使用特定的标签创建模板,这个默认模板提供了一些常见的示例,同时还从您的互动报表区域提取了一些数据,以便您可以方便地对模板进行定制。

您可以通过特殊的标签来开始/结束一个(数据)循环。

您可以像使用 Word 一样在模板中创建诸如表格、文件头/尾、图片以及格式,您在模板上做的任何设置都将显示在您最终的报表输出中。

以下是我对模板做的一些修改,并将模板保存为 AOP_Template.docx

将修改后的模板上传到静态资源管理中(Shared Components -> Static Application Files)。

点击上传按钮完成模板上传。

返回页面编辑器,配置刚才新增的动态行为。

  • Template Type: Static Application Files
  • Template Source: AOP_Template.docx

再次运行页面并点击打印按钮,您将看到修改后的结果。

祝贺!!您完成了您的第一个 AOP 报表!

但如果您只是希望原模原样地打印一个互动表格的话,其实有更简单的做法,您只需要在您的模板中使用 {&interactive} 即可。

让我们进一步修改这个标签,来展示 AOP 的魔法吧。

继续编辑您的 Word 模板,插入一个空白页,以及一个 {&interactive} 标签,保存文件名为 AOP_Template.docx

上传模板文件并查看页面打印结果。

让我们在页面上设置一下互动报表。

再次打印报表并查看结果。

修改报表输出格式:

  • Output Type:PDF

您可以安装 AOP Sample Application 以便查看更多的 AOP 例子。

钢哥的 Oracle APEX 系列文章:

本文标题:Oracle APEX 系列文章16:AOP - PDF报表打印新选择

文章作者:王方钢 / Kenny Wang

发布时间:2020年05月04日 - 21:05

最后更新:2021年01月30日 - 14:01

原始链接:https://wangfanggang.com/Oracle/Oracle-APEX/apex-series-16/

许可协议: 署名-非商业性使用-禁止演绎 4.0 国际 转载请保留原文链接及作者。

王方钢 / Kenny Wang wechat
0%