Your Android app should have an AppInitializer class which should implement the Intersoft.Crosslight.IApplicationInitializer interface, as follows. By default, Crosslight provides the class in Infrastructure folder.
The AppInitializer class provides methods that connect the application to the core services in the shared application layer and prepares the necessary configuration for your application during startup.
At this point, your Android project should be ready and you can start adding specific functionalities to your application.
Adding MVVM-enabled Fragments to Your Project
Assuming that the ViewModel and binding provider ready at the shared application layer, you may want to start creating activities that consume the ViewModel and present them in your Android application. Creating a fragment that can consume the ViewModel and optionally creating the view are the two steps you will probably want to take.
As explained earlier, the fragment in Android represents the controller in the MVC design pattern. In Crosslight, the fragment is implemented as the view context. The view context has a number of important responsibilities such as estabilishing connection the view model, perform automatic binding registration and disposal, and more. Consequently, Crosslight ships with a vast array of activities that include built-in ViewModel support which hides the complexity of the fragments and position the ViewModel to serve as the actual mediator that serves between the model and view – as in common MVVM applications. This is the power of Crosslight. With this common ground in mind, Crosslight will streamline all of users interaction in the application just by interaction in the view model level.
The most basic fragment in Crosslight Android is Fragment<TViewModel>. The following code shows the example of an fragment that consumes LoanCalculatorViewModel in the shared application layer as its view model and loads the LoanCalculatorView.axml to its view hierarchy.
The ImportBinding attribute instructs the fragment to automatically import binding definitions from the specified binding provider. This allows you to streamline all your binding definitions to logical class, and reuse them in cross platform projects. For more information, see Importing Binding Providers to View.
In Android fragment need to be hosted by an Activity. To launch the above fragment you need to have an activity inherited AppCompatActivity that target the same view model as follows.
You can also host the fragment in DrawerActivity when you want to have navigation drawer in your fragment.
Common View Context Members
Every view context implementation shares common characteristics such as the ViewModel property which returns the same type as defined in the class generic template. Since you can access the ViewModel instance that associated to the view controller at runtime, you are open to write your own custom implementation in case you developed your own controls that are not covered in the pre-built Crosslight binding adapters.
In addition to the ViewModel property, there are a number of methods that you can override to intercept a particular life cycle of the view context. The following list describes the virtual methods ordered by the life cycle sequentially.
By default, Crosslight already ships with default implementation for the above methods. In most cases, you override the InitializeView to perform additional initialization to the view such as creating a view element at runtime or configuring the view background. The following example shows how to set the view's background in InitializeView method.
Registering a View Identifier at Runtime
Previously, you’ve learnt how to define android:id for a view using IDEs (Visual Studio 2012, Xamarin Studio or Android Studio). Aside from assigning the views explicitly using IDEs, there are often times that you want to create views dynamically at runtime and assign an android:id to it.
To achieve this scenario, Crosslight provides a method that you can use to register an android:id to a view element at runtime. Once the view is associated to an identifier, it will work normally as if it were defined using the IDE. This means that any binding definitions that target the particular identifier will be applied consistently.
The following example shows how to create a Button view and register an android:id to it. The most ideal place to initialize additional view-related tasks is during the InitializeView lifecycle of the view context.
This powerful feature lets you achieve virtually any complex scenarios that involve dynamic view creation at runtime while leveraging the sophisticated data binding features in Crosslight.
Registering Binding Description Manually
The most recommended way to register binding definitions to your view is by importing the binding provider through the ImportBinding attribute such as explained in the earlier sections. However, there are times when it’s not ideal to register the binding definitions in the binding provider. For instance, in the case when a particular definition applies only in Android project, it makes perfect sense to register the definition only in the particular fragment.
To add binding description manually in an fragment, you use one of the AddBinding method overloads such as shown in the following example.
Setting Bindable Property Value at Runtime
One of the basic tasks that you may encounter is the setting bindable properties value at runtime. In most cases, bindable property is used during binding definition – typically in the binding provider class. Since a bindable property can participate in two-way binding mode – either the value is propagated from the model or from the control – it is possible for you to modify the value at runtime.
You use the SetPropertyValue extension method to set the value to a particular bindable property. In two-way binding mode, setting the property mode will reflect the control’s intrinsic value and automatically synchronize the new value to the model.
The following example shows how to set the Text property to an EditText which the system to set the text to the EditText and update to model.
At times, you may want to handle rotation event in a fragment. Handling rotation in your Android application can be done by overriding the OnSaveInstanceState method. The following code shows how to do so:
An easy way to prevent recreation of the views during rotation is by specifying the ConfigurationChanges property in your Activity attribute. This is useful to prevent views from being recreated on rotation.
Android Project Properties
Each Android application will need to have a file called AndroidManifest.xml which presents essential information about the application to the Android system, information the system must have before it can run any of the application's code. Most of the time you will not need to edit this document by hand. Xamarin provides feature such as editing of the application name, package name, version number and name, install location, permission required by the application, etc., through the Project Properties window in Visual Studio 2012 or Xamarin Studio. The following screenshot shows how it looks like in Visual Studio 2012:
The following screenshot shows editing of the AndroidManifest.xml in Xamarin Studio through project options:
Laying Out Content in Android
In most cases, it is recommended you lay out all views using the ScrollView widget, since Android devices vary in sizes and supported screen resolutions, a long text in a TextView may not have enough space to be rendered in devices with smaller resolutions. This is one of the reasons the Android Studio is recommended for designing your view as you can see how it will be rendered out in many devices with different resolutions at once. See the previous Android Studio topic for more information.
Best Practices for Designing on Android Platform
Developers may want to consult Best Practices for User Experience & UI documentation on Android Developers for more information on best practices when designing for Android platform. However, since Crosslight is designed to conform to best match Android navigation experience, you will mostly only need to design Android XMLs for your views. It is recommended you go through these topics prior to designing:
- Designing for Multiple Screen
- Pure Android
- Supporting Tablets and Handsets
The concepts from Android Developers website can be directly implemented to Crosslight, as the views are separated from the main fragment logic since Android uses a very flexible layouting scheme, which allows designers to work on the layouts separately through XMLs.