Intersoft Solutions Corporate Blog » Tips and Tricks

Using Crosslight Location Service in iOS 8

Yudhiy Ariawan — Mon, 15 Aug 2016 06:05:56 +0000

Using Crosslight Location Service

Location service provides a streamlined way to access location API that conforms to each the device’s platform. In order to get the current location of the device, we use following snippet code:

this.MobileService.Location.GetCurrentLocation(LocationAccuracy.Best,
    (locationResult) =>
    {
        if (locationResult.Error == null)
		{
		}
        else
		{
		}
    });

This method translate to, get the current location of the device, with best accuracy.

Problem: My app doesn’t returns current location. Why?

Some of you might found out that the code fails silently. You will get no error or warning, but it will never get a location update. The app will never even ask for permission to use location.

It took me a while until I found that we need to add a key to Info.plist and request authorization from the location manager asking it to start. It’s an iOS 8 (and later) related issue. The key, NSLocationWhenInUseUsageDescription, is required when you request authorization for location services. If this key is not present, the system ignores your request and prevents your app from using location services.

Solution: Asking user’s permission to access their location

So we’ll need to add the key to the Info.plist file. It takes a string which is a description of why the app need location services. We can enter a string like “Location is required to find out where you are”.





	...
	NSLocationWhenInUseUsageDescription
	Location is required to find out where you are.

Save the changes and re-run the app. Your app will now requesting permission by showing a popup.

Hopefully this post may helps developers using location services on iOS 8 (or later). If you have questions or feedback please feel free to submit in the comments section below.

Regards,
Yudi

Getting Started with Crosslight Collection Views and Grid Views

Arief — Thu, 26 Nov 2015 09:32:18 +0000

Hi guys, Arief here from the Intersoft Consultant team. Today I will talk about how to use iOS Collection View and Android Grid View in order to create a beautiful cross-platform navigation menu. At the end of this tutorial, you’ll learn how to use the collection view in your Crosslight applications, which looks similar to the following illustration.

Introduction

Collection View / Grid View (will be referred as Collection View from now on) is a very versatile user interface. As a matter fact, both iOS and Android have always been using it as a native pattern for Springboard (iOS home) as well as lots of other Android launchers. Nowadays those trends start to spread throughout business apps considering how user-friendly and eye-pleasing when compared to the plain old list view.

If you are interested in creating a gorgeous and cool business apps, using collection view is a must! In this tutorial, I will guide you step by step how you can create collection view using the Crosslight style.

Here are the steps that you need to follow:

Core Preparation
Assets Preparation
Designing Android Grid View
Designing iOS Collection View
Capturing Selection

Without further ado, let’s get started!

Preparing the Project

The first thing you’ll need is, of course, the project itself. Start by creating a new project using Crosslight Project Wizard and choose the Blank template. To do this, from Visual Studio 2012 and upwards, choose New, Project. From the dialog that appears, choose Crosslight and choose to create a new Crosslight application with the Blank template. For the purposes of this tutorial, we’ll name this project: CollectionView. Now that you have your project ready, let’s move on.

Core Preparation

Here are several things you need to prepare at the project Core level:

Prepare the ViewModel
Prepare the BindingProvider

Prepare the ViewModel

Begin by creating a new ViewModel in CollectionView.Core/ViewModels folder. Simply right-click on the ViewModels folder and choose Add, New Item. We will be repeating this method several times in later sections to add new items to our project, so keep this in mind.

Crosslight also ships with built-in item templates that are integrated with Visual Studio, so you can quickly create Crosslight classes right within Visual Studio or Xamarin Studio. In the next dialog that appears, choose Visual C#, Crosslight, then choose Crosslight List View Model. Name this ViewModel as CollectionViewModel.

Copy-paste these codes to the newly-created CollectionViewModel.cs:

using Intersoft.Crosslight;
using Intersoft.Crosslight.ViewModels;
using System.Collections.Generic;

namespace CollectionView.Core.ViewModels
{
    public class CollectionViewModel : ListViewModelBase
    {
        #region Constructors

        public CollectionViewModel()
        {
			List items = new List();

			items.Add(new NavigationItem("Ride", typeof(SimpleViewModel)) { Image = "CrosstransRide.png" });
			items.Add(new NavigationItem("Delivery", typeof(SimpleViewModel))  { Image = "CrosstransDeliver.png" });
			items.Add(new NavigationItem("Food", typeof(SimpleViewModel))  { Image = "CrosstransFood.png" });
			items.Add(new NavigationItem("Shop", typeof(SimpleViewModel))  { Image = "CrosstransShop.png" });

			this.SourceItems = items;
        }

        #endregion
    }
}

Let’s take a quick look at the above code. In the constructor of the CollectionViewModel, we initialize a list of NavigationItems that holds the navigation menus. NavigationItem is a very useful class provided by Crosslight that you can utilize to create a menu, as it holds all the common properties you need to create a navigation item. All you have to do is simply populate it with the menu title, image/icon name, and the target ViewModel as navigation target.

Preparing the BindingProvider

Next step would be adding a new Crosslight List Binding Provider under your CollectionView.Core/BindingProviders folder. Give it a name of CollectionBindingProvider.cs.

And change the code to the following:

using Intersoft.Crosslight;

namespace CollectionView.Core.BindingProviders
{
    public class CollectionViewBindingProvider : BindingProvider
    {
        #region Constructors

        public CollectionViewBindingProvider()
        {
            ItemBindingDescription itemBinding = new ItemBindingDescription
            {
                DisplayMemberPath = "Title",
                ImageMemberPath = "Image",
                NavigateMemberPath = "Target"
            };

            this.AddBinding("GridView", BindableProperties.ItemsSourceProperty, "Items");
            this.AddBinding("GridView", BindableProperties.ItemTemplateBindingProperty, itemBinding, true);
            this.AddBinding("GridView", BindableProperties.IsBatchUpdatingProperty, "IsBatchUpdating");
            this.AddBinding("GridView", BindableProperties.SelectedItemProperty, "SelectedItem", BindingMode.TwoWay);
            this.AddBinding("GridView", BindableProperties.SelectedItemsProperty, "SelectedItems", BindingMode.TwoWay);
            this.AddBinding("GridView", BindableProperties.IsEditingProperty, "IsEditing", BindingMode.TwoWay);

            this.AddBinding("RefreshButton", BindableProperties.RefreshCommandProperty, "RefreshCommand");

            // navigation
            //this.AddBinding("TableView", BindableProperties.DetailNavigationTargetProperty, new NavigationTarget(typeof(TViewModel)), true);

            // edit commands
            this.AddBinding("AddButton", BindableProperties.CommandProperty, "AddCommand");

            this.AddBinding("DeleteButton", BindableProperties.CommandProperty, "DeleteCommand");
            this.AddBinding("DeleteButton", BindableProperties.CommandParameterProperty, "SelectedItems");
        }

        #endregion
    }
}

In the above code, we simply comment out the DetailNavigationTargetProperty, as it won’t be needed because our goal is only to create a navigation menu. It will be needed if you want to create Master-Detail Navigation. We also assign the MemberPaths with the properties from NavigationItem, such as ImageMemberPath for the icon, DisplayMemberPath for displaying the title, and NavigateMemberPath for the target ViewModel menu. To learn more about Crosslight Binding Provider, check out this link.

Your Core is up and ready. Let’s prepare our assets next.

Assets Preparation

Previously in the Binding Provider, you have already specified the Image property in NavigationItem from ViewModel which contains the filename for the .png file that we will use. When you bind it to the BindableProperties.ImageProperty or ImageMemberPath, it will find the appropriate files to use in CollectionView.Android/Resources/drawable or in CollectionView.iOS/Resources. So you need to put these files inside both folders because we will be using it for our app’s interface.

Tip: Make sure to optimize the size of your image files. In some phones, images with humongous file size will be ignored and they won’t show. Okay, since you have finished preparing the assets, let’s continue to Android GridView!

Designing Android GridView

Designing a view for Android is relatively easy and simple. In overall, we’ll be doing these tasks:

Create an Activity for CollectionActivity.
Create the view layout.
Define the ContentLayoutId and ItemLayoutId.

To start, simply add a new item and use Crosslight Android Activity to get started. Put it inside the CollectionView.Android/Activities folder and name it CollectionActivity.cs.

After your CollectionActivity is created, change the contents of the class to the following code.

using Android.App;
using Intersoft.Crosslight;
using Intersoft.Crosslight.Android;

namespace CollectionView.Android.Activities
{
    [Activity(Label = "Menu")]
    [ImportBinding(typeof(CollectionBindingProvider))]
    public class CollectionActivity : GridActivity
    {
        public override ListViewInteraction InteractionMode
        {
            get{ return ListViewInteraction.Navigation; }
        }

        protected override int ContentLayoutId
        {
            get{ return Resource.Layout.CollectionLayout;}
        }

        protected override int GridItemLayoutId 
        {
	       get{ return Resource.Layout.ItemLayout; }
	    }

        protected override void InitializeView()
        {
            base.InitializeView();
            this.GridView.NumColumns = 2;
        }
    }
}

We need to replace the Activity with GridActivity, in which then you have more properties to override: ListViewInteraction. By overriding the ListViewInteraction into ListViewInteraction.Navigation, it allows the user to use the grid as a navigation button when an item is tapped.

ContentLayoutId is also overridden since we want to customize the appearance of our GridView, which we will do in just a moment. The ItemLayoutId is overridden to customize the item layout to be used with the GridView. Both ContentLayoutId and ItemLayoutId refers to Android layout files which exist in the CollectionView.Android/Resources folder.

Since we only have two columns for this scenario, we can simply provide the number of columns to show in the overridden InitializeView method by setting this.GridView.NumColumns to 2. The advantage of using this method is: you actually don’t need to specify the width of the Grid. The GridActivity automatically adjusts the optimal number of items by taking account the viewport width.

Earlier, we’ve specified the ContentLayoutId and ItemLayoutId in our Activity. Now let’s create those layouts. You will need to create two layouts inside CollectionView.Android/Resources/layout folder using Android Layout item template. We will name it CollectionLayout.axml & ItemLayout.axml.

Here’s the code for CollectionLayout.axml and ItemLayout.axml respectively.

From the designer’s view, the CollectionLayout looks like the following:

and here’s the contents for ItemLayout.axml:

From the designer’s view, it looks like this:

In summary, what I do in CollectionLayout.axml is setting the background for the page, add a header, and provide enough spacing between GridView items. The most important things to note is I’ve defined the GridView id, @+id/GridView. The will be the reference that we defined in BindingProvider to the property in ViewModel, so make sure the id name is right!

We will be doing a similar task with ItemLayout.axml, where we assign both ImageView to the Image Property in ViewModel and TextView to Title Property in ViewModel. By default, Crosslight provides two built-in ids for showing an image and a text for item template, which has the name ImageView and TextLabel respectively. But if you want to add additional view elements to the item template, then you can simply add a new binding definition in the binding provider like this which must be done in BindingProvider:

itemBinding.AddBinding ("CustomView", BindableProperties.TextProperty, "Title");

Run the project. You should get a result similar to the following:

http://blog.intersoftsolutions.com/wp-content/uploads/2015/11/2015_11_27_09_11_14.mp4

Next, let’s create the iOS version.

Designing iOS CollectionView

Similar to Android, building CollectionView on iOS follows a pretty similar path:

Create a ViewController for MainCollectionView.
Create the cell and the header.
Set the outlets.

Let’s start from the ViewController. Add a new item using Crosslight iOS Collection View Controller template and put it inside your CollectionView.iOS/ViewControllers folder and name it MainCollectionView.cs.

This is the code for the ViewController.

using CollectionView.ViewModels;
using CollectionView;
using Intersoft.Crosslight;
using Intersoft.Crosslight.iOS;
using Foundation;
using UIKit;

