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.
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.
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.
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.)
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
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.
tomcat-embed-jasper
dependency to your project (see below)@SoffitApplication
annotation to your application class (the one annotated with @SpringBootApplication
)src/main/webapp/WEB-INF/soffit/
/soffit/
(above); recommended: use only lowercase letters and dashes ('-') in the nameview.jsp
file inside the directory named for your soffit; add your markup (e.g. <h2>Hello World!</h2>
)src/main/resources/application.properties
, define the server.port
property and set it to an unused port (like 8090)$gradle assemble
to build your application$java -jar build/lib/{filename}.war
to start your applicationThat's it! You now have a functioning, minimal Soffit application running on localhost
at server.port
.
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>
tomcat-embed-jasper
dependencyGradle Example:
configurations {
providedRuntime
}
[...]
providedRuntime('org.apache.tomcat.embed:tomcat-embed-jasper')
Follow these steps to view your soffit in uPortal.
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 TomcatTo 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:
Bearer
contains information about the user: username, user attributes, and group affiliations in the portalPortalRequest
contains information about the request your soffit is filling, like parameters, mode, and window statePreferences
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 optionalDefinition
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 styleEach 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>
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.
Caching in soffits is available via the standard HTTP header Cache-Control
.
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.
There are several sample applications in this repo.