Skip to end of metadata
Go to start of metadata

Follow this walkthrough to migrate your Crosslight Android Classic to Crosslight Android Material. At the end of this tutorial, you should have the following result:

Samples:

basic-inventory.zip

Follow these steps:

Prerequisites

It is recommended that you have read through these conceptual topics in order to get a better understanding:

To use this walkthrough, you will need to use at least Crosslight version 5.0.500.543 in order to achieve the desired result.

Let's get started. 

Configuring Your Project

  1. Open your Crosslight Android Classic application. In this walkthrough, let's try to migrate the MyInventory classic sample to the new Crosslight Android Material.
  2. Open the project properties, and set the TargetFramework to Android 5.0 (Lollipop)
  3. Afterwards, set the Minimum Android version to 4.0.3 (API Level 15) and Target Android version (API Level 21)

  4. Install the Crosslight Android v7 NuGet Package using the Intersoft Package Manager Console. 

    To learn more on how to use Crosslight NuGet Packages, see Introduction to Crosslight NuGet Packages.

    To use the Intersoft Package Manager Console, you need to have properly installed Intersoft Mobile Studio 2016 and above.

  5. Ensure that the Crosslight references and its dependencies are properly installed.

Applying Crosslight Android Material Theme

  1. To properly incorporate Android Material theme to your application, you can simply use one of the two built-in Crosslight themes that are designed specifically for Material Design: Theme.Crosslight.Material and Theme.Crosslight.Material.Light. It is most recommended to use the default Theme.Crosslight.Material.Light theme. 

  2. Copy-paste the following code to the colors.xml file located inside Android/Resources/values/ folder.

  3. Clean up old styles or resources as they are no longer relevant.

Converting Your Activities and Fragments to Crosslight Material Fragments

There are several fundamental principles when converting classic Activities to new Material Fragments:

  • Activity is now only used as view container and very minimal Activities definitions are needed. In most cases, you'll only need StartActivity, DrawerActivity, and SearchActivity.
  • Configuring layout id and other properties and behaviors still use property overrides.
  • Assigning values that are considered as settings should be done in the Initialize method (override as needed) in the Fragment level and you can directly set the property there.
  • To configure bar items, you can still use menu AXML. Although, it is very much recommended to use the new Crosslight Android Material's new API with predefined CommandItemTypes which will allow you to define bar items easily.
  • Crosslight Android Material provides you with some built-in layout and styles so you do not need to provide it, unless you want to change it. See the complete reference here: Crosslight Android Material Theme Reference.
  • To learn how to configure more settings and behaviors introduced in Material Fragment, see Defining Android Material Views.

  1. Converting ListActivity. 
    Since the ListActivity is the main Activity, this needs to be converted into an Activity for view container and Fragment as it content view. For example, here's how the old ItemListActivity looks like.

    Classic ItemListActivity


    Here's the new file AppCompatActivity that will act as the view container. You can safely remove the previous ItemListActivity and replace it with the new AppCompatActivity.

    Material AppActivity


    Introduce a new ItemListFragment that inherits the new SearchableRecyclerViewFragment available in the v7 library.

    ItemListFragment

  2. Converting ItemEditActivity. The old FormActivity used to look like this.

    Classic ItemEditActivity


    You can safely delete the file altogether and replace it with the new FormFragment. With the new Crosslight v7 library, you don't have to deal with creating Activities anymore. Also, you don't have to specify the ShowActionBarUpButton behavior as this is automatic. You need to provide a new constructor overload that accepts one IntPtr object and one JniHandleOwnership object as this is needed for Fragment initialization.

    Material ItemEditFragment

    To add the bar item, you can simply take advantage of the new AddBarItem method that is provided in the new Fragment library. You can use this API in all Fragments existed in the new v7 library. Now that you've got your new FormFragment ready, let's proceed by converting ViewImageActivity next.

  3. The old ViewImageActivity used to look like this.

    Classic ViewImageActivity

    Let's convert this to a Fragment instead.

    Material ViewImageFragment

    At a first glance, the new Fragment definition seems longer and more tedious. However, it is more consistent. Previously, it was quite confusing determining which view context can accept a layout ID in the constructor, and which ones cannot. In this new library, the process is streamlined to overriding ContentLayoutId instead, making it more consistent, no matter what view context you're dealing with. Next, let's upgrade the look and feel of the existing item list to use CardView. Open up the item_layout.axml inside the Resources/layout folder and use the following code.

    You can now take advantage of modern view libraries and properties available in v7 libraries, such as the CardView and view properties like app:cardElevation to give your apps a modern Material look.

Conclusion

Congratulations! You've just finished migrating your MyInventory application from classic android to Material Android.

Sample

You can check out the old project here: http://git.intersoftsolutions.com/projects/CROS/repos/samples/browse/MyInventory and the new project here: http://git.intersoftsolutions.com/projects/CS/repos/basic-inventory/browse.

If you wish to run the sample, simply download the new project and open using Xamarin Studio or Visual Studio and hit Run.

 

Related Topics