namespace CollectionView.iOS
{
	[Register ("MainCollectionView")]
	[ImportBinding (typeof(CollectionBindingProvider))]
	public class MainCollectionView : UICollectionViewController
	{
		#region Constructors

		public MainCollectionView ()
			: base ("MainCollectionView", null)
		{
		}

		#endregion

		#region Properties

		public override UIViewTemplate CellTemplate {
			get { return new UIViewTemplate (CollectionViewCell.Nib); }
		}

		public override CollectionViewInteraction InteractionMode {
			get { return CollectionViewInteraction.Navigation; }
		}

		public override bool ShowSectionHeader {
			get { return true; }
		}

		public override UIViewTemplate SectionHeaderTemplate {
			get { return new UIViewTemplate(CollectionHeader.Nib); }
		}

		#endregion

		#region Methods

		protected override void InitializeView ()
		{
			base.InitializeView ();

			this.NavigationItem.Title = "Home";
                        UIImageView backView = new UIImageView(UIImage.FromFile ("CrosstransBg.png")); 
                        backView.ContentMode = UIViewContentMode.ScaleAspectFill; 
                        this.CollectionView.BackgroundView = backView;
			// Register Views
			this.RegisterViewIdentifier ("GridView", this.CollectionView);
		}

		#endregion
	}
}

Let’s take a look at some of the overridden methods and properties.

CellTemplate: This property is the equivalent of Android’s ItemLayoutID, which will define the view to be used as navigation item inside the Collection View.
InteractionMode: This method is the equivalent of Android’s ListViewInteraction, that defines the interaction when users tap on the navigation item.
SectionHeader & SectionHeaderTemplate: It will be used to specify the header for the Collection View.
InitializeView: This method is called when the view is initialized. Here, we set the background view of the Collection View. Afterward, this.RegisterViewIdentifier (“GridView”, this.CollectionView); is used to associate the Collection View with the GridView view identifier to be used by the Binding Provider.

Now your view controller is done! Next, we’ll create the CollectionView Header and Cells. Inside your CollectionView.iOS/Views, add 2 new items: Crosslight iOS Collection Cell, we will name it CollectionViewCell.cs (feel free to choose between iPhone or iPad) and Crosslight iOS Collection View Group Header which we will name it CollectionHeader.cs.

If you check back your MainCollectionView.cs, you can see that both CollectionViewCell.Nib & CollectionHeader.Nib are now detected. The Nib represents both .cs files that we’ve created before. However, we won’t touch any codes, instead we will play around with the layout using iOS XCode.

Let’s first open the MainCollectionView.xib inside your CollectionView.iOS/Views using Apple XCode. Inside the Document Outline, you can select File’s Owner, then the Identity Inspector will change according to what you selected. Specify the Custom Class as MainCollectionView.

Using the Connections Inspector, control + drag the view from Outlets to the Collection View to set the outlet, as shown in the following illustration.

Then, in the File Inspector, turn off Auto Layout.

In the Size Inspector, specify the cell’s width and height, also adjusting the auto-resizing behaviors so that it will layout nicely when the device is rotated.

Now you are done configuring your MainCollectionView.xib.

Let’s continue to CollectionViewCell.xib, in this case, you don’t need to worry about your File’s Owner, Simply drag and drop a Label and ImageView from the Object Library to the view.

Select your Label (or anything in your designer interface), Press the conjoined circle button on the right top. A panel with codes will appear, this is the Assistant Editor which will help you create Binding without having you to code anything.

Next, let’s set the outlets using the Assistant Editor. Select your CollectionViewCell.m and change it to CollectionViewCell.h, control + drag your Label into the panel and give it TextLabel as a name, then set the ImageView outlet with the name of ImageView.

You need to turn off the auto layout from both image, label, and their parent to use auto resizing. Here’s what I’ve done to each of them:

View: Change the background color, turn on the horizontal and vertical scaling so that it won’t grow or shrink when the display rotates.
TextLabel: Change the alignment to the middle, Pin it to the bottom using auto resizing and change the width to 120 and height to 50
ImageView: Change the view mode to Aspect fit, turn on the horizontal and vertical arrow inside auto-resizing, and changes the width and height to 60

In CollectionHeader.xib, what we do is just drag and drop an ImageView. Here are the settings for ImageView:

Change the image with CrosstransLogo.png,
View Mode to Aspect Fit,
Width = 150,
Turn on the horizontal and vertical arrow inside auto resizing

Here is the result:

http://blog.intersoftsolutions.com/wp-content/uploads/2015/11/Crosstransios.mp4

Your app is pretty much done, but we still ned to capture what user has selected.

Capturing Selection

In this section, we’ll learn how to capture selection made when the user taps on any of the navigation items.

If you recall earlier, we’ve defined how our CollectionView should navigate, which is done in our BindingProvider in the NavigateMemberPath inside using ItemBindingDescription.

ItemBindingDescription itemBinding = new ItemBindingDescription
            {
                DisplayMemberPath = "Title",
                ImageMemberPath = "Image",
                NavigateMemberPath = "Target"
            };

As you are aware, each MemberPath represents the component of our menu. In fact, it also contains the whole data associated with the specific Item you choose from the list that you have created in your ViewModel back then.

public CollectionViewModel()
        {
			List items = new List();

			items.Add(new NavigationItem("Ride", typeof(SimpleViewModel)) { Image = "CrosstransRide.png" });
			items.Add(new NavigationItem("Delivery", typeof(SimpleViewModel))  { Image = "CrosstransDeliver.png" });
			items.Add(new NavigationItem("Food", typeof(SimpleViewModel))  { Image = "CrosstransFood.png" });
			items.Add(new NavigationItem("Shop", typeof(SimpleViewModel))  { Image = "CrosstransShop.png" });

			this.SourceItems = items;
        }

BindingProvider will obtain the target of your navigation, represented by typeof(SimpleViewModel)). However even though we already successfully navigate, in our case each of our Item have the same Navigation target. What if we want to know which item/menu is selected? Here is how:

When you navigate to a new ViewModel, the Navigated method is called in the target ViewModel, and it contains the sender value which holds the information of the caller ViewModel. For the simplicity of this tutorial, we’ll change the SimpleViewModel to handle user input. Let’s change our SimpleViewModel.cs (CollectionView.Core/ViewModels folder):

using Intersoft.Crosslight;
using Intersoft.Crosslight.Input;
using Intersoft.Crosslight.ViewModels;

namespace CollectionView.ViewModels
{
    public class SimpleViewModel : ViewModelBase
    {
        #region Fields

        private string _footerText;
        private string _greetingText;
        private string _newText;

        #endregion

        #region Properties

        public string FooterText
        {
            get { return _footerText; }
            set
            {
                if (_footerText != value)
                {
                    _footerText = value;
                    OnPropertyChanged("FooterText");
                }
            }
        }

        public string GreetingText
        {
            get { return _greetingText; }
            set
            {
                if (_greetingText != value)
                {
                    _greetingText = value;
                    OnPropertyChanged("GreetingText");
                }
            }
        }

        public string NewText
        {
            get { return _newText; }
            set
            {
                if (_newText != value)
                {
                    _newText = value;
                    OnPropertyChanged("NewText");
                }
            }
        }

        public DelegateCommand ShowToastCommand { get; set; }

        #endregion

        #region Constructors

        public SimpleViewModel()
        {
            IApplicationContext context = this.GetService().GetContext();
            if (context.Platform.OperatingSystem == OSKind.Android)
                this.GreetingText = "Hello Android from Crosslight!";
            else if (context.Platform.OperatingSystem == OSKind.WinPhone)
                this.GreetingText = "Hello WinPhone from Crosslight!";
            else if (context.Platform.OperatingSystem == OSKind.WinRT)
                this.GreetingText = "Hello WinRT from Crosslight!";
            else if (context.Platform.OperatingSystem == OSKind.iOS)
                this.GreetingText = "Hello iOS from Crosslight!";

            this.FooterText = "Powered by Crosslight®";
            this.ShowToastCommand = new DelegateCommand(ShowToast);
        }

        #endregion

        #region Methods

        public override void Navigated (NavigatedParameter parameter)
        {
            if (parameter.Sender is CollectionViewModel) 
            {
                this.ToastPresenter.Show("You are choosing: " + (parameter.Sender as CollectionViewModel).SelectedItem.Title);
            }
        }

        private void ShowToast(object parameter)
        {
            this.ToastPresenter.Show("You entered: " + this.NewText);
            this.GreetingText = this.NewText;
        }

        #endregion
    }
}

The menu that user chooses will be represented by SelectedItem and there are two things to note here: SelectedItem actually obtained from the sender ViewModel which is from CollectionViewModel.cs and SelectedItem actually the default property provided from CollectionViewModel implementing the ListViewModelBase. In this case, we will show a toast presenter to indicate which menu the user has chosen, by obtaining the Title of SelectedItem and show it using Toast Presenter.

Also, If you put a breakpoint in the highlighted line above and inspect the NavigatedParameter, you can see from the shot below that it holds lots of information not only the SelectedItem but the whole CollectionViewModel.

You will use this neat trick to accomplish a lot of cool things using Crosslight, so don’t forget to save this favourite this blog for later uses. Okay, now let’s run our project!

Wait… should we also change the Android and iOS? No need at all using Crosslight you only need to change it in Core and it will be applied to each platform, very convenient! Here is the result:

http://blog.intersoftsolutions.com/wp-content/uploads/2015/11/2015_11_27_14_23_41.mp4

http://blog.intersoftsolutions.com/wp-content/uploads/2015/11/crosstransfull.mp4

Wrapping Up

With Crosslight, you will never have to worry about the code behind the scene. However, in this session, I want to emphasize the customizability of Crosslight, using minimal effort and codes we already successfully create a simple and gorgeous navigation menu. I believe the next steps for you is to discover more about Crosslight features and we still have more tutorials coming in the futures! So stay tuned with us and have fun!

You can find the source code for this post here: http://git.intersoftsolutions.com/projects/CT/repos/crosslightcollectionview/browse

See you in the next post,
Arief Handany

Creating Dockable View for iOS and Android

Nicholas Lie — Mon, 23 Nov 2015 11:51:49 +0000

In my previous post, I’ve shown you how to use a header and footer with custom views in a list/table view. Now, what if I want to show a dockable view at the bottom of the screen? Let’s take the previous sample a bit further to look like the following.

Starting off

To start off, I’ll just copy off the previous sample. If you haven’t read the previous post on how to provide header and footer to your TableView / ListView, it is highly recommended for you to do so before continuing.

If you have done so, let’s move on.

Creating dockable view on iOS

To create the dockable view on iOS, you’ll need to do the following:

Preparing custom table root view
Modifying the View
Modifying the View Controller

Preparing custom table root view

To provide the custom table root view, you’ll need to create a new Crosslight iOS View for iPhone, which is accessible from the Item Templates, available after you’ve successfully installed Crosslight.

Right click on the Views in HeaderAndFooter.iOS/Views folder and select Add, New Item.

Then choose, Crosslight iOS View for iPhone. Give it a name of CustomTableRootView.

First, let’s try to create a the custom table root view. Open the CustomTableRootView.xib in Xcode Interface Builder.

Adding the Docked View

Drag a new View from the Object library, set the outlet as DockedView, and provide the following constraints:

Horizontal Space Constraint: from Superview.Trailing equal to the View.Trailing with the following values.
Vertical Space Constraint: from Superview.Bottom equal to the View.Bottom with the following values.
Horizontal Space Constraint: from DockedView.Leading equal to the Superview.Leading with the following values.

Now that the docked view is ready, let’s drag a Label, set the outlet as TxtHeader, and drag a button, set the outlet as BthHeader. Both of them are given the previous outlet names, so that no code changes will be required in the BindingProvider side. If you wish, you can set the following constraints:

