Support and Documentation

Error pages

You can customize error pages corresponding to the standard HTTP status codes.

Modifying web.xml

For the Tomcat server, you associate error codes with the location of custom error pages in Brightspot's web.xml file. (See Interface HttpServletResponse for a listing of possible Tomcat error codes.)

The following example shows a custom page setup for error code 404.

  1. Open the file <root>/src/main/webapp/WEB-INF/web.xml.

  2. Under the root <web-app> element, define <error-page> elements where the <error-code> child element corresponds to a Tomcat error code and the <location> child element corresponds to a page URL defined in Brightspot.


Creating a custom error page

A custom error page must be associated with an error code set in Brightspot's web.xml file and have a permalink of /404. The following sections show two examples to construct a Brightspot 404 error page. The first and easiest method is to use the Text content type, which appears in Brightspot as Raw HTML. The second example follows the model-view-view model (MVVM) pattern to construct a page in which you create a model class, view templating components, and a view model class.

Example 1: Using Raw HTML
  1. In Brightspot, create a new Raw HTML object.

  2. At a minimum, set the following fields on the Main tab of the content edit page:

    • Name—A name to reflect the type of error page

    • HTML—The HTML code to be rendered by browsers.

  3. Add a permalink that matches the value of the <location> child element in the web.xml file.

  4. (Optional) Set the fields in the other tabs of the content edit page.

Example 2: Using MVVM pattern

Step 1: Create a model for the page

The following example shows a model for a 404 error page. The Brightspot-constructed permalink is based on the value of the httpError field.

public class Error404 extends Content implements Directory.Item, Page {

   @ToolUi.Placeholder("404 Error Page")
   private String name;

   private Image leadImage;

   private String body;

   @ToolUi.Note("Must match error code value in web.xml")
   private String httpError;

   public String getHttpError() {
       return httpError;

   /* Other getters and setters... */

   public String createPermalink(Site site) {
       return StringUtils.toNormalized(getHttpError());

As a result of this model, the content edit page for the Error404 content type is similar to the following:


Step 2: Add Handlebars placeholders

In the view's Handlebars template for the page, add placeholders for the error page content.

<!DOCTYPE html>

   <meta charset="UTF-8">
   <link href="/styleguide/All.min.css" type="text/css" rel="stylesheet"/>

   <div class="Error-headline">

   <div class="Error-leadImage">
      <img src="{{leadImageUrl}}" height="300" />

   <div class="Error-body">


Step 3: Add JSON keys

In the view's JSON file for the page, add key-value pairs for the error page content.

   "_template": "errorPages.hbs",
   "name": "{{words(5)}}",
   "httpError": "{{words(1)}}",
   "body": "{{paragraphs(1)}}",
   "leadImageUrl": "{{image(400, 300)}}"

Step 4: Create a view model for Error404

In the Error404ViewModel class, add methods to retrieve values from the Error404 object and to populate the view placeholders.

public class Error404ViewModel extends ViewModel<Error404> implements ErrorPagesView {

   public CharSequence getName() {
      return model.getName();

   public CharSequence getHttpError() {
     return model.getHttpError();

   public CharSequence getBody() {
     String body = model.getBody();
     if (body != null) {
         return RichTextViewBuilder.buildHtml(body, (rte) -> null);
     return null;

   public CharSequence getLeadImageUrl() {
     Image leadImage = model.getLeadImage();
     if (leadImage != null) {
         StorageItem file = leadImage.getFile();

         if (file != null) {
             return file.getPublicUrl();
     return null;