The planning calendar allows users to see different appointments at the same time and to create new appointments. It allows the user to display appointments for several objects, such as a team calendar, and compare them to each other.

Usage

Use the planning calendar if:

• You want to compare objects of the same type with each other over a period of time.
• You require responsive behavior.
• You have less than 100 lines in the calendar.

Do not use the planning calendar if:

• You want to show a calendar for one object and a detailed overview of appointments over a long time interval.
• You want to show a complex or graphical representation. In this case, please use the Gantt chart.
• You have more than 100 lines in the calendar. In this case, please use the Gantt chart.

Responsiveness

Types

You can define what size of interval the calendar should show, and whether multi selection should be possible. Additionally, the row header and the interval appointments are optional.

Components

This section describes the various components of the planning calendar.

1. Toolbar

The toolbar is optional and can contain a title as well as app-specific and generic actions.
If you have actions in the toolbar, we recommend that you use a title to describe the purpose of the planning calendar. For more information, check out the toolbar guideline article.

The generic actions are as follows:

• Search
• Add Appointment (icon: add)
• Add New Contact (icon: add-contact)
• Multi-Select Mode (icon: multi-select)
• Legend (icon: legend)
• Settings (icon: action-settings)
• Full Screen (icon: full-screen/exit-full-screen)

2. Header

The calendar header comprises the left part, which includes an optional switch to see the calendar in a different view (day, month, year), and the right part, which contains the calendar view.

4. List item

The list item contains the row header, row, appointments, and interval appointments. Each row can show different working and non-working days. This is useful if users want to view calendars from different countries that have different weekends.

5. Row header

This identifies the object for which the appointments are shown. The row header pops in if there is not enough space. It can contain a picture or icon, a title, and a subtitle.

6. Row

All appointments that appear for an object are shown here.

7. Appointment

Appointments enable an icon or picture, a title, and a subtitle to be shown. If appointments appear simultaneously, they are shown under each other.

App developers can define the colors of different appointment types, and appointments can be shown as tentative. Appointments are fully colored.

The control can register the click event, and the app development team must define what happens next.

If the view changes and there are too many small appointments at one time, an aggregation is shown. Aggregations show a number indicating how many appointments are not fully visible in this view. This functionality will be improved in future releases. Otherwise, the click/touch area would be too small.

There are two sizes of appointments – regular and half size. The half-sized appointments can save space, but also note that they do not show a second line for details of the appointment.

8. Interval appointment

Each row can also have interval appointments. These are smaller and always appear at the top of the row. They can be used to show appointments that last for a prolonged period of time, such as vacations or workshops.

Behavior and Interaction

To create an appointment, the user must trigger an action by clicking the Add   icon in the toolbar. Clicking directly on the row also creates a new appointment.

The user can click on the appointment to see further details. The app development team must define what kind of information is then shown. For example, clicking on an appointment can trigger a popover with detailed information.

A multi-select toggle can also be provided in the toolbar. This can be used, for example, to select multiple people in order to delete them from the planning calendar.

Various tooltips can be shown, but you should not use them to show additional information because users cannot access this functionality on touch devices.

Depending on the current time interval, appointments might be smaller and the text might be cut off, not truncated. However, this should not be an issue because the main use case is to see whether there is a free time slot. Additionally, the user can click or tap the appointment to see the details.

In the Months view, appointments may appear as aggregations due to lack of space for detailed visualization. Aggregations show a number indicating how many appointments are not fully visible in this view.

Users have the possibility to turn the alternating row coloring on or off. By default, the alternating rows option is turned on.

Appointments in the calendar have two sizes: regular appointment and half-size appointment. The exact sizes can be found in the visual specification. The app developer can choose the size that fits the use case, but keep in mind that the half-size appointment shows less information about the appointment.

Users also have the option to hide the interval header and the space that is reserved for it. This option can be included as an icon in the toolbar.

Interaction Flow for Switching Days

Guidelines

Switching the Row Header

If you want the end user to be able to rearrange the planning calendar by switching the row header, you can implement a flexible row header. This is not done by the control and should be implemented by the app development team.

The list items in the row header can be a value of any attribute of an appointment. The appointment attributes are part of app-specific content, so they should be specified by the app development team. The control does not provide default attributes.

Our guideline is to use the select control in the place of the calendar title. The select control will contain all the attributes that can serve as the row header. When a different attribute is selected, the calendar is rearranged accordingly. You can also add a counter after the list items to indicate how many appointments fall into a specific group.

It is also possible to have both the calendar title and select control, in which case you should have first the title and then the select.

On small screen sizes, use select instead of the calendar title. If you want to keep the calendar title, place select in the overflow menu.

Resources

A search is a means of accessing information quickly. If an amount of data is too large for users to find something just by scanning through it, you should consider providing a search function.

Usage

Use a search field (sap.m.SearchField) if you want to enable users to enter text to search for information. The search field is also the control of choice for filtering down a given amount of information.

Responsiveness

On tablets (size M) and smartphones (size S), the master list’s search field is not initially visible. It only appears when the user pulls down the list. Its position is not fixed, so it scrolls away. On desktops (size L), the master list’s search field is visible from the start. Its position is fixed and it does not scroll away.

Types

SAP Fiori comes with two different search types.

1. The manual searchis triggered explicitly after the user enters text in the search field and clicks or taps the Search button or presses the Enter key.
2. The live search(also known as “incremental search” or “search-as-you-type”) is triggered by each character that the user enters or deletes.

Queries that are entered are used to search the backend data for term matches (not case-sensitive). While a live search uses a “contains” approach, a manual search uses a “starts with” approach. “Contains” means that the result needs to match the query only partly to be a valid result. “Starts with” means that full terms of the result need to start with the entered query to be visualized.

Layout

The search input field (or search box) consists of two parts:

