Apereo Soffit

Soffit is a technology for creating content that runs in Apereo uPortal. It is intended as an alternative to JSR-286 portlet development.

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?

Add Soffit to your Java Web Application. Use .jsp or .html files to create the markup you want to appear in your content. That's it! With every other aspect of your project, simply carry on with what you were doing. Soffit allows your content to run in uPortal and gets out of your way so you can do development the way that you want to.

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, persistance, etc. are typically handled with Javascript and REST.

Minimal Soffit

Follow these three steps to create a minimal Soffit component.

Add Soffit as a dependency to your project

Gradle Example:

compile group: 'org.apereo.portal', name: 'soffit', version: "1.0.0-SNAPSHOT"

Maven Example:

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

Define the SoffitRendererController as a bean within your application

Spring Boot Example:

@Bean
public SoffitRendererController soffitRendererController() {
    return new SoffitRendererController();
}

Provide a `.jsp` file with your markup

/WEB-INF/soffit/my-soffit/view.jsp:

<h2>This is my amazing Soffit!</h2>

That's it -- try it out!

You're ready to build and start your soffit. If you're running locally, you can either use a different port than the portal (e.g. 8090) or deploy your .war file to Tomcat beside the portal.

A note on `tomcat-embed-jasper` for Spring Boot applications

Spring Boot is a great way to build soffits. The embedded Tomcat environment provided with a Spring Boot application requires the tomcat-embed-jasper dependency to leverage JSPs.

Gradle Example:

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.portlet.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

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.

bpowell/Soffit