Skip to content

Tag: UI

What is a Custom Renderer?!

One of the most initially confusing, yet essential components to Xamarin.Forms are custom renderers. If you look at almost any advanced feature or customization tutorial for Forms, you are likely to run into the term custom renderer. But what the heck is a custom renderer?!? Everyone seems to reference the use of them, yet no one seems to take the time to thoroughly explain what they are and how they work.

Custom renderers are really simple once you understand the foundation behind how Forms renderers the user interface. Forms maps every UI element to each of the native platforms’ UI elements. In other words, Forms has generic views/controls that are referenced in XAML and are transformed into the native platforms equivalent view. For example, Forms has a Xamarin.Forms.Button class, which gets rendered to UIKit.UIButton on iOS, and android.widget.Button on Android. Essentially, a renderer is simply a mapping between a Forms element, and a platform’s native element. A custom renderer goes one step further; the developer, can override or extend Xamarin’s renderer.

Why would we ever want to change Xamarin’s default renderer? While Xamarin implements a majority of our UI/UX needs, we might need more granular control over the look or behavior of our views.

How do we create a custom renderer? A simple scenario (yet annoying) that requires the use of a custom renderer is when you want to prevent autocorrect on an Entry field when rendered on iOS. An Entry field is Forms’ version of a textbox. Unfortunately, by default on iOS, the textbox has autocorrection and first letter capitalization turned on, yet Forms does not provide a simple way to disable these settings. This is an example of a situation where a custom renderer is required to accomplish our goal.

Suppose you have a simple login page that uses an Entry field for the username and password:

Notice that we are using the default Entry tags in the LoginPage’s XAML. The magic does not happen within the portable class library (PCL); rather, all of our customization will be handled in each platforms’ native project.

  1. For this example, create a folder in the iOS project called: Renderers
  2. Within that new folder, create a new class called: CustomEntryRenderer
  3. Add the following line to the class before the namespace: [assembly: ExportRenderer(typeof(Entry), typeof(MyCoolApp.iOS.CustomEntryRenderer))]
  4. Have the class inherit from: EntryRenderer
  5. Override: OnElementChanged

Within a custom renderer class, there are two important properties to be aware of, Control and Element. The Control property refers to the platform’s native view. The Element is the Forms’ mapping to the Control. For this simple example, we only need to manipulate two settings on the native Control, AutocapitalizationType and AutocorrectionType.

Now, whenever we use an Entry element within our PCL project, this custom renderer will override the default iOS renderer due to the assembly reference we added before the namespace. One nice design aspect to note is that the our views are blissfully unaware of the custom renderer (i.e. they are loosely coupled). That also means that since we did not implement an Android custom renderer, Android will continue to use the default renderer.

Custom App Header in Forms

iOS Navigation Bar NestedIt is safe to assume that any business with a customer facing application will want to brand their application with at least their logo. From the very onset of using Xamarin.Forms, I found myself annoyed with the lack of customizability of the navigation bar for iOS. To be fair, it is a pain to customize on the native side; however, the Forms’ abstraction removes most of your options.

NOTE: the navigation bar shows up when a Page is nested within a NavigationPage; this creates a navigation stack.

The equivalent implementation for Android is a toolbar or action bar. Within the Android project, you can customize the toolbar using the native Toolbar.axml layout file. Unfortunately, in order to customize the iOS navigation bar to the same extent as Android requires a custom renderer and a fair amount of hacking. Even with the ability to manipulate the look of the iOS navigation bar using a custom renderer, both platforms are now diverging from each other (not to mention if you support Windows). This messy solution wasn’t going to work for me. Two simple features resolved this dilemma.

I came to the realization that I could not use the navigation bar (iOS) or toolbar (Android) and maintain a unified solution between platforms. Simply put, I wanted the platform specific bars to disappear. Thankfully, Xamarin provides a simple way to turn them off. Using the static reference to NavigationPage provides the method SetHasNavigationBar. This method takes two parameters, the page the setting applies to and the boolean value.

