# Liferay full portlet

Please make sure to check the [Form Runner Liferay Proxy Portlet Guide](https://doc.orbeon.com/~/revisions/-LF_uc1WMpa4Sd-n5tDb/form-runner/linking-and-embedding/liferay-proxy-portlet) as well, as that is the recommended way to deploy Orbeon Forms into Liferay, and [Form Runner Embedding](https://github.com/orbeon/orbeon-forms-doc/tree/c432b92f4f85b0983a3ce0b85bb2bdd4e53d043e/form-runner/link-embed/images/embedding-bookshelf.png) for a comparison of portlet deployments.

## Availability

This is an Orbeon Forms PE feature.

## Supported Liferay versions

See [Supported Liferay versions](https://doc.orbeon.com/~/revisions/-LF_uc1WMpa4Sd-n5tDb/form-runner/linking-and-embedding/..#supported-liferay-versions).

## Deploying into Liferay

### Configuration

The Orbeon Forms WAR can be directly deployed into the Liferay portal. By default, the Form Runner demo forms and XForms examples are immediately available within the portlet:

![Orbeon Forms welcome page in Liferay](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEkBiSDvlXs3VWiO0Zu%2F-LEkBmMpnaxnftLGDglW%2F-LEkBz31966NDzS0eKU7%2Fliferay-full-home.png?generation=1528743339462964\&alt=media)

The following steps assume that:

* Liferay is deployed on port 8080
* the Orbeon Forms WAR is deployed under the name "orbeon" (which is the default if the WAR file is called orbeon.war)

Installation steps:

1. **Deploy orbeon.war:** Start Liferay. When it is fully started move the `orbeon.war` into the Liferay deploy directory (e.g. `~/liferay/deploy`). At this point, you should see message indicating that Orbeon is being deployed. Monitor the Liferay output as well as the `logs/orbeon.log` for possible errors.
2. **Enable dynamic resource reloading (optional):** Remove the file `webapps/orbeon/META-INF/context.xml` and restart Liferay. For more information on what this does, see note 2 below.
3. **Configuration for Form Runner (optional):** You can skip this step if you do not intend to use Form Runner or Form Builder in a portlet. Otherwise, create a file `WEB-INF/resources/config/properties-local.xml` which declares the following properties (and other properties you might want to override):

   ```markup
    <properties xmlns:xs="http://www.w3.org/2001/XMLSchema"
                xmlns:oxf="http://www.orbeon.com/oxf/processors">

        <!-- Configure authentication properties through headers -->
        <property
            as="xs:string"
            name="oxf.fr.authentication.method"
            value="header"/>

        <!-- If you want the Liferay user email used for Form Runner authentication -->
        <property
            as="xs:string"
            name="oxf.fr.authentication.header.username"
            value="Orbeon-Liferay-User-Email"/>

        <!-- If you want Liferay roles used -->
        <property
            as="xs:string"
            name="oxf.fr.authentication.header.roles"
            value="Orbeon-Liferay-User-Roles"/>

    </properties>
   ```

   The host name (`localhost`), port (`8080`), and context path (`orbeon`) must be updated to match your local configuration.
4. **Add the Orbeon Forms portlet:** Log into the portal, go to the Add menu and create a new page, for example *Orbeon Page*. Then go to the Applications tab and click or drag "Orbeon Forms Portlet" to the page. The Orbeon Forms home page will show.

![](https://4129616727-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LEkBiSDvlXs3VWiO0Zu%2F-LEkBmMpnaxnftLGDglW%2F-LEkBz39f2zfp6IBHjap%2Fliferay-applications.png?generation=1528743353482672\&alt=media)

NOTE:

When Liferay deploys Orbeon Forms, it changes some of the descriptors and adds a `META-INF/context.xml` which is not present in the distribution of Orbeon Forms. This file contains:

```markup
<context antijarlocking="true" antiresourcelocking="true">
```

which causes Tomcat to, on startup, make a copy of the Orbeon web application into its temp directory and use that copy instead of the files under `webapps/orbeon`. That copy is removed when the server shuts down, and will be done again the next time the server is started. This makes starting Liferay slower, but more importantly this means that changes you make to files under `webapps/orbeon` after the server started will never be picked up. So any modification to the resources (`WEB-INF/resources`) of your application will require a restart of Liferay. This can be quite time consuming and annoying, hence our recommendation to remove the `META-INF/context.xml` generated by Liferay.

### Accessing Liferay users and roles

#### Using the xxf:get-request-header() function

When running in Liferay, you can access some specific user and roles information from XForms.

Getting the current user's email:

```
xxf:get-request-header('orbeon-liferay-user-email')
```

Example:

`'test@liferay.com'`

Getting the current user's full name:

```
xxf:get-request-header('orbeon-liferay-user-full-name')
```

Example:

`'Joe Bloggs'`

Getting the current user's role names:

```
xxf:get-request-header('orbeon-liferay-user-roles')
```

This returns a sequence of strings, with one string per role.

Example:

`('Administrator', 'Power user', 'User')`

Alternatively, you can use the standard `Orbeon-Username` and `Orbeon-Roles` headers. See also [Access Control](https://doc.orbeon.com/~/revisions/-LF_uc1WMpa4Sd-n5tDb/form-runner/access-control-and-permissions).

#### Portlet filters

\[SINCE Orbeon Forms 4.10]

The portlet is configured to use two portlet filters in `portlet.xml`.

The first filter, `AddLiferayUserHeadersFilter`, extracts Liferay user information and sets it as headers ("properties" in portlet API parlance). This sets the following properties/headers:

* `Orbeon-Liferay-User-Id`
* `Orbeon-Liferay-User-Screen-Name`
* `Orbeon-Liferay-User-Full-Name`
* `Orbeon-Liferay-User-First-Name` \[SINCE Orbeon Forms 2018.1]
* `Orbeon-Liferay-User-Middle-Name` \[SINCE Orbeon Forms 2018.1]
* `Orbeon-Liferay-User-Last-Name` \[SINCE Orbeon Forms 2018.1]
* `Orbeon-Liferay-User-Email`
* `Orbeon-Liferay-User-Group-Id`
* `Orbeon-Liferay-User-Group-Name`
* `Orbeon-Liferay-User-Roles`

The second filter, `AddOrbeonAuthHeadersFilter`, handles either container or header-based auth, and then sets the following headers/properties:

* `Orbeon-Username`
* `Orbeon-Group`
* `Orbeon-Roles`

These in turn are used internally by Orbeon to handle other aspects of authentication/authorization.

### Performance tuning

For large pages, we have found that the Liferay strip filter can take an extremely long time to process a response. You can disable that filter in your `portal-ext.properties` with:

```
com.liferay.portal.servlet.filters.strip.StripFilter=false
```

*NOTE:* `portal-ext.properties` *is a standard Liferay configuration file you place under the* [*Liferay Home directory*](https://dev.liferay.com/discover/deployment/-/knowledge_base/6-2/liferay-home)*.*

## Creating a new landing page for the portlet

By default, the portlet shows a list of Orbeon Forms sample forms and apps.

To change this, you need to:

1. Modify `WEB-INF/resources/page-flow-portlet.xml.`
2. Create a new landing page in XHTML format.
3. Change the default Orbeon theme so that no custom Orbeon CSS is added.

A simple way do implement this is as follows:

First, replace this line in `page-flow-portlet.xml`:

```markup
<page path="/" model="apps/home/page-flow.xml"/>
```

with:

```markup
<page path="/" view="home.xhtml"/>
```

Second, create a new file, `WEB-INF/resources/home.xhtml`, with content such as:

```markup
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>Form Runner Home</title>
    </head>
    <body>
        <a href="/fr/">Link to the Form Runner home page</a>
        <a href="/fr/acme/form1/summary">Link to summary page of form acme/form1</a>
        <a href="/fr/acme/form2/new">Link to new page of form acme/form2</a>
    </body>
</html>
```

This is the landing page itself, and it can contain any XHTML you like. Typically would include links to specific Form Runner paths as shown in the example above.

Finally, to change the Orbeon portlet theme to the plain theme, set this property:

```markup
<property
  as="xs:anyURI"
  name="oxf.epilogue.theme.embeddable"
  value="oxf:/config/theme-embeddable.xsl"/>
```

<https://github.com/orbeon/orbeon-forms/blob/master/src/main/resources/config/properties-form-runner.xml> <https://github.com/orbeon/orbeon-forms/blob/master/src/main/resources/config/properties-form-runner.xml>