Custom Homepage/Error Pages

Custom Home Page

A custom homepage (which uses a URL other than index) can be created by redirecting the default /index path using a Vanity URL (for each respective host). To specify a custom homepage URL for a site, add a Vanity URL with the following dotCMS reserved URL to ONE Vanity URL on the site:

• /cmsHomePage

Note:

• The case of the URL is important, and must match the above case exactly.
• For information on how to create a default homepage for your site, please see the Creating a Homepage documentation.

Custom Error Pages

Custom error pages can be created for each host by redirecting their default path via Vanity URL (for each respective host). These are the steps to take.

1. Create your custom error page as a regular page in dotCMS: for instance /error-pages/404
2. Create a virtual link with the following properties. Use the exact title and URL or the Vanity URL won't work.

• Title: “cms404Page”
• Applies to: define whether the Custom Error page will be used by “All Hosts” or a specific host.
• URL: “/cms404Page”
• Enter URL to Redirect to: your page location for example “/error-pages/404”

This applies to the following error pages:

• /cms400Page
• /cms401Page
• /cms402Page
• /cms403Page
• /cms404Page
• /cms500Page
• /cms503Page

Global and Local Custom Error Pages

When creating a Vanity URL, there is a drop down select field option for setting the Host that the Vanity URL “Applies to“:

1. “All Hosts” option-allows a relative or discrete path to be set for “ALL HOSTS” managed by dotCMS when handling the error type.

2. Localpath: /folderpath/my404errorpage (each host has its own custom error page using the exact same location and pagename)
   OR

3. Global or External Path: http://myglobalsite/myfolderpath/my404errorpage (This requires the creation of one host to serve as a “global” error page repository)
   In this case, the following parameters will be passed in the url:

   • ep_originatingHost: domain on which the error occurred
   • ep_errorCode: the type of error that ocurred
   • ep_error_uri: the url that caused the error
     

    demo.dotcms.com/error/errorPage.html?ep_originatingHost=demo.dotcms.com&ep_errorCode=404&ep_error_uri=/test/someBadPath.html
   

   This way a “smart” error page can then detect these parameters set in the url and react with a custom response based on those parameters. In other words, one smart error page can be the global error page for many sites but still display custom error messaging for each domain/host from which the error was generated. This is a feature developed to multi-tennent sites to have “catch-all” custom error pages that still deliver error messaging/styling that appears specific to each host.

4. Specific Host- allows a relative or discrete path to be set for a each host individually when handling the error type. This option allows Custom error page pathing and error pages to be customized to each host individually

5. Localpath: /folderpath/my404errorpage OR

6. Global or External Path: http://myglobalsite/myfolderpath/my404errorpage (This requires the creation of one host to serve as a “global” error page repository)
   

Redirecting Error pages to a Global or External Host

The host that originated the error, the error code itself, and the bad path attempted (errorURI), can be retrieved by adding the following lines to the velocity on custom error pages:

#set($hostWithError = $request.getParameter('ep_originatingHost'))
#set($errorCode = $request.getParameter('ep_errorCode'))
#set($errorUri = $request.getParameter('ep_error_uri'))  

Webmasters can manage custom error pages on all sites from the same “default host” or allow each host to maintain its own custom error pages using the options provided above. These custom error pages can be relatively pathed or use discrete error page URL paths to other hosts or even to external pages.