Skip to end of metadata
Go to start of metadata

The latest Crosslight release adds a flexible and full-featured drawer navigation which lets you easily create great apps with modern drawer navigation metaphor. Building upon MVVM pattern, you can upgrade your apps to leverage drawer navigation with minimal effort – thanks to the clear separation between user interaction logic and views.

On this page:

The drawer navigation is integrated into the navigation service which automatically intercepts "push" navigation and redirect it to the center view instead. This means that if you already have an existing navigation screen, upgrading to drawer navigation will work out-of-the-box without requiring additional efforts. See the following illustration to learn the concept of drawer navigation.

Key Features

In general, the drawer navigation in iOS offers the following features:

  • Built upon MVVM with integrated navigation service
  • Flexible one or two-side drawer
  • Intuitive design based on iOS platform guidelines
  • Support translucent, blurred status bar
  • Support Facebook-style "transition to black" status bar
  • Smooth panning gesture with accelerated flick velocity
  • Rock-solid stability with optimized rendering performance
  • Automatic rotation handling
  • Fully customizable appearance and drawer settings

The following illustrations overview the drawer navigation features.

Implementing Drawer Navigation in iOS Apps

In general, there are a number of tasks required to implement the drawer navigation such as setting up the drawer's ViewModel and assigning the ViewModel as root in the shared application layer, then finally creating a view controller that derives from UIDrawerNavigationController to present the drawer view in native iOS presentation.

The following sections explain how to implement drawer navigation in details.

Implementing drawer navigation requires basic knowledge of Crosslight navigation concept which extensively use MVVM pattern for clear logic separation. For more information about Crosslight navigation pattern, see Understanding Crosslight Navigation Services and Using NavigationItem for Various Navigation Patterns.

Configuring DrawerViewModel

The drawer navigation is fundamentally a view container which means it serves as a host that contains child views. The first step to implement drawer navigation is to create a ViewModel in the core project that derives from the DrawerViewModelBase class. The DrawerViewModelBase conforms to IDrawerViewModel interface which provides the members required to implement the drawer navigation such as LeftViewModel, CenterViewModel and RightViewModel properties.

Creating a DrawerViewModel is easy and straightforward, see the following code sample.

DrawerViewModel.cs

As seen in the above sample, the DrawerViewModel class lets you define the ViewModel that you would like to present in the left drawer, center, and right drawer respectively. The specified view models will be automatically to its respective native view context at runtime. In addition, you may also open a drawer side initially by using the Open method and specify the desired DrawerSide value.

To learn more how Crosslight works with ViewModel to enable cross-platform development, please refer to  Understanding Data Binding and MVVM Design Pattern and  Designing Consistent Navigation Interface.

Setting DrawerViewModel as RootViewModel

Now that we have created your drawer view model, you would want to present it as the main view when the app starts. To achieve this, you can simply change the root view model in the AppService.cs, usually located in the Infrastructure folder of your core project.

The following code example shows how to set the drawer view model as the root view model.

AppService.cs

Using UIDrawerNavigationController

Finally, you create a view controller in the iOS app layer that derives from UIDrawerNavigationController. Similar to all view controllers provided in Crosslight, the UIDrawerNavigationController supports MVVM pattern by default through the class type parameters. In most cases, you will only need as minimal as a line-of-code to implement the drawer navigation controller. See the code example below.

DrawerNavigationController.cs

This is made possible because all user interaction logic are written in the ViewModel, not views. This allows you to easily change the views in the future without affecting the user interaction logic. For more information about Crosslight fundamentals, see Understanding Crosslight Architecture and Fundamentals.

Configuring Drawer Appearance

Apart of the user interaction logic which is commonly built on the shared/core application layer, all view-specific settings remain in the view level such as the drawer appearance and behaviors that are specific to each platform.

The iOS drawer navigation provides a vast array of appearance settings that you can easily customize, such as the drawer's width, enable drop shadow, customize the status bar transition mode, configure the flick velocity value, and much more. All the drawer settings are available in the DrawerSettings property of the drawer controller.

The following code shows how to customize the appearance of the drawer view.

DrawerNavigationController.cs

For more information about the settings available in the drawer and its description, please refer to the DrawerSettings Class.

Configuring Drawer Animation

Crosslight iOS drawer navigation provides three built-in animation types: Slide, SlideParallax, and Scale. The default value for animation is Slide.

The following illustration shows the SlideParallax animation using default animation settings.

For SlideParallax animation, you can also customize the parallax velocity through the provided SlideParallaxVelocity property.

The following illustration shows the Scale animation.

For Scale animation, you can also customize the scale velocity through the provided ScaleVelocity property.

You can easily customize the drawer animation through the DrawerSettings property available in the UIDrawerNavigationController class. Note that all animation types have been designed to work consistently in any interface orientation. Rotation at runtime has been handled automatically as well. In addition, all animation types support progressive transition, allowing users to intuitively panning the drawer to reveal the content.

The following code shows how to customize the drawer to use Scale animation.

DrawerNavigationController.cs

Samples

To see iOS drawer navigation in action, please refer to the following samples:

  • Navigation Drawer Samples – provides 5 variant of navigation drawer samples including simple drawer style, Facebook style, translucent style, and two-sided drawer style.
  • Data Navigation Drawer Samples – migration of original data samples which transforms classic navigation into modern drawer navigation.