1. The text input, which is left-aligned. Initially, the field shows a placeholder (Search). As soon as the user enters a character, this prompt text disappears. It appears again if the user deletes the entry.
2. If a manual search is to be implemented, a search button with a magnifier icon is placed on the right side of this input control. The user clicks or taps this button to trigger the search. In live searches, the magnifier icon is also placed here, but it functions more like an additional indicator to signify that this is a search input field. It also functions as an explicit search button if the user wants to search again for a query that has already been entered.

All item attributes defined by the app development team are searched. When the results are displayed, the items found do not necessarily have to show the attribute through which the item was found. The results are displayed in the same list that contained the original item set. Initial grouping and the order of the list are not affected by the search.

When the split screen is used, the search field appears at the top of the master list. In full screen mode, the search field is placed at the top of the page.

Behavior and Interaction

Entering a Search Term

Search terms can be entered easily into the input field. The search box then displays all full-text search terms. There is no line break and no truncation if the query is longer than the input field. Results might also be displayed that do not match the query in their title or subtitle. This might be because details can also be searched for. The user can see the matching terms in the specific details section.

Deleting a Search Term

The user can click or tap the ex ( ) button to remove the text from the field. In the case of the live search, this also resets the search. In a manual search, deleting the search term and then triggering the search resets the search results.

Refreshing

If the Refresh button is available, the user can update the list without triggering a new search. This is usually needed when backend data changes quickly and often.

If the currently selected item is no longer available after the list has been refreshed, the next item in the line is selected. If no next item is available, the first item in the line should be selected next.

On touch devices, the Refresh icon is not visible in the search field. In this case, Pull Down to Refresh is used instead. The Pull Down to Refresh arrow icon is animated and spins to signal that the user should release it.

Properties

The following methods are important.

For the live search:

• attachLiveChange(oData?, fnFunction, oListener?) Attach event handler fnFunction to the ‘liveChange’ event of this sap.m.SearchField.
• detachLiveChange(fnFunction, oListener) Detach event handler fnFunction from the ‘liveChange’ event of this sap.m.SearchField.
• fireLiveChange(mArguments?) Fire event liveChange to attached listeners.

For the manual search:

• attachSearch(oData?, fnFunction, oListener?) Attach event handler fnFunction to the ‘search’ event of this sap.m.SearchField.
• detachSearch(fnFunction, oListener) Detach event handler fnFunction from the ‘search’ event of this sap.m.SearchField.
• fireSearch(mArguments?) Fire event search to attached listeners.

If a Refresh button is needed:

• getShowRefreshButton() Getter for property showRefreshButton.
• setShowRefreshButton(bShowRefreshButton) Setter for property showRefreshButton.

To show the Search button:

• getShowSearchButton() Getter for property showSearchButton.
• setShowSearchButton(bShowSearchButton) Setter for property showSearchButton.

To ensure the focus is set to input:

• setSelectOnFocus(bSelectOnFocus) Setter for property selectOnFocus.

Guidelines

• Implement the live search whenever possible.
• Use a manual search only if the amount of data is too large and if your app would otherwise run into performance issues.
• Show an appropriate prompt text:Search if queries are sent to all connected services, or Search In: if the search is limited to a certain source or providing service.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

A multi-input field allows the user to enter multiple values, which are displayed as tokens. These can be displayed in single and multiline mode. To help the user enter a valid value, you can enable the autocomplete suggestions feature and the value help option.

Usage

Use the multi-input field if:

• You want the user to select multiple ranges (with the value help option and the value help dialog).
• The dataset to choose from is expected to increase over time (for example, to more than 200 values).
• You need to provide the value help option to help users select or search multiple business objects.

Do not use the multi-input field if:

• You want the user to select one entry only. In this case, use the input field or combo box instead.
• You want the user to select from a pre-defined set of options only. In this case, use the multi-combo box instead.

Responsiveness

In the examples below, the autocomplete feature is shown in different sizes for single and multiline modes.

Single Line Mode (Default)

Size S (Smartphones)

• Cozy mode.
• When the user taps the multi-input field, a new full-screen dialog opens in which the autocomplete suggestions can be selected. When the user makes a selection, the dialog closes and the token is displayed.
• The user can review the tokens by swiping them to the left or right.

Size M (Tablets)

• Cozy mode.
• The user can review tokens by swiping them to the left or right.
• The autocomplete suggestions appear below or above the multi-input field.

Size L (Desktops)

• Compact mode.
• The user can review tokens by pressing the right or left arrows on the keyboard.
• The autocomplete suggestions appear below or above the multi-input field.

Types

The input types of the multi-input are identical to those of the input field. For more information, see input field.

Behavior and Interaction

Single Line Mode

Adding a Token

Reviewing Tokens

Deleting Tokens

The user can delete tokens by pressing the Backspace or Del button (when selected) on a desktop’s keyboard, or by tapping the Delete icon on a mobile device.

Using Value Help

Multiline Mode

Single line mode is active by default, so to activate multiline mode, you need to enable it (property: enableMultiLineMode).

Adding a Token

The user can add a token via autocomplete suggestions or value help. The token is created by selecting an item from the autocomplete box. The input is ready for the next entry. Tokens are placed next to each other. If there is not enough space on one line, the control expands.

Reviewing Tokens

When the multi-input field is not focused, it is shown in collapsed mode. The token that was entered last is displayed. If there is more than one token, the number of hidden tokens is shown next to the last token.

When tokens are entered into the multi-input field, the control expands to show all tokens. On screen size S, a new dialog is opened to review the tokens.

Copying and Pasting Data from a Spreadsheet or Text File

The multi-input control can handle paste actions containing, for example, multiple items that have been selected in a column of a spreadsheet or text file. The user simply selects a whole column in the spreadsheet and copies it. When items are entered into the multi-input field, the user just pastes them from the clipboard and each item is represented as a token.

Guidelines

• Use the multiline mode instead of the single line mode (default). This provides greater flexibility for displaying multiple tokens.
• Give the control a width that is appropriate for the range of values that are going to be entered. Try to avoid setting a fixed width on this control. Instead, embed it in a proper layout (such as a form, simple form, or grid layout) and work with the layout data property.
• Provide meaningful labels for all input fields. Do not use the placeholder as a replacement for the label. The placeholder should only provide an additional hint.
• The multi-input field can currently contain tokens and one free text value. If you allow only validated values, display an error or warning when the user tries to leave the field to indicate that the value entered is invalid, or remove the value.

