Skip to end of metadata
Go to start of metadata

Introducing Crosslight Android Material, a brand-new powerful library for rapidly building modern Android apps with Material Design aesthetics. Building upon Crosslight's mature and rock-solid foundation, the new Material library provides comprehensive APIs which make it easy for developers to add Material experiences such as card views, list-to-detail shared transitions, floating action buttons, parallax scrolling, collapsible toolbars, and much more.

In contrast to Google's complicated and tedious Support Design Library, Crosslight Android Material is designed with intuitive and elegant APIs that are thoughtfully orchestrated, enabling you to add Material experiences with just simple property sets while delivering great Material experiences that comply to Google's design guidelines.

This page overviews the key concepts and features of Crosslight Android Material, and also provides links to walkthroughs and samples you need to quickly get started.

On this page:

Introducing Intersoft.Crosslight.Android.v7 Assembly

In a nutshell, Crosslight Android Material is resembled in a new assembly called Intersoft.Crosslight.Android.v7 which mainly comprised of four essential building blocks – Material Themes, Material Views, Material UI Components, and Material Experiences.

Please refer to the following architecture diagram to quickly understand the concepts and key components available in Crosslight Android Material.

New Dependencies

In addition to Intersoft.Crosslight.Android.v7, there are several new dependencies required in Crosslight Android Material projects, even though your application might not actively use them. The new dependencies are as follow:

  • Xamarin.Android.Support.Design
  • Xamarin.Android.Support.v4
  • Xamarin.Android.Support.v7.AppCompat
  • Xamarin.Android.Support.v7.CardView
  • Xamarin.Android.Support.v7.RecyclerView

The new v7 assembly can be found in Intersoft.Crosslight.Android.v7 package which you can easily add to your project through NuGet. When the Intersoft.Crosslight.Android.v7 package is added to your project, NuGet will automatically resolve all required dependencies mentioned above.

Simplified Android Development

In addition to massive APIs and components, Crosslight Android Material introduces a much simpler programming pattern for building modern Android apps which are fundamentally different with the previous patterns in Crosslight Android Classic.

The following highlights the improved programming pattern introduced in Crosslight Android Material:

  • Fragment is now the first-class view context in Crosslight which you will use in most of your content view. As the result, all fragments now support navigation, both push and modal.
  • Activity is used only for the main view container such as drawer activity, and no longer required to define a content view.
  • Simple set-able properties and object models are introduced in favor to member overrides. For example, to set interaction mode of a list view, you can simply use this.InteractionMode = ListViewInteraction.None instead of overriding the InteractionMode property.
  • Working with view elements such as adding bar items can be done with simple API in favor to separate AXML definition.
  • Back button is no longer a concern in Crosslight Android. It's automatically visible when the target view is navigated either with push or modal mode.

To grasp a quick idea how a view implementation looks like in Crosslight Material, see the following example.

As seen in the code above, creating a Material-enabled view with the new Crosslight Material library is dramatically easier and simpler. More information on Material views and migration guide from Crosslight Android Classic will be discussed in the latter section in this page.

Supported API Level

Material Design can be used in Android version 2.1 and newer via the v7 AppCompat library, which is used on virtually all Android devices that were made after 2009. However, to take advantage of all Material experiences, it is recommended to target version 5.0 (API 21+), where as the tested minimum version using Crosslight Android Material is version 4.0.3 (API 15). Furthermore to maintain backward compatibility with previous version you can follows the guide in the following article: Maintaining Compatibility.

Applying Material Theme

Crosslight Android Material provides two built-in Material themes that you can easily apply to your Android projects:

  • Theme.Crosslight.Material.Light which inherits from the standard Theme.AppCompat.Light.NoActionBar theme.
  • Theme.Crosslight.Material which inherits from the standard Theme.AppCompat.NoActionBar theme.

Other standard themes in Google v7 support library which still depend on classic ActionBar are not supported as Crosslight Android Material is solely designed with Toolbar and Collapsing Toolbar for the best, modern user experience.
The following illustration shows a Crosslight Android Material application with default theme applied.

In addition, Crosslight Android Material theme also provides additional predefined styles and key attributes that defines the default view definition used by Crosslight Android Material. The following are some predefined styles that Crosslight Android Material themes provides.

Button Style
The default button style is colored raised button instead of the default grey button.

Dialog Style
The default dialog style used the accent color defined in the application.

Progress Dialog Style
The default  progress dialog style used the primary and accent color defined in the application.

You can use this theme in your AndroidManifest.xml as follows.

You can also inherit the theme and define your own style if needed. Customizing the theme is discussed in the latter section below.

Understanding Material Views

As seen in the overview diagram earlier, Material Views is the core building block in the Android Material library which mainly comprised of Activity and Fragment classes. Crosslight Android Material introduces a better view design pattern that emphasizes clear separation-of-concern, where Activity is now designed to represent view containers while Fragment is used to represent view content.  

