CODEWITHSUNDEEP
sapui5sap-fioriwidescreen
Mike
Mike

Reputation: 14624

How to disable or enable letterboxing and adjust UI5 for the widescreen?

I have an UI5-based app (1.66+), which works correctly, but there are huge empty spaces on the left and right sides of the screen (aka letterboxing is on):

Widescreen SAPUI5 app

I want to disable letterboxing to use the entire screen space.

I tried the following approaches so far:

  1. To use "fullWidth": true in sap.ui section of manifest.json
  2. To add desktop-related classes to the HTML-tag in index.html:
<html class="sap-desktop sapUiMedia-Std-Desktop sapUiMedia-StdExt-LargeDesktop">
  1. To add appWidthLimited: false to index.html:
<script>
    sap.ui.getCore().attachInit(function () {
        new sap.m.Shell({
            app: new sap.ui.core.ComponentContainer({
                height: "100%",
                name: "APPNAME"
            }),
            appWidthLimited: false
        }).placeAt("content");
    });
</script>

Just like it is described in «How to customise Shell container in SAPUI5».

But none of them works for me.

Update:
I succeeded to solve the issue via a static XML-template — just add <Shell id="shell" appWidthLimited="false"> to the main XML-template, but now I want to understand how to implement it via JS in new sap.m.Shell(…) definition.

The starting point for code experiments is below.

index.html:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>widescreen</title>
        <script id="sap-ui-bootstrap"
            src="../../resources/sap-ui-core.js"
            data-sap-ui-theme="sap_fiori_3"
            data-sap-ui-resourceroots='{"letterboxing.widescreen": "./"}'
            data-sap-ui-compatVersion="edge"
            data-sap-ui-oninit="module:sap/ui/core/ComponentSupport"
            data-sap-ui-async="true"
            data-sap-ui-frameOptions="trusted">
        </script>
    </head>
    <body class="sapUiBody">
        <div data-sap-ui-component data-name="letterboxing.widescreen" data-id="container" data-settings='{"id" : "widescreen"}' id="content"></div>
    </body>
</html>

Component.js:

sap.ui.define([
    "sap/ui/core/UIComponent",
    "sap/ui/Device",
    "letterboxing/widescreen/model/models"
], function (UIComponent, Device, models) {
    "use strict";

    return UIComponent.extend("letterboxing.widescreen.Component", {

        metadata: {
            manifest: "json"
        },

        init: function () {
            // call the base component's init function
            UIComponent.prototype.init.apply(this, arguments);

            // enable routing
            this.getRouter().initialize();

            // set the device model
            this.setModel(models.createDeviceModel(), "device");
        }
    });
});

Upvotes: 9

Views: 7321

Answers (6)

Amanuel Abate
Amanuel Abate

Reputation: 1

Not only the appWidthLimited: false setting on the sap.m.Shell, but also "fullWidth": true in sap.ui section of manifest.json as well.

That is how it works for me! The two settenings together, not just the one! :)

Upvotes: 0

Boghyon Hoffmann
Boghyon Hoffmann

Reputation: 18084

Ok, so there seems to be many similar questions regarding how to disable/enable letterboxing. This answer should provide a solution for each case:

Standalone Apps

Look for the instantiation of sap.m.Shell in your project and configure its appWidthLimited property accordingly.

For example:

SAP Web IDE searching in project

In index.html or in a module assigned to data-sap-ui-on-init

sap.ui.require([
  "sap/m/Shell",
  "sap/ui/core/ComponentContainer",
], (Shell, ComponentContainer) => new Shell({
  appWidthLimited: false|true, // <-- default: true
  // ...
}).placeAt("content"));

In root view

<Shell xmlns="sap.m" appWidthLimited="false|true">
  <App>
    <!-- ... -->

Of course, the Shell can be configured dynamically in JS too with myShell.setAppWidthLimited.

Note: if the letterboxing is not required, consider removing sap.m.Shell entirely. There is no real purpose of sap.m.Shell if the application always runs with full width or embedded in FLP.