Give the DockedView a height of 45.
Vertically align the label as well as the button.
Give an inner padding of 20.

That’s pretty much it. Let’s modify the View a bit.

Modifying the View

Let’s open the CustomTableRootView.cs and modify that a bit by adding a new ResizeTableView method.

using System;
using System.Drawing;
using System.Linq;
using CoreGraphics;
using Foundation;
using UIKit;

namespace HeaderAndFooter.iOS
{
    public partial class CustomTableRootView : UIView
    {
        #region Constructors

        public CustomTableRootView(IntPtr handle) : base(handle)
        {
        }

        #endregion

        #region Fields

        public static readonly UINib Nib = UINib.FromName("CustomTableRootView", NSBundle.MainBundle);

        #endregion

        #region Methods

        public static CustomTableRootView Create()
        {
            return (CustomTableRootView) Nib.Instantiate(null, null)[0];
        }


        internal void ResizeTableView(nfloat top)
        {
            var tableView = this.Subviews.FirstOrDefault(o => o is UITableView);
            tableView.Frame = new CGRect(0, top, tableView.Bounds.Width, this.Bounds.Height - top - this.DockedView.Bounds.Height);
        }

        #endregion
    }
}

Here, we prepare a handy method to resize the table view when the view is used, called ResizeTableView. By calling this method, the TableView that contains this dock view will have its bounds re-adjusted. This is done so that the scrolling container in the TableView does not exceed the docked view. Take a closer a look at the contents of the method.

In line 36, we first search for the TableView that is added as a subview of the ViewController. In line 37, we set a new bounds for it, not changing the width at all, but just by adjusting the height by taking account the DockedView.Bounds.Height as well.

Modifying the View Controller

Next, open up the MainViewController.cs. Here’s the contents.

using CoreGraphics;
using Foundation;
using HeaderAndFooter.ViewModels;
using Intersoft.Crosslight;
using Intersoft.Crosslight.iOS;
using UIKit;

namespace HeaderAndFooter.iOS.ViewControllers
{
    [Register("MainViewController")]
    [ImportBinding(typeof(MainBindingProvider))]
    public class MainViewController : UITableViewController
    {
        #region Properties

        public override UIViewTemplate FooterViewTemplate
        {
            get { return new UIViewTemplate(CustomFooter.Nib); }
        }

        public override TableViewInteraction InteractionMode
        {
            get { return TableViewInteraction.Navigation; }
        }

        public override bool ShowGroupHeader
        {
            get { return false; }
        }

        public override UITableViewStyle TableViewStyle
        {
            get { return UITableViewStyle.Plain; }
        }

        public override bool UseCustomRootView
        {
            get { return true; }
        }

        #endregion

        #region Methods

        protected override void InitializeView()
        {
            base.InitializeView();

            // set navigation title
            this.NavigationItem.Title = "Crosslight App";
        }

        protected override UIView GetCustomRootView()
        {
            return CustomTableRootView.Create();
        }

        public override void ViewWillLayoutSubviews()
        {
            base.ViewWillLayoutSubviews();

            // adjust tableview frame based on top layout guide	
            ((CustomTableRootView)this.View).ResizeTableView(this.TopLayoutGuide.Length);
        }

        #endregion
    }
}

Here, we removed the overridden property for HeaderViewTemplate, since we’re going to use the new DockedView to replace the header. Therefore, we then override a new property called UseCustomRootView and return true.

After we’ve done that, we then override the GetCustomRootView() method to return the CustomTableRootView that we’ve just created by calling CustomTableRootView.Create();

The custom root view is one of the unique features introduced in Crosslight’s advanced UITableViewController. It allows you to easily replace the root view with a custom one with just a few property sets, while still retaining the developer experience and automatic binding feature. In the case above, when UseCustomRootView is returning a true value, the GetCustomRootView method will be automatically called when the controller is initializing.

Lastly, we override the ViewWillLayoutSubviews method. This method is called when a new subview is added to the ViewController, which can be done at any time, whether during ViewController creation or programmatically adding a subview at runtime, therefore, when the DockedView is added, we then call our handy method to resize the TableView so that the scrolling container wouldn’t “bleed” past the DockedView.

That’s it. Run the project and you should get the result similar to the following video.

http://blog.intersoftsolutions.com/wp-content/uploads/2015/11/iOS1.mp4

Creating dockable view on Android

Now that we’ve finished the iOS version, let’s create the Android version. To create the docakble view on Android, you’ll need to complete the following:

Preparing custom layout
Replacing the content layout in Activity

Preparing custom layout

First things first, let’s create a new Android Layout, and let’s name it CustomLayout.axml. To do this, right click on the HeaderAndFooter.Android/Resources/layout folder.

Select Add, New Item. Under Android, select Layout.

Provide the layout for the CustomLayout.axml as follows.

Let’s take a closer look. Here, we’ve used a RelativeLayout as the root ViewGroup and we’ve added 2 major elements to the RelativeLayout, which is a LinearLayout that will act as our DockedView and ListView.

At a glance, you might be wondering why the ListView is defined after the LinearLayout. This is purely for build purposes. The XML parser parses the text from top to bottom. Since in the ListView, we’ve defined android:layout_above=“@id/Footer”, the build will fail if the LinearLayout is not defined beforehand. Hence, the ListView is defined after the LinearLayout.

One important thing to notice that the ListView’s id is set to @android:id/list. This conforms the standard method to override the built-in ListActivity’s layout in native Android development itself. For more information on that topic, click here. This is done because in the ListActivity class, you can reference the ListView as simply as calling this.ListView, however since you’ve overridden the whole layout, then the ListView must be re-referenced this way so that the Android understands. Everything else is just standard Android layouting process.

Replacing the content layout in Activity

After the layout is prepared, let’s modify some codes in the Activity. Open up MainActivity.cs inside HeaderAndFooter.Android/Activities folder and see the contents as follows.

using Android.App;
using HeaderAndFooter.ViewModels;
using Intersoft.Crosslight;
using Intersoft.Crosslight.Android;

namespace HeaderAndFooter.Android
{
    [Activity(Label = "Crosslight App", Icon = "@drawable/icon")]
    [ImportBinding(typeof(MainBindingProvider))]
    public class MainActivity : ListActivity
    {
        #region Properties

        protected override int ContentLayoutId
        {
			get { return Resource.Layout.CustomLayout; }
        }

        protected override int FooterLayoutId
        {
            get { return Resource.Layout.CustomFooter; }
        }

        public override ListViewInteraction InteractionMode
        {
            get { return ListViewInteraction.Navigation; }
        }

        #endregion

        #region Methods

        protected override void InitializeView()
        {
            base.InitializeView();

            this.RegisterViewIdentifier("TableView", this.ListView);
        }

        #endregion
    }
}

In the ContentLayoutId property, we’ve replaced the old layout to the new CustomLayout that we’ve created earlier and we’ve also removed the HeaderLayoutId. You’ve completed the Android version. Let’s run this project and you should get the result similar to the following.

http://blog.intersoftsolutions.com/wp-content/uploads/2015/11/Android1.mp4

Wrapping Up

You’ve seen how easy and elegant it is to provide a dockable view to your table view on iOS as well as list view on Android. Achieving the same task without Crosslight would be really tedious and time consuming. The dockable view also comes with automatic binding support, so you can take advantage of native binding process with whatever layout you have. Nice and simple.

You can find the code to the sample here:
http://git.intersoftsolutions.com/projects/CT/repos/crosslightdockableview/browse. To use this sample, you’ll need at least Crosslight build 4.0.5000.323 and above.

See you in the next post,
Nicholas Lie

Redesigning Xamarin Field Service Sample with Crosslight – Part 1

Nicholas Lie — Fri, 20 Nov 2015 07:00:00 +0000

Hi guys, Nicholas here. I’m back with another blog post, this time covering the Xamarin Field Service sample. Many of you have asked: “How can I transform the Xamarin Field Service sample using Crosslight?” And that tickled something in the back of our minds. This could be our next Crosslight reference sample! So we embarked on a quest to transform the Xamarin Field Service completely using Crosslight and see how much we can do about it.

Tablet-only Design?

Xamarin Field Service on Android, iPad and Windows 8.1

Before delving further, we need to take a step back and have a good look on overall UI and UX design of this app. When talking about cross-platform, yes, it would be valid to say that this app works cross-platform. But it only works on tablets. Why can’t the design be brought to the phone as well?

Let me share with you some of the design quirks found in the app, and how we decided to transform the experience in overall. We’re not talking about any code stuff first in this post. Just pure, plain UX, then we’ll move on to code sharing aspects in the next post.

The Assignments Screen

The assignments screen. At a first glance, nothing seems to be wrong with it. So, we decided to add additional swipe gesture touches to it, to change statuses quickly. Overall, I’m totally fine with it.

The Assignment Detail

Until it pushes the entire screen to display the assignment detail. Let’s take a look at Xamarin’s Field Service push navigation.

http://blog.intersoftsolutions.com/wp-content/uploads/2015/11/iPad-Transition.mp4

Xamarin Field Service – iPad Push Navigation

The transition between the assignments list and the assignment detail screen. It’s quite rare to see an iPad app performs a push navigation in such manner, especially in a list navigation. Most mobile apps will present itself with a SplitView on iPad, in which the push navigation will be contained within itself, not navigating the entire view. This is apparent in several iPad’s default apps, such as Mail, Contacts, Messages and Notes. I’m not saying this design is incorrect. But what if there is a way to enhance the navigation experience, much like the Apple’s native experience?

Problem: User experiences abrupt changes when navigating to detail view, hindering the user experience.
Objective: Show the detail view without abrupt, major changes in screen presentation.
Considerations: Obviously, we can’t add a SplitView to do that.
Our solution: Crosslight Dialog Presenter.

Crosslight Field Service – iPad Dialog Presenter

The Dialog Presenter is be a perfect candidate to replace the push navigation. By displaying a beautiful translucent modal panel from the right-hand side to the center that covers third-quarter of the screen, we managed to simulate the “content navigation” found in split view apps, enhancing the overall detail navigation experience. To close the dialog presenter, users can simply tap on the left hand side of the screen, outside the dialog presenter.

Have you managed to get started with the Dialog Presenter? If not, I’ve covered how to get started with the Dialog Presenter in another post.

Reusing the same view, the dialog presenter’s content can be easily adapted to iPhone’s more compact screen and uses simple push navigation, as follows.

Crosslight Field Service – iPhone Push Navigation

Crosslight is all about reusability, efficiency and design pattern consistency. You can easily design views that work perfectly in either phone or tablets, thanks to its robust, thoughtfully engineered navigation service.

Displaying the Navigation Items

Okay, we’ve managed to solve the list navigation experience. But how about containing all those navigation items in the detail view of our dialog presenter? Currently, we have 7 items: Summary, Map, Items, Labor Hours, Expenses, Documents, Confirmations. I’m not including History since it’s not supported by Xamarin just yet.

Xamarin Field Service – iPad Navigation List

Problem: The navigation items takes up too much space and exceeds the 5-items-limit for the tabs.
Objective: Display the navigation items inside the dialog presenter, while still maintaining a native and pleasant iPad UX.
Considerations: Can we simplify the navigation items even futher?
Our solution: Tabbed navigation.

Up to this point, you might have several objections in mind, such as: “What if Xamarin decided to bring that History menu back up and even adding more modules to the app? Your tabbed solution will not be able to solve that issue, no?” Yes. We admit it won’t be able fit more items inside it, as Apple has provided a maximum threshold of 5 items of the tab controllers.

However, we can improve the navigation item categorization to include lesser items and display them as needed. Remember, as a UI/UX designer, you have to keeps things simple for your users. And contextual. Imagine you’re designing the app for your mom, therefore, you have to keep it as simple as possible.

