CwwOnline.TabbedPageExt.Xamarin

[package version: 1.0.2 and higher]

A TabbedPage for Xamarin Forms which supports:

• UI virtualization: Tab pages can either directly be created (before they are selected) or they can be created at the moment the tab is selected.
• Crossplatform 'More' view: For all platforms (android, iOS, uwp, ..) a 'more' tabbar button (iOS) or toolbar button (android, uwp) is automatically inserted popping up an iOS-like "More" listview to select one of the 'hidden' pages. As an option it also possible to configure the tabbed page to show a popup menu when touching the 'more' toolbar button (ios, android, uwp). The popup menu lists each overflow page with an icon and the page title.
• Navigation support: Possibility to push the TabbedPage itself on the navigation stack.

Important: You can use TabbedPageExt instead of TabbedPage in all of your projects EXCEPT when you want to implement OnAppearing and OnDisappearing in one or more of your tab pages. These methods will NOT be called!

Example view:

Mode 1: 'More' page list (as in iOS)

"

Mode 2: 'More' popup menu (as in android)

"

Supported platforms

• iOS
• Android
• UWP

Installation

The plugin is available on NuGet: https://www.nuget.org/packages/CwwOnline.TabbedPageExt.Xamarin/. Install the plugin into your PCL project and in your iOS, Android and UWP client projects. In case of Android and UWP the plugin assumes that one of the following image files are present in the Android resources folder and the UWP main folder:

• tabbedpageext_more_vert_black.png (in case you want a black 'more' icon in the toolbar), and
• tabbedpageext_more_vert_white.png (in case of a white icon) You can find various resolutions of these files in the plugin's Android "resources/drawable" folders here; If necessary you can however also override the expected icon's filename. See properties.

If you want to have a popup menu when pressing 'More' then you must also install the Rg.Plugins.Popup package. This plugin is also available on NuGet: https://www.nuget.org/packages/Rg.Plugins.Popup. It extends the footprint of your app somewhat but it is an easy to use tool in your project in case you are looking for flexible and customizable popups.

Usage

TabbedPageExt extends the TabbedPage class of xamarin.forms in a couple of ways:

• The child pages that you want to add to the class are instantiated at the moment when the user selects them.
• On Android and UWP TabbedPageExt also supports the concept of and 'overflow' page in a similar way as in iOS. The only difference is that the 'More' icon/button is on the top toolbar. Pressing the button shows a full page with a listview from where a page can be opened. TabbedPageExt creates itself the 'overflow' list page (also on iOS). This has the advantage that on all platforms the page (when opened) always appears on the top of the app; also when the tabbed page itself is pushed on the navigation stack.
• On all platforms (i.e. also on iOS, if you want) TabbedPageExt can also be told to show the overflow pages in a popup menu.
• The overflow breakpoint is configurable.

Creating and populating a TabbedPageExt page

The following example shows how to create a TabbedPageExt page and populate it with a number of child pages.

public class MyTabbedPage: TabbedPageExt.TabbedPageExt
{
  public MyTabbedPage()
      : base(Device.RuntimePlatform == Device.Android ? IconColor.White : IconColor.Black)
   {
      MorePageTitle = "Meer";
      var tabPage1 = new TabPage(
         "Tab1",
         "tab1_icon_white.png", "tab1_icon_black.png",
         typeof(ContentPage1),
         new ContentPage1ViewModel());
      this.TabPages.Add(tabPage1);
      
      var tabPage2 = new TabPage(
         "Tab2",
         "tab2_icon_white.png", "tab2_icon_black.png",
         () =>
         {
            return (ContentPage2)Activator.CreateInstance(typeof(ContentPage2), new ContentPage2ViewModel());
         });
      this.TabPages.Add(tabPage2);
      
      var tabPage3 = new TabPage(
         "Tab3",
         "tab3_icon_white.png", "tab3_icon_black.png",
         () =>
         {
            return (ContentPage3)Activator.CreateInstance(typeof(ContentPage3), new ContentPage3ViewModel());
         });
      this.TabPages.Add(tabPage3);
      
   }
}

TabbedPageExt expects an *IconColor enum value in its constructor which defines whether the 'More' icon in the app's toolbar must be black or white. The icon itself is defined in the plugin's assembly.

Property MorePageTitle let's you change the 'More' icon title from the default ("More") to whatever language you want, like: "Meer" (dutch).

The page is populated with a number of child pages by creating a TabPage for each of them:

• The title of the first page is "Tab1"; the page icon is "tab1_icon_white.png"; the icon used in the 'more' page list or popupmenu is "tab1_icon_black.png"; the actual content of the page comes from MyContentPage (and MyContentPageViewModel) which is created when the page is selected. MyContentPage is typically a normal xamarin.forms ContentPage. TabPage is instructed to instantiate this page by passing the page Type and an optional viewmodel object. When present, the viewmodel will be given as parameter to the page constructor.
• The 2nd page is defined by passing a Func<> delegate to TabPage to create the ContentPage when the page is opened.
• Other pages can then be added by using any of the above 2 methods.

The 2nd method has the advantage that you have the freedom to create the the ContentPage's viewmodel at the moment the page is opened. If you opt to create view models using some kind of factory concept or dependency injection then of course method 1 works equally well.

Note: Creating and populating a TabbedPageExt page using XAML is not supported.

Instantiating a TabbedPageExt

