Skip to main content

Delivering Mobile Apps

 

OutSystems

Customize the Unhandled Errors Screen

Whenever an unhandled error occurs in an OutSystems mobile application the user is redirected to a default error screen, like the one shown below.

unhandled-error-screen.png

Although a developer should ensure that all exceptions are being properly handled, there could be some unpredicted scenarios where an error is thrown. In those cases, you might want to customize the error screen to match the overall look and feel of the application.

The error screen can be customized via a JSON that is configured in the Extensibility Configurations property available in mobile modules. The Extensibility Configurations allows you to define which error messages should be shown to the user, what label should the reload button have, or what should be the CSS style applied to the error screen.

Here is an example of an Extensibility Configuration that customizes the error screen:

{
  "clientRuntime": {
    "errorPage": {
      "messages": {
        "defaultMessage": "Oops... An unexpected error occurred. :(",
        "screenNotFound": "The screen you're trying to access does not exist.",
        "noDefaultScreen": "There is no home screen defined in the application.",
        "appOffline": "The application is currently offline. Try again later.",
        "incompatibleProducer": "A producer is not compatible with this module."
      },
      "extraMessage": "If you have any questions, try contacting our services at 808 000 888.",
      "reloadLabel": "GO TO HOME SCREEN",
      "css": "body { background-color: red; }"
    }
  }
}

Error Page Customization JSON Properties

The error screen is customized by a JSON object defined in the Extensibility Configurations. The following table explains the purpose of all properties supported by the error screen customization JSON. Note that each property accepts a string as its value.

Property Purpose
clientRuntime.errorPage.messages.defaultMessage The message that is displayed to the user when a generic error occurs.
clientRuntime.errorPage.messages.screenNotFound The message displayed when the user navigates to an inexistent screen.
clientRuntime.errorPage.messages.noDefaultScreen The message displayed when no default screen was configured in the application.
clientRuntime.errorPage.messages.appOffline Error message shown when the server is offline.
clientRuntime.errorPage.messages.incompatibleProducer Message shown when the application uses an outdated and incompatible producer module.
clientRuntime.errorPage.extraMessage An extra message that is always displayed when any of the aforementioned errors occur.
clientRuntime.errorPage.reloadLabel Text displayed by the button used to reload the application.
clientRuntime.errorPage.css CSS rules to be included in the error page. When this field is defined, the default error stylesheet is not included in the error page.

Error Page CSS Customization

The error page has a set of fixed HTML elements. The HTML structure of the error page is shown in the image above. To customize the look of the error screen, you can use these identifiers and classes:

CSS Identifier/Class HTML Element Inline CSS Purpose
#error-screen-wrapper div   Container that wraps the whole error screen HTML body.
#error-screen-message-wrapper div   Container that wraps user-visible content (error message, extra details, reload button).
#error-screen-message-text div   Main error message. It shows one of the messages defined in the configuration JSON detailed above, based on the nature of the error.
.error-screen-button button   Class used by the two buttons present on the error screen (reload and show details).
#error-screen-message-reload-button button display: inline Reload button displaying the text defined in the customization JSON. Clicking this button changes its inline style to “display: none” and the spinner’s to “display: inline-block”.
#error-screen-spinner div display: none Container for the loading animation that plays after clicking reload (by default, it is a spinner animation).
#error-screen-message-text-extra div   The extra message defined in the JSON is displayed in this container.
#exception-detail div display: none Wrapper for the exception message and stack trace. It is only shown when the “Remote Stack Display” option is enabled in Service Center.
#error-screen-show-detail-button button   Button used to show/hide the stack trace.
#exception-detail-text div hidden Wrapper for the exception message and stack trace.
#error-screen-exception-message div   Exception message.
#error-screen-exception-stack pre   Stack trace.

Custom CSS Example

error-screen-example-1.png error-screen-example-2.png

With the provided options for CSS customization, you can create apps whose error screens match the graphical design of other screens. An example of an error screen with a customized style is displayed in the two images above. The corresponding CSS is included below. You should minify the CSS before including it in the extensibility configurations JSON to reduce it to a single line.

Images used in the error page should be included in the CSS and base64 encoded.