Crosslight Field Service – iPad Tabs

Our answer was to reduce the number of navigation items into maximum of 5 items: Summary, Items, Labor Hours, Expenses, and Confirmations. The Map and Documents can easily fit into the Summary tab. It all makes sense, considering that the Map and Documents do not contain any data entry capabilities and does not require any user interactions whatsoever. In other words, they’re designed to be read-only, which would fit the Summary tab. Why use 7 tabs if you can manage with just 5? And here’s how it looks on the iPhone.

Crosslight Field Service – iPhone Tabs

As for the History problem, since users can’t perform any data interaction with it, you can simply add a History icon button within the Summary tab that displays the previous records related with the assignment, or if you would like to separate each the list of Documents and list of History records, you can introduce a segmented button, like the one found in Apple’s App Store Purchased screen, especially the “All” and “Not on This iPad“.

App Store – iPad – Purchased

The Summary Screen

When I think of Summary, I always assume that the user expects the view to contain read-only information. For that same reason, the Summary screen is perfect to display static list of items, in which the user can perform only one action upon it.

Xamarin Field Service – iPad – Summary

Problem: The number of items to be included tab navigation can only contain max. 5 items.
Objective: Reduce the number of navigation items and display relevant information in a simpler manner.
Considerations: Decide which navigation menus that don’t need user interaction.
Our solution: Put Maps and Documents inside the Summary screen.

Crosslight Field Service – Maps and Documents in Summary

Therefore, we decide to inject Map and Documents inside the Summary screen. Including the Map was pretty simple. We display then Map on the top header, along with other relevant information about the customer. If users were to click on the map view, then Apple Maps will be fired up with a placemark showing more details about the location in the form of map annotations. As for the Documents, it is achievable simply by adding the documents list at the very bottom of the Summary page.

The Items Screen

How many times have you encountered an iPad app with adding and editing experience that is not located in the navigation bar? I’m sure, not much. For me, it’s my first time.

Xamarin Field Service – Items

And because of that, I’m pretty sure this is not Apple’s standard design.

Problem: The user actions are not part of the navigation bar and it’s confusing.
Objective: Provide a method for the user to display the relevant information as needed.
Considerations: What does the user usually expect when perform user actions?
Our solution: By removing the sticky header altogether, we’ve managed to place the user actions where it truly belongs.

Crosslight Field Service – Items

The addition and editing of items generally occurs from the navigation bar, in which we have done so with the dialog presenter approach. Since the Items screen is similar to the Labor Hours and Expenses screen, we’re taking the same approach to both of the screens.

The Sticky Header

Xamarin Field Service – Sticky Header

Problem: With the sticky header gone, what is the best place to put it?
Objective: Find an alternative to place the sticky header with global accessibility.
Considerations: The information should be globally accessible, anytime, anywhere.
Our solution: Provide a header callout that displays the removed information.

In my personal opinion, it’s the “sticky header” in the content detail view is what breaks the overall iPad experience. This is why we have removed this view and opted to stick it in only the Summary view, the correct place where it belongs. Users also do not have to see this information the whole time.

Crosslight Field Service – iPad

However, if the user wants to see that quick information, he can just tap on the top header anytime and a callout will present the temporary information he needed.

The “Active Work” Indicator/Player

Before we proceed, we might have forgotten one other thing. The “active work” indicator/player. If you notice, when the assignment is marked as Active, the player pops out from the bottom of the screen to let the user know that the current assignment is active and he can pause at any time. This will count automatically as a new entry in the Labor Hours screen.

Problem: Display globally-available information that shows the current work is active that adheres to Apple’s standard user experience.
Objective: Display the “active work” indicator/player in the dialog presenter content detail.
Considerations: It has to be global (user should be able to see it all the time). The dialog presenter content is already cramped up. Where would be the correct place to put the view?

Before I present you with our approach to the above problem, I want you to think how to solve this problem. Think of all the possible places and approaches to tackle this problem. And yes, Apple did have this exact same problem in one of their apps. Can you guess what the app is?

Did you come up with any solution to the above problem? If not, let me tell you what our solution is: Apple’s Music Player View.

Apply Music – Player

Think about it. The Music app introduced in iOS 8.4 has this exact same problem. When the music is playing, how can Apple show the user on what music is playing, globally, and whether the user can perform any actions upon it?

Crosslight Field Service – Active Work View

Yes, we dealt with the problem the same way. Both of the solutions are consistent in iPhone and iPad.

The Confirmation Screen

The last, but not the least view in the app: the confirmation screen. This screen also presents quite a challenge to be redesigned and optimized.

Xamarin Field Service – Confirmation

Take a look at the design above. And imagine running it on a phone.
The design is quite tricky to address, since it has one list and a signature pad.

Problem: The screen’s design cannot be adapted to phones.
Objective: Revamp the screen in such a way that will accommodate users running on tablets and phones.
Considerations: The vertical-scrolling list might be a problem.
Our solution: Change the vertical-scrolling list into a horizontal-scrolling list and add the signature pad directly beneath it.

Crosslight Field Service – Confirmation Screen

Therefore, we’ve elegantly redefined how things work in the Confirmation screen by making the Photos section acts as a carousel view with Signature Pad placed directly underneath it. This way, it can work on smaller screens like phones.

How about Android?

Android fans, do not fret. Let’s take a look at the Android designs of the Field Service app.

Here’s a gallery of how it looks on the phone.

And here’s how it looks on Android tablets.

Umm, wait, the images above look very similar with iOS rather than Android, particularly the swipe-to-action screens. Could it be possibly that I attach wrong images, you might asked. Nope! We’ve great surprises for you, Android fans! Stay tuned for my answer in the next post.

Wrapping Up

I hope this post may give you meaningful insights on better design for cross-platform, especially one that works for both tablets and phones. By streamlining the design and user flow at the beginning, jumping into development becomes much an easier task with clearer goal in mind.

If you haven’t try out Crosslight, you can quickly jump start by requesting your free 30 day trial here. You will be guided by our consultant team during your evaluation period.

In the next post, we’ll see how can we use Crosslight to create this app and make it work across all platforms of different screen sizes and see how much code for this app can be optimized to work for multiple platforms.

Update

Read the part 2 here, which contains highlights of the finished sample along with snippet codes and detailed explanations.

Till next post,
Nicholas Lie

Adding Header and Footer for iOS TableView and Android ListView

Nicholas Lie — Wed, 18 Nov 2015 07:01:08 +0000

Hi guys, I’m back with another blog post, this time covering how to use the a custom view for header and footer to be used alongside iOS TableView / Android TableView. You’ll see how you can easily create custom views and use them as headers and footers in your Crosslight apps.

After this project has completed, you’ll end up with a custom header and footer in your ListView/TableView. When you click on the Add Item button on the top, new item will be added to the list, and you can see how the header and footer is correctly persisted when the items collection is updated.

To complete this project, there are several steps need to be completed:

Preparing the project
Creating custom views for iOS
Preparing the BIndingProvider
Preparing the ViewModel
Modify iOS ViewController and running the project
Creating custom views for Android
Modifying Android ListActivity and running the project

Without further ado, let’s get started.

Preparing the project

For this sample, I’ll keep it nice and simple. This time, I’ll start from the Navigation template created using Crosslight Project Wizard. I’ll name this project: HeaderAndFooter.

Creating custom views for iOS

Let’s begin by creating a new custom header view for iOS, by right-clicking on the VIews folder in HeaderAndFooter.iOS/Views folder and choose Add, New File.

Then choose Crosslight, Crosslight iOS View for iPhone.

Give it a name of CustomHeader. This will generate two files, CustomHeader.xib and CustomHeader.cs for the designer files.

Then open the CustomHeader.xib using Xcode Interface Builder.

In Xcode Interface Builder, drag a Label and a button.

Set the label outlet as TxtHeader and the button as BtnHeader. I won’t go too much on the layouting details, but you can ensure the followings are set:

Set the View size as Freeform, so you can adjust the view size freely.
Turn off Auto Layout.
Ensure that the View background is set to Default (no fill), this will avoid clipping issues when placed as the header view.

Your custom header is now ready. Let’s move on to custom footer.

Basically, you’re going to perform the same tasks as adding a custom header, but the difference is that you’re going to give it a file name of CustomFooter, then provide a label with the outlet of TxtCopyright.

Preparing the BindingProvider

Since you’ve successfully created the custom views, let’s prepare the BindingProvider first to prepare the properties and commands you wish to bind to the View. Open up NavigationBindingProvider (I renamed this file to MainBindingProvider to avoid confusion) and add the highlighted lines.

using Intersoft.Crosslight;

namespace HeaderAndFooter
{
    public class MainBindingProvider : BindingProvider
    {
        #region Constructors

        public MainBindingProvider()
        {
            ItemBindingDescription itemBinding = new ItemBindingDescription()
            {
                DisplayMemberPath = "Title",
                NavigateMemberPath = "Target"
            };

            this.AddBinding("TableView", BindableProperties.ItemsSourceProperty, "Items");
            this.AddBinding("TableView", BindableProperties.ItemTemplateBindingProperty, itemBinding, true);
            this.AddBinding("TableView", BindableProperties.SelectedItemProperty, "SelectedItem", BindingMode.TwoWay);
            
            this.AddBinding("BtnHeader", BindableProperties.TextProperty, "ButtonText");
            this.AddBinding("BtnHeader", BindableProperties.CommandProperty, "AddCommand");
            this.AddBinding("TxtCopyright", BindableProperties.TextProperty, "CopyrightText");
            this.AddBinding("TxtHeader", BindableProperties.TextProperty, "HeaderText");
        }

        #endregion
    }
}

From the added lines, notice that we’re going to do the following:

Bind ButtonText property in the ViewModel to the BtnHeader button.
Bind the ViewModel’s built-in AddCommand to the BtnHeader button. This is available in the EditableListViewModel shipped in Crosslight.
Bind the HeaderText property in the ViewModel to the TxtHeader label.
Bind the CopyrightText property in the ViewModel to TxtCopyright label. This is for the footer.

Since you’ve prepared everything in the BindingProvider, let’s modify the ViewModel.

Modifying the ViewModel

The NavigationViewModel now looks like the following. It’s located inside the HeaderAndFooter.Core/ViewModels folder.

using System.Collections.ObjectModel;
using System.Collections.Specialized;
using System.Linq;
using Intersoft.Crosslight;

namespace HeaderAndFooter.ViewModels
{
    public class NavigationViewModel : SampleListViewModelBase
    {
        #region Constructors

        public NavigationViewModel()
        {
            ObservableCollection items = new ObservableCollection();

            items.Add(new NavigationItem("Simple Page", "About", typeof(SimpleViewModel)));
            items.Add(new NavigationItem("About This App", "About", typeof(AboutNavigationViewModel)));

            this.SourceItems = items;

            this.ButtonText = "Add Item";
            this.CopyrightText = "Copyright © Intersoft Solutions";
        }

        #endregion

        #region Properties

        private string _aboutText { get; set; }
        private string _buttonText { get; set; }
        private string _copyrightText { get; set; }
        private string _headerText { get; set; }

        public string AboutText
        {
            get { return _aboutText; }
            set
            {
                if (_aboutText != value)
                {
                    _aboutText = value;
                    OnPropertyChanged("AboutText");
                }
            }
        }

        public string ButtonText
        {
            get { return _buttonText; }
            set
            {
                if (_buttonText != value)
                {
                    _buttonText = value;
                    OnPropertyChanged("ButtonText");
                }
            }
        }

        public string CopyrightText
        {
            get { return _copyrightText; }
            set
            {
                if (_copyrightText != value)
                {
                    _copyrightText = value;
                    OnPropertyChanged("CopyrightText");
                }
            }
        }