At this point my navigation stack no longer has a header. This allows me to add a completely custom implementation that will work for all platforms. An easy way to create such a header is with the combination of a boxview, a back button, and a logo. The specifics are not important because it will vary greatly between applications. An example could look like the following:

But how do I apply this XAML to each of my pages?! This can be accomplished with a ControlTemplate. A ControlTemplate is a UI template that can be applied to any XAML page. You’ll define the template in the ResourceDictionary located in the App.xaml file. You will also include a ContentPresenter within the template. A ContentPresenter is the content area or body of the pages the template is being applied to. The ControlTemplate Key will be used to reference the template in your pages.

Once the ControlTemplate is created, we need to apply it to our Pages. This is accomplished by adding a StaticResource reference of the template Key inside our pages’ ControlTemplate property in the XAML.

iOS Custom App HeaderYou now have a fully customizable header for your application. You can add EventHandlers, Commands, or GestureRecognizers to interact with your header as needed. You will have to implement the back button logic as well.

Creating Xamarin.Forms Solution

In this post, we will see how to create a simple Xamarin.Forms application. We will be using Xamarin Studio as our IDE of choice; the initial setup is almost identical using Visual Studio. There is one cavate when determining your developer environment, Mac OS X is required to compile iOS applications and Windows is required to compile Windows applications (thanks Google for playing nice). In a later blog post, I will cover how to add a Windows application to an existing project created on Mac OS X using a Windows virtual machine.

To get started, first open Xamarin Studio on a Mac. From the menu bar, select File > New > Solution. The following dialog will appear. This dialog will allow you to select which project template to use for your solution. Select Multiplatform > App > Forms App and then click Next.

Xamarin Studio New Solution Choose A Template

You will then see another dialog to configure the main settings for your Forms App.

In the App Name textfield, put the name of your application. If the name of the application is more than one word,  Xamarin Studio will add dashes to the complete package name. This can have unintended consequences later on when using advanced features such as intent filtering. My recommendation is to not add any spaces using this dialog and we will fix the display name after the solution has been created (iOS: Open Info.plist > Update Application Name textfield to the desired display name | Android: Right Click on Android Project > Select Android Application > Update Application Name textfield to the desired display name).

In the next textfield, type your organization’s identifier such as a company name. It is customary to prefix the name of your organization with “com.”; the organization identifier and app name will be concatenated to make your applications’ package name (e.g. com.MyCompany.HelloForms).

Next, select which platforms you intend to target. Notice that only Android and iOS are available, this is due to the fact that we are using a Mac. We will add Windows to the solution in a later blog post.

Under the Shared Code section you have the option between using a Portable Class Library (PCL) or a Shared Library. There are pros and cons to using either option. For this example, we will use a PCL since it is the simplest of the two and is the preferred method.

Lastly, you will have the option to use XAML for building your User Interface (UI). This option does not prevent you from using C# to create some or even all your views, it simply indicates your preference. If you are not familiar with XAML, it stands for Extensible Application Markup Language and is an XML based language used to create UIs. XAML is not unique to Xamarin; Microsoft actually developed it and is used with a multitude of technologies such as SilverLight and WPF. For this demo, leave XAML left checked. Then click Next.

Xamarin Studio New Solution Configure Your Forms App

In the final dialog, you will configure your main project settings.

In the Project Name textfield, put the name of your application. This will be used as the name of your PCL project and the prefix to your Android and iOS projects (e.g. HelloForms.Droid and HelloForms.iOS).

In the Solution Name textfield, put the name of your solution. This does not have to match your project name.

Location indicates where on the file system your new solution will be located.

Version Control instantiates a local git repository inside the solution directory. We will not be using git for this demo.

Leave Xamarin Test Cloud unchecked for this demo. Click Next.

Xamarin Studio New Solution Configure Project

We now have a fully functioning application. In the next blog post, we will go over the structure of the solution in detail.