class sap.f.FlexibleColumnLayoutSemanticHelper

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Extends:
Module: sap/f/FlexibleColumnLayoutSemanticHelper
Application Component: CA-UI5-CTR

Helper class, facilitating the implementation of the recommended UX design of a sap.f.FlexibleColumnLayout-based app.

Note: Using this class is not mandatory in order to build an app with sap.f.FlexibleColumnLayout, but exists for convenience only.

Sample usage of the class:


 var helper = sap.f.FlexibleColumnLayoutSemanticHelper.getInstanceFor(myFlexibleColumnLayout);
 helper.getCurrentUIState();
 helper.getNextUIState(2);
 helper.getNextUIState(0);

Calling getCurrentUIState() will return information which action buttons (Close, FullScreen, ExitFullScreen) must be currently shown in which column, according to UX guidelines, as well as to what layout clicking them should lead.

Calling getNextUIState(2) will return information about the expected layout and action buttons if the application should display three views (master-detail-detail), based on the current state.

Similarly, calling getNextUIState(0) will return information about the expected layout and action buttons if the application should display the initial view only (master), based on the current state.

For more information, see sap.f.FlexibleColumnLayoutSemanticHelper#getCurrentUIState and sap.f.FlexibleColumnLayoutSemanticHelper#getNextUIState


Constructor

Constructor for an sap.f.FlexibleColumnLayoutSemanticHelper.

new sap.f.FlexibleColumnLayoutSemanticHelper(oFlexibleColumnLayout, oSettings)
Param Type Default Value Description
oFlexibleColumnLayout sap.f.FlexibleColumnLayout

The sap.f.FlexibleColumnLayout object whose state will be manipulated.

oSettings object

Determines the rules that will be used by the helper.

defaultTwoColumnLayoutType? sap.f.LayoutType sap.f.LayoutType.TwoColumnsBeginExpanded

Determines what two-column layout type will be suggested by default: sap.f.LayoutType.TwoColumnsBeginExpanded or sap.f.LayoutType.TwoColumnsMidExpanded.

defaultThreeColumnLayoutType? sap.f.LayoutType sap.f.LayoutType.ThreeColumnsMidExpanded

Determines what three-column layout type will be suggested by default: sap.f.LayoutType.ThreeColumnsMidExpanded or sap.f.LayoutType.ThreeColumnsEndExpanded.

maxColumnsCount int

Determines the maximum number of columns that will be displayed side by side.

    Possible values:

  • Value of 1 only single-column layouts will be suggested.
  • Value of 2 Up to 2-column layouts will be suggested.
  • Value of 3 (default) - Up to 3-column layouts will be suggested.

initialColumnsCount int

Determines whether a single-column or a 2-column layout will be suggested for logical level 0.

    Possible values:

  • Value of 1 (default) - A single-column layout will be suggested for logical level 0.
  • Value of 2 - A 2-column layout will be suggested for logical level 0.

mode string

Deprecated as of version 1.50, use maxColumnsCount param instead.

Determines the suggested layout types: Normal (3-column layouts), MasterDetail (2-column layouts for the first two pages, all other pages will open in fullscreen), and SingleColumn (one page at a time only).


Methods Overview

Method Description
getCurrentUIState

Returns an object, describing the current state of the control and the expected action buttons for each column.

    The returned object has the following structure:
  • layout - the value of the layout property
  • maxColumnsCount - the maximum number of columns that can be displayed at once based on the control width. See sap.f.FlexibleColumnLayout#getMaxColumnsCount
  • columnsSizes - an object with fields beginColumn, midColumn, endColumn, representing the relative percentage sizes of the three columns as integers
  • columnsVisibility - an object with fields beginColumn, midColumn, endColumn, representing the visibility of the three columns
  • isFullScreen - true if only one column is visible at the moment, false otherwise Note: This may be due to small screen size (phone) or due to a layout, for which a single column takes up the whole width
  • isLogicallyFullScreen - true if the current layout is one of the following: sap.f.LayoutType.OneColumn, sap.f.LayoutType.MidColumnFullScreen, sap.f.LayoutType.EndColumnFullScreen, false otherwise Note: While isFullScreen can be true for any layout, due to small screen size, isLogicallyFullScreen will only be true for the layout values, listed above.
  • actionButtonsInfo - an object with fields midColumn, endColumn, each containing an object, telling whether action buttons should be shown in the mid and end columns, and what value of the layout property should be set upon clicking these buttons. Each of these objects has the following fields: closeColumn, fullScreen, exitFullScreen. If null, then the respective action button should not be shown, otherwise provides the value of layout property for the action button.

Note: This method relies on the internal FlexibleColumnLayout reference to be rendered in the DOM tree. For convenience, use methods sap.f.FlexibleColumnLayoutSemanticHelper#isDOMReady and sap.f.FlexibleColumnLayoutSemanticHelper#whenDOMReady.