        public string HeaderText
        {
            get
            {
                _headerText = this.Items.Count() + " items.";
                return _headerText;
            }
            set
            {
                if (_headerText != value)
                {
                    _headerText = value;
                    OnPropertyChanged("HeaderText");
                }
            }
        }

        #endregion

        #region Methods

        protected override bool CanExecuteAdd(object parameter)
        {
            return true;
        }

        protected override void ExecuteAdd(object parameter)
        {
            base.ExecuteAdd(parameter);

            NavigationItem newItem = new NavigationItem("Simple Page", "About", typeof(SimpleViewModel));
            var items = this.SourceItems.ToObservable();
            items.Add(newItem);
        }

        protected override void OnCollectionChanged(NotifyCollectionChangedEventArgs e)
        {
            this.OnPropertyChanged("HeaderText");
        }

        #endregion
    }
}

Let’s take a deeper look at this class, starting from the top. In the constructor, we’ve prepared our SourceItems with ObservableCollection. We then initialize the ButtonText property and the CopyrightText property. The ButtonText and CopyrightText property are all MVVM-ready properties. The HeaderText is also an MVVM-ready property, but in the property getter, the text is always updated according to the number of items which exists in the list.

Right after the properties, we then override the built-in CanExecuteAdd method to return true so that the AddCommand can be executed, as well as overriding the actions for the ExecuteAdd method. Here, we simply add a new NavigationItem to the list. Just right after the method, Crosslight has provided an elegant way to perform any additional changes to other properties or any other implementation by overriding the OnCollectionChanged method. In the method, we trigger the OnPropertyChanged of the HeaderText, so that the number of items is always updated in our custom header.

Modify iOS ViewController and running the project

Now that you got the Core project covered, let’s modify the MainViewController (located inside HeaderAndFooter.iOS/ViewControllers) a bit.

using CoreGraphics;
using Foundation;
using HeaderAndFooter.ViewModels;
using Intersoft.Crosslight;
using Intersoft.Crosslight.iOS;
using UIKit;

namespace HeaderAndFooter.iOS.ViewControllers
{
    [Register("MainViewController")]
    [ImportBinding(typeof(MainBindingProvider))]
    public class MainViewController : UITableViewController
    {
        #region Properties

        public override UIViewTemplate HeaderViewTemplate
        {
            get { return new UIViewTemplate(CustomHeader.Nib); }
        }

        public override UIViewTemplate FooterViewTemplate
        {
            get { return new UIViewTemplate(CustomFooter.Nib); }
        }

        public override TableViewInteraction InteractionMode
        {
            get { return TableViewInteraction.Navigation; }
        }

        public override bool ShowGroupHeader
        {
            get { return false; }
        }

        public override UITableViewStyle TableViewStyle
        {
			get { return UITableViewStyle.Plain; }
        }

        #endregion

        #region Methods

        protected override void InitializeView()
        {
            base.InitializeView();

            // set navigation title
            this.NavigationItem.Title = "Crosslight App";
        }

        #endregion
    }
}

In the MainViewController, we’ve overridden the HeaderViewTemplate as well as FooterViewTemplate to return the Nib for each custom header and footer view that we’ve just defined. We also made things simpler by not showing the group header as wellas ensuring that the used TableViewStyle is Plain. Run the project. You should get the following result.

http://blog.intersoftsolutions.com/wp-content/uploads/2015/11/iOS-header-footer.mp4

If you’re curious about the separator that exists between the header with the table view, as well as the footer with the table view, it’s because I’ve added an additional view in the custom header and footer layout, with the height of 1 unit and giving it a light gray background, to show the boundaries of the custom header and custom footer view. We’re going to do the same with Android layout later. You’ve completed the iOS version. Let’s move on to the Android.

Creating custom views for Android

Similar to iOS, you’ll need to create a custom header view first for Android. To do this, simply right click on the Resources/layout folder in the HeaderAndFooter.Android/Views folder, then choose Add, New Item.

From the dialog that appears, choose Android, Layout, and give it a name of CustomHeader.

And here’s the contents of the CustomHeader.axml file.

This layout simply contains a pretty much similar layout with iOS, that contains a label, a button, and a gray separator at the bottom. Repeat the same procedure for the custom footer layout. Here’s the contents of the CustomFooter.axml file.

Modifying Android ListActivity and running the project

Since you’ve prepared the custom views let’s modify the Android ListActivity to display our custom header and footer. Open up MainActivity in the HeaderAndFooter.Android/Activities folder and take note of the following changes.

using Android.App;
using HeaderAndFooter.ViewModels;
using Intersoft.Crosslight;
using Intersoft.Crosslight.Android;

namespace HeaderAndFooter.Android
{
    [Activity(Label = "Crosslight App", Icon = "@drawable/icon")]
    [ImportBinding(typeof(MainBindingProvider))]
    public class MainActivity : ListActivity
    {
        #region Methods

        protected override void InitializeView()
        {
            base.InitializeView();

            this.RegisterViewIdentifier("TableView", this.ListView);
        }

        #endregion

        #region Properties

        protected override int ContentLayoutId
        {
            get { return Intersoft.Crosslight.Android.Resource.Layout.listgroupsectionlayout; }
        }

        protected override int FooterLayoutId
        {
            get { return Resource.Layout.CustomFooter; }
        }

        protected override int HeaderLayoutId
        {
            get { return Resource.Layout.CustomHeader; }
        }

        public override ListViewInteraction InteractionMode
        {
            get { return ListViewInteraction.Navigation; }
        }

        #endregion
    }
}

All you need to do is just override the FooterLayoutId as well HeaderLayoutId and provide the layout you’ve just created. If you notice in the template, right in the InitializeView method, we’re registering the ListView with the TableView identifier at runtime. This is how you would register a view at runtime. For more information in registering view at runtime, check out this document in the Developer Center.

You’re now ready to run the project. You should get the result similar to the following.

http://blog.intersoftsolutions.com/wp-content/uploads/2015/11/Android-header-footer.mp4

Wrapping Up

You’ve seen how easy it is to set up a custom header and footer view to use with iOS TableView and Android ListView. With Crosslight, the custom views are automatically compatible with data binding and Crosslight takes care of the magic, so you can focus on building your app instead of having to worry about wiring behind the scenes. Hopefully this gives you a good insight on how Crosslight accomplishes business scenarios elegantly, without compromising any of the MVVM-design pattern enforced throughout the app.

As always, you can find the source code to this post here: http://git.intersoftsolutions.com/projects/CT/repos/crosslightheaderandfooter/browse.

See you in the next post,
Nicholas Lie

Extending Crosslight Form Builder

Nicholas Lie — Tue, 17 Nov 2015 07:00:18 +0000

Since you’ve managed to get started with Crosslight Form Builder, let’s move on a bit to see how we can extend the capabilities of the Crosslight Form Builder beyond its original capabilities. In this post we’re going to learn how to add an option to choose the driver in CrosslightFormBuilder sample, as well as showing a custom view with the driver’s photo in the form, with the driver’s phone number, which when tapped, will initiate a call to the driver.

There are two major enhancements to be done:

Providing driver selection
Providing custom driver view

Providing Driver Selection

Let’s try to create the Driver selection. At a quick overview, here’s a list of subtasks to be done in order to achieve this functionality:

Prepare the Driver model
Prepare the Driver Repository that populates the list of drivers.
Prepare the DriverListViewModel that populates the items from the repository.
Update the Form Metadata and connect the DriverListViewModel.

Let’s go through each one, step-by-step.

Prepare the Driver model

To create the Driver model, let’s create a new file named Driver.cs under CrosslightFormBuilder.Core/Models folder. The contents are as follows.

#region Usings

using CrosslightFormBuilder.Models;

#endregion

namespace CrosslightFormBuilder.Core.Models
{
    public class Driver : ModelBase
    {
        #region Constructors

        public Driver(int id, string name, string phone, byte[] image)
        {
            this.Id = id;
            this.Name = name;
            this.Phone = phone;
            this.Image = image;
        }

        #endregion

        #region Fields

        private int _id;
        private byte[] _image;
        private string _name;
        private string _phone;

        #endregion

        #region Properties

        public int Id
        {
            get { return _id; }
            set
            {
                if (_id != value)
                {
                    _id = value;
                    OnPropertyChanged("Id");
                }
            }
        }

        public byte[] Image
        {
            get { return _image; }
            set
            {
                if (_image != value)
                {
                    _image = value;
                    OnPropertyChanged("Image");
                }
            }
        }

        public string Name
        {
            get { return _name; }
            set
            {
                if (_name != value)
                {
                    _name = value;
                    OnPropertyChanged("Name");
                }
            }
        }

        public string Phone
        {
            get { return _phone; }
            set
            {
                if (_phone != value)
                {
                    _phone = value;
                    OnPropertyChanged("Phone");
                }
            }
        }

        #endregion
    }
}

The Driver model contain 4 MVVM-ready properties: ID (int), Image (byte[]), Name (string), and Phone (string). That’s basically it. I’ve also prepared a constructor for quick and easy initialization. Now your Driver model is ready. Let’s move on.

Prepare the Driver Repository

Upon reading the heading, you might have two questions: What is this repository thingy and why do I need it? The repository pattern is more of a best-practice design pattern that handles the actual data processing for your applications. A data repository for your app.

For example, right now your app might currently retrieve data by performing queries to a database server, then one day you decided to change the data retrieval process. Rather than making changes to each and every ViewModel, you can do so by just replacing the data repository. No changes in ViewModel needed. To learn more about the Repository Pattern, check out our Developer Center documentation here.

So, let’s get started in creating our Driver repository. First thing you need to do is define the interfaces needed for the repository. Create a new interface in CrosslightFormBuilder.Core/ModelServices, named IDataRepository.cs, also creating the folder as necessary. The contents of the file are as follows.

public interface IDataRepository where TEntity : class
{
    #region Methods

    TEntity Get(TKey id);
    IEnumerable GetAll();

    #endregion
}

We’ll prepare an interface to get the Driver entity based on the given ID. Notice that everything is defined as generic here. Also another interface to return all entities when calling GetAll() method.

Proceed by creating the interface for the Driver repository in CrosslightFormBuilder.Core/ModelServices folder, named IDriverRepository.cs, also creating the folder as necessary.

public interface IDriverRepository : IDataRepository
{
    #region Methods

    Driver GetByName(string name);

    #endregion
}

There’s nothing much to see here, we simply added a new method to get the Driver entity by the driver’s Name by subclassing the previously created IDataRepository interface. Let’s move on by creating the concrete DriverRepository implementation. Create a new file called DriverRepository.cs inside CrosslightFormBuilder.Core/ModelServices folder.

public class DriverRepository : IDriverRepository
{
    #region Properties

    public List _items { get; set; }

    #endregion

    #region Methods

    public Driver Get(int id)
    {
        return this.GetAll().FirstOrDefault(o => o.Id == id);
    }

    public IEnumerable GetAll()
    {
        if (_items == null)
        {
            _items = new List();
            _items.Add(new Driver(1, "John", "+123456", this.GetType().Assembly.GetManifestResourceStream("CrosslightFormBuilder.Core.Assets.john.png").ToByte()));
            _items.Add(new Driver(2, "Brad", "+134567", this.GetType().Assembly.GetManifestResourceStream("CrosslightFormBuilder.Core.Assets.brad.png").ToByte()));
            _items.Add(new Driver(2, "Charles", "+145678", this.GetType().Assembly.GetManifestResourceStream("CrosslightFormBuilder.Core.Assets.charles.png").ToByte()));
        }

        return _items;
    }

    public Driver GetByName(string name)
    {
        return this.GetAll().FirstOrDefault(o => o.Name == name);
    }

    #endregion
}