API reference: sap.m.Shell
UX guideline: Letterboxing

Apps on SAP Fiori launchpad (FLP)

The app or component …:

  • should not contain sap.m.Shell anywhere (please check the root view).
  • launches from the FLP instead (no index.html).

Statically in manifest.json

"sap.ui": {
  "fullWidth": true|false

Documentation: Descriptor for Applications, Components, and Libraries

Dynamically at runtime

// AppConfiguration required from "sap/ushell/services/AppConfiguration"
AppConfiguration.setApplicationFullWidth(true|false); //*

According to SAP Fiori design guidelines, switching the letterbox state during runtime is allowed:

Letterboxing can be switched on or off [...] for individual pages within an application. [...]

In some cases, applications may need to have the flexibility to change the width at runtime for different views. [...] Apps can change the width in the AppConfiguration service at runtime for different views.

* The API setApplicationFullWidth, however, is deprecated since UI5 1.120. If you really need switching the letterbox state during the application runtime, please create a new customer ticket at https://me.sap.com/getsupport with the component CA-FLP-FE-UI.

API reference: sap.ushell.services.AppConfiguration
UX guideline: Letterboxing

⚡ Limitations

Currently, the static fullWidth setting has no effect in:

  • FLP on Cloud Foundry in BTP (Deployed apps running in an iframe). SAP is still looking into it.
     → ✅ FIXED since SAPUI5 1.120 (somewhere around 1.120.7)
  • Apps generated via SAP Fiori elements — by design.

Upvotes: 15

daniel kullmann
daniel kullmann

Reputation: 14023

For some reason, AppConfiguration.setApplicationFullWidth(true); does not work for me. I don't have a valid application container.

I solved the problem in this, admittedly hacky, way: In my app controller, I added this implementation of the onAfterRendering method:

onAfterRendering: function () {
    var oElement = this.getView().byId("idAppControl").$();
    while (oElement && oElement.hasClass) {
        if (oElement.hasClass("sapUShellApplicationContainerLimitedWidth")) {
            oElement.removeClass("sapUShellApplicationContainerLimitedWidth");
            break;
        }
        oElement = oElement.parent();
    }
}

Upvotes: 0

Mike
Mike

Reputation: 14624

Static implementation via XML-template:

<mvc:View controllerName="letterboxing.widescreen.controller.index" xmlns:mvc="sap.ui.core.mvc" displayBlock="true" xmlns="sap.m">
    <Shell id="shell" appWidthLimited="false">
        <App id="app">
            <pages>
                <Page id="page" title="{i18n>title}">
                    <content></content>
                </Page>
            </pages>
        </App>
    </Shell>
</mvc:View>

For dynamic implementation via JS-controller with appWidthLimited: false in sap.m.Shell, see: https://stackoverflow.com/a/55867413

Upvotes: 0

piotr-koca
piotr-koca

Reputation: 94

According to Available OpenUI5 Versions the newest OpenUI5 version is 1.65.0. How is you app based on 1.66.0?

Setting appWidthLimited: false on the sap.m.Shell should do the work. Check out this example (plunker / github) (in the Plunker run preview in a new window)

Upvotes: 1

Geraldo Megale
Geraldo Megale

Reputation: 363

You can achieve that removing the shell control from index.html:

sap.ui.getCore().attachInit(function () {
    sap.ui.require(["sap/ui/core/ComponentContainer"], function (ComponentContainer) {
        new ComponentContainer({
            name: "yourProject",
            async: true,
            manifest: true,
            height: "100%"

        }).placeAt("content");

    });
});

instead of this:

<script>
    sap.ui.getCore().attachInit(function () {
        new sap.m.Shell({
            app: new sap.ui.core.ComponentContainer({
                height: "100%",
                name: "APPNAME"
            }),
            appWidthLimited: false
        })
        .placeAt("content");
    });
</script>

Upvotes: 0

Related Questions