Configure Web Files

Introduction

Goal

Fine-tune the web files feature for your project's specific requirements.

Background

Projects created using the Maven archetype are already configured for Web Files.The default configuration will be fine in most cases. However there is a number of configuration options that allow you to fine-tune the web files feature for your project's specific requirements.

Maximum Web File Size Limit

By default, the maximum allowed file size for Web File files is 256Kb. The maximum can be changed at

/hippo:configuration/hippo:modules/webfiles/hippo:moduleconfig/maxFileLengthKb

In case you have very many large files, instead of increasing this limit, you might want to store the files either in the galleries or as assets folder in the CMS or store them in local static webapp files. Setting maxFileLengthKb to a large value can have a negative impact on performance for local development as well as a larger impact during changes in production due to the anti-caching in the URL after a change. Also see Web Files Best Practices.

Included Files

Only specific files in a web file bundle are imported into the repository. The list of included file name patterns is located at:

/hippo:configuration/hippo:modules/webfiles/hippo:moduleconfig/includedFiles

The default list of file name patterns contains all extensions typically used in modern frontend development:

• *.css
• *.eot
• *.ftl
• *.gif
• *.html
• *.ico
• *.jpeg
• *.jpg
• *.js
• *.json
• *.map
• *.otf
• *.png
• *.svg
• *.ttf
• *.woff
• *.xml
• *.properties
• *.txt

Additional file name patterns can be added via a YAML source in the repository-data-application module. For example, the following YAML source also includes Shockwave Flash files (for your old-fashioned customer) and plain text files:

definitions:
  config:
    /hippo:configuration/hippo:modules/webfiles/hippo:moduleconfig:
      includedFiles:
        operation: add
        type: string
        value: ['*.swf', '*.xhtml']

Excluded Directories

All directories in web file bundles are imported into the repository, except some excluded ones. The list of excluded directory names is located at:

/hippo:configuration/hippo:modules/webfiles/hippo:moduleconfig/excludedDirectories

The default list of excluded directories includes those used by popular version control systems, like .git and .svn. Everything in an excluded directory is also excluded automatically.

Globbing Name Patterns

All includedFiles and excludedDirectories name patterns use the same 'glob' syntax as  java.nio.file.Files#getPathMatcher(String), except that each pattern only matches the file name of a path (i.e. the last part). Hence the / character is not allowed. Some examples of valid patterns are:

Development Environment: Watch and Auto-Import

Developers can change the web files in a project without having to restart Tomcat or rely on a hot-deployment agents like JRebel. The repository watches the web file bundles on file system for changes. Whenever the files or directories that make up a web file bundle change, the repository automatically re-imports the changes.

Enable Web File Watch

The web file watch is enabled whenever the Java system property  project.basedir is set to absolute path of the root directory of the local Maven project. The easiest way to do this is by using the Maven property  project.basedir in the configuration of the Cargo plugin in the root  pom.xml file of a project:

<profile>
  <id>cargo.run</id>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.cargo</groupId>
        <artifactId>cargo-maven2-plugin</artifactId>
        <configuration>
          ...
          <container>
            <systemProperties>
              <!-- enables web files watch -->
              <project.basedir>${project.basedir}</project.basedir>
           </systemProperties>
          </container>
        </configuration>
      </plugin>
    </plugins>
  </build>
</profile>

The project structure created by the Hippo archetype will have this in place already.

Watching Multiple Maven Modules

By default the Maven module repository-data/webfiles is watched for web file bundle changes. Additional Maven modules to watch can be configured in the repository at:

/hippo:configuration/hippo:modules/webfiles/hippo:moduleconfig/watchedModules

For example, the following YAML source adds an additional Maven module called "repository-data/extrawebfiles" to the list of watched modules:

definitions:
  config:
    /hippo:configuration/hippo:modules/webfiles/hippo:moduleconfig:
      watchedModules: [repository-data/webfiles,repository-data/extrawebfiles]

Watch on Linux, else Poll for Changes

There are two implementations for watching changes in web file bundles: one using the Java 7 WatchService, and one using the FileAlterationMonitor of Apache Commons IO. The former is more efficient since it does not require polling of the file system for changes, but has some issues on various operating system. 

Which implementation is used can be configured. The implementation based on the WatchService is only used when the current operating system name (as reporting by the Java system property "os.name") matches one of the globbing patterns configured at:

/hippo:configuration/hippo:modules/webfiles/hippo:moduleconfig/useWatchServiceOnOsNames

The default value is " Linux". To try out the WatchService on Windows, add a second value " Windows*". An empty value will disable the WatchService implementation.

The fallback watch implementation scans the web file bundle directories periodically for changes. The delay between consecutive scans can be configured at:

/hippo:configuration/hippo:modules/webfiles/hippo:moduleconfig/watchDelayMillis

By default, the delay is 500 milliseconds. Decrease it to pick up changes faster. Increase it to use less CPU cycles.