Here, you can then provide the real implementation to retrieve the list of drivers, also getting the drivers by name and ID. The highlighted line shows how the list of Drivers are populated, by utilizing the constructor we’ve provided for our Driver model earlier. Also notice that we’ve provided the image to be used for each driver. Oh yeah, before we forget, let’s go ahead and use these images for the drivers and put it inside the CrosslightFormBuilder.Core/Assets folder, also creating the folder as needed.

Make sure that these images’ BuildAction is set to EmbeddedResource so that they can be used in your application. Also, if you try to build the project now, you might get an error on the ToByte() method. To fix this, create a new file that contains an extension method to convert a Stream to array of bytes. Create a file named StreamExtensions.cs, and put it inside the CrosslightFormBuilder.Core/Extensions folder.

public static class StreamExtensions
{
    #region Methods

    public static byte[] ToByte(this Stream input)
    {
        using (MemoryStream ms = new MemoryStream())
        {
            input.CopyTo(ms);
            return ms.ToArray();
        }
    }

    #endregion
}

A handy tip for you: these extension method provides an easy way to extend the functionalities of a certain class, that is reusable within your application. For example, if you wish to create an extension, for let’s say, converting a string to a byte[], you can definitely do something similar to this.

Now that you’ve the got the repository part ready, let’s hook it up to the ViewModel.

Prepare the DriverListViewModel

Start by creating a new ViewModel file called DriverListViewModel.cs and put it inside CrosslightFormBuilder.Core/ViewModels folder. Here’s the contents of the file.

public class DriverListViewModel : ListViewModelBase
{
    #region Constructors

    public DriverListViewModel()
    {
        this.SourceItems = this.Repository.GetAll().ToObservable();
    }

    #endregion

    #region Properties

    private IDriverRepository Repository
    {
        get
        {
            if (Container.Current.CanResolve())
                return Container.Current.Resolve();
            return new DriverRepository();
        }
    }

    #endregion
}

Here, we populate the SourceItems when the DriverListViewModel is constructed, just by calling the previously created GetAll() method from our interface. Also notice that we’ve provided the Repository property which is resolved upon the property’s getter. This is also called as IoC (Inversion of Control). To use the IoC pattern, you’ll need to register the previously created DriverRepository to be used globally in the application. To do this, open up the AppService.cs file in the CrosslightFormBuilder.Core/Infrastructure folder and add this line in the constructor.

public CrosslightAppAppService(IApplicationContext context) : base(context)
{
    Container.Current.Register().WithLifetimeManager(new ContainerLifetime());
}

Your ViewModel is now ready to be used to populate the list of Drivers.

Update the FormMetadata

Since you already have the list of drivers properly populated from the DriverListViewModel, we’ll need to modify the OrderFormMetadata a bit. From the initial OrderFormMetadata class in the Order.cs file, let’s modify the TaxiChoiceSection class to include the driver selection.

public class TaxiChoiceSection
{
    #region Fields

    [Display(Caption = "Car Type")]
    [Editor(EditorType.AutoDetect)]
    [Layout(Style = LayoutStyle.RightDetail)]
    public CarType CarType;

    [Editor(EditorType.Selection)]
    [SelectedItemBinding(Path = "Driver")]
    [Binding(Path = "Driver.Name")]
    [SelectionInput(SelectionMode.Single, DisplayMemberPath = "Name", ListSourceType = typeof(DriverListViewModel))]
    public Driver Driver;

    [Display(Caption = "Airport?")]
    [Editor(EditorType.Switch)]
    [Layout(Style = LayoutStyle.RightDetail)]
    public bool IsAirport;

    #endregion
}

The highlighted lines above shows the added definition for the driver selection. Let’s inspect this line by line.

[Editor(EditorType.Selection)]
This determines which editor type to be used.
[SelectedItemBinding(Path = “Driver”)]
This attribute determines which binding path for the selected item used in the Form Builder. In this case, the item for the Form Builder is of type Order, which has the Driver property. That’s where we’re going to bind our selection into. (OrderViewModel.Item.Driver)
[Binding(Path = “Driver.Name”)]
The BindingAttribute determines which property of the Driver model that is going to be displayed in the form after selection has completed.
[SelectionInput(SelectionMode.Single, DisplayMemberPath = “Name”, ListSourceType = typeof(DriverListViewModel))]
The SelectionInputAttribute determines the selection editor behavior, which ViewModel provides the items source for the list, as well as the property to be displayed on the list of selection, or also often known as DisplayMemberPath.

By now, you’ve successfully provided a driver selection for the Form Builder. How about adding the custom view on the bottom of the form?

Providing Custom Driver View

After the user has selected the driver, it’s best for us to show the driver that the user has selected by providing a custom view at the bottom of the form. Let’s learn how you can use a custom view resource to be used along with the Form Builder, complete with data binding capabilities. In overall, there are several steps needed to achieve this:

Provide the custom driver view for iOS
Update the Form Metadata
Provide the Binding Provider
Bind to ViewModel
Provide the custom driver view for Android

Let’s go through each step, one-by-one.

Provide the Custom Driver View for iOS

To provide the custom driver view for iOS, all you need to do is creating a new Crosslight view for iPhone. To do this, you can utilize the item template shipped with Crosslight. In your iOS project, in the Views folder, right-click and add a new file. Under Crosslight, choose Crosslight iOS View for iPhone.

Let’s give it a name of CallDriverButton. What this will do is Crosslight will create two files, namely CallDriverButton.xib and CallDriverButton.cs. All you need to do is create a new layout by opening the CallDriverButton.xib in Xcode Interface Builder.

Create your layout any way you want it. Just create an ImageView, a Label, and a Button.

Set the outlet for each.

ImageView: DriverImage
Label: DriverName
Button: CallButton

I know, my layout looks awful. But all I really want to show you is how you can inject your own custom views into the form using the Form Builder. So, after your layout’s done, save it and go back to Xamarin Studio.

Update the Form Metadata

Now that your layout is done, let’s update our OrderFormMetadata a bit to include this new view in our form layout. Open up Order.cs, and let’s create a new section and call it CallDriverSection, or anything you want.

public class CallDriverSection
{
    [Editor(EditorType.Custom, CustomEditorIdentifier = "CallDriverButton")]
    public object CallDriver;
}

Now I’d like you to pay attention how easy it is to embed a custom view into a Crosslight Form. From the definition above, you can see that we simply set the editor type to custom, then set the CustomEditorIdentifier set to CallDriverButton. In iOS, this corresponds to the name of the XIB that we’ve defined for our custom view. While on Android, this also corresponds to the name of the Android Layout file we’ve defined for our custom view layout. Simple as that.

We’ve made it super easy for developers to create a beautiful platform-specific data form by combining robust pre-built editors for common input and flexible custom views for more complex user interface. This allows you to mix and match what works best for you, and let Crosslight do the magic at runtime.

After you’ve created this section, let’s add this at the bottom of our form.

[Form(Title = "Order Form")]
public class OrderFormMetadata
{
    #region Fields

    [Section(Header = "Passenger Details")]
    public PassengerDetailsSection PassengerDetails;

    [Section(Header = "Taxi Choice")]
    public TaxiChoiceSection TaxiChoiceSection;

    [Section]
    public CallDriverSection CallDriverSection;

    #endregion
}

You’re done with the form metadata. But there’s something missing. What about those outlets we’ve defined earlier? How can we bind data to it?

Provide the Binding Provider

Simple. It’s basically the way you would do any data binding with Crosslight. Yes, you should provide a BindingProvider for the form. In addition to automatic bindings, Form Builder also supports natural data binding process through the use of BindingProvider. In this case, let’s create a new BindingProvider called OrderBindingProvider.cs. Let’s put this under CrosslightFormBuilder.Core/BindingProviders folder. The contents of the OrderBindingProvider are as follows.

public class OrderBindingProvider : BindingProvider
{
    #region Constructors

    public OrderBindingProvider()
    {
        this.AddBinding("DriverImage", BindableProperties.ImageProperty, "Item.Driver.Image");
        this.AddBinding("DriverName", BindableProperties.TextProperty, "Item.Driver.Name");
        this.AddBinding("CallButton", BindableProperties.TextProperty, "Item.Driver.Phone");
        this.AddBinding("CallButton", BindableProperties.CommandProperty, "CallCommand");
    }

    #endregion
}

Here, we’ve simply used the outlets we’ve defined earlier and bind them automatically to the selected Driver in the form. We’ve also added a binding from the CallButton to the CallCommand in the ViewModel, which can be used to call the driver immediately upon click. And don’t forget to use the newly created OrderBindingProvider in your OrderViewController.

Again, Crosslight does a lot of magic behind the scene which enables you to define data binding in such a simple definition. Looking back, we just need to create a view, define the outlets, and provide the bindings. Crosslight takes care the connection between all those layers at runtime.

[Register("OrderViewController")]
[ImportBinding(typeof(OrderBindingProvider))]
public class OrderViewController : UIFormViewController
{
    ...
}

Bind to ViewModel

Afterwards, in the OrderViewModel, we simply add a new DelegateCommand for the phone number.

public class OrderViewModel : EditorViewModelBase
{
    #region Properties

    /// 
    /// Gets the type of the form metadata associated to the editor.
    /// 
    /// 
    /// The type of the form metadata.
    /// 
    public override Type FormMetadataType
    {
        get { return typeof(OrderFormMetadata); }
    }
    
    public DelegateCommand CallCommand { get; set; }

    #endregion
    
    #region Constructors
    
    public OrderViewModel()
    {
        this.CallCommand = new DelegateCommand(ExecuteCall);
    }
    
    #endregion

    #region Methods
    
    private void ExecuteCall(object obj)
    {
        this.MobileService.Telephony.Call(this.Item.Driver.Phone);
    }

    /// 
    /// Executes the save command.
    /// 
    /// Parameter.
    protected override void ExecuteSave(object parameter)
    {
        this.Validate();

        if (!this.HasErrors)
        {
            StringBuilder passengerDetails = new StringBuilder();
            passengerDetails.Append("Name: " + this.Item.Name + "\n");
            passengerDetails.Append("Pickup Time: " + this.Item.PickupTime + "\n");
            passengerDetails.Append("Going to the airport? " + this.Item.IsAirport + "\n");
            passengerDetails.Append("Car Type: " + this.Item.CarType + "\n");
            passengerDetails.Append("Driver: " + this.Item.Driver.Name);

            this.MessagePresenter.Show(passengerDetails.ToString(), "Confirm Order", new[] {"Yes", "No"}, selection =>
            {
                if (selection == 0) //Yes
                {
                    this.ToastPresenter.Show("Your order has been placed.");
                }
                else
                {
                    this.ToastPresenter.Show("You cancelled the order.");
                }
            });
        }
        else
        {
            this.MessagePresenter.Show(this.ErrorMessage);
        }

    }
    

    /// 
    /// Called when this instance is navigated.
    /// 
    /// Parameter.
    public override void Navigated(NavigatedParameter parameter)
    {
        base.Navigated(parameter);

        this.Item = new Order();
        this.Item.PickupTime = DateTime.Now;
    }

    #endregion
}

Everything seems pretty much the same, except for the additional CallCommand we’ve defined for the CallButton. Run the project and you should now see iOS version is now working properly. Try selecting a driver and that driver detail will be automatically shown in the custom view you’ve defined. When you run this on an iPhone, you can even immediately perform a phone call to the driver’s number directly.

http://blog.intersoftsolutions.com/wp-content/uploads/2015/11/iOS.mp4

What about Android?

Provide the Custom Driver View for Android

This is where the Form Builder excels. Since you’ve completed the iOS version, all you need to do is just provide the custom layout and use the previously created OrderBindingProvider. Let’s take a look how to achieve this.

