sdi_appstate-ui

This bundle contains the components for the user interface of map.apps SDI app state management.

Usage

App states are saved in the map.apps SDI database on the server, so it is required to install and configure the map.apps SDI savestate backend web application on the application server. You can find detailed installation instructions in the map.apps SDI product documentation.

Configuration Reference

The following sections describe the configurable components and properties.

Tools

Tool ID	Component	Description
`sdi_stateManagementTool`	`StateManagementTool`	Toggles the state management dialog window.

FilteredAppStateStore

If the listOwnSharedAppStates property is true, only the app states for the currently logged-in user are shown in the list.

{
    "sdi_appstate-ui": {
        "FilteredAppStateStore": {
            "listOwnSharedAppStates": false
        }
    }
}

StateController

Property `askBeforeLoading`

The askBeforeLoading property can be used to control whether a confirmation dialog should be shown before an app state is loaded.

The default value is true.

NOTE: When loading an app state from the list in map.apps Manager, a confirmation dialog is never displayed. The app will always open in a new browser tab.

Example

{
    "sdi_appstate-ui": {
        "StateController": {
            "askBeforeLoading": true
        }
    }
}

Configure the width of the app state details dialog window

The detailWindowWidth property can be used to control the width of the state details dialog window. If not specified, a default value is used.

Example:

{
    "sdi_appstate-ui": {
        "StateController": {
            "detailWindowWidth": 800
        }
    }
}

Configure the height of the app state details dialog window

The detailWindowHeights property can be used to control the height of the state details dialog window. The value is an array with five entries. Each entry describes the height (in pixels) of the dialog under a certain condition.

The ordered values apply to the following situations:

When a new state is created and the permission options are hidden.
When an existing state is edited and the permission options are hidden.
When a state is created or edited and the permission options are shown, but without the section for role permissions.
When a state is created or edited and the permission options are shown, including the section for role permissions.
In all other cases.

Example with the default values:

{
    "sdi_appstate-ui": {
        "StateController": {
            "detailWindowHeights": [265, 335, 600, 720, 785]
        }
    }
}

To configure the permission options take a look at the section StateDetailsModelFactory below and how to define the visibilityOptions for the permission matrix.

The StateDetails widget for editing an app state includes a matrix for setting the user permissions on that app state. You can configure the labels of the user roles in that permission matrix, that means how the roles "public", "private", and all other roles that the current user possesses, are denoted.

You can change the labels by overriding the corresponding properties in the internationalization (i18n) files of the sdi_appstate-ui bundle.

For that add i18n to your app.json at first:

{
    "properties": {
      ...
    },
    "load": {
        "i18n": [
        " bundle"
        ],
        "allowedBundles":
          [...]
    }
}

After that create or change bundle.js files to override the labels and and take a look at the example below.

Hint: You can create/edit new files like /nls/bundle.js also in the map.apps manager.

The following example from a custom /nls/bundle.js file demonstrates the configuration of new labels for the special roles _public_ and _private_, as well as for the roleXY.

define([], function () {
    return {
        "sdi_appstate-ui": {
            "stateDetails": {
                "permissions": {
                    "roleAlias": {
                        "_public_": "Owner",
                        "_private_": "Everyone",
                        "roleXY": "Role YZ"
                    },
                    "ariaLabels": {
                        "viewCheckbox": "${role} may view",
                        "editCheckbox": "${role} may edit"
                    }
                }
            }
        },de: true
    };
});

The following example from a custom /nls/de/bundle.js file demonstrates the configuration of new labels for the special roles _public_ and _private_, as well as for the roleXY for German language.

define([], function () {
    return {
        "sdi_appstate-ui": {
            "stateDetails": {
                "permissions": {
                    "roleAlias": {
                        "_public_": "Besitzer",
                        "_private_": "Alle",
                        "roleXY": "Rolle YZ"
                    },
                    "ariaLabels": {
                        "viewCheckbox": "${role} darf lesen",
                        "editCheckbox": "${role} darf editieren"
                    }
                }
            }
        }
    };
});

As you can see in the example, you can also modify 'aria-labels'. These define what a screen reader will read when the user tabs over the view and edit checkboxes.

Follow the documention in map.apps to learn more about i18n.

StateDetailsModelFactory

Define visible portions of the permission matrix

The visibilityOptions property controls the rows and columns that will be displayed in the permission matrix.

Options must be defined as an array
Each entry in the array defines a portion of the permission matrix to be shown.
The following array entries are supported:
- PUBLIC: The row "Everyone".
- PRIVATE: The row "Owner".
- ROLES: The section for the individual user roles.
- VIEW: The "view" column.
- EDIT: The "edit" column.
- *: Wildcard to show all available portions of the permission matrix.
Ensure that at least one of VIEW or EDIT is included, otherwise the permission matrix is empty
Default value is [*] to show all available portions.

Example

The following configuration will show only the "view" column for the "Everyone" and "Owner" rows in the permission matrix.

{
    "sdi_appstate-ui": {
        "StateDetailsModelFactory": {
            "visibilityOptions": [
                "PUBLIC",
                "PRIVATE",
                "VIEW"
            ]
        }
    }
}

This results in the following permission matrix:

isibilityOptions example

Define the roles shown in the permission matrix

The allowedRoles property controls the user roles that a state can be shared with.

The property value must be an array
The array entries are the roles that should be visible in the permission matrix, or the wildcard * to show all available roles.
Default value is [*], to show all available roles.

Control the visibility of the checkbox for updating app state data

The enableUpdateMapChanges property controls whether users could update the app state data when edit an app state.

The property must be a boolean
Default value is true, so users can edit the data of an app state.

{
    "sdi_appstate-ui": {
        "StateDetailsModelFactory": {
            "visibilityOptions": [
                "PUBLIC",
                "PRIVATE",
                "ROLES",
                "VIEW",
                "EDIT"
            ],
            "allowedRoles": [
                "role1",
                "role2"
            ],
            "enableUpdateMapChanges": true
        }
    }
}