Example value:

 
 {
	   "layout":"ThreeColumnsMidExpanded",
	   "maxColumnsCount":3,
	   "columnsSizes":{
		  "beginColumn":25,
		  "midColumn":50,
		  "endColumn":25
	   },
	   "columnsVisibility":{
		  "beginColumn":true,
		  "midColumn":true,
		  "endColumn":true
	   },
	   "isFullScreen":false,
	   "isLogicallyFullScreen":false,
	   "actionButtonsInfo":{
		  "midColumn":{
			 "fullScreen":null,
			 "exitFullScreen":null,
			 "closeColumn":null
		  },
		  "endColumn":{
			 "fullScreen":"EndColumnFullScreen",
			 "exitFullScreen":null,
			 "closeColumn":"TwoColumnsBeginExpanded"
		  }
	   }
	}
 
 

getDefaultLayouts

Returns the default layout types for the different numbers of columns.

    The returned object has the following fields:
  • defaultLayoutType - the layout that will be suggested by default when only 1 column needs to be shown
  • defaultTwoColumnLayoutType - the layout that will be suggested by default when 2 columns have to be shown side by side
  • defaultThreeColumnLayoutType - the layout that will be suggested by default when 3 columns have to be shown side by side

sap.f.FlexibleColumnLayoutSemanticHelper.getInstanceFor

Returns an instance of the sap.f.FlexibleColumnLayoutSemanticHelper class for a given sap.f.FlexibleColumnLayout object.

getNextUIState

Returns an object, describing the state that the control will have after navigating to a different view level.

About the format of return value, see: sap.f.FlexibleColumnLayoutSemanticHelper#getCurrentUIState

isDOMReady

Returns true if internal FlexibleColumnLayout reference is rendered in the DOM tree.

isReady

Abstract wrapper for sap.f.FlexibleColumnLayoutSemanticHelper#isDOMReady. Returns true if criteria are met for the APIs in this helper to be used.

whenDOMReady

Returns promise which can be used to find out when the internal FlexibleColumnLayout is rendered. This is needed because methods in FlexibleColumnLayout rely on the control being rendered.

whenReady

Returns promise which can be used to find out when internal criteria for this helper's API reliability are met.

getCurrentUIState

Returns an object, describing the current state of the control and the expected action buttons for each column.

Note: This method relies on the internal FlexibleColumnLayout reference to be rendered in the DOM tree. For convenience, use methods sap.f.FlexibleColumnLayoutSemanticHelper#isDOMReady and sap.f.FlexibleColumnLayoutSemanticHelper#whenDOMReady.

Example value:

 
 {
	   "layout":"ThreeColumnsMidExpanded",
	   "maxColumnsCount":3,
	   "columnsSizes":{
		  "beginColumn":25,
		  "midColumn":50,
		  "endColumn":25
	   },
	   "columnsVisibility":{
		  "beginColumn":true,
		  "midColumn":true,
		  "endColumn":true
	   },
	   "isFullScreen":false,
	   "isLogicallyFullScreen":false,
	   "actionButtonsInfo":{
		  "midColumn":{
			 "fullScreen":null,
			 "exitFullScreen":null,
			 "closeColumn":null
		  },
		  "endColumn":{
			 "fullScreen":"EndColumnFullScreen",
			 "exitFullScreen":null,
			 "closeColumn":"TwoColumnsBeginExpanded"
		  }
	   }
	}
 
 

getDefaultLayouts

Returns the default layout types for the different numbers of columns.

sap.f.FlexibleColumnLayoutSemanticHelper.getInstanceFor

Returns an instance of the sap.f.FlexibleColumnLayoutSemanticHelper class for a given sap.f.FlexibleColumnLayout object.

Param Type DefaultValue Description
oFlexibleColumnLayout sap.f.FlexibleColumnLayout

The sap.f.FlexibleColumnLayout object to get a semantic helper instance for

oSettings object

An optional settings object to be used when creating the instance. Note: will be considered only for the first getInstanceFor call for the given sap.f.FlexibleColumnLayout object.

getNextUIState

Returns an object, describing the state that the control will have after navigating to a different view level.

About the format of return value, see: sap.f.FlexibleColumnLayoutSemanticHelper#getCurrentUIState

Param Type DefaultValue Description
iNextLevel int

the view level that should be represented. 0 means initial (master only), 1 - master-detail, 2 - master-detail-detail, 3 and above - subsequent views

isDOMReady

Returns true if internal FlexibleColumnLayout reference is rendered in the DOM tree.

isReady

Abstract wrapper for sap.f.FlexibleColumnLayoutSemanticHelper#isDOMReady. Returns true if criteria are met for the APIs in this helper to be used.

whenDOMReady

Returns promise which can be used to find out when the internal FlexibleColumnLayout is rendered. This is needed because methods in FlexibleColumnLayout rely on the control being rendered.

whenReady

Returns promise which can be used to find out when internal criteria for this helper's API reliability are met.