Properties

Since the multi-input field is derived from the input field, refer to the properties in the input field article.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

The calendar date interval displays a range of days in a single row. The control allows the user to select a single day, multiple days, or a range of days. Content corresponding to the date selection is usually displayed below the control. The user can navigate the date intervals by browsing through them (using the previous and next arrows), or by going directly to a specific month or year.

Compared to the regular date range selection control, this control offers a flexible date range and consumes very little horizontal space.

Responsiveness

Layout

The date interval control is divided into two main areas: date interval navigation, and date interval display and selection.

Behavior and Interaction

The behavior and interaction of the calendar date interval control can be divided into two parts: navigation and selection.

Navigation

Previous/Next

The user clicks or taps the previous or next arrow to replace the currently displayed date interval with the previous or next date, respectively. Previous and next navigation can be used while the user is in selection mode, as well as in month or year navigation mode.

Selection

The calendar date interval control can be set up for single day selection, multiple day selection, or day range selection.

The date picker lets users select a localized date using touch, mouse, or keyboard input. It consists of two parts: the date input field and the date picker.

Use this control if the user needs to enter a single date or a date range. The control also allows users to navigate directly from one month or year to another.

Usage

Responsiveness

The date picker provides responsive behavior that allows for simple operation on all devices. It is smaller in compact mode and provides a touch-friendly size in cozy mode.

With one click on the input field, the date picker opens in full screen. To close the window, the user can select a date (which triggers the close event), or click Cancel without selecting a date.

Components

Date Input Field

In the input field, the user can enter a date directly or select it using the date picker. The system validates the entry and provides the user with feedback. You can also show placeholder text in the field.

Date Picker

With the date picker, the user can see a day view, month view, or year view. The current day and the selected date are highlighted. The calendar week is also visible in the day view. The calendar closes when a final day is selected. The user can click or tap the arrows to navigate to the previous and the next day, month, or year view depending on the current view.

The selected date is shown with a blue background. The current day is indicated with a purple border.

Behavior and Interaction

Selecting a Date

Guidelines

Date Formats

Long Date Format

Use the long date format for master list/object list item/title and object header/title. Here are some examples:

• English (US): January 16, 2022
• German (DE): 16. Januar 2022
• Danish (DK): 16. Jan. 2022

Short Date Format

Use the short date format for master list/object list item/list of object attributes if space is a concern. For example, you might need to save space if there is a label with the date. Here are some examples of the short date format:

• English (US): 1/16/22
• German (DE): 16.01.22
• Japanese (JP): 22/01/16

Relative and Medium Date Format

If appropriate, use a relative format for master list/object list item/list of object status. For example: today, 1 day ago, 2 days ago, and so on up to 6 days ago. After 6 days, use an absolute date with the medium format.

Use the absolute date with medium format in the corresponding object header in the details area. Do not use the relative format here.

Responsive Table

If screen space is at a premium (for example, if there are too many columns), use the short date format in table cells. Otherwise use the medium format.

If you need to display the weekday, use the full format. For example:

• English (US): Sunday, January 16, 2022
• German (DE): Sonntag, 16. Januar 2022
• French (FR): dimanche 16 janvier 2022

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

The control for selecting the date range is a single-field input control. Users can enter a localized date range using touch, mouse, or keyboard input, or by selecting a date range in the calendar. They can also navigate directly from one month or year to another.

Usage

Responsiveness

The date range selection is fully responsive. It is smaller in compact mode and provides a touch-friendly size in cozy mode. For more information about cozy and compact modes, see the article on content density.

Components

Date Range Input Field

Date Range Picker

Behavior and Interaction

Selecting a Date Range

Switch View

Selecting an End Date

Selecting a Range

Entering Single Dates

The date range selection also allows the user to input single dates. The user can type one date into the input field, or select the same day as a start and end date in the calendar.

Styles

Delimiter

The delimiter visualizes the start and end date. If no delimiter is given, the app uses the one defined for the used locale.

Placeholder

If no range is selected, show a placeholder text to indicate the correct format. If no placeholder is defined, the control shows the default locale placeholder format. You can define your own placeholder, but you must also take localized versions into account.

Validation

Use in-line validation to give the user feedback, especially in the form of errors and warnings. Possible warning states are warning, error, and success. The date range input field in question is highlighted by a frame in the corresponding color. If the focus is inside the field, an explanation is shown. Ensure that this explanation is as specific as possible.

Guidelines

Display Format

You can choose whether the displayed texts are to be shown in short, medium, or long format, or in another date format like dd–MM–yyyy. However, other date formats (besides short, medium, and long) should be used carefully due to local dependencies.

Input Types

The following input types are available. (Note: these examples show German date formats for January 14, 2014.)

• Unicode CLDR short format: 14.01.14
• Unicode CLDR medium format: 14.01.2014
• ISO date format: 2014-01-14
• ISO date format without delimiters: 20140114
• Unicode CLDR short format without delimiters: 140114
• Unicode CLDR medium format: 14012014

Date Formats

Long Date Format

Use the long date format for master list/object list item/title and object header/title. Here are some examples:

• English (US): January 16, 2022
• German (DE): 16. Januar 2022
• Danish (DK): 16. Jan. 2022

Short Date Format

Use the short date format for master list/object list item/list of object attributes if space is a concern. For example, you might need to save space if there is a label with the date. Here are some examples of the short date format:

• English (US): 1/16/22
• German (DE): 16.01.22
• Japanese (JP): 22/01/16

Relative and Medium Date Format

If appropriate, use a relative format for master list/object list item/list of object status. For example: today, 1 day ago, 2 days ago, and so on up to 6 days ago. After 6 days, use an absolute date with the medium format.

Use the absolute date with medium format in the corresponding object header in the details area. Do not use the relative format here.

Responsive Table

