Bootstrap Web Files

Introduction

Goal

Import or update web files in the repository using the bootstrap mechanism or manual upload.

Summary

Web files can be imported into the content repository via the repository bootstrap mechanism. Subsequent updates can be done using reload on startup during redeployment, or using manual upload.

Development Environment

In a local development environment web files that are modified on the file system are automatically imported into the repository. When locally (re-)starting an existing repository, changes made to the web files during downtime will be imported into the existing repository. This guarantees that during local development the repository web files always reflect the web files on file system correctly. When Web File Watch is disabled (see Configure Web Files), the automatic (re-)import during a restart is disabled too, and a re-import will be done depending on the reload on startup of the initialize item for the web files.

Production Environment

When deploying the application in a production environment, the repository bootstrap mechanism is the primary way to import web files into the content repository.

An entire web file bundle is bootstrapped using one special initialize item. When redeploying reload on startup can be used to rebootstrap the web file bundle.

Alternatively web files can be updated manually so that a redeployment is not needed.

Web File Bundle Initialize Item

End projects store web file bundles as regular files and directories on the file system. These files and directories are then packaged into .jar files that are included in the .war files of the web application(s). A single Hippo initialize item bootstraps a packaged web file bundle into the repository.

In a Maven project, the files and directories that make up a web file bundle are stored in a separate module. The default Maven module for web files as configured when you start a new project is bootstrap/webfiles.

A Maven module can contain one or more web file bundles. Each bundle is located in a separate directory below src/main/resources named after the bundle. For example, the following directory structure shows a Maven module called bootstrap/webfiles that contains a web file bundle called site with two web files in it: css/style.css and js/script.js.

bootstrap
  webfiles
    src
      main
        resources            
          site
            css
              style.css
            js
              script.js

A web file bundle can be imported via a special initialize item in the file 

bootstrap/webfiles/src/main/resources/hippoecm-extension.xml

The default intialize item for the site web file bundle in a project created using the Maven archetype looks like this:

<sv:node sv:name="myproject-webfiles-site">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hippo:initializeitem</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:webfilebundle" sv:type="String">
    <sv:value>site</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:sequence" sv:type="Double">
    <sv:value>31000</sv:value>
  </sv:property>
</sv:node>

The initialize item will import all files and directories in the site directory into the repository, at the JCR path /webfiles/site.

Reload on Startup

A web file bundle initialize item can be reloaded when the web application is redeployed. The initialize item should then be marked with a hippo:reloadonstartup and hippo:version element. A reloaded web file bundle completely replaces an existing web file bundle. For the above example that would be something like:

<sv:node sv:name="myproject-webfiles-site">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hippo:initializeitem</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:webfilebundle" sv:type="String">
    <sv:value>site</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:sequence" sv:type="Double">
    <sv:value>31000</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:reloadonstartup" sv:type="Boolean">
    <sv:value>true</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:version" sv:type="String">
    <sv:value>1.01.01</sv:value>
  </sv:property>
</sv:node>

Manual Upload

Alternatively, a web file can be updated manually using the Console by browsing to the web file's jcr:content node (e.g. /webfiles/site/css/bootstrap.css/jcr:content) and clicking on the Upload binary link next to the jcr:data property.

When using this method you must make sure a new timestamp value is applied to  the /webfiles/site/webfiles:anticache property. Otherwise browsers may still serve older cached versions of the web files.