Using the Resource Server

How to configure a new or existing web application to use the Resource Server and corresponding utilities. These directions all assume that a Maven managed and structured project is being used.

Create a Skin Descriptor

Create a skin descriptor file in the main web application directory, for example: src/main/webapp/resources.xml

List all JavaScript and CSS files your application uses in this file. The files will be included in the order specified. To ensure the best performance files from the same path should be loaded in order.

The jQuery 1.4.2, jQuery UI 1.8 and Fluid 1.2.1 are resources from the Resource Server application, this is denoted by the resource="true" attribute. The duplicate entries specify standard and minified versions to enable easier debugging of the application.
All CSS and JavaScript files are listed even if they aren't all used on every view, the end result will be a single .js file for the browser to download once and use across all views.

src/main/webapp/resources.xml

<resources xmlns="http://www.jasig.org/uportal/web/skin"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.jasig.org/uportal/web/skin https://source.jasig.org/schemas/resource-server/skin-configuration/skin-configuration-v1.2.xsd">

 <css>css/jquery.loadmask.css</css>
 <css>css/main.css</css>
 
 <js included="plain" resource="true">/rs/jquery/1.4.2/jquery-1.4.2.js</js>
 <js included="aggregated" resource="true">/rs/jquery/1.4.2/jquery-1.4.2.min.js</js>
 
 <js included="plain" resource="true">/rs/jqueryui/1.8/jquery-ui-1.8.js</js>
 <js included="aggregated" resource="true">/rs/jqueryui/1.8/jquery-ui-1.8.min.js</js>
 
 <js included="plain" resource="true">/rs/fluid/1.2.1/js/fluid-all-1.2.1-v2.js</js>
 <js included="aggregated" resource="true">/rs/fluid/1.2.1/js/fluid-all-1.2.1-v2.min.js</js>
 
 <!-- Order is important here, the log script needs to be the first thing followed by the debug toggle -->
 <js>js/jquery.log.js</js>
 <js included="plain">js/debug.js</js>
 
 <js>js/json.stringify.js</js>
 <js>js/jquery.loadmask.js</js>
 <js>js/date.format.js</js>
 <js>js/jquery.ajaxmanager.js</js>
 <js>js/jquery-tools-validator-1.2.5.js</js>
 
 <js>js/hrs.js</js>

</resources>

Update JSPs to use Skin Descriptor

In any JSP where CSS or JavaScript is used replace all <link> and <script> tags with the <rs:aggregatedResources> tag. The path specified is absolute in reference to the deployed web application's directory

<%@ taglib prefix="rs" uri="http://www.jasig.org/resource-server" %>

<rs:aggregatedResources path="/resources.xml"/>

Compress Inline JavaScript

Most uses of JavaScript require some inline JS code to initialize the components from the included JavaScript files. To reduce the size of the page sent to the browser use the <rs:compressJs> tag to wrap any inline JavaScript.

<script type="text/javascript" language="javascript">
<rs:compressJs>
(function($) {
    //View specific init code
})(hrs.jQuery);
</rs:compressJs>
</script>

Maven Dependencies, Plugins, & Configuration

The next three sections all pertain to the project's pom.xml. To simplify configuration it is recommended that a property is added to specify the resource-server version. This guide is not updated for every release so go to the org.jasig.resourceserver Maven page to figure out the current version.

The resource server plugin uses the character encoding specified in the project.build.sourceEncoding property to read and write resources. The plugin will fail if project.build.sourceEncoding is not set.

<properties>
    ...
    <resource-server.version>1.0.23</resource-server.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

resource-server-utils Dependency

In the <dependencies> block add the following dependency.

<dependency>
   <groupId>org.jasig.resourceserver</groupId>
   <artifactId>resource-server-utils</artifactId>
   <version>${resource-server.version}</version>
</dependency>

resource-server-content Overlay

To ensure the portlet will work even if the Resource Serving Web Application is not available or is an older version all Resource Server content used by the portlet should also be included in the final project WAR. The Maven WAR overlay process makes this easy to do.

In the <dependencies> block add the following dependency.

<dependency>
    <groupId>org.jasig.resourceserver</groupId>
    <artifactId>resource-server-content</artifactId>
    <version>${resource-server.version}</version>
    <type>war</type>
</dependency>

In the <build> <plugins> section add or update the maven-war-plugin to included an overlay section like the following example. Referencing the Create a Skin Descriptor section the paths to the three elements marked with resource="true" are listed as includes. The result is that those files will be included under those paths in the final WAR, ensuring that if the Resource Serving Web Application is not available the portlet will still function correctly.

<plugin>
    <artifactId>maven-war-plugin</artifactId>
    <version>2.1.1</version>
    <configuration>
        <overlays>
            <overlay>
                <groupId>org.jasig.resourceserver</groupId>
                <artifactId>resource-server-content</artifactId>
                <includes>
                    <include>rs/jquery/1.4.2/</include>
                    <include>rs/jqueryui/1.8/</include>
                    <include>rs/fluid/1.2.1/js/</include>
                </includes>
            </overlay>
        </overlays>
    </configuration>
</plugin>

Skin Compression Maven Plugin

In the <build> <plugins> section add the resource-server-plugin. This plugin read the resources.xml file at packaging time and performs the aggregation and compression of local JavaScript and CSS.

<plugin>
    <groupId>org.jasig.resourceserver</groupId>
    <artifactId>resource-server-plugin</artifactId>
    <version>${resource-server.version}</version>
    <executions>
        <execution>
            <id>aggregate-resources</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>batch-aggregate</goal>
            </goals>
            <inherited>false</inherited>
            <configuration>
                <displayJsWarnings>false</displayJsWarnings>
                <includes>
                    <include>resources.xml</include>
                </includes>
                <sharedJavaScriptDirectory>js/</sharedJavaScriptDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

Enable Resource Server Integration

To allow the resource-server-utils library to determine if the Resource Serving Web Application is available add the following content to the file src/main/webapp/META-INF/context.xml

src/main/webapp/META-INF/context.xml

<Context crossContext="true">
</Context>

Enable GZip Compression and Browser Caching

A few filters need to be added to src/main/webapp/WEB-INF/web.xml to enable compression and browser side caching.

src/main/webapp/WEB-INF/web.xml

<filter>
    <filter-name>gzipFilter</filter-name>
    <filter-class>net.sf.ehcache.constructs.web.filter.GzipFilter</filter-class>
</filter>
<filter>
    <filter-name>CacheExpiresFilter</filter-name>
    <filter-class>org.jasig.resourceserver.utils.filter.PathBasedCacheExpirationFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>gzipFilter</filter-name>
    <url-pattern>/img/*</url-pattern>
</filter-mapping>
<filter-mapping>
    <filter-name>CacheExpiresFilter</filter-name>
    <url-pattern>/media/*</url-pattern>
    <url-pattern>*.js</url-pattern>
    <url-pattern>*.css</url-pattern>
</filter-mapping>