If screen space is at a premium (for example, if there are too many columns), use the short date format within table cells. Otherwise, use the medium format.

If you need to display the weekday, use the full format. For example:

• English (US): Sunday, January 16, 2022
• German (DE): Sonntag, 16. Januar 2022
• French (FR): dimanche 16 janvier 2022

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

The date/time picker allows users to select date and time values in a combined input.

Usage

Responsiveness

The date/time picker runs on all form factors and fully adapts to all devices.

Behavior and Interaction

Selecting Date and Time Values

Scrolling

Within the date/time input popover, each area can be scrolled individually by dragging and dropping the areas.
On large devices, the user can also use the standard scrolling mechanism.

Guidelines

Date Picker and Time Picker

In general, we recommend separating the date/time picker controls as the time picker supports the mask input function and the date picker allows the user to enter date in different formats. This makes it easier and more convenient for the user to enter the desired values. For additional guidelines and information on the individual controls, see the resources section below.

Default Values

Independently of the chosen control, set the default values of the date/time picker carefully to avoid unnecessary scrolling. It often makes sense to set the default for the time to the full or half hour, setting the minutes to 00 or 30. Sometimes, it may also make sense to use the current time and date.

Formatting Dates and Times

For guidelines and information on the SAPUI5 date formatters, see formatting dates.

Properties

AM and PM are locale-dependent. The locale can be set using the property “localeId”.

You can set the display format (property: displayFormat) to define the format in which the time input field and the time picker dropdown display the time.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

The time picker allows the user to select a localized time. It can be used with touch, mouse, or keyboard input.

Usage

Use the time picker if:

• You want the user to select a time.
• You want the user to select a time range. In this case, one time picker can be used to set the starting time and a second one to set the end time.
• You want the user to select a detailed time duration, such as 1 minute and 30 seconds.

Do not use the time picker if:

• You want the user to select a duration such as 15 minutes, 30 minutes, 1 hour, or 2 hours. In this case, use the select control instead.

Responsiveness

Components

Time Input Field

The time input field allows the user to enter a time directly in the field, or select it using the time picker dropdown. The input is validated and feedback is given to the user.

The time input field can also contain a placeholder (input prompt).

Time Picker Button

When the user clicks or taps the time picker button, the time picker dropdown opens to allow the user to choose a time.

Time Picker Dropdown

In the time picker dropdown, the user can select a time by setting hours, minutes, seconds and AM/PM or a subset of these (with hours and minutes only).

Guidelines

Time Formats

Only let the user select time in seconds if this information is really necessary.

If the user has to set a time that is timezone sensitive, always provide information about the timezone. For example, if you want the user to choose a time on a calendar for a meeting that might also involve people from other timezones, provide information about those timezones. Ideally, you should also display the local time in the other attendees’ timezones so that the user can choose a time that is convenient for everyone.

12-Hour System

In the 12-hour system, the date picker can contain selections for hours, minutes, seconds, and AM/PM.

24-Hour System

In the 24-hour system, the date picker can contain selections for hours, minutes, and seconds. AM/PM is not available in this mode.

For more information, see formatting time.

Resources

The step input control allows the user to change the input values in predefined increments (steps).

Usage

Use the step input if:

• The user needs to adjust amounts, quantities, or other values quickly.
• The user needs to adjust values for a specific step (for example, in a shopping cart).

Do not use the step input if:

• The user needs to enter a static number (for example, postal code, phone number, or ID). In this case, use the regular input field control instead.
• You want to display a value that rarely needs to be adjusted and does not pertain to a particular step. In this case, use the regular input field control instead.
• You want the user to enter dates and times. In this case, use the date picker, date range selection, time picker, or date/time picker instead.

Responsiveness

Components

Behavior and Interaction

Styles

The step input has different styles for its four states: default, warning, error, and success.

Guidelines

Properties

Resources

The planning calendar allows users to see different appointments at the same time and to create new appointments. It allows the user to display appointments for several objects, such as a team calendar, and compare them to each other.

Usage

Use the planning calendar if:

• You want to compare objects of the same type with each other over a period of time.
• You require responsive behavior.
• You have less than 100 lines in the calendar.

Do not use the planning calendar if:

• You want to show a calendar for one object and a detailed overview of appointments over a long time interval.
• You want to show a complex or graphical representation. In this case, please use the Gantt chart.
• You have more than 100 lines in the calendar. In this case, please use the Gantt chart.

Responsiveness

Types

You can define what size of interval the calendar should show, and whether multi selection should be possible. Additionally, the row header and the interval appointments are optional.

Components

This section describes the various components of the planning calendar.

1. Toolbar

The toolbar is optional and can contain a title as well as app-specific and generic actions.
If you have actions in the toolbar, we recommend that you use a title to describe the purpose of the planning calendar. For more information, check out the toolbar guideline article.

The generic actions are as follows:

• Search
• Add Appointment (icon: add)
• Add New Contact (icon: add-contact)
• Multi-sSelect Mode (icon: multi-select)
• Legend (icon: legend)
• Settings (icon: action-settings)
• Full Screen (icon: full-screen/exit-full-screen)

2. Header

The calendar header comprises the left part, which includes an optional switch to see the calendar in a different view (day, month, year), and the right part, which contains the calendar view.

3. Calendar view

The calendar view defines the granularity of the appointments. You can decide what kind of view (Hours, Days, or Months or Week) the appointments display and how many values are shown. There is a default value for the number of values shown. App developers can change this value, but they should then ensure that the app is still responsive.

Week view always displays seven days in one screen. It can be found in the view select as a default view. When applications have this view available, we strongly recommended setting a different number of days displayed in the days view (more or less than seven). Otherwise, the user might be confused as the navigation the two views differs.

The start date is always the beginning of the week. This can be Saturday, Sunday, or Monday, depending on the locale data.

Users can also navigate to the next or previous view, and easily switch to another year, month, or day.

4. List item

The list item contains the row header, row, appointments, and interval appointments. Each row can show different working and non-working days. This is useful if users want to view calendars from different countries that have different weekends.