First, create a new Android Layout file by right clicking on the CrosslightFormBuilder.Android/Resources/layout folder. Then choose Add, New Item. Select Android, Layout. Remember to give it a name of CallDriverButton, as this corresponds to the CustomViewIdentifier defined in the FormMetadata earlier.

Provide the layout as follows.

After ensuring the IDs are correct, you’re only left to hook up the OrderBindingProvider in your OrderActivity. Let’s do that now.

[Activity(Label = "Order Form")]
[ImportBinding(typeof(OrderBindingProvider))]
public class OrderActivity : FormActivity
{
    ...
}

You’re done. Run the project and you’ll get the same result with iOS version.

http://blog.intersoftsolutions.com/wp-content/uploads/2015/11/Android.mp4

Beautiful, isn’t it?

Wrapping Up

The entire project for this tutorial can be found here. To use this sample, you’ll need to use at least Crosslight 4.0.5000.321 and above. Hopefully this will help you learn more about the Crosslight Form Builder.

You’ve seen how you can easily inject a custom view to the form by using the ViewResource custom editor. Probably some time in the future I’ll add a custom ViewBuilder tutorial as well. This will be very useful for those of you who wants to build a custom control that works seamlessly with the FormBuilder. We’ve also used this approach in building Crosslight Form Builder for each platform inside Crosslight framework.

Cheers,
Nicholas Lie

Editing Data with View Projection

Jimmy Petrus — Thu, 20 Aug 2015 10:40:55 +0000

In my post last week, I have introduced a truly time-saving feature in Crosslight 4 called view projection. As its name implies, this feature supposed to be used only for data listing/viewing purpose. Typically, you will use a much simple (flat) object model that represents the shape of data which can be conveniently bound to the list view. However, the flattened object does no longer represent the actual hierarchy of your data, thus making it non suitable for editing. That said, how can we handle data editing scenario? Is it possible to enable data editing while leveraging view projection? Read on.

The quick answer is yes — data editing can be used together with view projection, but we’ll get there a bit later. When using view projection, we suggest that you load only necessary data that is actually used in the list view. Since the loaded data is not designed to be editable, the best practice for data editing is to reload the data complete with the related entities on demand, typically when user tapped on the cell to navigate. Thanks to the full-fledged app framework and entity services in Crosslight, that can be easily done in the Navigated method of EditorViewModel instance, like so:

public async override void Navigated(NavigatedParameter parameter)
{
    base.Navigated(parameter);

    if (parameter.Data != null)
    {
        this.ActivityPresenter.Show("Loading");
        this.IsDataLoading = true;

        // reload item along with the specified navigation properties
        await this.Repository.GetSingleAsync((parameter.Data as SalesOrderHeader).SalesOrderID, new string[] { "Customer", "Address1", "SalesOrderDetails", "SalesOrderDetails.Product" });

        // call OnItemChanging so the recently fetched related entities can be tracked after item reloading
        this.OnItemChanging(this.Item, this.Item);

        this.IsDataLoading = false;
        this.ActivityPresenter.Hide();
    }
}

The above code is quite self explanatory. It will asynchronously load the entity along with the related entities given its primary key value when the editor view is navigated. The essence of the above code lies in the GetSingleAsync method which now has a new overload that accepts an array of related properties to be reloaded along with the entity in one shot. That’s really intuitive.

To improve performance, it’s wise to load the entity only when it’s navigated the first time. That’s pretty easy to implement, let’s make changes to the code like this:

public async override void Navigated(NavigatedParameter parameter)
{
    base.Navigated(parameter);

    if (parameter.Data != null)
    {
        // only load additional data if it hasn't been loaded previously
        if (this.Item.Customer == null)
        {
            this.ActivityPresenter.Show("Loading");
            this.IsDataLoading = true;

            // reload item along with the specified navigation properties
            await this.Repository.GetSingleAsync((parameter.Data as SalesOrderHeader).SalesOrderID, new string[] { "Customer", "Address1", "SalesOrderDetails", "SalesOrderDetails.Product" });

            // call OnItemChanging so the recently fetched related entities can be tracked after item reloading
            this.OnItemChanging(this.Item, this.Item);

            this.IsDataLoading = false;
            this.ActivityPresenter.Hide();
        }
    }
}

Piece of cake. Now, if the properties of the entity has changed, or the related entities have changed during editing, the changes won’t sync back to the list view. That’s actually normal, because the objects in the list view is no longer related to the entities being edited. Remember the code we wrote above? We reloaded the entity specifically for editing purpose during navigation.

There’s where the new entity.UpdateProperties() API comes to rescue. Simply call the API on the edited entity, it will automatically scan the changes and reflect them back to the projected properties. And even better, if you’ve upgraded to Crosslight 4’s Enterprise App Framework, then you have zero line of code to write. That’s made possible because the API is now baked to the DataEditorViewModelBase class, specifically in the OnDataChanged method. Here’s the code snippet for your convenience:

/// Called when a data item is changed.
protected override void OnDataChanged(TModel item)
{
    IEntity entity = this.Item as IEntity;
    if (entity != null)
        entity.UpdateProperties();

    base.OnDataChanged(item);
}

And here’s the result as expected using the view projection samples:

You might be wondering how the UpdateProperties API does its magic. How does it know which related entities have changed and which projected properties to sync back? The answer lies in the Crosslight’s powerful data framework which has complete information about the entity’s relationships and its metadata as well as built-in changes management.

If you haven’t familiar with Crosslight data framework — or haven’t used it yet, I strongly recommend you to start using it. Learn more here.

Now, let’s pull the data samples from our Git and see the editing in action with view projection. Run the sample in either iOS and Android platform, tap on a cell, edit some fields, i.e., City, then save it. Go back to the list view, voila, the changes are sync’ed back as expected, just as if it were an entity loaded with navigational properties.

In this post, we’ve looked at how a data-driven Crosslight app is built, covering both data list and editing by combining view projection and entity’s API. Now you also have better understanding on how Crosslight is designed to provide great developer experiences by eliminating much of the boilerplate code, so you can focus on the code that matters to your business apps. If you’ve any questions, we’d be happy to welcome you aboard on our community forum.

Best,
Jimmy

Introducing Crosslight View Projection

Jimmy Petrus — Mon, 10 Aug 2015 11:05:42 +0000

Couple weeks ago, we’ve finally released Premier Studio 2015, one of our most remarkable milestones. We shipped Crosslight 4 with a host of new exciting components, Visual Studio 2015 across all product lineup, and Windows Edge support for WebUI components. That’s not all. We also launched a fully redesigned website which was the result of months of redesign works. In case you missed the news, check out the full coverage on the release here, and the website redesign concept here.

So now you’ve got the new Studio installed, what’s next? We’ve made available a wealth of resources to help you quickly get started. For the starting point, I recommend you to check out the release notes and follow the links in the page. Over the next few weeks, we’ll blog around the new features introduced in this release, covering each of them in more practical way.

This week, I’d like to discuss about the new features in Crosslight data access components, and how you can leverage them to build faster, more reliable data intensive apps.

Displaying a list of data that includes information from several related tables is a very typical application scenario. Consider the order list in an order tracking app, it makes a good sense to show aggregated amount and shipping information along with the order item, perhaps something like this.

Showing the list from orders table only is certainly straightforward, but how to include the related information? That’s easy, thanks to the data service component (both client & server) included in Crosslight. Just use the Includes API in the query definition, so the related entities will be fetched automatically from the server, like so:

public override QueryDescriptor GetQueryDescriptor()
{
    QueryDescriptor queryDescriptor = this.GetBaseQueryDescriptor();
    queryDescriptor.Includes.Add("Customer");
    queryDescriptor.Includes.Add("Address1");

    return queryDescriptor;
}

That works well in most cases, particularly for list with few included related entities. However, when you added more related entities to the list, the payload will become larger too, exponentially. This often leads to issues like: longer time to transfer the data, more overhead in entity processing, and more critically, larger memory allocation. But, that’s all natural due to the way related entities work. To understand how a response with related entities look like, take a look at the JSON below.