Creating and opening a TabbedPageExt is done as with any xamarin.forms page. Next example pushes and opens the page on the navigation stack.

private void OnOpenMyTabbedPage(object sender, EventArgs e)
{
   var navigationPage = App.Current.MainPage as NavigationPage;
   var tabbedPage = new MyTabbedPage();
   navigationPage.PushAsync(tabbedPage);
}

Set overflow threshold

The overflow threshold (default = 4) can be set by assigning a value to property MaxTabs of TabbedPageExt. You must set the value before adding child pages. An example:

public MyTabbedPage()
      : base(Device.RuntimePlatform == Device.Android ? IconColor.White : IconColor.Black)
   {
      MaxTabs = Device.RuntimePlatform == Device.iOS ? 4 : 5;
      
      // Add TabPages
      ...
   }

Note: On iOS you should never set the threshold higher than what is defined in the platform since iOS will automatically introduce a 'More' tab when you overflow the limit.

More page list or popup menu

As per default TabbedPageExt is configured to show an iOS-like page overflow selection list when tapping the 'more' button. To change the mode to show a popup menu you must set the property MorePageMode to MorePagesAccessMode.MorePopupMenu. You must set the value before adding child pages. An example:

public MyTabbedPage()
      : base(Device.RuntimePlatform == Device.Android ? IconColor.White : IconColor.Black)
   {
      MaxTabs = (Device.RuntimePlatform == Device.iOS) ? 4 : 5;
      MorePageMode = MorePagesAccessMode.MorePopupMenu;
      
      // Add TabPages
      ...
   }

Adding and removing child pages

TabbedPageExt exposes the TabPages property (an ObservableCollection) upon which you can invoke the Add, Remove, and Clear methods.

When you remove a child page that is not in the 'overflow' page list, then the plugin will move the first page in the 'overflow' list to the visible list. If you don't want that then you must set the DontMovePages property to true.

Styling

More page list

The iOS-like page list is created as a basic ContentPage with a ListView. The plugin doesn't set any color, height, etc. properties.

More popup menu

The android-like popup menu is a popup of which the list is fixed aligned to the top and right side of the screen using a defined margin. Default styles are:

• Margin: 0,44,8,0 (iOS) and 0,56,8,0 (Android and UWP)
• Width: 200
• Height: Number of page items x platform-dependent item height (iOS: 44, Android: 45, UWP: 33).
• TextColor of the page title label: White.
• Background color: "#303030"
• Page item seperator color: "#9C969C"
• Page item selected background color: "#707070"

You can change the above defaults by defining different values through a number of properties of your TabbedPageExt page. See API description.

API description

TabbedPageExt properties

MorePageTitle	A string for the "More" text presented on the More tab (iOS) or the More toolbar icon (other platforms).
MoreToolbarIcon	A string defining the name of the icon image on the 'More' button of the app toolbar. When set it overrides the default icon provided by the plugin.
MorePagesMode	Defines how overflow pages (i.e. those exceeding MaxTabs while adding them) are made accessible. Set to enum value MorePagesAccessMode.MorePage (default) or MorePagesAccessMode.MorePopupMenu.
MaxTabs	The maximum number of tabs to be shown on the TabbedPage. Default = 4.
DontMovePages	Set this property to True when you don't want the first hidden tab page to be shown in case a visible page is removed. Default = False.
MorePopupMenuMargin	A xamarin.forms Thickness definition which you can set to override the default margin of the popup menu. Note that the margin aligns the menu on the top right side of the screen. That cannot be changed.
MorePopupMenuBackgroundColor	Set this Color property to override the default background color of a popup menu.
MorePopupMenuItemTextColor	Set this Color property to override the default text color of a page title in a popup menu.
MorePopupMenuItemSelectedBackgroundColor	Set this Color property to override the default background color of a selected page item in a popup menu.
MorePopupMenuItemSeperatorColor	Set this Color property to override the default color of the seperator lines in a popup menu.
MorePopupMenuItemSeperatorVisibility	You can tell the plugin with this property to hide or show the seperator lines in a popup menu. Default: show.
MorePopupMenuItemHeigth	The plugin assumes that page items in a popup menu have a given height in a given platform. You can force a specific height here.

TabPage constructor

TabPage has 2 constructors.

Constructor 1

public TabPage(string title, string pageIcon, string moreListIcon,
               Type pageType, object viewModel = null)

title	A string specifying the title of the page.
pageIcon	A string defining the name of a resource file containing the icon that must be used as 'tab' page icon. On iOS the icon is shown on the tab bar at the bottom of the screen. On Android it is shown together with the title on the page's tab appearing at the top of the screen. Leave the icon empty for Android of you only want to have a title in the tab.
moreListIcon	A string defining the name of a resource file containing the icon that must be shown on the left side of the page title in a 'more' page list or popup menu.
pageType	The Type of the page that must be created when the user taps/opens the page.
viewModel	An object (typically a view model) that must be assigned as parameter in the page constructor. Leave empty if the plugin must construct the page without a parameter.

Constructor 2

public TabPage(string title, string pageIcon, string moreListIcon,
               Func<ContentPage> createContentPage)

title	See constructor 1.
pageIcon	See constructor 1.
moreListIcon	See constructor 1.
createContentPage	A func delegate that creates the page (must derive from ContentPage) and returns the page as value. The method is invoked when the user taps/opens the page.