5. Row header

This identifies the object for which the appointments are shown. The row header pops in if there is not enough space. It can contain a picture or icon, a title, and a subtitle.

6. Row

All appointments that appear for an object are shown here.

7. Appointment

Appointments enable an icon or picture, a title, and a subtitle to be shown. If appointments appear simultaneously, they are shown under each other.

App developers can define the colors of different appointment types, and appointments can be shown as tentative. Appointments are fully colored.

The control can register the click event, and the app development team must define what happens next.

If the view changes and there are too many small appointments at one time, an aggregation is shown. Aggregations show a number indicating how many appointments are not fully visible in this view. This functionality will be improved in future releases. Otherwise, the click/touch area would be too small.

There are two sizes of appointments – regular and half size. The half-sized appointments can save space, but also note that they do not show a second line for details of the appointment.

8. Interval appointment

Each row can also have interval appointments. These are smaller and always appear at the top of the row. They can be used to show appointments that last for a prolonged period of time, such as vacations or workshops.

Behavior and Interaction

To create an appointment, the user must trigger an action by clicking the Add   icon in the toolbar. Clicking directly on the row also created a new appointment.

The user can click on the appointment to see further details. The app development team must define what kind of information is then shown. For example, clicking on an appointment can trigger a popover with detailed information.

A multi-select toggle can also be provided in the toolbar. This can be used, for example, to select multiple people in order to delete them from the planning calendar.

Various tooltips can be shown, but you should not use them to show additional information because users cannot access this functionality on touch devices.

Depending on the current time interval, appointments might be smaller and the text might be cut off, not truncated. However, this should not be an issue because the main use case is to see whether there is a free time slot. Additionally, the user can click or tap the appointment to see the details.

In the month view, appointments may appear as aggregations due to lack of space for detailed visualization. Aggregations show a number indicating how many appointments are not fully visible in this view.

The “alternating rows” functionality gives users the possibility to row coloring on or off. By default, the alternating rows option is turned on.

Appointments in the calendar have two sizes, regular and half appointment. The exact sizes can be found in the visual specification. The app developer can choose the size that fits the use case, but keep in mind that the half-size appointment shows less information about the appointment.

With “hiding the interval header”, the user also has the option to hide the interval header and the space that is reserved for it. This option can be included as an icon in the toolbar.

Interaction Flow for Switching Days

Guidelines

Switching the Row Header

If you want the end user to be able to rearrange the planning calendar by switching the row header, you can implement a flexible row header. This is not done by the control and should be implemented by the app development team.

The list items in the row header can be a value of any attribute of an appointment. The appointment attributes are part of app-specific content, so they should be specified by the app development team. The control does not provide default attributes.

Our guideline is to use the select control in the place of the calendar title. The select control will contain all the attributes that can serve as the row header. When a different attribute is selected, the calendar is rearranged accordingly. You can also add a counter after the list items to indicate how many appointments fall into a specific group.

It is also possible to have both the calendar title and select control, in which case you should have first the title and then the select.

On small screen sizes, use select instead of the calendar title. If you want to keep the calendar title, place select in the overflow menu.

Resources

The rating indicator can be used to rate content or to indicate a rating. It enables users to rate an item on a numeric scale. The most popular scale is 1 (lowest) to 5 (highest).

Responsiveness

The rating indicator runs on all form factors and therefore works on all devices. It is embedded in a container and thus behaves as part of it.

Layout

Context

Use the rating indicator in forms, tables, or in a dialog box.

Popover with Details

In collaborative rating scenarios, the rating indicator shows an average of all ratings. You may show the sum of ratings in brackets behind the rating indicator as a text or link. You may also add a popover that shows the detailed ratings for the average of all ratings.

Behavior and Interaction

Hover

When the user hovers over the rating indicator, a different icon or image is shown (property: iconHovered). This is an orange star by default.

Select

If enabled for rating, the rating that the user previously selected is shown. When the user performs a rating, an event is triggered.

Types

Properties

Rating Symbols

You can also specify the URLs for the images or icons that are used as rating symbols (property: iconUnselected). Five star symbols are used by default. Although you can use other images or icons, we generally recommend that you use the star symbol. You can only choose 1 symbol for the unselected and 1 for the hovered state.

Number of Rating Symbols

You can specify the number of rating symbols (property: maxValue). We recommend using a maximum of 7 symbols, although 5 symbols are preferred.

Float Values

Float values can be visualized as a half or full star (property: visualMode).

Size of Rating Symbols

The recommended sizes of the image or icon to be displayed are:

• Small: 1 rem (16 px)
• Medium: 1.375 rem (22 px) – default
• Large: 2 rem (32 px)

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

A text input field allows users to enter and edit text or numeric values in one line. To help users enter a valid value, you can enable the autocomplete suggestion feature and the value help option.

Usage

Use the input field if:

• The user needs to enter a short, single-line text or number.
• The user needs to enter a password, URL, phone number, or email address.
• The user needs to make a single selection from a large amount of data (for example, more than 200 items).
• The user needs to find an object by searching for more than one attribute, such as an ID, city, and customer name. Use this control in combination with the autocomplete suggestion feature and value help option. For a small set of values (for example, fewer than 20 items), consider using the select control. Otherwise, use the combo box (for 20–200 items).

Do not use the input field if:

• The user needs to enter dates and times. In this case, use the date picker, date range selection, or date/time picker.
• The user needs to enter long texts. In this case, use the text area.
• The user needs to carry out a search. In this case, use the search field instead.
• The user needs to select multiple values. In this case, use the multi-combo box (for fewer than 200 items) or the multi-input field (for more than 200 items) instead.

Responsiveness

In the examples below, the input field is shown in combination with the tabular autocomplete feature for different device sizes.

Types

Six input types are currently supported (API). Be sure to select the correct type for your use case. Depending on the input type, a different keyboard layout is displayed on a mobile device (see some sample input types).

Note: The control does not provide validation based on the type. The app development team must carry out format validation. If binding is used, validation is carried out by the model, but the error handling still needs to be taken care of on the UI.