{
  "$id": "1",
  "$type": "Intersoft.Data.WebApi.QueryResult, Intersoft.Data.WebApi.v4",
  "AffectedRows": null,
  "InlineCount": null,
  "Results": [
    {
      "$id": "2",
      "Address1": {
        "$id": "3",
        "AddressID": 1092,
        "AddressLine1": "99700 Bell Road",
        "AddressLine2": null,
        "City": "Auburn",
        "StateProvince": "California",
        "CountryRegion": "United States",
        "PostalCode": "95603",
        "rowguid": "79cdd89c-3c91-48db-8277-46d04aad7251",
        "ModifiedDate": "2002-09-01T00:00:00.000",
        "CompleteAddress": "99700 Bell Road\nAuburn, California"
      },
      "Customer": {
        "$id": "4",
        "CustomerID": 29847,
        "NameStyle": false,
        "Title": "Mr.",
        "FirstName": "David",
        "MiddleName": null,
        "LastName": "Hodgson",
        "Suffix": null,
        "CompanyName": "Good Toys",
        "SalesPerson": "adventure-works\\linda3",
        "EmailAddress": "david16@adventure-works.com",
        "Phone": "969-555-0117",
        "PasswordHash": "+gtwbVycsIIj2loVtrHNRN6IBLl20lQpRK8+JhzxyEo=",
        "PasswordSalt": "AwqZdYk=",
        "rowguid": "fdd7d9cb-9a81-40fc-baf6-facde8da4923",
        "ModifiedDate": "2002-09-01T00:00:00.000"
      },
      "SalesOrderID": 71774,
      "RevisionNumber": 2,
      "OrderDate": "2015-06-01T00:00:00.000",
      "DueDate": "2015-06-13T00:00:00.000",
      "ShipDate": "2015-06-08T00:00:00.000",
      "ModifiedDate": "2015-06-08T00:00:00.000"
    }
}

As seen in the above JSON, every included entity will be added as a child record in the server response. This allows the Crosslight entity manager to attach the records properly in the client side. In our simple test, the order list retrieved with the Includes approach took 72 KB in size.

If you’re new to Crosslight or unfamiliar with the QueryDescriptor API, you might want to check out Dynamic Data Access with Query Descriptor.

Obviously, you can address the above issues with custom server query or custom views, which are well supported by Crosslight. But, creating custom query every time you need to display data is counter-productive and tedious at best, agree?

So what solution do we have in store? Read on.

Enter View Projection.

Building on our experiences in architecting large scale enterprise apps, and also based on our customer’s feedback, we are introducing a more efficient way to create a shaped view in Crosslight 4. Called view projection, you can easily create a data view comprised of various information from related tables into a single flat list – dramatically shrinking payload size and processing time. We believe this is a better, more efficient, and more reliable way to fetch and present data in Crosslight apps.

Using the same order list scenario above, we can now extend the order entity with new properties to contain the additional information we’d like to fetch, then simply add the new Select attribute to indicate which property and related table to fetch, like so:

public partial class SalesOrderHeader
{
    [Select("Address1.CompleteAddress")]
    public string ShipAddress { set; get; }

    [Select("Customer.CompanyName")]
    public string CustomerCompany { set; get; }
}

By defining such a simple metadata in the client side, the server will automatically construct the query behind the scene. Back in the client, you’ll get the data with the additional information in a flat list, then simply bind it to a list view. Piece of cake.

Here’s the example result of the response.

{
  "$id": "1",
  "$type": "Intersoft.Data.WebApi.QueryResult, Intersoft.Data.WebApi.v4",
  "AffectedRows": null,
  "InlineCount": null,
  "Results": [
    {
      "$id": "2",
      "$type": "ViewProjectionSample.DomainModels.SalesOrderHeader, ViewProjectionSample.DomainModels",
      "SalesOrderID": 71774,
      "RevisionNumber": 2,
      "OrderDate": "2015-06-01T00:00:00.000",
      "DueDate": "2015-06-13T00:00:00.000",
      "ShipDate": "2015-06-08T00:00:00.000",
      "ModifiedDate": "2015-06-08T00:00:00.000",
      "SalesOrderDetails": [ ], 
      "Address": null,
      "Address1": null,
      "Customer": null,
      "ShipAddress": "99700 Bell Road\nAuburn, California",
      "CustomerCompany": "Good Toys"
    }
}

As expected, the Customer and Address entities are no longer included in the returned result. Instead, the ShipAddress and CustomerCompany properties are simply filled with the requested information.

Per our test using the same order query, the view projection took only 37 KB, about half the size of the response size using Includes approach. If you build relatively complex data apps, this view projection alone could reduce the response size up to 75%.

That’s not all. Nested properties is also supported, so you can easily include any entity regardless of the depth, as long as their relationships are well defined. Here’s an example of nested property selection.

[Select("Product.Category.CategoryName")]
public string ProductCategory { set; get; }

[Select("Order.ShipToAddress.Country.Name")]
public string ShipCountry { set; get; }

In addition to nested properties, the new Select attribute is also smart enough to do some heavy data aggregation and calculation. Say you want to include the order details count and total to the order list, you can specify the Select attribute like this:

[Select("SalesOrderDetails.OrderQty", Aggregate.Sum)]
public int ProductQuantity { set; get; }

As expected, the returned result will look something like this:

{
  "$id": "1",
  "$type": "Intersoft.Data.WebApi.QueryResult, Intersoft.Data.WebApi.v4",
  "AffectedRows": null,
  "InlineCount": null,
  "Results": [
    {
      "$id": "2",
      "$type": "ViewProjectionSample.DomainModels.SalesOrderHeader, ViewProjectionSample.DomainModels",
      "SalesOrderID": 71774,
      "RevisionNumber": 2,
      "OrderDate": "2015-06-01T00:00:00.000",
      "DueDate": "2015-06-13T00:00:00.000",
      "ShipDate": "2015-06-08T00:00:00.000",
      "ModifiedDate": "2015-06-08T00:00:00.000",
      "SalesOrderDetails": [ ], 
      "Address": null,
      "Address1": null,
      "Customer": null,
      "ShipAddress": "99700 Bell Road\nAuburn, California",
      "CustomerCompany": "Good Toys",
      "ProductQuantity": 2
    }
}

Unbelievably simple, isn’t it? We haven’t quite finished yet, read on.

How about using some mathematical operations along with the data aggregate, you asked. Well, we’ve got those covered too. Here’s a quick example:

[Select("SalesOrderDetails", "OrderQty * UnitPrice * (1 - UnitPriceDiscount)", Aggregate.Sum)]
public double SubTotal { set; get; }

In addition to sum, as you might already have in mind, we also supported other aggregate options such as count, min, max, and average.

And if you just realized, we haven’t touch the server part even a bit, are we missing something? Nope. The server recognizes all these new Select metadata, thanks to the much improved WebApi component introduced in the new Intersoft.Data.WebApi.v4 assembly.

In fact, all you have to do at the server side is to update the Intersoft WebApi assemblies and the related Nuget packages to the latest version. Check out this upgrade guide for details.

Last but not least, all the powerful new capabilities above are equally supported in Crosslight SQLite as well, so if you build sync-aware apps, the same metadata will work just fine, whether the app loads data from the remote server or local storage. In addition, the view projection has been carefully designed to support data editing and update scenario as well which I’ll cover in the next post.

We’ve designed Crosslight with strong focus on developer experience since the initial release. We continue to provide even greater developer experience in this new release, making the impossible possible with intuitive and simple API design.

We still have a lot of stories to cover around data access improvements, but for now, let’s pull some samples and see the demo of view projection features for yourself. If you have any questions, join us in our community forum.

Best,
Jimmy

Create Drill Down Chart with UXChart

yanesblog — Tue, 05 Mar 2013 03:24:03 +0000

Quite often, you will need to allow your user to drill-down data from yearly data to monthly or from categories to individual items. Now it’s very easy with our new concept which gives you freedom to create unlimited levels of drill-down charts from a single data source in minutes.

In this blog post, I want to show an example of drilling down chart data, i.e. to display master-detail data in the same chart, by clicking a point of the first series will let another series shown, which represents detailed data related to the selected point. This is critical for creating interesting and fun charts to interact with. This blog entry includes basic knowledge of what you can do with our chart right out of the box. See the following screenshot for the drilling down chart that we want to create.

To get started, we use the Child properties in UXChart to specify which chart that we want to display as detail of origin chart. Specifically, all charting collections must be defined in View in a first place. On first load, you are allowed to display one chart only, and the others’ visibility must be set to collapse. See the code below:

Next, we need to hook our custom command to control the drilldown action, we called it DrillDownCommand.

public DelegateCommand DrillDownCommand { get; set; }

And then we assign DrillDownCommand to some execute the method in our ViewModel.

this.DrillDownCommand = new DelegateCommand(ExecuteDrillDown);

In the execute method, we can initialize the data from the data source and retrieve detail information about the chart itself.

private void ExecuteDrillDown(object parameter)
{
   UXChartDrillDownCommandArgs args = parameter as UXChartDrillDownCommandArgs;

   if (args.Level == 1)
   {
     Data parent = args.DataPointContext as Data;
     if (parent != null)
     {
       InitializeDataByArea(parent.Area);
     }
   }
}

In conclusion, with simple implementation, we already make drill down function very simple and effortless. Now feel free to try and make your very own drill down chart. There’s unlimited level that you can figure out and explore.

For more information about our ClientUI control in Silverlight & WPF, please refer to the online documentation. You can download our sample here. Feel free to drop us any questions or feedback.

Till we meet again.

Cheers,
Yanes

WebFileUploader: Store Uploaded Files in Database

yudhiy — Thu, 31 Jan 2013 10:30:03 +0000

Last year I posted an article which showed how to store the files which are uploaded using UXFileUpload (ClientUI control for Silverlight and WPF) in database. In this article, I will show a similar scenario which can be done using WebFileUploader, a member of Intersoft Solutions ASP.NET controls.

WebFileUploader is an easy to use; high performance and advanced file upload component which allows you to upload multiple files without page refresh. WebFileUploader uses 100% HTML technology for all its features, and fully supports all modern browsers including Firefox, Safari, Chrome and Opera. Using 100% HTML technology means that WebFileUploader doesn’t require Flash plug-in to support multiple files uploading and many other features.

This scenario, to store the uploaded files in database, can be divided to two parts. The first part is to configure WebFileUploader for IIS application; and the other part, using server-side code to process uploaded files and store them into database.

To configure WebFileUploader for IIS application

Some configuration is needed in the web.config to run WebFileUploader in IIS. The list below shows how to configure WebFileUploader for IIS 7 application.

By default, ASP.NET application restricts maximum request length to 4 MB. To enable our application to accept larger files, please configure the maxRequestLength in web.config to higher value. The maxRequestLength value is measured in kilobytes. Here is a snippet to increase your file size to 100MB.
```
  
    
  
```
Add WebFileUploader handler to
section under
. Here is the snippet.
Add WebFileUploader module to
section under
in our project web.config. Here is the snippet.
Set maxAllowedContentLength to a higher value, which is measured in bytes, to 100MB in web.config. This attribute specifies the maximum length of content in a request. The default value is 30000000, which is approximately 28.6 MB.
```
  
    
      
    
  
```
Unlock the mode override in applicationHost.config. Open IIS 7 application configuration file, the default location is in C:windowssystem32inetsrvconfig, and change the overrideModeDefault to Allow.

Save the changes and then try to upload a file. If WebFileUploader has been successfully uploaded the file to the designated folder, it means that we are on half way to achieve the goal and ready to proceed to the next step.

Using server-side code to process uploaded files and store them into database

A database, called Files.mdf, is added into the App_Data folder of the web project. This database has Files table which consists of following fields.

Column Name	Data Type	Allow Nulls
Id	uniqueidentifier	False
FileData	varbinary(MAX)	True
OriginalName	nvarchar(50)	False
DateCreated	datetime	False

A Stored Procedure, sprocFilesInsertSingleItem, will be used to insert a single item of file into Files.mdf database.

INSERT INTO Files
(
	Id,
	FileUrl,
	FileData,
	OriginalName
)
VALUES
(
	@id,
	@FileUrl,
	@FileData,
	@originalName
)

Next, we are going to use the OnAfterUpload server-side event of WebFileUploader. It is the server-side event which fired when a file upload is succeeded. Generally, there are three processes to be performed on this event.

Read and manipulate the uploaded file using FileStream class.
Invoke and execute sprocFilesInsertSingleItem stored procedure to store the uploaded file on Files.mdf database.
Delete the specified file from the UploadPath folder.

protected void WebFileUploader1_AfterUpload(object sender, ISNet.WebUI.WebTextEditor.WebFileUploaderFileEventArgs e)
{
    byte[] fileData = ReadFile(e.WebFileUploadInfo.Path + "\" + e.WebFileUploadInfo.FileName);
    string originalName = e.WebFileUploadInfo.FileName;

    using (SqlConnection mySqlConnection = new SqlConnection(@"Data Source=.SQLEXPRESS;AttachDbFilename=|DataDirectory|Files.mdf;Integrated Security=True;Connect Timeout=30;User Instance=True"))
    {
        // Set up the Command object
        SqlCommand myCommand = new SqlCommand("sprocFilesInsertSingleItem", mySqlConnection);
        myCommand.CommandType = CommandType.StoredProcedure;

        // Set up the ID parameter
        SqlParameter prmId = new SqlParameter("@id", SqlDbType.UniqueIdentifier);

        Guid id = Guid.NewGuid();
        prmId.Value = id;
        myCommand.Parameters.Add(prmId);

        // Set up the FileUrl parameter
        SqlParameter prmFileUrl = new SqlParameter("@fileUrl", SqlDbType.NVarChar, 255);

        prmFileUrl.Value = DBNull.Value;
        myCommand.Parameters.Add(prmFileUrl);

        // Set up the FileData parameter
        SqlParameter prmFileData = new SqlParameter("@fileData ", SqlDbType.VarBinary);

        prmFileData.Value = fileData;
        prmFileData.Size = fileData.Length;
        myCommand.Parameters.Add(prmFileData);

        // Set up the OriginalName parameter
        SqlParameter prmOriginalName = new SqlParameter("@originalName", SqlDbType.NVarChar, 50);
        prmOriginalName.Value = e.WebFileUploadInfo.FileName;
        myCommand.Parameters.Add(prmOriginalName);

        // Execute the command, and clean up.
        mySqlConnection.Open();
        bool result = myCommand.ExecuteNonQuery() > 0;
        mySqlConnection.Close();
    }

    File.Delete(e.WebFileUploadInfo.Path + "\" + e.WebFileUploadInfo.FileName);
}

private static byte[] ReadFile(string filePath)
{
    byte[] buffer;
    FileStream fileStream = new FileStream(filePath, FileMode.Open, FileAccess.Read);

    try
    {
        int length = (int)fileStream.Length; // get file length
        buffer = new byte[length];           // create buffer
        int count;                           // actual number of bytes read
        int sum = 0;                         // total number of bytes read

        // read until Read method returns 0 (end of the stream has been reached)
        while ((count = fileStream.Read(buffer, sum, length - sum)) > 0)
        {
            sum += count; // sum is a buffer offset for next reading
        }
    }
    finally
    {
        fileStream.Close();
    }

    return buffer;
}

That’s it! Now the files uploaded by WebFileUploader control will be stored in database. It’s pretty easy and straightforward, don’t you think so?

Click here to download the sample and feel free to drop me a line in the comment box if you find this post useful.