Configure Web Files

Overview

This page describes how to adjust the web files feature in Bloomreach Content to meet project-specific requirements.

Projects generated with the Maven archetype include a default web files configuration. In most cases, the default settings are sufficient. However, you can modify several options to better fit your project's needs.

Note: Review the Web Files Best Practices for additional guidance.

Maximum Web File Size

By default, the maximum allowed size for a single web file is 256 KB. You can change this limit by updating the following configuration property:

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

If your project requires many large files, consider storing them in the galleries or assets folders in the CMS, or as static files in your web application. Increasing maxFileLengthKb can negatively affect performance, especially during development and when deploying changes to production. Each change triggers anti-caching behavior in the URL, which can further impact performance. For more details, see Web Files Best Practices.

Included Files

Only certain files from a web file bundle are imported into the repository. The list of included file name patterns is defined at:

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

By default, the configuration includes file extensions commonly used in frontend development:

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

The *.txt extension was added in Web Files 2.0.1 and brXM 10.0.3.

To include additional file types, add patterns using a YAML source in the repository-data-application module. For example, to include Shockwave Flash (*.swf) and XHTML (*.xhtml) files:

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

Included files determine which files are imported into the repository. This does not control public accessibility. For information on securing web files, see Secure Web Files.

Excluded Directories

All directories in web file bundles are imported into the repository except those explicitly excluded. The list of excluded directory names is configured at:

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

By default, directories used by version control systems (such as .git and .svn) are excluded. All files and subdirectories within an excluded directory are also excluded.

Globbing Name Patterns

The includedFiles and excludedDirectories patterns use the glob syntax from java.nio.file.Files#getPathMatcher(String). Each pattern matches only the file or directory name (the last path segment). The / character is not allowed.

Examples of valid glob patterns:

Pattern	Matches files and directories whose name...
`bower.json`	is exactly "bower.json"
`*.json`	ends with ".json"
`*.{less,scss}`	ends with ".less" or ".scss"
`??.bak`	consists of two characters followed by ".bak"
`[a-c]*.jpg`	starts with 'a', 'b', or 'c' and ends with ".jpg"

Development Environment: Watch and Auto-Import

You can update web files in your project without restarting Tomcat or using hot-deployment tools like JRebel. The repository monitors web file bundles on the file system and automatically re-imports changes when files or directories are modified.

Enable Web File Watch

Web file watch is enabled when the Java system property project.basedir is set to the absolute path of your Maven project root. The recommended approach is to configure this property in the Cargo plugin section of your root pom.xml:

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

Projects generated by the Hippo archetype include this configuration by default.

Watching Multiple Maven Modules

By default, the repository watches the repository-data/webfiles Maven module for changes. To watch additional Maven modules, update the configuration at:

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

The repository reads the web files module configuration only at startup. Restart the repository after making configuration changes.

For example, to add a module named repository-data/extrawebfiles:

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

Watch Implementation: Linux and Other Platforms

Two implementations are available for monitoring changes in web file bundles:

Java 7 WatchService: Efficient, event-based monitoring.
Apache Commons IO FileAlterationMonitor: Polls the file system for changes.

By default, the WatchService implementation is used only on Linux. On Windows, known JDK bugs (JDK-7052697, JDK-6972833) affect reliability. On Mac OS X, no native implementation is available (JDK-7133447).

Info: The WatchService-based implementation is enabled when the operating system name (from the Java system property os.name) matches any glob pattern configured at:
/hippo:configuration/hippo:modules/webfiles/hippo:moduleconfig/useWatchServiceOnOsNames
The default value is Linux. To enable WatchService on Windows, add Windows* to the list. To disable WatchService entirely, set an empty value.

The fallback implementation uses periodic scanning. You can configure the scan interval (in milliseconds) at:

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

The default interval is 500 milliseconds. Decrease the value for faster detection of changes, or increase it to reduce CPU usage.