Behavior and Interaction

Entering Text Using the Autocomplete Feature

Have a look at the interaction flow below:

Entering Text Using the Value Help Dialog

Have a look at the interaction flow below:

Styles

An input field can have four states: default, warning, error, or success.

Properties

Value State and Value State Message

The input control offers the four value states listed below. For the error and warning states, you can show an additional value state text when the focus is on the input field.

1. None (default): No value state message is shown.
2. Warning
3. Error
4. Success: No value state message is shown.

For more guidance on when to use which state, check out the article on message handling.

Maximum Length

Use this property to set the maximum number of characters allowed. There is no limit by default.

Placeholder

Description

Width

The width of the input field is set to 100% by default. Input fields are usually used in forms, where the width is determined by the form element or container that the input field is embedded in. Therefore, we do not recommend defining a fixed width, but rather working with proper layout containers, like the form, simple form, and responsive grid layout, and with the layout data property, where the width is defined by the 12-column approach.

Editable and Enabled States

Text Alignment

Value Help

The values can also be pasted into the input field by copying and pasting, or dragging and dropping, if the user prefers this. In this case, the values will be automatically transformed into conditional expressions. Example: Copying values “1234” and “5678” leads to the token generation “=1234” and “=5678”. Additionally, these values will be found within the conditions tab of the value help dialog.

Autocomplete Suggestion

The input control offers three different types of autocomplete suggestions: single, two-value, and tabular. The width of the autocomplete and the input fields are set by default, but you can change these via the maxSuggestionWidth property. The position of the suggestion box depends on the space available below the control. If there is not enough space, the suggest box is shown above the control.

Guidelines

Always provide a meaningful label for any input field.

Maximum Length

Limit the length of the input field. For example, if you expect the user to enter a two-digit number, limit the maximum length to two. The maximum permissible character length is not defined by default. If the backend has a limit, ensure that you set this property accordingly.

Placeholder

Avoid using the placeholder attribute as an alternative to a label. This is important because the placeholder text is overwritten as soon as the form is filled out. Labels are necessary to indicate the meaning of the form fields when the placeholders are no longer visible.

Description

The description field should be used, for example, for displaying units or currency. Do not use a description for help text or as a label replacement. Note that the description is not placed in a new line in size S. Therefore, only use the description property for small input fields with a short description.

Width

• Avoid setting a fixed width, but rather embed it in a proper layout (such as a form, simple form, or grid layout) and use the layout data property to define the responsive behavior for sizes S, M, and L:
  • Simple form – See a live example of a simple form and code snippet.
  • Form – See a live example of a form.
  • Grid layout – See a live example of a grid layout and code snippet.
• Ensure an appropriate width for the range of values to be entered for the sizes S, M, and L. Keep in mind that word length can vary between languages, so take localization into account.

Editable and Enabled States

Editable

Property settings: editable = true, enabled = true

The input control is enabled and editable by default. Set the control to editable to allow the user to enter a value.

Not Editable

Property settings: editable = false, enabled = true

Use this state, for example, to display data only.

Disabled

Property settings: editable = not relevant, enabled = false

Set the control to disabled in an edit scenario to indicate that the user cannot change the control, for example, due to missing access rights or previous conditions not having been fulfilled or selected.

Text Align

Align left if:

• Text is used. Also use left alignment for a phone number, URL, password, and email address.

Align right if:

• Amounts and decimal numbers are used.
• Values need to be added and compared.

Value Help

Show the value help option to help the user select the correct value (such as a customer ID) from a large data set via the:

• Value help dialog (complex)
• Select dialog (simple)
• Custom dialog

Use this option in combination with the autocomplete suggestion feature.

When the user clicks or taps the value help icon, the data entered into the input field must be transferred to the processing dialog so that the user does not have to enter the search term again. Likewise, data entered in the processing dialog must be transferred back to the input field.

Autocomplete Suggestion

Use the autocomplete suggestion feature to display real-time suggestions and to help the user enter information more accurately and efficiently. If you expect the suggest values to be longer than the input field itself, you can change the width via the maxSuggestionWidth property.

Single Value with Autocomplete

Use the single-value autocomplete feature if you want to search by only one attribute, such as an ID or a customer name.

Two Values with Autocomplete

Use the two-value autocomplete feature if you want to search by two attributes, such as a customer name and an ID. This ensures that the search is carried out for both attributes.

Tabular Autocomplete

If you need to display more than two attributes, use the tabular autocomplete feature. Try to keep the number of columns to a minimum, and focus on the columns that are really relevant for the use case. Define appropriate responsive behavior for sizes S and M. For more information, see responsive table.

The width of the columns is distributed equally by default. To avoid truncation, accurately estimate the primary attribute length and set a minimum width for this column.

Creating and Editing Objects

Sometimes a new object needs to be created if the user cannot find a specific item via autocomplete or value help. In this case, we recommend that you place the New action next to the input field.

If you want the user to be able to edit a selected object directly, you should place the Edit link next to the input field.

If both actions are needed, they should be toggled based on the content of the input field. If a valid object is selected, you should display Edit. If the input field is empty or the object is not valid, you should display New. This pattern can also be applied for the multi-input field, combo box, multi-combo box, and select controls.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

The rating indicator can be used to rate content or to indicate a rating. It enables users to rate an item on a numeric scale. The most popular scale is 1 (lowest) to 5 (highest).

Responsiveness

The rating indicator runs on all form factors and therefore works on all devices. It is embedded in a container and thus behaves as part of it.

Layout

Context

Use the rating indicator in forms, tables, or in a dialog box.

Behavior and Interaction

Hover

When the user hovers over the rating indicator, a different icon or image is shown (property: iconHovered). This is an orange star by default.

Select

If enabled for rating, the rating that the user previously selected is shown. When the user performs a rating, an event is triggered.

Types

There are two types of rating indicators:

• Interactive – used for rating an item
• Disabled

As the non-interactive state (rating result preview) is not available currently, use the disabled state instead.