body {
        background-color: #00465e;
}
#error-screen-wrapper {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
}
#error-screen-message-text:before {
    content:
    url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAAyCAYAAAAeP4i
    xAAAABGdBTUEAALGPC/xhBQAAAAlwSFlzAAAuIQAALiEBB1v8/wAAABl0RVh0U29mdHdhc
    mUAcGFpbnQubmV0IDQuMC4xNzNun2MAAASYSURBVGhDzZrbixNXHMfjW60vLbR0c2Z213q
    tJucksl6WWlEEFaoPQv+BolDvUur/oGBBHwSLolYFqa6IoCKC+tJWXC9QWh+VKquru5lJs
    tsouzWN098ve466yW8u52Q2yRe+sMm5/T4z5/KbzCbikJdITMt3ZlIFO7Mzb4kTeSZu5xk
    fdBh/DZ89tIt/M/4c3A+ff3YtsTtvc45tZTetk5NMf+Fa/EcI7rEKWNfQfiDP0gfwQshum
    6fhZGq5a4urcFXfUMGZ2rHE9VxHeqUcZupUSPZ0wdW/QAURr/mloS4+Sw4bn3Aeu0mxGQb
    5p37QqTFMuVewxrbHtoYG7N7pcBdOU4M1w47F+158JmbIcMw00sU/hivzOzVAU83E3ecd2
    U9lWHpCCOjgPtlxCwzT7IE2jNe98oO2uBM1hrPortY0A/pTVEft4ILFz0XaAFyW3kR10E6
    GC71Dhksrz1KdsC5GqcbtZf5quDM1W4ZdL4A4TzdsR/PLMuzJgsXdCykH0SDcpU07vZEVG
    8iyIBeXrfNKm3eRZVHsWJlVMvx3ApDLVOUwl7773vPKZa/yYkgLBiEqA88877+yV9q2h6w
    TasZvyvAnlLOyc00SQAWhFBWm2CshlAxhcAYNWWkhMXCn4vuoikGuhVAKg6mDUKrC/EC2C
    TQTByUGgohHZCUf+0Eo+cH4QighzFZNGMafVc8V2JPnkxV8PLJ6YyCEUi1MKIQSwIyu/Wb
    SmGHOMbEokbcyW6jCII8dOiJHDZaCiQwBGjt8nBwzyPjYjNPqCFUYZh2YytOpg0DDGj8N2
    674lSqM4qgwUWQKgQaG+3h+PKEKozoOmLGfzCHQwJBDkJdUoY4bgWkUAg13pJJwYvolxAQ
    mDghlXCOx/aQzfvKMDDFc42f6yD5MHcvUQutssaiJrXk92ZeugaHS8GJH60IoxQUjF7v59
    os2hVCqzQBMXN1+4Xg3OhDRjUIoNQzD+CnYtdLaKQr67fNETGoExk1CigJ3ZB5VGGQdCNx
    iddIZE5hhlsnKNJ4/pCpQLi5ZowWh2mnBLP960piBVmk8Cj7sJSsRLsxb5pXv3JPD+os67
    KLAlP/40yss+LKura+ZOFCFQI3Yi+boHIxhMEEJYBCMLkQ1ZptziTEhfCdBVfZzFaa/HiZ
    KFkvBaN8JMIDckOG/k2tnlkIB2cDPtTA6qfj7MCYQ6Jydpd9uwQl5jmoQZAVj8jyBMKYQE
    OslGXa9oNCGSto/mRZm9ZDfR3Fh9mLy+yBDnC+LXeJzGTYt2Iq/pRq3kx0mtslwgwXPKCe
    pDtrBbpKfjfxe8XF3N77o+Y3qqJV2GL8zmOz5UIYZTcXuzEdwUN6jOmyFXZb+CyA+keHpa
    QKmsTQ/FjPebwyhhNMMOmvZmoEp/ov2dApSEXczxpv5NqvkWJktsf3DwPuqvpqzRJ9OXqZ
    rmV1chGk9Uw47dYLb3esycSVOIOwL+r1W6BRfyWGap1F4KMN3K+C/qeAi+glA7Hc7sgtlt
    62V25FaACfuVtcWRyGwW/jAA3dtXAUMf/8L3w1CnduQaR+DM2E7/o9WPGsgkfgfuIXTKdr
    F2vwAAAAASUVORK5CYII=');
    display: block;
    margin-bottom: 15px;
}
#error-screen-message-wrapper {
    position: absolute;
    top: 100px;
    height: 150px !important;
    width: 80%;
    right: 10%;
    text-align: center;
}
#error-screen-wrapper {
    font-family: Open Sans, Helvetica, Arial, sans-serif;
    font-size: 18px;
    font-weight: normal;
    color: white;
}
.error-screen-button {
    margin-top: 2em;
    margin-bottom: 2em;
    color: #5DBDE6;
    border: 0px;
    font-size: 18px;
    border: none;
    background-color: transparent;
}
/*
* Source: https://projects.lukehaas.me/css-loaders/
*/
#error-screen-spinner,
#error-screen-spinner:before,
#error-screen-spinner:after {
    border-radius: 50%;
    width: 2.5em;
    height: 2.5em;
    -webkit-animation-fill-mode: both;
    animation-fill-mode: both;
    -webkit-animation: load 1.8s infinite ease-in-out;
    animation: load 1.8s infinite ease-in-out;
}
#error-screen-spinner {
    color: #ffffff;
    font-size: 10px;
    margin: 80px auto;
    position: relative;
    text-indent: -9999em;
    -webkit-transform: translateZ(0);
    -ms-transform: translateZ(0);
    transform: translateZ(0);
    -webkit-animation-delay: -0.16s;
    animation-delay: -0.16s;
}
#error-screen-spinner:before,
#error-screen-spinner:after {
    content: '';
    position: absolute;
    top: 0;
}
#error-screen-spinner:before {
    left: -3.5em;
    -webkit-animation-delay: -0.32s;
    animation-delay: -0.32s;
}
#error-screen-spinner:after {
    left: 3.5em;
}
@-webkit-keyframes load {
    0%,
    80%,
    100% {
        box-shadow: 0 2.5em 0 -1.3em;
    }
    40% {
        box-shadow: 0 2.5em 0 0;
    }
}
@keyframes load {
    0%,
    80%,
    100% {
        box-shadow: 0 2.5em 0 -1.3em;
    }
    40% {
        box-shadow: 0 2.5em 0 0;
    }
}
  • Was this article helpful?