2.1.2. Creating a portal extension

Warning

You are looking at documentation for an older release. Not what you want? See the current release documentation.

In this tutorial, you create a portal extension. The project consists of two modules: a library (jar) and a webapp (war). The sample code can be found at eXo Samples repository.

Note

This tutorial describes a traditional portal extension with a jar. As of 4.3, you do not need a jar to configure a portal extension. See details in New extension mechanism as of Platform 4.3.

  1. Create a Maven project with two modules as below:

  2. Edit pom.xml: 

    
<?xml version="1.0" encoding="UTF-8"?>
    
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>org.exoplatform.samples</groupId>
    
    <artifactId>custom-extension</artifactId>
    
    <version>4.3.x</version>
    
    <packaging>pom</packaging>
    
    <name>custom-extension-pom</name>
    
    <description>The sample custom-extension</description>
    

    
    <modules>
    
        <module>lib</module>
    
        <module>webapp</module>
    
    </modules>
    

    
    <properties>
    
        <project.version>4.3.x</project.version>
    
        <exoplatform.version>4.3.0</exoplatform.version>
    
    </properties>
    

    
    <dependencyManagement>
    
        <dependencies>
    
            <dependency>
    
                <groupId>org.exoplatform.platform</groupId>
    
                <artifactId>platform</artifactId>
    
                <version>${exoplatform.version}</version>
    
                <type>pom</type>
    
                <scope>import</scope>
    
            </dependency>
    
        </dependencies>
    
    </dependencyManagement>
    
</project>

  3. Edit webapp/pom.xml: 

    
<?xml version="1.0" encoding="UTF-8"?>
    
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    
    <modelVersion>4.0.0</modelVersion>
    
    <parent>
    
        <groupId>org.exoplatform.samples</groupId>
    
        <artifactId>custom-extension</artifactId>
    
        <version>4.2.x</version>
    
  </parent>
    
  <artifactId>custom-extension-webapp</artifactId>
    
  <packaging>war</packaging>
    
  
    
    <dependencies>
    
    </dependencies>
    
    <build>
    
        <finalName>custom-extension</finalName>
    
    </build>
    
</project>

    Note that in this file you define the file name of the webapp. It will be custom-extension.war. You can change it here but you will have to change other configuration accordingly.

  4. Edit WEB-INF/web.xml: 

    
<?xml version="1.0" encoding="UTF-8"?>
    
<web-app>
    
    <display-name>custom-extension</display-name>
    
    <listener>
    
        <listener-class>org.exoplatform.container.web.PortalContainerConfigOwner</listener-class>
    
    </listener>
    
</web-app>

  5. Edit WEB-INF/conf/configuration.xml: 

    
<?xml version="1.0" encoding="UTF-8"?>
    
<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    
    xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd http://www.exoplatform.org/xml/ns/kernel_1_2.xsd"
    
    xmlns="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd">
    
</configuration>

    This file is supposed to be a service configuration file, but you do not configure anything so far. In the examples that follow and in some later tutorials of the Developer guide, you will write more configuration when necessary.

  6. Edit lib/pom.xml: 

    
<?xml version="1.0" encoding="UTF-8"?>
    
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    
  <modelVersion>4.0.0</modelVersion>
    
  <parent>
    
        <groupId>org.exoplatform.samples</groupId>
    
        <artifactId>custom-extension</artifactId>
    
        <version>4.2.x</version>
    
  </parent>
    
  <artifactId>custom-extension-config</artifactId>
    
  <packaging>jar</packaging>
    
  
    
    <dependencies>
    
    </dependencies>
    
</project>

  7. Edit lib/src/main/resources/conf/configuration.xml: 

    
<?xml version="1.0" encoding="UTF-8"?>
    
<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    
    xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd http://www.exoplatform.org/xml/ns/kernel_1_2.xsd"
    
    xmlns="http://www.exoplatform.org/xml/ns/kernel_1_2.xsd">
    
    <external-component-plugins>
    
        <target-component>org.exoplatform.container.definition.PortalContainerConfig</target-component>
    
        <component-plugin>
    
            <name>Add PortalContainer Definitions</name>
    
            <set-method>registerChangePlugin</set-method>
    
            <type>org.exoplatform.container.definition.PortalContainerDefinitionChangePlugin</type>
    
            <priority>101</priority>
    
            <init-params>
    
                <values-param>
    
                    <name>apply.specific</name>
    
                    <value>portal</value>
    
                </values-param>
    
                <object-param>
    
                    <name>addDependencies</name>
    
                    <object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies">
    
                        <field name="dependencies">
    
                            <collection type="java.util.ArrayList">
    
                                <value><string>custom-extension</string></value>
    
                            </collection>
    
                        </field>
    
                    </object>
    
                </object-param>
    
            </init-params>
    
        </component-plugin>
    
    </external-component-plugins>
    
</configuration>

    • priority: set to "101" that is higher than the built-in extension platform-extension.war if you want your custom-extension to override configuration in that built-in one.

    • dependencies: a collection of portal extensions. Here it is only custom-extension.

    • custom-extension: this name, the file name of the .war and the display-name you configure in web.xml should match each other.

  8. Build the project with mvn clean install command. You will have a jar in lib/target/ folder and a war in webapp/target/ folder.

Deployment

To deploy this simple portal extension in case you do not use Add-ons Manager:

For Tomcat:

  1. Copy custom-extension.war to the $PLATFORM_TOMCAT_HOME/webapps/ directory.

  2. Copy custom-extension-config.jar to the $PLATFORM_TOMCAT_HOME/lib/ directory.

  3. Restart the server.

For JBoss:

  1. Add new WEB-INF/jboss-deployment-structure.xml file to custom-extension.war with the following content: 

    
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
    
    <deployment>
    
        <dependencies>
    
            <module name="deployment.platform.ear" export="true"/>
    
        </dependencies>
    
    </deployment>
    
</jboss-deployment-structure>

  2. Add custom-extension.war to $PLATFORM_JBOSS_HOME/standalone/deployments/ platform.ear directory.

  3. Add custom-extension-config.jar to $PLATFORM_JBOSS_HOME/standalone/deployments/platform.ear!/lib directory.

  4. Restart the server.

Add-ons Manager compliance

In case you want to make your portal extension a standard add-on so that users can install it using eXo Add-ons Manager, the packaging will be different. The section Packaging shows you how.

The Add-ons Manager deploys the extension in the same way for Tomcat. For JBoss, it uses another method to deploy the .war. Here are the details:

Copyright ©. All rights reserved. eXo Platform SAS
blog comments powered byDisqus