drewwills / Soffit

The underside of an arch or architrave

Soffit for Apereo uPortal

Soffit is a technology for creating content that runs in Apereo uPortal. It is intended as an alternative to JSR-286 portlet development. For the present, this technology is developed as an add-on in a separate repo (this one); in the near future, we hope to include it to the uPortal project directly and depricate this repo. We will post an announcement here when that happens.

Why Would I Want This Component?

You are a Java web application developer. You are tasked with developing content for Apereo uPortal.

You are not excited about doing Java Portlet development in the traditional way or even using Spring Portlet MVC. You correctly conclude that the Java Portlet APIs are large, obtuse, and actively interfere with contemporary web development practices and frameworks that you want to be using.

Apereo Soffit is an alternative approach to producing content for uPortal that is not based on JSR-286 or the portlet container.

How Does It Work?

Soffit is a strategy for adding content to uPortal. It defines and manages the relationship between content objects (soffits) and the portal service itself. Currently there are two required steps for using soffits.

Step One: Add Support for Soffit to uPortal

Soffit is a lightweight addition to uPortal; very few changes are needed. There is a pull request in the uPortal Git repo that contains a branch with all necessary settings. (NOTE: the Soffit .jar file is not "finished" and therefore it is not released into Maven Central; you will need to $git clone this project and then $gradle install it locally before you can build uPortal with Soffit.)

Instructions for merging Soffit support

Important! Make sure you clone this project and run $./gradlew clean install before performing the steps below. This step is a prerequisite.

From inside the root of your uPortal repo...

// Recommended:  add Soffit technology on a feature branch
$git checkout -b add-soffit

$git remote add drewwills https://github.com/drewwills/uPortal.git

$git fetch drewwills

$git merge drewwills/add-soffit

$ant clean deploy-ear

Step Two: Develop a Soffit

A soffit's interaction with the portal is HTTP-based. It is posible to write a soffit in any language or platform that can accept, process, and respond to a connection over HTTP. At the present time, the creators of Soffit expect to develop soffits mostly with Java and Spring Boot.

Minimal Soffit Setup Instructions Using Spring Boot

1. Use the Spring Initializer to create a new Spring Boot project with the following settings:
   • Gradle Project (recommended)
   • Packaging=War (recommended)
   • Dependencies=Cache (recommended) & Web (required)
   • Additional dependencies you intend to use (optional -- you can add them later)
2. Add Soffit as a dependency to your project (see below)
3. Add the tomcat-embed-jasper dependency to your project (see below)
4. Add the @SoffitApplication annotation to your application class (the one annotated with @SpringBootApplication)
5. Create the directory path src/main/webapp/WEB-INF/soffit/
6. Choose a name for your soffit and create a directory with that name inside /soffit/ (above); recommended: use only lowercase letters and dashes ('-') in the name
7. Create a view.jsp file inside the directory named for your soffit; add your markup (e.g. <h2>Hello World!</h2>)
8. In src/main/resources/application.properties, define the server.port property and set it to an unused port (like 8090)
9. Run the command $gradle assemble to build your application
10. Run the command $java -jar build/lib/{filename}.war to start your application

That's it! You now have a functioning, minimal Soffit application running on localhost at server.port.

Adding the Soffit dependency

Gradle Example:

compile("org.apereo.portal:soffit:0.9.0-SNAPSHOT")

Maven Example:

<dependency>
    <groupId>org.apereo.portal</groupId>
    <artifactId>soffit</artifactId>
    <version>0.9.0-SNAPSHOT</version>
</dependency>

Adding the tomcat-embed-jasper dependency

Gradle Example:

configurations {
    providedRuntime
}

[...]

providedRuntime('org.apache.tomcat.embed:tomcat-embed-jasper')

Publishing your Soffit

Follow these steps to view your soffit in uPortal.

In the Portlet Manager

• Select Register New Portlet
• Choose Portlet in the list of types and click Continue
• Select /uPortal and Soffit Connector in the Summary Information screen and click Continue (assumes you have Soffit installed in your portal)
• Enter portlet metadata normally (e.g. name, tile, fname, groups, categories, lifecycle state, etc.)
• Under Portlet Preferences, override the value of org.apereo.portal.soffit.connector.SoffitConnectorController.serviceUrl with the URL of your soffit, e.g. http://localhost:8090/soffit/my-soffit running independently (outside Tomcat) or http://localhost:8080/my-porject/soffit/my-soffit running inside Tomcat
• Click Save

Soffit Data Model

To be of any use, real soffits must go beyond Hello World! Soffit provides a rich data model for sharing data from the portal with your application. There are (currently) four objects in this data model:

• The Bearer contains information about the user: username, user attributes, and group affiliations in the portal
• The PortalRequest contains information about the request your soffit is filling, like parameters, mode, and window state
• The Preferences object contains a collection of publish-time settings for your soffit chosen by the administrator; these are options you define for your needs; using preferences is optional
• The Definition contains publish-time metadata about your soffit in the portal; these are settings defined by and consumed by the portal itself, like title and chrome style

Accessing th data model in a JSP

Each of these objects is defined within the Expression Language (EL) Context in which your .jsp files execute. Use camel-case spelling to reference them, for example...

<h2>Hello ${bearer.username}</h2>

A Word on Modern Web User Interfaces

Soffit assumes that you want to develop user interfaces using Javascript and modern frameworks like React, AngularJS, Backbone.js, etc. Normally a Soffit component will render one time; considerations like state changes, transactions, persistence, etc. are typically handled with Javascript and REST.

Configuration Options

Caching

Caching in soffits is available via the standard HTTP header Cache-Control.

Example

Cache-Control: public, max-age=300

Cache scope may be public (shared by all users) or private (cached per-user). Specify max-age in seconds.

Cache re-validation is not yet supported, so

Cache-Control: no-store

and

Cache-Control: no-cache

currently have the same effect.

Sample Applications

There are several sample applications in this repo.