You are here: Using the Navigation Drawer
FlexForm Widget
A FlexForm is the top most container widget, and is usually the first widget you add to an application. It serves as a container for all other widgets on the screen. Your app can support multiple screens by supporting multiple FlexForms and allowing a user to navigate between these screens.
FlexForm widget is not listed in the Default library. To create a new FlexForm widget, go to the Project explorer, expand any channel such as Mobile, Tablet, and Responsive web. Then, right-click on the Forms and select New Form.
Following are a few actions that you can perform on a FlexForm:
- Animations: You can add animations such as move, rotate, and more to the widgets in the FlexForm. An example for this is the sliding menu/hamburger menu, which can be designed to slide from left to right or right to left as per your specification.
- Layout: You can specify the layout of a FlexContainer and its child widgets in the FlexForm by using different positional properties. You can also specify if you want the widgets to be placed vertically, horizontally, or without any positional restrictions. These layout features help you to design a form and ascertain how it will look in a device.
- Skin: You can define the background by setting a skin to the FlexContainer in the FlexForm. You can blur your container, provide a shadow effect to your FlexContainer, and even make the FlexContainer transparent.
The FlexForm widget capabilities can be broadly categorized into the following:
- Layout
- Animations
- Form Lifecycle
- Drawer Features
- Scrolling functionalities
- Data Management
- 3D Touch
- User Input Handling
- UI Appearance
- Enabling RTL
- Miscellaneous
- Configurations Common To All Widgets
Layout
| Properties | Description |
|---|---|
| anchorPoint | Specifies the anchor point of the widget bound rectangle using the widget's coordinate space. |
| contentOffset | Specifies the x and y coordinates of the top-left of the scrollable region. |
| contentSize | Specifies the width and height of the container to accommodate all the widgets placed in it. |
| layout | Specifies if the arrangement of the widgets either in horizontal or vertical direction. |
| layoutType | Specifies if the arrangement of the widgets either in free form or vertical direction. |
| requiresBottomSafeAreaInset | Implements the Safe Area Layout for iOS devices, specifically the iPhone X series. Content of the flex form occupies the full screen at the bottom and overlaps the virtual home indicator. |
| requiresLeftSafeAreaInset | Implements the Safe Area Layout for iOS devices, specifically iPhone X series. Content of the flex form starts from (0,0) pixel. |
| requiresRightSafeAreaInset | Implements the Safe Area Layout for iOS devices, specifically iPhone X series. Flex form widget occupies full screen at left/ right part of the screen. |
| requiresTopSafeAreaInset | Implements the Safe Area Layout for iOS devices, specifically the iPhone X series. Content of the flex form starts from (0,0) pixel. |
| zIndex | Specifies the stack order of a widget. |
| Methods | Description |
|---|---|
| forceLayout | When this method is called, underlying OS layout cycle is forced to layout the widgets of the FlexForm. |
| Events | Description |
|---|---|
| doLayout | This event is invoked for every widget when the widget position and dimensions are computed. |
| onBreakpointChange | This event defines a callback that is executed when there is a change in the breakpoint. |
| onResize | This event defines a callback that is executed when there is a change in the width of the browser. This event has been deprecated since V8 SP2. |
Animations
| Properties | Description |
|---|---|
| transform | Contains an animation transformation that can be used to animate the widget. |
| inTransitionConfig | Specifies the configuration to be used when the user arrives on this form. |
| outTransitionConfig | Specifies the type of transition effect to be applied when the Form is going out of view. |
Form Lifecycle
| Events | Description |
|---|---|
| init | Gets called only once in form life cycle that is when the form is ready with its widget hierarchy. |
| onDestroy | Specifies an event which is triggered when the FlexForm is destroyed. |
| onHide | Specifies an Event which is triggered when a form goes completely out of view. |
| postShow | postShow is invoked after a form is displayed. |
| preShow | preShow is executed every time a form is to be displayed. |
Drawer Features
| Events | Description |
|---|---|
| onDrawerClosed | Called when a Navigation Drawer has finished closing. |
| onDrawerOpened | Called when a Navigation Drawer has finished opening. |
| onDrawerSlide | Sent when the position of a NavigationDrawer changes. |
| onDrawerStateChanged | Called when the NavigationDrawer motion state changes. |
| Methods | Description |
|---|---|
| closeNavigationDrawer | Close the NavigationDrawer on forms that have been created using a template that supports the NavigationDrawer. |
| openNavigationDrawer | Open the NavigationDrawer on forms that have been created using a template that supports the NavigationDrawer. |
| Properties | Description |
|---|---|
| drawerLayout | Gets and sets the FlexContainer that contains the elements of the NavigationDrawer, which is named drawerLayout. |
| drawerWidth | Gets and sets the width of the Navigation Drawer. |
| drawerShadowColor | Sets or gets the shadow color that covers the form when the NavigationDrawer is open, indicating that the controls on the form are not available for interaction. |
| drawerOpenIcon | The icon to be displayed when Navigation bar is open. |
| drawerClosedIcon | The icon to be displayed when Navigation bar is closed. |
| drawerOpena11yHint | Specifies the descriptive text that explains the action of the widget. |
| drawerCloseda11yHint | Specifies the descriptive text that explains the action of the widget. |
| navigationDrawerListeners | Maps Navigation Drawer events to user defined handler functions. |
Scrolling functionalities
| Properties | Description |
|---|---|
| allowHorizontalBounce | Specifies whether the scroll bounce is enabled or disabled in the horizontal direction. |
| allowVerticalBounce | Specifies whether the scroll bounce is enabled or disabled in the vertical direction. |
| bounces | Specifies whether the scroll bounce is enabled or disabled. |
| enableOnScrollWidgetPositionForSubwidgets | Enables the FlexForm widget to iterate into all the widgets that make use of the onScrollWidgetPosition event. |
| enableScrolling | Specifies whether the scrolling is enabled on the container or not. |
| retainScrollPosition | Specifies if the Form must remember the scroll position when the user revisits the Form. |
| scrollDirection | Specifies the direction in which the widget should scroll. |
| verticalScrollIndicator | Specifies whether the scroll indicator must be shown or not in the vertical direction. |
| Methods | Description |
|---|---|
| scrollToBeginning | Gives you the control to scroll to the beginning of the form. |
| scrollToEnd | Gives you the control to scroll to the end of the FlexForm. |
| scrollToWidget | Gives you the control to scroll the FlexForm up to the position of selected widget. |
| Events | Description |
|---|---|
| onDecelerationStarted | An event callback is invoked by the platform when the user stops scrolling but the content still moves before the content actually stops. |
| onScrollEnd | An event callback is invoked by the platform when the scrolling is ended. |
| onScrollWidgetPosition | This event callback is invoked by the platform when the widget location position gets changed on scrolling. |
| onScrolling | An event callback is invoked by the platform when the scrolling is in progress. |
| onScrollStart | An event callback is invoked by the platform when the user starts scrolling the content. |
| onScrollTouchReleased | An event callback is invoked by the platform when the user touch is released from the touch surface. |
Data Management
| Methods | Description |
|---|---|
| add | Used to add widgets to the FlexForm |
| addAt | Used to add widgets to the Form container at the specified index. |
| clone | When this method is used on a container widget, then all the widgets inside the container are cloned. |
| remove | Removes a widget from the FlexForm. |
| removeAt | Removes a widget at the given index from the FlexForm. |
| removeAll | Removes all the widget on the FlexForm. |
3D Touch
| Methods | Description |
|---|---|
| registerForPeekandPop | Registers a widget to enable 3D Touch peek and pop gestures. |
| setOnPeek | Sets and overrides the existing onPeekCallback for the widget. |
| setOnPop | Overrides the existing onPopCallback for the widget. |
| unregisterForPeekandPop | Unregisters a widget from 3D Touch peek and pop gestures. |
User Input Handling
| Events | Description |
|---|---|
| onZoomEnd | An event callback is invoked by the platform when the zooming has ended. |
| onZooming | An event callback is invoked by the platform when the container is zooming. |
| onZoomStart | An event callback is invoked by the platform when the container is about to zoom. |
| widgetToZoom | An event callback is invoked by the platform to return one of the child widgets of source to zoom. |
| Methods | Description |
|---|---|
| setZoomScale | Allows you the zoom the widgets with an option to animate. |
| Properties | Description |
|---|---|
| disableZoom | Allows you to enable or disable zooming the FlexForm. |
| maxZoomScale | Specifies the maximum zoom scale factor that can be applied to the form. |
| minZoomScale | Specifies the minimum zoom scale factor that can be applied to the form. |
| zoomScale | Specifies the current scale factor applied to the form content. |
UI Appearance
| Properties | Description |
|---|---|
| backgroundColor | Specifies the background color of the widget in hex format. The background can be a single color or a gradient of several colors. |
| configureExtendBottom | Enables you to configure extendBottom property. |
| configureExtendTop | Enables you to configure extendTop property. |
| configureStatusBarStyle | Enables you to configure statusBarStyle property. |
| defaultIndicatorColor | Enables you to set color to the progress indicator when it is show on the form. |
| extendBottom | Helps in extending the bottom of the form. |
| extendTop | Helps in extending the top of the form. |
| footerOverlap | Specifies if the footer must overlap the form. |
| formTransparencyDuringPostShow | Specifies the transparency in percentage when a form is loaded. |
| headerOverlap | Specifies if the header must overlap the form |
| inputAccessoryViewType | The extra buttons (or controls) allow specific operations needed by your application, such as moving to the next or previous text field, making the keyboard disappear and so on. The area above the keyboard is known as Input Accessory View. |
| menuFocusSkin | skin property of a form level menu and it determines the look and feel of the Menu Item when focused. |
| menuNormalSkin | skin property and it determines the look and feel of a menu items when not in focus. |
| menuPosition | Specifies if the application menu is shown or hidden in the application. |
| navigationBarColor | Helps you set the color for a device's navigation bar. |
| needAppMenu | Specifies if the application menu items should be displayed as a part of the menu controls on the form. |
| needsIndicatorDuringPostShow | Specifies if there must be an indication to the user that the form content is being loaded. |
| opacity | Specifies the opacity of the widget. |
| pagingEnabled | Specifies the whether the paging is enabled for the container. |
| prefersStatusBarHidden | Specifies whether the status bar must be shown or not. |
| setContentOffset | Gives you the control to offset a portion of the content in a Form to bring the widgets in invisible area to visible area. |
| showActionBar | Specifies if the action bar should be displayed. |
| showActionBarIcon | Specifies the icon to be displayed for the action bar. |
| showMiniAppMenu | Specifies if the application menu is shown or hidden in the application. |
| statusBarColor | Helps you set the color for a device's status bar. |
| statusBarForegroundColor | Helps you set the foreground color of the status bar, such as color for any text or icon on the status bar. |
| statusBarHidden | Lets you show or hide the status bar. |
| statusBarStyle | Helps you set a style for the status bar. |
| systmeUiConfig | Controls the behavior of the status and navigation bars. |
| titleBar | Specifies the title bar must be displayed on the form. |
| titleBarAttributes | Contains data that supports Application bar functionality in iOS. |
| titleBarConfig | Specifies the position of the title bar of the form. |
| titleBarSkin | Specifies the skin to be applied to the title Bar of the form. |
| viewConfig | Helps to give reference height and reference width to a container when it is in grid layout. |
| windowSoftInputMode | Defines how the main Form interacts with the window containing the on-screen soft keyboard. |
| Methods | Description |
|---|---|
| setBackgroundImageForNavbar | Helps to set the background image for the title bar for iOS specific applications. |
| setTitleBarLeftSideButtonSkin | Enables you to set the properties for a left-side button of a titlebar. |
| setTitleBarRightSideButtonSkin | Enables you to set the properties for a right-side button of a titlebar. |
| show | Used to display the FlexForm. |
Enabling RTL
| Properties | Description |
|---|---|
| retainContentAlignment | Helps to retain the content alignment of the widget while applying RTL. |
| retainFlexPositionProperties | Helps to retain the left, right and padding properties while applying RTL. |
| retainFlowHorizontalAlignment | Enables you to change the horizontal flow of the widget from left to right. |
Miscellaneous
| Properties | Description |
|---|---|
| captureGPS | Specifies if the Form must display a popup seeking permission from the user to access the location details. |
| enabledForIdleTimeout | Idle time indicates the amount of time that a user has not interacted with the application. |
| maxAppMenuButtons | Specifies the number of appmenu buttons should be displayed on the screen. |
| noCache | Indicates that if the form is enabled for caching on the device browser. |
| secureData | Specifies if the browser must retain and use the information that you have filled in a form |
| submitSecure | Specifies if the information must be sent using secure connection (https) or insecure connection (http). |
| windowSoftInputMode | Defines how the main Form interacts with the window containing the on-screen soft keyboard. |
| Methods | Description |
|---|---|
| getTitleVerticalPositionAdjustment | Gets the position of the title vertically on the navigation bar. |
| hideTitleBar | Gives you the control to hide a titlebar within a form. |
| setHidesBackButton | Hides or shows the back button in the title bar |
| setLeftBarButtonItems | Allows you to add BarButtonItems to the left side of the NavigationBar |
| setDefaultUnit | Specifies the default unit to be used for interpretation of numbers with no qualifiers when passed to layout properties. |
| setPreviewActionItems | Sets the preview actions for a form to be displayed when the user swipes up the preview/peek of a form. |
| setRightBarButtonItems | Sets the preview actions for a form to be displayed when the user swipes up the preview/peek of a form. |
| setTitleVerticalPositionAdjustment | Set position of the title vertically on the navigation bar. |
| showTitleBar | Gives you the control to show a titlebar to a FlexForm. |
| widgets | Returns an array of the widget references which are direct children of Form. |
| Events | Description |
|---|---|
| onKeyBoardDidHide | This is an event callback that is invoked by iOS when the keyboard has been hidden. |
| onKeyBoardDidShow | This is an event callback that is invoked by iOS when the keyboard has just been shown. |
| onKeyBoardWillHide | This is an event callback that is invoked by iOS when the keyboard is about to be hidden. |
| onKeyBoardWillShow | This is an event callback that is invoked by iOS when the keyboard is about to be shown. |
| onActionBarBack | An event callback that is invoked by the platform when the back button is pressed on an action bar. |
| onDeviceBack | Specifies an event which is triggered when the user uses the back button on the device. |
| onDeviceMenu | Specifies an event which is triggered when the user access the device menu. |
| onLocaleChanged | An event callback invoked by the platform when the locale changes. |
| onMapping | An event created by Volt MX Iris when you drag and drop a service. |
| onNavigate | An event callback invoked when you navigate from one form to another. |
| onOrientationChange | Specifies an Event which is triggered when there is a change in orientation of the form from portrait to landscape or vice versa. |
| onSizeChanged | Specifies the event that is triggered when the app window is resized. |
Configurations Common To All Widgets
| Properties | Description |
|---|---|
| accessibilityConfig | Enables you to control accessibility behavior and alternative text for the widget. |
| enableCache | Enables you to improve the performance of Positional Dimension Animations. |
| id | id is a unique identifier of form consisting of alpha numeric characters. |
| info | A custom JSObject with the key value pairs that a developer can use to store the context with the widget. |
| parent | Helps you access the parent of the widget. |
Programming FlexForms
In earlier versions of Volt MX Iris you used BoxForm, horizontal (HBox) and vertical (VBox) boxes as containers to align widgets. These widgets are now obsolete and are listed in the Deprecated section of this reference. They still work, so older applications will continue to function, but should not be used in current versions of Iris.
- A FlexForm allows you to place and size widgets anywhere and you can place any number of widgets on it. It gives you absolute position and dimension of the widgets.
- A FlexForm has two layout types: Free Form Layout and Flow Vertical Layout. In the Free Form Layout, widgets can overlap with other widgets. In Flow Vertical Layout, widgets are placed one below the other.
- A FlexForm fills the entire device screen with the exception of the OS header and footer. A FlexForm can also display a title bar (or application bar as it is known in iOS). This bar will be displayed at the top of the form.
- FlexContainers are often used to add another level of organization within a FlexForm.
Form stacking
Typically a form is displayed in response to a user action on another form. That means the navigation between forms happen by the events on another form. All the navigation actions should be pushed into a stack to track the navigation path, so that the user can navigate back to the previous forms in the exact reverse order of its forward navigation. When navigating to a form that is already in the stack, the target form is brought back to the top of the stack by popping all the above forms out of the stack.
FlexForm Lifecycle
A FlexForm lets you add other container and widgets to create a widget hierarchy.
Lifecycle Methods:
A form is defined to have a lifecycle method that gets called at appropriate events. These events allow you to manage the application for better resource handling.
The following are the lifecycle methods of a form:
addWidgets - called when the form is used for first time either
- for accessing its widgets,
- accessing its properties,
- for showing the form through the show method,
- for any other method that invokes the form.
For example, any of the following can trigger the addWidgets method of form1 if form1 is not yet initialized:
- form1.label1
- form1.title
- form1.show()
init - called immediately after an addWidgets event for any initializations required for the form. Init initializes the form and any widgets.
In case of Server side Mobile Web and SPA, addWidgets preserve">var var init events gets called as soon as the form is created. In case of native platforms, as an optimization, these events are deferred until the first access.
preShow - called just before a form is visible on the screen. A form can be made visible by explicitly calling the show method of the form.
postShow - called immediately after the form is visible on the screen. A form is made visible by explicitly calling the show method of the form.
onHide - called when the form goes out of the screen. A form can go out of the screen when another form is to be shown.
onDestroy - called when a form is destroyed. A form is destroyed when the developer explicitly calls destroy and this event gets called before destroying the form.
The following image illustrates the lifecycle of a form:
Click here to view the Application Life Cycle events.
Creating a Form using a constructor: voltmx.ui.Form2
var form1 = new voltmx.ui.Form2(basicConf, layoutConf, pspConf);
- basicConf is an object with basic properties.
- layoutConf is an object with layout properties.
- pspConf is an object with platform specific properties.
Note: The configuration properties should be passed only in the respective configuration objects otherwise they are ignored.
Example
//Defining the properties of FlexForm testfrm preserve">var
var a FlexScrollContainer flexScrollContainer1
function addWidgetstestfrm() {
var flexScrollContainer1 = new voltmx.ui.FlexScrollContainer({
"id": "flexScrollContainer1",
"top": "5dp",
"left": "6dp",
"width": "97.15%",
"height": "271dp",
"isVisible": true,
"bouncesZoom": true,
"zoomScale": 1.0,
"layoutType": voltmx.flex.FREE_FORM
}, {});
flexScrollContainer1.setDefaultUnit(voltmx.flex.DP);
flexScrollContainer1.add();
testfrm.add(flexScrollContainer1);
};
function testfrmGlobals() {
var MenuId = [];
testfrm = new voltmx.ui.Form2({
"id": "testfrm",
"contentOffset": {
"x": "3dp",
"y": "4dp"
},
"contentSize": {
"width": "5dp",
"height": "6dp"
},
"enableScrolling": true,
"bounces": true,
"allowHorizontalBounce": true,
"allowVerticalBounce": false,
"pagingEnabled": true,
"title": "myfrmt",
"needAppMenu": true,
"enabledForIdleTimeout": true,
"skin": "frm",
"zoomScale": 22,
"minZoomScale": 1.0,
"maxZoomScale": 1.0,
"layoutType": voltmx.flex.FREE_FORM,
"addWidgets": addWidgetstestfrm
}, {
"displayOrientation": constants.FORM_DISPLAY_ORIENTATION_PORTRAIT,
}, {
"retainScrollPosition": true,
"needsIndicatorDuringPostShow": true,
"formTransparencyDuringPostShow": "100",
"inputAccessoryViewType": constants.FORM_INPUTACCESSORYVIEW_DEFAULT,
"bouncesZoom": false,
"configureExtendTop": true,
"configureExtendBottom": false,
"configureStatusBarStyle": false,
"extendTop": false,
"titleBar": true,
"footerOverlap": false,
"headerOverlap": false,
"inTransitionConfig": {
"transitionDirection": "fromLeft",
"transitionEffect": "none"
},
"outTransitionConfig": {
"transitionDirection": "fromRight",
"transitionEffect": "none"
}
});
testfrm.setDefaultUnit(voltmx.flex.PX);
};
Note: For a form, there is no limit set on the vertical height and hence a form never declines the child widgets request for preferred height.
Using the Navigation Drawer
The Navigation Drawer, or "Hamburger menu" is a native feature of the Android platform, and is supported in Iris using the Navigation Drawer property of the FlexForm. This feature applies to Android only, so if you intend to support other platforms it may be better to implement your own version of this control using cross platform features.
The Navigation Drawer is selected in Iris using templates. There is no way to add it programmatically. See the Iris Users Guide for more information on adding this feature to your application.