Properties

Rating Symbols

You can also specify the URLs for the images or icons that are used as rating symbols (property: iconUnselected). Five star symbols are used by default. Although you can use other images or icons, we generally recommend that you use the star symbol. You can only choose 1 symbol for the unselected and 1 for the hovered state.

Number of Rating Symbols

You can specify the number of rating symbols (property: maxValue). We recommend using a maximum of 7 symbols, although 5 symbols are preferred.

Float Values

Float values can be visualized as a half or full star (property: visualMode). The rating indicator can display a half star only in preview mode (disabled).

Size of Rating Symbols

The recommended sizes of the image or icon to be displayed are:

• Large: 2 rem (32 px)
• Normal: 1.375 rem (22 px) – default
• Small: 1 rem (16 px)
• XS: 0.75rem (12px)

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

A slider is a control that enables the user to adjust single values within a specified numerical range.

Usage

Use the slider to change values with graphical support.

Responsiveness

The slider itself is not responsive. It adjusts to the responsiveness of its parent container by recalculating and resizing the width of the control.

The slider supports the cozy and compact form factors. The compact form factor is used for apps that run on a mouse and keyboard operated device.

Types

Only a horizontal slider is available.

Behavior and Interaction

Changing the Value

• If the slider is editable, the hand cursor appears when the grip is hovered.
• The slider can be changed when the grip is adjusted via drag and drop.
• The grip can be moved with or without increments based on the predefined steps.
• The slider can be changed by clicking or tapping the bar. The grip then moves to this new position.

Slider with Text Fields

The slider can be used with text fields instead of tooltips. In this case, the value of the grip will be displayed.

Slider with Input Fields

The slider can be used with input fields instead of text fields – this allows the user to enter a specific value.

Slider with Tick Marks

You can apply tick marks to the slider. The tick marks are related to the step property. The tick marks are responsive. If the distance between 2 tick marks is less than 8px, all tick marks except for the first and last will disappear.

Styles

The slider can be shown with or without a progress bar. By default, the progress bar is shown.

Examples

Properties

• The step property must be positive. If a negative number is provided, the default value 1 is used instead.
• The minimum, maximum, and value properties can be decimals (float values). The slider automatically sets the minimum value to 0 and maximum value to 100 by default.
• The width of the control can be provided in %, em, px, and all possible CSS units. The slider automatically sets the width of the slider to 100% by default.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

A slider is a control that enables the user to adjust single values within a specified numerical range.

Usage

Use the slider to change values with graphical support.

Responsiveness

The slider itself is not responsive. It adjusts to the responsiveness of its parent container by recalculating and resizing the width of the control.

The slider supports the cozy and compact form factors. The compact form factor is used for apps that run on a mouse and keyboard operated device.

Types

Only a horizontal slider is available.

Behavior and Interaction

Changing the Value

• If the slider is editable, the hand cursor appears when the grip is hovered.
• The slider can be changed when the grip is adjusted via drag and drop.
• The grip can be moved with or without increments based on the predefined steps.
• The slider can be changed by clicking or tapping the bar. The grip then moves to this new position.

Slider with Text Fields

The slider can be used with text fields instead of tooltips. In this case, the value of the grip will be displayed.

Slider with Input Fields

The slider can be used with input fields instead of text fields – this allows the user to enter a specific value.

Styles

The slider can be shown with or without a progress bar. By default, the progress bar is shown.

Examples

Properties

• The step property must be positive. If a negative number is provided, the default value 1 is used instead.
• The minimum, maximum, and value properties can be decimals (float values). The slider automatically sets the minimum value to 0 and maximum value to 100 by default.
• The width of the control can be provided in %, em, px, and all possible CSS units. The slider automatically sets the width of the slider to 100% by default.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

The upload collection control allows users to upload single or multiple files from a device (desktop, tablet, or phone) to the SAP Fiori app. Typically, uploaded files appear in an Attachments tab. However, files can also be displayed elsewhere.

Usage

Use the upload collection control if:

• You want to show a list of uploaded files that can be modified.
• You want to allow users to add or remove files, and to change the file names.
• You are still using the old sap.ca.ui.FileUpload control.

Do not use the upload collection control if:

• The user can upload only one file to the app. In this case, use the sap.ui.unified.FileUploader control instead.

Responsiveness

The upload collection control supports small, medium, and large containers.

Layout

The toolbar at the top of the upload collection control contains an Attachments header with a counter on the left, and an Add button ( ) for adding new items on the right. You can overwrite both the default text Attachments and the counter (property: numberOfAttachmentsText).

Files are listed vertically. Each item has a Rename ( ) and a Remove ( ) button.

While most file types have generic icons (for example documents, spreadsheets, or presentations), image files have a small thumbnail preview.

Attributes and Statuses

You can display additional attributes and statuses below the file name. Attributes can include the name of the person who uploaded the file, the upload date, the version number, file size, and so on.

App developers can also set individual statuses. These statuses usually refer to an object’s state in a workflow (such as Approved or Overdue).

If multiple attributes or statuses are displayed, they are separated by a bullet.

Technical Statuses

In contrast to the statuses mentioned above, technical statuses are not bound to a workflow or business process. Their main use is to show the current editing status of an object (Draft, Locked, Unsaved Changes). For further uses and more details see the object display components and draft handling articles.

Types

The upload collection control offers two different modes: UploadCollection and UploadCollectionForPendingUpload.

The classic upload collection allows users to upload single or multiple files directly to the app, where these files are displayed as a list.

In contrast, the upload collection for pending upload requires the user to first add multiple files to a list (usually presented in a dialog) and then explicitly trigger the upload for the entire list.

When the dialog with the list is confirmed, the user returns to the app screen with the upload collection set to busy until the upload is finished.

Behavior and Interaction

Uploading Files

As long as no files have been added to the upload collection, applications need to show a mock-entry that provides users with a hint on how to upload their files.

The Add button ( ) triggers a native operating system dialog that allows users to select the files they want to upload. You can decide whether the dialogs should allow users to select multiple items, or only one item.

