Liferay6.2：使用Ext插件进行高级自定义

Advanced Customization with Ext Plugins - 使用Ext插件进行高级自定义

Ext plugin是扩展Liferay的强大工具。 因为它们增加了Liferay实例的复杂性，所以如果已经确定无法使用其他方法实现目的，则只能使用Ext plugin。 查看 Application Display Templates 以自定义支持应用程序的display(显示)，，或者查看Customizing Liferay Portal with Hooks 使用hook plugin时作为备用方案。 如果ADT或hook不够用，则可以学习使用Ext plugin的用例以及对如何对它进行设置。 首先要考虑的是为什么要尽可能避免使用Ext插件。

在决定使用Ext plugin之前，需要权衡成本。 Ext plugin允许你使用内部API，甚至允许覆盖Liferay核心文件。 当升级到Liferay的新版本(即使是维护版本或service pack)时，你必须检查所有改动之处并手动修改Ext plugin以将改动的地方与Liferay合并。 此外，Ext plugin不可热部署。 要部署Ext plugin，必须重新启动服务器。 最后，使用Ext plugin，部署或重新部署到生产系统需要执行其他一些步骤。

既然已经了解了Ext plugin的局限性，现在看看为什么要使用它们：

• 将自定义类指定为portal属性值。 例如，如果要把某些属性的值指定为自定义类(例如，global.startup.events = my.custom.MyStartupAction)，你需要用Ext plugin将自定义类添加到portal类加载器。
• 为Spring文件中声明的任意Liferay bean提供自定义实现(如果可以，优先考虑使用hook的 service wrappers，其次考虑Ext plugin 的)。
• 添加portal属性引用的JSP，如果该JSP只能从Ext plugin更改(先看看该属性是否可以先从 hook plugin修改）。
• 覆盖一个类(除非别无选择，否则不推荐)。

考虑到这些用例，你将学习如何使用Ext来实现这些目的：

• 创建一个Ext plugin
• 开发Ext plugin
• 在生产中部署
• 迁移旧扩展环境

现在先创建一个Ext plugin。

Creating an Ext Plugin

你可以在Liferay IDE或终端环境中创建Ext plugin。 Ext plugin存储在 Plugins SDK’s 的ext目录中。

也可以在Liferay Maven项目中创建Ext plugin。

本教程介绍如何使用Ant在Plugins SDK项目中创建Ext plugin。 这可以从Liferay IDE和终端中显示出来。 要了解如何创建Liferay Maven项目，请参阅教程Creating Liferay Maven plugins from IDE或 Creating Liferay Maven Plugins from the Command Line教程。

Using Liferay IDE to Create an Ext Plugin - 使用IDE创建EXT plugin

按照以下步骤，创建Ext plugin：

1. 转到 File → New → Liferay Plugin Project。
2. 输入项目的名称及其display名称。在下图中，示例用于两者。请注意，display名称字段将自动填入项目名称的大写版本。
3. 选中 Use default location 复选框。由于你使用的是Ant，因此默认位置设置为Liferay plugin SDK的位置。如果你想更改plugin项目的保存位置，请取消选中该框并指定备用位置。
4. 选择构建类型的Ant(liferay-plugins-sdk)选项。
5. 你应该已经选择过了configured SDK和Liferay runtime。如果尚未将Liferay IDE指向Plugins SDK，请单击Configure SDKs以打开Installed Plugin SDKs management wizard(已安装的Plugin SDK管理向导)。如果需要设置运行时服务器，还可以访问New Server Runtime Environment wizard(新服务器运行时向导)；只需单击Liferay Portal Runtime selection box旁边的New Liferay Runtime按钮。
6. 为插件类型选择Ext。
7. 单击Finish。

Plugins SDK在创建Ext plugin的项目文件夹时会自动将-ext附加到插件项目名称。 在Liferay IDE中，你已经创建了一个全新的plugin，当然，也可以向现有plugin项目添加新plugin。

Anatomy of an Ext Plugin - 剖析Ext Plugin

关于Ext plugin的目录结构，有几点需要注意。 下面是Ext文件夹结构的列表。 此列表后面的屏幕截图显示了Liferay IDE中Ext plugin的结构：

• [project name]-ext/
  • docroot/
    • WEB-INF/
      • ext-impl/
        • src/
      • ext-lib/
        • global/
        • portal/
      • ext-service/
        • src/
      • ext-util-bridges/
        • src/
      • ext-util-java/
        • src/
      • ext-util-taglib/
        • src/
      • ext-web/
        • docroot/

以下是/docroot/WEB-INF/ 子目录的详细说明：

ext-impl/src：包含portal-ext.properties配置文件，自定义实现类以及用于覆盖portal-impl.jar中核心类的类。

ext-lib/global：包含libraries，该libraiie 在部署Ext plugin时会被复制到应用程序服务器的全局classloader中。

ext-lib/portal：包含在Liferay主应用程序中被复制的libraries。这些libraries通常是必需的，因为它们会被你在ext-impl/src 中添加的类所调用。

ext-service/src：包含可供其他plugin使用的类。在高级方案中，此文件夹可用于保存覆盖portal-service.jar 中类的类。 Service Builder将service的接口放在此处。

ext-web/docroot：包含Web应用程序的配置文件，包括WEB-INF/struts-config-ext.xml，该文件允许你自定义Liferay的核心struts类。注意，建议使用 hooks 来自定义struts action。你自定义的任何JSP也都属于此处。

ext-util-bridges，ext-util-java和ext-util-taglib：只有在需要自定义Liferay libraries中的类时才需要这些文件夹：util-bridges.jar，util-java.jar和util- taglib.jar。如果没有自定义任何这些libraries，则可以忽略这些文件夹。

默认情况下，还会向插件添加多个文件。以下是最重要的文件：

build.xml·：Ext plugin项目的Ant构建文件。

docroot/WEB-INF/liferay-plugin-package.properties: 包含plugin的特定属性，包括plugin的display name，version，author和license type。

docroot/WEB-INF/ext-impl/src/portal-ext.properties：用于覆盖Liferay的配置属性。 当然还是推荐优先尽可能的使用hook plugin覆盖属性。 在将自定义类指定为portal property 时，需要使用Ext插件来覆盖属性。你可以将portal-ext.properties文件与每个Ext plugin一起使用，但不要覆盖多个portal-ext.properties文件中的相同属性，因为无法确保加载顺序，可能会导致意外的系统行为结果。

docroot/WEB-INF/ext-web/docroot/WEB-INF文件：

• portlet-ext.xml：用于覆盖Liferay portlet的定义。 为此，请先在Liferay的源代码中从portlet-custom.xml 复制所需portlet的完整定义，然后应用必要的更改。
• liferay-portlet-ext.xml：此文件类似于portlet-ext.xml，但是用于覆盖Liferay特有的其他定义元素。 要覆盖这些定义元素，请在Liferay的源代码中从liferay-portlet.xml复制所需portlet的完整定义，然后应用必要的更改。
• struts-config-ext.xml和tiles-defs-ext.xml：这些文件用于自定义Liferay核心portlet使用的struts action。

Tip：创建Ext plugin后，从docroot/WEB-INF/ext-web/docroot/WEB-INF中删除不需要自定义的文件。 Liferay会跟踪每个Ext plugin部署的文件，并且不允许部署覆盖同一文件的多个Ext plugin。 如果删除未自定义的文件，则可以避免与已经部署的Ext plugin发生冲突。

现在已经创建了一个Ext plugin，并且熟悉其目录结构及其最重要的文件。 现在开始使用Ext plugin来自定义Liferay Portal。

Developing an Ext Plugin - 开发Ext Plugin

在部署plugin时Ext plugin会改变Liferay本身；它不是一个可以随时轻松删除的独立component。因此，Ext plugin开发过程与其他plugin类型不同。重要的是要记住，一旦部署了Ext plugin，其部分文件会将被复制到Liferay installation中；删除更改的唯一方法是重新部署一个未修改的Liferay application。

Plugins SDK允许你在开发阶段部署和重新部署Ext plugin。重新部署涉及清理(即删除)你的应用程序服务器并解压指定的Liferay包以从头开始。这样，在开发过程中对Ext plugin所做的任何更改都会得到正确应用，并且之前更改中从plugin中删除的文件不会留在Liferay应用程序中。由于这种增加的复杂性，你应该使用另一种插件类型来尽可能地实现目的。

在深入了解详细信息之前，以下是Ext plugin开发过程的概述：

• 如何configure Plugins SDK环境以在应用程序服务器上为Liferay Portal开发Ext plugin。
• 如何首次deploy和publish Ext plugin。
• 如何在更改Ext plugin后正常redeploy或使用 clean redeployment过程。
• 如何打包(package)Ext plugin以进行分发。
• 需要高级自定义技术的Liferay Portal自定义项示例。

现在开始学习开发过程的每一步。

Set Up the Build Environment - 设置构建环境

在部署Ext plugin之前，必须编辑Plugins SDK 根文件夹中的build.[username].properties文件。 如果该文件尚不存在，请立即创建。 用计算机上的用户ID替换[username]。打开build属性文件后，添加以下属性 - 确保各个路径对应你系统上的正确位置：

ext.work.dir=[work]

app.server.dir=[work]/liferay-portal-[version]/[app server]

app.server.zip.name=[...]/liferay-portal-[app server].zip

你的app.server.zip.name属性必须指定Liferay bundle .zip文件的路径。你为ext.work.dir属性指定的work目录是你解压的Liferay bundle运行时的位置。app.server.dir属性必须指向工作目录中的应用程序服务器目录。 在应用程序服务器的路径中查看Liferay bundle，以确定用于app.server.dir属性的值。

例如，如果你的工作目录是C/work，请将其指定为ext.work.dir属性的值。 如果你的Liferay bundle .zip文件是C：/downloads/liferay-portal-tomcat-6.2.0-ce-ga1- [timestamp].zip，请将app.server.zip.name属性设置为该文件的路径。 如果Liferay bundle.zip文件中应用程序服务器的相对路径为liferay-portal-6.2-ce-ga3\tomcat-7.0.42，请指定app.server.dir属性值C：/work/liferay-portal-6.2-CE-GA3/Tomcat-7.0.42。

Note：一些Liferay bundle随附示例网站。 它对于展示Liferay的某些功能很有用，但是如果你删除它，你可能不希望每次解压bundle时重新安装它。 要防止重新安装示例网站，请解压bundle，删除[work]/liferay-portal-[version]/[app server]/webapps/welcome-theme 文件夹，然后重新压缩bundle。

现在可以修改Ext plugin 并且部署了。

Initial Deployment - 初步部署

环境设置好之后就可以开始自定义了。 在本练习中，你将自定义user profile的各个部分。 此示例可以使用hook和users.form.add.main 属性完成，但出于演示目的，你将学习如何通过Ext plugin覆盖portal属性来自定义user profile。 要自定义users.form.add.main portal属性，请打开docroot/WEB-INF/ext-impl/src/portal-ext.properties 文件并输入新设置，如下所示：

users.form.update.main=details,password,organizations,sites,roles

在上面的自定义中，users.form.add.main属性不再为user group，persional site 和categorizations(分类)指定user profile页面部分。 只有在自定义users.form.add.main portal属性的值列表中指定的部分才会显示在portal的user profile页面中。

在Ext plugin中进行自定义后，现在可以部署插件。

Deploy the Plugin - 部署插件

你可以从Liferay IDE或终端部署插件。

• 在Liferay IDE中部署：将Ext plugin项目从Package Explorer拖到服务器上以部署插件。 Liferay IDE会自动重启服务器，以便服务器检测并发布您的Ext plugin。

服务器重新启动后，请尝试使用Liferay Portal查看Ext plugin引入的自定义项。

Tip：如果你使用Liferay IDE部署了Ext插件，但是在portal中没有看到自定义项，则可能未成功部署Ext plugin。要确认Ext plugin是否已成功部署，请尝试从终端部署; 查看Ant部署目标报告是成功还是失败。

例如，如果你自定义了users.form.update.main属性，请以管理员身份登录并转到Control Panel → Users and Organizations。 编辑现有用户并验证右侧导航菜单是否仅显示了你在users.form.update.main属性上指定的部分。

图2：如果您自定义了users.form.update.main属性，Liferay Portal的用户信息仅显示您指定的部分。

这是一个Ext plugin的简单应用程序。你可以继续进行更复杂的自定义，以说明重新部署Ext plugin的正确方法，这便与初始部署(initial deployment)不同。

现在我们自定义user profile中的的“Details”部分。在这里我们不覆盖其JSP，而是使用更强大的方法添加新部分甚至合并现有部分。你可以从portal-ext.properties中引用自定义部分，并通过创建JSP来实现它们。 你将再次修改属性users.form.update.main和属性users.form.add.main以设置以下属性：

users.form.add.main=basic,organizations,personal-site
users.form.update.main=basic,password,organizations,sites,roles

您删除了原始”Details“ section并添加一个名为basic的自定义部分。 当Liferay读取属性时，它会根据以下约定查找每个部分的实现：

• 该部分在以下目录中的JSP中实现：
  ext-web/docroot/html/portlet/users_admin/user/
• JSP的名称与扩展名为.jsp的section的名称相同。 如果section名称有短划线(-)，请用下划线(_)替换它。 例如，如果section名为my-info，则应将JSP命名为my_info.jsp以符合JSP命名标准。
• 显示给用户的部分名称来自language bundle。 使用Liferay未包含的key/value时，将其添加到Ext plugin的Language-ext.properties文件，和特定于语言的属性文件(language-specific properties)中，该文件中是你要提供翻译的语言变体。 这些文件位于Ext plugin的ext-impl/src目录中。

在此例中，你需要在Ext plugin中的如下路径创建一个文件：

ext-web/docroot/html/portlet/users_admin/user/basic.jsp

你可以从头开始编写文件的内容，或者只从Liferay的source code 中复制details.jsp文件并从那里进行修改。你可以删除一些字段(例如，birthday或gender)，保留 screen name，email address，first name等等字段，以简化用户创建和用户更新。 确保完全删除与该字段相关的tag。

你不需要向Language-ext.properties添加新key，因为名为basic的key已经包含在Liferay language bundle。

让我们重新部署Ext plugin来查看更改。

Redeployment - 重新部署

到目前为止，Ext plugin开发类似于其他plugin类型的开发。现在到了有区别之处了。首次部署插件时，其部分文件将复制到Liferay installation中。更改Ext plugin后，你需要redeploy 或clean redeploy，具体取决于你在初始部署后对plugin所做的修改。我们来谈谈每个重新部署方法以及何时使用每个方法。

Clean Redeployment：如果你删除了plugin的一部分，如果你的plugin的更改可能影响plugin部署，或者你想要从干净的Liferay环境开始，请在重新部署Ext plugin之前undeploy plugin并clean应用程序服务器(application server)。通过clean 应用程序服务器，将删除现有的Liferay installation，Plugin SDK环境中指定的bundle将在其位置解压(根据 build.[username] .properties中的app.server.zip.name的值解压新的bundle)。根据您是在Liferay IDE还是终端中进行开发，采取的具体步骤会有所不同：

Using Liferay IDE:

1. 从服务器中删除plugin。在Servers视图中选择Ext plugin，选择plugin的Remove选项。
2. Clean应用程序服务器。 请记住在clean应用程序服务器之前先关闭它。 这在Windows上是必需的，因为服务器进程会锁定已安装的Liferay bundle文件。
   在Package Explorer视图中选择Ext plugin项目时，选择plugin的Liferay→Clean App Server …option。

图3: 如何清理应用程序服务器

1. Start the Liferay server.
2. 拖动Ext plugin并将其放到Liferay server上。
3. 在Servers视图中选择Liferay服务器时，单击Publish选项。

Distribution - 分发

完成Ext plugin的开发后，可以将其打包成 .war文件以进行分发和生产部署。

使用Liferay IDE ：在Package Explorer视图中选择Ext plugin项目，选择项目的Liferay → SDK → war option。

Advanced Customization Techniques - 高级自定义技术

使用Ext plugin，你可以在Liferay中更改任何内容。 现在是时候看看Ext plugin可能实现的一些额外的自定义技术了。像之前说的，使用Ext plugin时要慎重。

对于每个新版本的Liferay，都可以对实现类进行更改。 如果直接更改Liferay的源代码，则必须将更改合并到较新的Liferay版本中。 为了尽量减少这种冲突，最好的方法是不要改变任何东西。 相反，你可以扩展需要更改的类并覆盖所需的方法。 然后使用必需的Liferay配置文件来引用你的子类作为原始类的替代。

下面，你将了解以下主题：

• 使用高级配置文件
• 更改核心service的API
• 替换portal-impl中的核心类

首先，你将学习使用高级配置文件。

Using Advanced Configuration Files - 使用高级配置文件

Configuring Lucene Analyzers - 配置Lucene分词器

Liferay使用Lucene来促进Portal内的搜索和索引。 在旧版Liferay中，你可以从portal-ext.properties文件配置Lucene Analyzer。 虽然方便，但是对于所有portal-index field只有一个分词器不太合适。比如，很难为通过keyword查询和通过 text fields查询提供正确的行为(behaviors)。

从Liferay 6.1开始，你不再从portal-ext.properties文件配置Lucene。取而代之的是，Lucene 分词器是在Spring配置文件中定义的。 默认的analyzer配置定义在/portal-impl/src/META-INF/search-spring.xml。 Liferay 6.1引入了per-field analyzers，允许Lucene的查询解析器(query parser)识别正确的分词器来处理对应的字段。

在这两种常见的场景下，配置Lucene分词器非常有用，分别是：创建自定义语言Analyzer以覆盖Liferay语言Analyzer的时候，创建自定义indexer来索引新字段的时候。 Liferay在search-spring.xml中提供了大量语言analyzer，并使用正则表达式匹配将本地化字段映射到特定分词器。 如果你的语言不包含在默认语言中，或者你对其中一个默认语言分析器不满意，则可以使用自定义analyzer覆盖它。 如果你已经创建了自定义索引器以索引新字段，则可以使用默认分词器应用到新字段，选择特定的分词器(例如KeywordAnalyzers之一)，或使用自定义自定义分词器。

要自定义Lucene分词器配置，必须创建一个Ext plugin。Analyzer类直接引用Lucene API，因此无法从hook plugin配置Lucene分词器。 在Ext plugin中，创建一个文件/docroot/WEB-INF/ext-impl/src/META-INF/ext-spring.xml 并使用自定义配置声明要覆盖的bean。

以下是在search-spring.xml中配置的 com.liferay.portal.search.lucene.PerFieldAnalyzerWrapper bean的一些预置analyzer：

<entry key="tag"
       value-ref="com.liferay.portal.search.lucene.LikeKeywordAnalyzer" /> 
<entry key="templateId" 
       value-ref="org.apache.lucene.analysis.KeywordAnalyzer" />
<entry key="treePath"
       value-ref="com.liferay.portal.search.lucene.LikeKeywordAnalyzer" /> 
<entry key="type" 
       value-ref="org.apache.lucene.analysis.KeywordAnalyzer" /> 
<entry key="userName"
       value-ref="com.liferay.portal.search.lucene.LikeKeywordAnalyzer" /> 
<entry key=".*_ar" 
       value-ref="org.apache.lucene.analysis.ar.ArabicAnalyzer" />
<entry key=".*_de_DE"
       value-ref="org.apache.lucene.analysis.de.GermanAnalyzer" /> 
<entry key=".*_el_GR" 
       value-ref="org.apache.lucene.analysis.el.GreekAnalyzer" />
<entry key=".*_fa_IR"
       value-ref="org.apache.lucene.analysis.fa.PersianAnalyzer" /> 
<entry key=".*_fr_[A-Z]{2}"
       value-ref="org.apache.lucene.analysis.fr.FrenchAnalyzer" />

你可以为任何字段定义自定义分词器，包括自定义字段。

Tip：利用ext自定义分词器之后，如果想要部署到Weblogic环境(测试或生产)下，将开发环境中ROOT/WEB-INF/lib下的*ext.jar以及需要引用的jar全部复制到Weblogic环境下的相同目录，重启后生效。

Tip：如果你确定要利用Lucene与Liferay集成构建全文检索系统，则可以利用EXT修改Lucene的Analyzer。如果选择在集群环境下集成Solr检索服务系统，就不需要这样更改分析器了，Solr有自己的修改分析器方法，而且更加方便。

接下来你可以了解如何更改核心服务的API。

Deploying in Production - 在生产环境中部署

通常，你无法使用Ant在生产环境或测试环境中部署Web application。 此外，某些应用程序服务器(如WebSphere或WebLogic)拥有自己的部署工具，不能与Liferay的自动部署过程一起使用。 在生产中部署和重新部署Ext plugin有两种方法可供考虑。

Method 1: Redeploying Liferay’s Web Application - 方法1：在Liferay的Web Application中重写部署

你可以在任何支持 auto-deployment的应用程序服务器中使用这种方法；它有这样的好处：需要传输到生产系统的唯一artifact是Ext plugin的.war文件，.war可以使用ant war target生成。这个.war文件通常很小，易于传输。在服务器上执行以下步骤：

1. 重新部署Liferay：
   如果是第一次将Ext plugin部署到此服务器，请跳过此步骤。否则，首先执行在应用服务器上首次用于部署Liferay的相同步骤。如果你正在使用bundle，请再次解压缩。如果在现有应用程序服务器上手动安装Liferay，则必须重新部署Liferay .war文件，并将Liferay和Ext plugin 全局所需的libraries复制到应用程序服务器中的相应目录中。
2. 将Ext plugin .war复制到auto-deploy目录中。对于bundle的Liferay发行版本，deploy文件夹位于Liferay的bundel的root文件夹中（例如，liferay-portal- [version]/）。
3. Liferay检测并部署Ext plugin后，重新启动Liferay服务器。

Method 2: Generate an Aggregated WAR File - 方法2：生成聚合WAR文件

某些应用程序服务器不支持自动部署；WebSphere和WebLogic就是两个例子。使用聚合(Aggregated)的.war文件，所有Ext plugin会在部署到生产之前被合并起来。 单个.war文件包含Liferay以及所有由Ext plugin产生的更改。 在部署聚合的Liferay .war文件之前，将Liferay和所有Ext plugin所需的依赖项.jar文件复制到生产服务器中的全局应用程序服务器类class loader中。具体位置因服务器而异; 请参阅Deployment以获取应用程序服务器的详细信息。

要生成聚合的.war文件，请首先将Ext plugin部署到你在开发环境中使用的Liferay bundle。 部署完成后，重新启动服务器，以使plugin被完全部署然后再关闭它。 现在聚合文件已准备好了。

从应用服务器中压缩Liferay Web application文件夹来生成.war文件。将Ext plugin所依赖的所有libraries复制到应用程序服务器的全局classpath中。

现在，在你的服务器上执行以下操作：

1. 使用聚合的.war文件重新部署Liferay。
2. 停止服务器并将新版本的全局libraries复制到应用程序服务器中的相应目录。

接下来，我们将向您展示如何将扩展环境(从旧版Liferay)迁移到Ext plugin。