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.

Make sure to read the Web Files Best Practices too!

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
The *.txt extension has been added in Web Files 2.0.1 and Bloomreach Experience Manager 10.0.3.

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']
Note that Included files refer to what files will be imported into the repository. This is not the same as which files are publicly accessible. See Secure Web Files for how allowing public access to web files works.

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:

Pattern Ignores files and directories whose name...
bower.json is "bower.json"
*.json ends with ".json"
*.{less,scss} ends with ".css" 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

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
The web files module configuration is only read when the repository starts up. Changes to the configuration require a restart of the repository to be picked up.

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. 

By default, the web files watch implementation based on the Java 7 WatchService is only used on Linux. On Windows two JDK bugs ( JDK-7052697 and  JDK-6972833) result in a bad end-user experience. On Mac OS X there's no native implementation yet ( JDK-7133447).

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.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?