{"id":34664,"date":"2017-12-08T12:37:58","date_gmt":"2017-12-08T20:37:58","guid":{"rendered":"https:\/\/blog.xamarin.com\/?p=34664"},"modified":"2017-12-08T12:37:58","modified_gmt":"2017-12-08T20:37:58","slug":"native-forms-polished-shiny-xamarin-forms-2-5-0","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/xamarin\/native-forms-polished-shiny-xamarin-forms-2-5-0\/","title":{"rendered":"Native Forms is Polished and Shiny in Xamarin.Forms 2.5.0"},"content":{"rendered":"

\t\t\t\tSince we previewed Native Forms<\/a> in June, we\u2019ve been working to smooth the rough edges and polish it up for Xamarin.Forms 2.5.0 by fixing bugs and integrating the excellent feedback from the community.<\/p>\n

Last month at Microsoft Connect(); in New York, several Native Forms examples were used in the keynote presentation. Most notably, James Montemagno demonstrated adding a Xamarin.Forms page to the open source Kickstarter iOS application. You can watch the entire keynote on Channel9<\/a>.<\/p>\n

\"\"<\/p>\n

Another example is the SmartHotel360 suite of applications, which includes a maintenance application that uses Native Forms to composite Xamarin.Forms pages into native Xamarin.iOS and Xamarin.Android applications. The full code for these applications will be made available soon on GitHub.\n<!–\n\"\"<\/a>\n–><\/p>\n

This post covers these changes and serves as a guide for you to get started embedding Native Forms in your own applications.<\/p>\n

What is Native Forms?<\/h2>\n

The tl;dr;<\/strong> is that Native Forms allows you to use a Xamarin.Forms ContentPage in a native Xamarin.iOS, Xamarin.Android, or UWP application.<\/p>\n

But why, you may ask, would I want to do that? Let’s consider some scenarios:<\/p>\n

Existing Xamarin.Forms Reuse<\/strong><\/p>\n

Perhaps you wrote a login page for a service in a previous Xamarin.Forms project. Now, you’re working on a native Xamarin project which uses the same service. Rather than write that page again, you can simply reuse it directly from the Forms project.<\/p>\n

Migrate Xamarin.Forms to Xamarin Native<\/strong><\/p>\n

Let’s say you used Xamarin.Forms to quickly create a prototype or proof-of-concept application. For version two, you have decided that on iOS you need to go native. However, you’re not thrilled with the prospect of rewriting every single page from the prototype for your native app. With Native Forms, you can reuse pages from the prototype and only rewrite what you absolutely have to.<\/p>\n

Mix Xamarin.Forms into Xamarin Native Projects<\/strong><\/p>\n

You\u2019re working on multiple native projects and facing the prospect of writing the same \u201cSettings\u201d and \u201cAbout\u201d pages three times. Stop! Just write them once in a Xamarin.Forms project and embed them in your native apps!<\/p>\n

A Simple Scenario<\/h2>\n

To show Native Forms in action, let\u2019s walk through a scenario with some code. The full code for this example can be found on GitHub<\/a>.<\/p>\n

Let\u2019s say I\u2019m creating brand new native applications for UWP, Android, and iOS. In each one, I\u2019d like to add a tip calculator, but I really don\u2019t want to write three tip calculators from scratch. Luckily for me, Charles Petzold has already written one in Xamarin.Forms<\/a>, so all I have to do is embed it in each of the native apps.<\/p>\n

In the demo solution, I\u2019ve created three native projects, plus a project for the TipCalc code:<\/p>\n

\"Solution\"
Solution<\/figcaption><\/figure>\n

In my TipCalc project, I\u2019ve simply copy-pasted the code from the original TipCalc solution\u2019s PCL project. The code works as-is without any changes, but in my project I\u2019ve updated some obsolete XAML and added some MessagingCenter<\/code> code, which I\u2019ll talk about later.<\/p>\n

To embed the code in each native application, I need to add a reference to the TipCalc project and install the Xamarin.Forms NuGet package. Once I\u2019ve done that, my references in each native project will look something like this:<\/p>\n

\"iOS
iOS project references<\/figcaption><\/figure>\n

Before each native project can embed any Xamarin.Forms pages, they need to initialize Forms by calling Forms.Init()<\/code>. When<\/em> a native application does this is up to you, as long as it happens before constructing any instance of a Forms ContentPage<\/code>. You may choose to do it at startup (e.g., during UIApplicationDelegate.FinishedLaunching()<\/code> or Activity.OnCreate()<\/code>), or you may want to wait until right before the first ContentPage<\/code> is constructed. The right option for you will depend primarily on when it\u2019s most convenient in your application flow.<\/p>\n

After Xamarin.Forms is initialized, it\u2019s just a matter of setting up navigation to the TipCalcPage<\/code>. Native Forms adds some extension methods to Xamarin.Forms, which handle converting a ContentPage<\/code> to the appropriate native type.<\/p>\n

In a native iOS project, for example, you would normally use UINavigationController.PushViewController()<\/code> with a UIViewController<\/code>. Native Forms provides an extension to ContentPage<\/code>, which converts the page to a UIViewContoller<\/code> for you. The method for navigating to the tip calculator could be as simple as:<\/p>\n

public void NavigateToTipCalc()\n{\n    _navigation.PushViewController(new TipCalcPage().CreateViewController(), true);\n}<\/code><\/pre>\n
where _navigation<\/code> is a UINavigationController<\/code>. That\u2019s it; call that method from the \u201cTip Calculator\u201d button and the application navigates to the Xamarin.Forms page.<\/p>\n
\"Navigating
Navigating to the embedded Forms page on iOS<\/figcaption><\/figure>\n
On Android, Native Forms provides the CreateFragment()<\/code> and CreateSupportFragment()<\/code> methods. These will convert a ContentPage<\/code> into a Fragment<\/code> suitable for navigation. For example, add a method like this to a FragmentActivity<\/code>:<\/p>\n
public void NavigateToTipCalc()\n{\n    var ft = SupportFragmentManager.BeginTransaction();\n\n    ft.AddToBackStack(null);\n    ft.Replace(Resource.Id.fragment_frame_layout,\n        new TipCalcPage().CreateSupportFragment(this), \"TipCalc\");\n\n    ft.Commit();\n}<\/code><\/pre>\n
\"Navigating
Navigating to the embedded Forms page on Android<\/figcaption><\/figure>\n
For native UWP applications, navigation is typically done with the Frame<\/code> class; the Frame.Navigate()<\/code> method takes a Page<\/code> type and navigates to an instance of it. Native Forms provides a similar extension to Frame<\/code>, which takes a ContentPage<\/code> instance. Navigating can be as simple as:<\/p>\n
private void NavigateToTipCalc()\n{\n    Frame.Navigate(new TipCalcPage());\n}<\/code><\/pre>\n
\"Navigating
Navigating to the embedded Forms page on UWP<\/figcaption><\/figure>\n
As you can see, using Native Forms doesn\u2019t take a whole lot of code.<\/p>\n
Handling Communication<\/h2>\n
Chances are good that you also need to communicate between the native context and the Xamarin.Forms portions of your apps. If you\u2019re reusing Xamarin.Forms code from another project, you may already have something set up using whatever event aggregator, message bus, or other method makes sense for your stack. But if you don\u2019t already have something in place, Xamarin.Forms comes with a built-in messaging service (called MessagingCenter<\/code>) which can be used to wire up communications between native applications and the Xamarin.Forms pages they host.<\/p>\n
In this demo solution, I\u2019ve modified the TipCalc project a bit to allow it to send and receive data to and from its host app using MessagingCenter<\/code>. I\u2019ve defined messages and their arguments:<\/p>\n
public static class Messages {\n    public static object Sender = new object();\n    public const string InitialAmount = \"InitialAmount\";\n    public const string Tip = \"Tip\";\n}\n\npublic class InitialAmountArgs {\n    public InitialAmountArgs(double initialAmount) {\n        InitialAmount = initialAmount;\n    }\n\n    public double InitialAmount { get; }\n}\n\npublic class TipArgs {\n    public TipArgs(double tip) {\n        Tip = tip;\n    }\n\n    public double Tip { get; }\n}<\/code><\/pre>\n
With that infrastructure in place, it\u2019s easy for the native applications to specify an initial amount for the tip calculator. Each native app has a field for entering the initial amount; when the user updates that field, a message is sent:<\/p>\n
MessagingCenter.Send(TipCalc.Messages.Sender, TipCalc.Messages.InitialAmount, \n    new InitialAmountArgs(InitialAmount));<\/code><\/pre>\n
The view model in the TipCalc project (TipCalcModel<\/code>) listens for that message and reacts accordingly:<\/p>\n
MessagingCenter.Subscribe(this, Messages.InitialAmount, (s, e) =>\n{\n    SubTotal = e.InitialAmount;\n});<\/code><\/pre>\n
It\u2019s also simple for the native apps to respond to changes in the calculated tip value. Whenever the TipAmount<\/code> in TipCalcModel<\/code> changes, it sends a message:<\/p>\n
MessagingCenter.Send(Messages.Sender, Messages.Tip, new TipArgs(value));<\/code><\/pre>\n
The native application can listen for that message and react; for example, the iOS application sets the text of a UILabel:<\/p>\n
MessagingCenter.Subscribe(TipCalc.Messages.Sender, TipCalc.Messages.Tip,\n    (obj, args) => TipAmount.Text = args.Tip.ToString(\"C\"));<\/code><\/pre>\n
Here\u2019s the app in action on UWP. The user enters an initial amount, which is passed to the tip calculator, and the result from the tip calculator is relayed back to the native page:<\/p>\n
\"Communication
Communication on UWP<\/figcaption><\/figure>\n
Just Pages?<\/h2>\n
Savvy readers will have noticed that the extension methods all provide return types that don\u2019t necessarily require<\/em> full page navigation. It’s also possible to use UIViewController<\/code>, FrameworkElement<\/code>, and Fragment<\/code> as part<\/em> of a page rather than a full screen. We previously showed<\/a> how to display a ContentPage<\/code> on UWP inside of a Flyout<\/code>, instead of a full page.<\/p>\n
In theory, these methods could be used to embed a ContentPage<\/code> as part of a larger page on each platform. As of right now, that’s very much an officially un<\/strong>supported<\/em> use case. That said, if you experiment with that use case, I\u2019d love to hear how it works for you.<\/p>\n
Update to 2.5.0 Today!<\/h2>\n
You can begin using Native Forms today in our latest stable version, Xamarin.Forms 2.5.0, available on NuGet. If you have any feedback or suggestions, please let us know in the forums<\/a>!\t\t<\/p>\n","protected":false},"excerpt":{"rendered":"
Since we previewed Native Forms in June, we\u2019ve been working to smooth the rough edges and polish it up for Xamarin.Forms 2.5.0 by fixing bugs and integrating the excellent feedback from the community. Last month at Microsoft Connect(); in New York, several Native Forms examples were used in the keynote presentation. Most notably, James Montemagno […]<\/p>\n","protected":false},"author":1962,"featured_media":39167,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[2],"tags":[16],"class_list":["post-34664","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-developers","tag-xamarin-forms"],"acf":[],"blog_post_summary":"
Since we previewed Native Forms in June, we\u2019ve been working to smooth the rough edges and polish it up for Xamarin.Forms 2.5.0 by fixing bugs and integrating the excellent feedback from the community. Last month at Microsoft Connect(); in New York, several Native Forms examples were used in the keynote presentation. Most notably, James Montemagno […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts\/34664","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/users\/1962"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/comments?post=34664"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/posts\/34664\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/media\/39167"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/media?parent=34664"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/categories?post=34664"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/xamarin\/wp-json\/wp\/v2\/tags?post=34664"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}