Web Files Troubleshooting - BloomReach Experience - Open Source CMS
06-12-2019

Web Files Troubleshooting

In case you are experiencing problems with Web Files, for example not being pushed to the repository, browser auto reloading does not work or Web Files are not rendered by the HST site frontend, you can find here common problems and their solutions. 

Problem 1 : My Web File does not get pushed to the repository

at http://localhost:8080/cms/console?path=/webfiles I do not see my Web File I am editing locally in my IDE. One of the following reasons could be your problem

1. Web File watch is not enabled

See Web Files configuration at  Enable web file watch how to enable the web file watch.

2. You are editing a file outside repository-data/webfiles module

By default, only repository-data/webfiles files are pushed to the repository. See Web Files configuration at Watching multiple Maven modules how to enable more modules.

3. The file is too large

See  Web Files configuration at  Maximum Web File size limit how to increase the default file size limit, but, also see Web Files Best Practices for alternative and possibly better solutions because on purpose the default Web File limit is set to 256Kb.

4. The file is not a default included file

See Web Files configuration at  Included files how to add new file patterns to also be included. 

Problem 2 : After changing a css, js or freemarker template file, the browser does not automatically reload

First of all make sure that the changes of the file end up in the repository below http://localhost:8080/cms/console?path=/webfiles . If not, check out  Problem 1. If refreshing the browser yourself works, checkout the following reasons:

1. Auto reload is switched off in configuration

At  /hippo:configuration/hippo:modules/autoreload/hippo:moduleconfig, make sure that 

enabled: true

2. The javascript for opening a web socket to get change events pushed is not injected

During local development with mvn cargo.run, by default a javascript is injected in the page to open up a web socket. Looking into the source code of the html, you should see in the <head> element a <script> element containing:

(function(window, console) {

    var AUTO_RELOAD_PATH = "/autoreload",

If you do not see the above in the source code, most likely your base JSP or freemarker does not contain in the <head> element the right headContribution. Make sure that your base template looks something as below with respect to the headContributions (including the category includes and excludes).

<!doctype html>
<html>
  <head>
    <@hst.headContributions categoryExcludes="htmlBodyEnd, scripts" xhtml=true/>
  </head>
  <body>
    <!-- all body html -->
    <@hst.headContributions categoryIncludes="htmlBodyEnd, scripts" xhtml=true/>
  </body>
</html>

In case of JSP, replace <@hst.headContributions with <hst:headContributions.

Problem 3 : HST does not create correct links for Web Files or does not render them correctly

Make sure that there is a Web Files sitemap item with children as follows in the hst:default sitemap:

/hst:hst:
  /hst:configurations:
    /hst:default:
      /hst:sitemap:
        /webfiles:
          hst:containerresource: true
          hst:namedpipeline: WebFilePipeline
          hst:refId: WEB-FILES-ID 
        /_default_:
          /_any_:
            hst:parameternames: version
            hst:parametervalues: ${1}
            hst:relativecontentpath: {2}

Problem 4: After uploading Web Files manually, the changes are not visible in the browser

You uploaded new nodes in the console or updated the Binary property with the upload option. After saving the changes the new file does not show up in the site.

Check if you updated the anti-caching alias at /webfiles/site/webfiles:anticache with a new timestamp value.

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?