Once the files have been selected and the dialog closes, the uploading progress is shown in the list.

Users can cancel individual uploads by pressing the Remove  button provided on each item.

Depending on the use case, the Add button (  ) can be either disabled or hidden.
If a user cannot upload any files at all, the button should be hidden completely.
If a user is only temporarily unable to upload files (for example, due to the server connection), the button should only be disabled to indicate that this state is temporary.

Opening Files

The user can click or tap the icons or thumbnails in front of the attachment. Opening files is handled differently depending on the operating system.

On a desktop device, clicking the file name or icon of a file opens the respective program that has been assigned to this file type. Mobile devices usually open a dialog in which the user can select an app that supports this file type.

Renaming Files

The rename function works identically on desktop and mobile devices.

The user clicks or taps the Rename (  ) button.

The file name becomes an input field in which the existing name is highlighted. At the same time, the Rename  (  ) and Remove  buttons are replaced by two options: OK and Cancel.

When the user starts typing, the highlighted text is overwritten. Alternatively, the user can use the mouse or keyboard to change the selected text.

There are three ways in which to validate the new file name:

• The user clicks or taps somewhere outside the input field to change the focus.
• The user clicks OK.
• The user presses ENTER.

Editing Files

If users need to edit more than just the name of uploaded files, applications can implement an edit dialog with all the elements that can be changed by the user.

The image shows an example of how to structure such a dialog. The fields depend entirely on the use case and can be freely determined by each application.

Further details about editing parts of an object in a dialog can be found in the article manage objects – parts of an object. If multiple files need to be edited simultaneously, make sure to follow the guidelines for mass editing.

Deleting Files

The delete function works identically on desktop and mobile devices.

As soon as the user clicks or taps the Remove  button on a file, a dialog appears asking the user to confirm the deletion of the respective file.

The file name has to be specified in the dialog. Delete confirms the deletion and the file is removed from the list. Cancel aborts the process, closes the dialog, and brings the user back to the file list without making any changes.

Clickable Attributes

Object attributes can be made clickable. This can be very helpful to provide users with a direct way to access certain information such as a person’s profile, contact data, or the version history of a file.

Examples:

Uploaded By: John Miller

Last Edited By: Donna Moore

Version 1.1

Do not use more than two or three linked attributes per item. Excessive use of clickable attributes will overload the UI with interactive elements and have a negative impact on usability.

Sorting and Filtering

Applications can enable sorting and filtering by placing the respective buttons next to the Add (  ) button. If both functions are provided separately, place Sort (  ) first, followed by Filter (  ). Each button should trigger the respective popover or dialog.

It is also possible to use the view settings dialog to handle both sorting and filtering in the same step. If you do this, use a combined button named Sort and Filter.

If a Filter is Set

Keep in mind to show the info bar if a filter is set. The sorting criteria should not be displayed in the info bar.

Clicking the info bar should bring up…
…the filter dialog if sorting and filtering are provided via separate buttons.
…the view settings dialog if only one Sort and Filter button is used.

Optionally, a button can be provided on the right hand side of the info bar to remove all filters.

Custom and Bulk Actions

App developers can introduce their own actions and apply an action to multiple objects (bulk actions).

Place both custom and bulk actions in the toolbar of the upload collection control. For the order of the actions, apply the same rules as for other toolbars.

If you want to use custom or bulk actions, you must use multiple selection (property: mode = MultiSelect). This mode removes the actions from each item. Instead, offer all necessary actions in the toolbar.

Uploading a New Version

With SAPUI5 version 1.38 and higher, the old version of an upload collection will be automatically replaced when the user uploads a newer version. This change no longer requires the user to delete the old version manually.

To upload a new version, the user needs to select a file and click Upload New Version. This button needs to be provided by the application as a custom action (see previous section). The following dialog (identical to standard uploading procedure) allows the user to pick a new file to replace the old one.

Handling Duplicates

Some applications may allow duplicate files and file names. This section covers steps to prevent duplicates.

Duplicate File Name During Renaming

In this example, there are two different image files: Product Picture – Front and Product Picture – Back.

The user types in a name that is identical to one that already exists.

When the user clicks OK or tries to remove the focus from the input field, the field is highlighted (semantic color: error).

Placing the focus back on the field shows the error message (form field validation).

Duplicate Files During Upload

If a duplicate is recognized during the upload process, a dialog appears that allows the user to do one of the following:

1) This text explains the current conflict (no actions possible).

2) With Upload and replace, the current file is replaced with the newly updated one.

3) With Upload and rename automatically, the current file is kept and an incrementally increasing number is added to the newly uploaded file, such as “Technical Specs_2”.

4) With Skip this file, the file is not uploaded and the current file is kept instead.

5) If Do this for all n conflicts is checked, the selected action is applied to all remaining conflicts.

6) The OK button confirms selected action(s).

7) The Cancel button cancels the entire upload process.

Styles

The showSeparators property allows you to display dividers between each item. The default value is All, meaning that all dividers are shown. We recommend that you only turn off the separators if you expect to have just a few items since they can help to maintain a better overview in long lists.

Guidelines

When to Show/Deactivate/Hide Actions

Apps can control the visibility and the active state for all actions at item level. This applies to the Edit and Delete buttons.

The properties are as follows:

• VisibleEdit
• VisibleDelete
• EnableEdit
• EnableDelete

All the properties are set to true by default.

If users are not allowed to edit uploaded files, all the Edit buttons should be set to invisible. The same applies to the Delete function.

Identical actions should be placed directly beneath one another.

Do not leave buttons enabled, only to show an error message informing the user that the function is not available.

Identical actions should always appear beneath one another.

If users are not allowed to use a certain function, these buttons should not be shown at all.

If certain actions are unavailable in some cases, such as for files from other users, we recommended that you disable these actions.

Do not disable all actions. If users are not allowed to use a certain action, these buttons should not be shown at all.

Identical actions should be placed directly beneath one another. In the example opposite, the Remove buttons on the lower two items should be visible but disabled.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.