Skip to end of metadata
Go to start of metadata

Crosslight iOS Dialog Presenter is a highly versatile user interface component allowing you to present a dialog and receive additional input from users. Unlike other Crosslight presenter variations such as Message Presenter which provides only basic interaction, dialog presenter lets you present a custom view content that may contain additional input controls and more sophisticated UI logic bound to a ViewModel. Similar to the other presenter variants, you can easily consume dialog presenter right from the ViewModel.

Dialog Presenter provides several built-in presentation styles designed with modern and adaptive layout in mind, which makes dialog presenter more appealing compared to the modal navigation.

On this page:

The following figure shows the iOS dialog presenter running in different device kind and size.

Overview

Designed with iOS 8's visual aesthetic and design standards, dialog presenter will show your content in a light background with blur visual effect applied. In addition, the message title, button separator, and button color and size are designed to match iOS 8 user interface standards. The layout is automatically measured for you, so all you need to do is simply show the dialog presenter using the provided API.

The following illustration shows an overview of the Crosslight dialog presenter in its default appearance.

Key features include:

  • Designed with iOS 8's visual aesthetic and design standards, featuring pixel-perfect layout with translucent effect.
  • Engineered with universal design in mind, featuring 3 built-in presentations – form sheet, full screen, and gorgeous iPad-optimized edge popover.
  • Powerful architecture and API, enables great extensibility with the utmost flexibility.
  • Fully customizable appearance, behaviors, and transitions.
  • Includes 8 built-in transitions.
  • Integrates seamlessly with existing Crosslight navigation framework.
  • Presentation concept is strongly separated from the content which enable you to present any content in the dialog presenter. For existing view controllers, no code or UI logic change is necessary.
  • Supports many sophisticated presentation scenarios found in today's modern apps.

Using Dialog Presenter

Working with Crosslight dialog presenter is very simple and straightforward. Typically, you will use the cross-platform dialog presenter API in the ViewModel to show the dialog. Consider that you want to show a ViewModel called RateViewModel in a dialog, then you will simply call the Show<RateViewModel> method of the dialog presenter. Every ViewModel class inheriting from ViewModelBase class can conveniently access the dialog presenter through the DialogPresenter property.

When the dialog is closed, the callback parameter will be automatically invoked of which you can obtain the DialogResult object. The dialog result contains numerous interesting properties that you can inspect to get the values of the user interaction such as the tapped button.

The following code example shows the basic usage of dialog presenter.

If you are using Crosslight Enterprise App Framework, you might want to use the awaitable version of the dialog presenter API in the ViewModel code. The following code shows an example of the awaitable version which is much cleaner and easier to maintain.

To learn more about cross-platform dialog presenter API and the available dialog options, please refer to Dialog Presenter.

Customizing Dialog Presenter Appearance

In addition to the basic options available in the cross-platform dialog presenter API, the dialog presenter on iOS platform provides more sophisticated appearance settings and behaviors that are specific to the iOS platform, such as the presentation style, transition type and duration, overlay settings, content background and blur effects, button font and colors, and much more.

You use the ConfigurePresenter(Action<IContentPresenterSettings> configureSettingsCallback) method to provide additional customization to the presenter settings. Available to any view controller types, Crosslight will automatically call the ConfigurePresenter method along with the default presenter settings when the view controller is about to be presented to the screen. In addition to iOS-specific configuration, this method also gives you a final chance to override the dialog options that comes from the originating code.

The following code example shows how to use the ConfigurePresenter method in the view controller.

Common Appearance

By default, dialog presenter is configured with default settings which simulate the native look and feel of iOS user interface. However, you can customize the dialog appearance completely to your liking. Most of the appearance aspects in the dialog presenter can be customizable.

The following figure shows the common dialog appearance settings that you can customize.

To see the complete customizable appearance properties, please see the DialogPresenterSettings class.

Presentation Style

Crosslight dialog presenter includes three pre-built content presentation styles which are designed with full compliance to iOS 8 adaptive design guidelines. The form sheet and full screen styles are two of the most common presentation styles that you can apply in any iOS device kind. In addition, Crosslight includes an innovative style called Edge presentation style which displays content relative to the edge of screen. The Edge style is ideal for device kind with larger display, allowing users to interact with the dialog momentarily without disrupting the current view context.

The following illustration shows an overview of the three content presentation styles supported in Crosslight dialog presenter.

Transition

By default, the dialog presenter uses a subtle zoom transition to simulate the native iOS user experience. Crosslight provides 8 gorgeous transitions that you can apply to the dialog presenter. All these transitions support spring animation by simply setting the Bounce property to true.

The following code example shows how to customize the entry animation of the dialog presenter. Note that if the exit transition is not specified, it will automatically use reversed animation from the entry transition. In most cases, you will not need to specify the exit transition explicitly.

Beyond the built-in transition, it is also possible to create your own custom transition which can be easily plugged to the dialog presenter – thanks to the extensible transition architecture introduced in Crosslight 4. The discussion of this subject will be covered in a separate documentation topic.

Contextual Appearance

Crosslight dialog presenter is built with versatile design, enabling you to target virtually any type of view controllers. You can think the dialog presenter as a seamless navigation container that manage your view controller. This means if your view controller is supposed to navigate to a child view controller in a standard presentation, then you can expect dialog presenter to treat your view controller in the exactly same way.

Since dialog presenter sports a beautiful translucent style by default, you might want to re-style your table view controller to be transparent as well. However, if you have several nested view controllers, it will become tedious to set the appearance of each view controller manually by hand. Dialog presenter includes a unique feature called contextual appearance, allowing you to streamline all appearance settings for a certain class type.

The following code example shows how to set all table view controllers within the dialog presenter – regardless of the depth –  to use the specified TableViewAppearance class.

You can only apply the contextual appearance settings to the view controllers introduced in Crosslight such as UITableViewController<TViewModel>.

Conditional Settings Based on Device Kind

When building universal iOS apps, you might want to configure the dialog presenter settings conditionally based on the device kind, for instance, showing full screen presenter on iPhone, while it makes more sense to use edge style on the iPad. You can easily achieve this scenario by writing the necessary conditions directly in the settings callback. See the code example below.

Samples

Check out the comprehensive dialog presenter samples here: http://git.intersoftpt.com/projects/CROS-SUPP/repos/dialogpresenter-sample/browse. Prior to running the samples, make sure to set the iOS project as the startup project.