Purpose
Provide an author-able means for defining, creating and managing custom Error pages per content tree/site.
Provide an author-able means for defining, creating and managing custom Error pages per content tree/site.
Overview
Edit/Design mode
40x Handling
Author is displayed the corresponding error page
50x Handling
Normal/OOTB 500x/Exception error handling behavior is respected. JSP exceptions are displayed inline w the JSP.
Edit/Design mode
40x Handling
Author is displayed the corresponding error page
50x Handling
Normal/OOTB 500x/Exception error handling behavior is respected. JSP exceptions are displayed inline w the JSP.
Preview mode
40x Handling
Author is displayed the corresponding Error page
50x Handling
A custom “Error page” is displayed that includes the Request Progress and Stack Trace.
Disabled (Publish) mode
The corresponding Error page is displayed.
40x Handling
Author is displayed the corresponding Error page
50x Handling
A custom “Error page” is displayed that includes the Request Progress and Stack Trace.
Disabled (Publish) mode
The corresponding Error page is displayed.
How to Use
In AEM Dispatcher configuration, set DispatcherPassError to ‘0’. This allows erring requests to be sent back to AEM.
Watch a video on how to use the ACS AEM Commons Error Page Handler.
Create the proxy overlays for Sling errorhandler scripts (404.jsp and default.jsp) which include the acs-commons counterparts.
In AEM Dispatcher configuration, set DispatcherPassError to ‘0’. This allows erring requests to be sent back to AEM.
Watch a video on how to use the ACS AEM Commons Error Page Handler.
Create the proxy overlays for Sling errorhandler scripts (404.jsp and default.jsp) which include the acs-commons counterparts.
Create the overlay for 404.jsp
/apps/sling/servlet/errorhandler/404.jsp
<%@page session="false"%><% %><%@include file="/apps/acs-commons/components/utilities/errorpagehandler/404.jsp" %>
Then create the overlay for the default.jsp
/apps/sling/servlet/errorhandler/default.jsp
/apps/sling/servlet/errorhandler/404.jsp
<%@page session="false"%><% %><%@include file="/apps/acs-commons/components/utilities/errorpagehandler/404.jsp" %>
Then create the overlay for the default.jsp
/apps/sling/servlet/errorhandler/default.jsp
<%@page session="false"%><%
%><%@include file="/apps/acs-commons/components/utilities/errorpagehandler/default.jsp" %>
In your base page implementation, add the following cq:Widget to the Page Properties dialog
In your base page implementation, add the following cq:Widget to the Page Properties dialog
<errorpages
jcr:primaryType="cq:Widget"
path="/apps/acs-commons/components/utilities/errorpagehandler/dialog/errorpages.infinity.json"
xtype="cqinclude"/>
OR create your own custom pathfield widget
<errorpages
jcr:primaryType="cq:Widget"
fieldLabel="Error Pages"
fieldDescription="Error pages for this content tree"
name="./errorPages"
xtype="pathfield"/>
Create a sling:OsgiConfig node to enable the Error Page Handler
/apps/myapp/config/com.adobe.acs.commons.errorpagehandler.impl.ErrorPageHandlerImpl.xml
<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
jcr:primaryType="sling:OsgiConfig"
enabled="{Boolean}true"
cache.serve-authenticated="{Boolean}true"
cache.ttl="{Long}300"/>
Note: ttl is the TTL of the in-memory error page cache in seconds
Note: ttl is the TTL of the in-memory error page cache in seconds
Create a CQ Page that will act as the default Error page, and also contain all custom variations of error pages. Each error page’s “name” (Node name) should correspond to the HTTP Response Status code it should respond to.
- 500: Internal Server Error
- 404: Not Found
- 403: Forbidden
- Ex. /content/geometrixx/en/errors
- Ex. /content/geometrixx/en/errors/404
- Ex. /content/geometrixx/en/errors/500
- Ex. ./errorPages => /content/geometrixx/en/errors
Note: At this time the full Sling exception-name look-up scheme is not supported. Implementing a 500 error page is sufficient.
In Memory TTL-based Cache (Since v1.5.0)
Introduced in ACS AEM Commons 1.5.0, Error Page Handler comes w an in-memory TTL based. It is recommended you upgrade to 1.5.0 and configure the cache per your requirements using the sling:OsgiConfig settings outlined above.
Introduced in ACS AEM Commons 1.5.0, Error Page Handler comes w an in-memory TTL based. It is recommended you upgrade to 1.5.0 and configure the cache per your requirements using the sling:OsgiConfig settings outlined above.
JMX MBean
The cache implementation is an implementation detail and may change over time without notice; This may change the MBean behavior, attributes, and operations. *
The cache implementation is an implementation detail and may change over time without notice; This may change the MBean behavior, attributes, and operations. *
An ErrorPageHandler MBean is available when the Error Page Handler is enabled. This MBean reports on the In-Memory caches entries, size in KB, hit/miss rates. It also provides functionality to clear the cache and to view the contents of the cache.
Error Page Handler Cache overview
Viewing the contents of the cache for a particular entry
Error Page Handler Cache overview
Viewing the contents of the cache for a particular entry
Error Images (Since v1.7.0)
Introduced in ACS AEM Commons 1.7.0, Error Page Handler supports serving an “error image” in the event a request with a qualified “image” extension (jpg, jpeg, png, and gif) cannot be found. The OSGi config properties described in further detail below int he Advanced section can be used to configure this feature.
- error-images.enabled
- error-images.path
Advanced Sling OSGi Configuration
The Error Page Handler has a few more advanced settings that are typically unused/left as default.
/apps/myapp/config/com.adobe.acs.commons.errorpagehandler.impl.ErrorPageHandlerImpl.xml
The Error Page Handler has a few more advanced settings that are typically unused/left as default.
/apps/myapp/config/com.adobe.acs.commons.errorpagehandler.impl.ErrorPageHandlerImpl.xml
<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
jcr:primaryType="sling:OsgiConfig"
enabled="{Boolean}true"
vanity.dispatch.enabled="{Boolean}true"
serve-authenticated-from-cache="{Boolean}true"
ttl="{Long}300"
error-page.system-path="/content/error"
error-page.fallback-name="500"
/>
enabled true/false to toggle the Error Page Handler on and off
vanity.dispatch.enabled true/false to toggle using the ACS Commons Vanity Path Re-writer Mapper. Since v3.10.0.
not-found.behavior = redirect-to-login || respond-with-404 Defines the default behavior for 404’ing requests. Defaults to respond-with-404. (Since v1.9.4)
not-found.exclusion-path-patterns = [ /content/foo/.* ] Defines a list of path patterns (Regex) should respond using the opposite method to not-found-behavior. Example. If not-found-behavior=respond-with-404, anonymous requests sent to /content/site/profile/.* can be sent to the login page, instead of responding with the usual 404. (Since v.1.9.4)
cache.serve-authenticated true allows authenticated requests to service the the in-memory cache. If your error pages do not contain any server-side personalization, this should be set to true to maximize cache effectiveness. (Since v1.5.0)
cache.ttl TTL in seconds for the in-memory Error Page Handler cache; Defaults to 300 seconds (5 mins). (Since v1.5.0)
error-page.system-path is the absolute path to system Error page resource to serve if no other more appropriate error pages can be found. It does not include an extension.
error-page.fallback-name defines the error page name (not path) to use if a valid Error Code/Error Servlet Name cannot be retrieved from the Request. Defaults to 500
error-page.extension defines the extension to call the fallback error page with; This is almost ALWAYS “html” unless the application is using non-standard extensions.
paths define a list of valid inclusive content trees under which error pages may reside, along with the name of the default error page for the content tree. This is a fallback/less powerful option for adding the ./errorPagesproperty to CQ Page property dialogs. Examples:
[/content/geometrixx/en:errors,/content/geometrixx/fr:/content/geometrixx/fr/erruers/ ]
error-images.enabled boolean value; true to enable, false to disable. Defaults to false. (Since version 1.7.0)
error-images.path is a <selectors.extension> (ex. .img.png) absolute path to a nt:file image, or relative path to an image component resource.
enabled true/false to toggle the Error Page Handler on and off
vanity.dispatch.enabled true/false to toggle using the ACS Commons Vanity Path Re-writer Mapper. Since v3.10.0.
not-found.behavior = redirect-to-login || respond-with-404 Defines the default behavior for 404’ing requests. Defaults to respond-with-404. (Since v1.9.4)
not-found.exclusion-path-patterns = [ /content/foo/.* ] Defines a list of path patterns (Regex) should respond using the opposite method to not-found-behavior. Example. If not-found-behavior=respond-with-404, anonymous requests sent to /content/site/profile/.* can be sent to the login page, instead of responding with the usual 404. (Since v.1.9.4)
cache.serve-authenticated true allows authenticated requests to service the the in-memory cache. If your error pages do not contain any server-side personalization, this should be set to true to maximize cache effectiveness. (Since v1.5.0)
cache.ttl TTL in seconds for the in-memory Error Page Handler cache; Defaults to 300 seconds (5 mins). (Since v1.5.0)
error-page.system-path is the absolute path to system Error page resource to serve if no other more appropriate error pages can be found. It does not include an extension.
error-page.fallback-name defines the error page name (not path) to use if a valid Error Code/Error Servlet Name cannot be retrieved from the Request. Defaults to 500
error-page.extension defines the extension to call the fallback error page with; This is almost ALWAYS “html” unless the application is using non-standard extensions.
paths define a list of valid inclusive content trees under which error pages may reside, along with the name of the default error page for the content tree. This is a fallback/less powerful option for adding the ./errorPagesproperty to CQ Page property dialogs. Examples:
[/content/geometrixx/en:errors,/content/geometrixx/fr:/content/geometrixx/fr/erruers/ ]
error-images.enabled boolean value; true to enable, false to disable. Defaults to false. (Since version 1.7.0)
error-images.path is a <selectors.extension> (ex. .img.png) absolute path to a nt:file image, or relative path to an image component resource.
If an extension or relative path, this value is applied to the resolved error page. (ex. if error-image.path is ‘jcr:content/image.img.png’ and the resolve error path is ‘/content/acme/error’ then ‘/content/acme/error/jcr:content/image.img.png’ will be used to render the image.). Defaults to ‘.img.png’ which will render the error page’s Page image. (Since version 1.7.0)
Note: It is better to use the Page Properties-defined errorPages than the paths in the OSGi Configuration. Typically paths is left blank.
Note: It is better to use the Page Properties-defined errorPages than the paths in the OSGi Configuration. Typically paths is left blank.
Internationalization on Error Pages
If your error pages require the I18N bundle, you must extend the I18NFilter configuration to include it in the ERROR-scoped filter chain.
Create an nt:file node to configure the Sling I18N Filter
/apps/sling/config/org.apache.sling.i18n.impl.I18NFilter.config service.ranking=I"-10000"
If your error pages require the I18N bundle, you must extend the I18NFilter configuration to include it in the ERROR-scoped filter chain.
Create an nt:file node to configure the Sling I18N Filter
/apps/sling/config/org.apache.sling.i18n.impl.I18NFilter.config service.ranking=I"-10000"
sling.filter.scope=["REQUEST","ERROR"]
Note: You must use a .config file because the service.ranking must be of type integer, which cannot be set on a sling:OsgiConfig node.
Note: You must use a .config file because the service.ranking must be of type integer, which cannot be set on a sling:OsgiConfig node.
Service User
On AEM 6.2 or above, this service uses a Service User for repository access. This user is configured with the expected permissions required, but additional permissions may be required if your repository design deviates from the expected structure.
User name: acs-commons-error-page-handler-service
ACLs:
jcr:read on /content
Source: https://adobe-consulting-services.github.io/acs-aem-commons/features/error-handler/index.html
On AEM 6.2 or above, this service uses a Service User for repository access. This user is configured with the expected permissions required, but additional permissions may be required if your repository design deviates from the expected structure.
User name: acs-commons-error-page-handler-service
ACLs:
jcr:read on /content
Source: https://adobe-consulting-services.github.io/acs-aem-commons/features/error-handler/index.html
No comments:
Post a Comment
If you have any doubts or questions, please let us know.