The improved design pattern eliminates the confusion of having multiple view contexts such as FormActivity and FormFragment, ViewPagerActivity and ViewPagerFragment, and more importantly, addressed the complexity in determining when to use Activity or Fragment.

The following table highlights the design pattern comparison between the classic and the new Material view.

Crosslight Android Classic / Xamarin NativeCrosslight Android Material
Requires to define multiple view context for a screen, Activity and Fragment.Focused solely on Fragment for content view.
Fragment is not navigable.Fragment is navigable, both push and modal are supported.
Overlapping Activity and Fragment functions, leading to anti-pattern.Clear separation-of-concern.

Activities

With Crosslight Android Material, defining views is a lot simpler. You only need to deal with 3 types of Activity classes which are:

You typically use these activities in the root views of your Android app, or when a different container is required to accomplish a specific task such as presenting global search view. In the case where your application has multiple root views such as in Login and Home (which shown after login), then you will need to use activities for Login and Home. For everything else, you can use fragments instead.

Fragments

With the improved view design pattern, it becomes clear that activity will only serve as container and all view content should be defined in fragments. Crosslight Android Material provides several fragment classes that you can use for your view content. The following are the list of available fragment classes in Crosslight Android Material.

  • FragmentBase
    Fragment without predefined layout, provides API to customize fragment behavior. 
  • RecyclerViewFragment
    Fragment with predefined list layout, inherits from FragmentBase. 
  • SearchableRecyclerViewFragment
    Fragment with predefined list layout with search capability, inherits from RecyclerViewFragment. 
  • GridViewFragment
    Fragment with predefined grid layout, inherits from RecyclerViewFragment. 
  • FormFragment
    Fragment with predefined form builder, inherits from FragmentBase. 
  • MasterDetailFragment
    Fragment with predefined master detail layout, inherits from FragmentBase. 
  • DetailFragment
    Fragment with predefined detail layout, inherits from FragmentBase. 
  • SplitFragment
    Fragment with predefined master detail layout, with independent toolbar, inherits from FragmentBase. 
  • TabFragment
    Fragment with predefined tab layout, inherits from FragmentBase. 
  • ViewPagerFragment
    Fragment with predefined view pager layout, inherits from FragmentBase. 
  • ViewSliderFragment
    Fragment with predefined image slider layout, inherits from FragmentBase. 
  • MapFragment
    Fragment with predefined map layout, inherits from FragmentBase. 

A variety of Material features that can be generally applied to all fragments can be found in the FragmentBase class. To learn more, please refer to Using Material Fragment.

Understanding Material Components

All fragments introduced in Crosslight Android Material have been thoroughly designed to comply with Material design guidelines by providing default elements structure and various APIs to customize the Material components and features available in each fragment. Some of the Material components integrated to the fragments are as follows.

Toolbar

Collapsing Toolbar

 

Shared Transition

Floating Action Button

Action Toast Presenter

Grid View


To learn more how to use these Material components and enable the features, see Using Material Fragment.

Customizing Theme And Resource Overrides

As mentioned earlier, Crosslight Android Material provides two basic theme.

  • Theme.Crosslight.Material.Light 
  • Theme.Crosslight.Material

To learn more about the values definition in these themes along with other built-in layout, see Crosslight Android Material Theme Reference.

After learning the theme definition and other resources, you can then customize the theme according to your need. When customizing the theme, you'll encounter some attribute values that are linked to a resource value.

styles.xml
colors.xml

As seen in the above example, the colorPrimary attribute is set to color/primary which is defined in colors.xml. Since the resource value is used, you can easily override the value directly in your application by re-declaring the colors.xml in your application. This means that you don't need to re-create the styles and require only minimum configuration to customize the primary color of your application. Note that there are many other resource value that you can override.

In most cases, you can simply customize the theme to suit your application's branding by overriding the values. However, if you wish to go beyond the Material theme customization provided in Crosslight, please refer to this document: http://developer.android.com/guide/topics/ui/themes.html

Get Started

At this point, you have learned the main concepts and key components and features introduced in Crosslight Android Material. Get started with Crosslight Android Material is easy, please refer to the links below based on your interest.

TaskGo to
Migrating your existing Crosslight Android project to Material.Migrating from Crosslight Android Classic
Creating a new Crosslight solution containing Android Material project along with other platforms.Getting Started with Crosslight
Learn more about Crosslight Android Material view concept and life cycle.Getting Started with Crosslight Android Material
Learn more about general Material features available in Crosslight Android Material.Using Material Fragment

Samples

Exploring working samples is often the fastest and most effective way to learn and get started with Crosslight Android Material. Please check out the following samples (recommended in order from top to bottom):

Basics

App References

To check out more advanced samples, please visit http://git.intersoftsolutions.com/projects/cs.