Gastropods/readme.md

Guide: Getting Started With Shell (Early Preview)

Shell is a new container for your Xamarin.Forms applications that provides several key benefits.

• Beautifully themed UI by default, beginning with Material Design
• Modern navigation UI out-of-the-box via a Flyout control
• Navigate via routes
• Performance!
• Unified design by default (not yet implemented)

Pre-requisites

Preview NuGet

We have posted a preview of Xamarin.Forms that includes a very early preview of Shell. Download the packages here and add them to your local NuGet source.

Limitations

Android and iOS are the most complete platforms. UWP is in progress. No other platforms are part of the initial release plan.

Getting Started

Add a new XAML file call Shell.xaml. Replace the ContentPage with this sample code:

Note to change your application namespace from Gastropod to your own app name.

<?xml version="1.0" encoding="utf-8" ?>
<Shell xmlns="http://xamarin.com/schemas/2014/forms"
            xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
            xmlns:local="clr-namespace:Gastropod"
            Route="gastropod"
            RouteHost="www.xamarin.com"
            RouteScheme="http"
            x:Class="Gastropod.Shell">
    <Shell.FlyoutHeader>
        <local:FlyoutHeader />
    </Shell.FlyoutHeader>
</Shell>

Open Shell.xaml.cs and updated it to extend Shell instead of ContentPage.

public partial class Shell : Xamarin.Forms.Shell

Open App.xaml.cs and assign your new Shell to MainPage.

public partial class App : Application
{
    public App()
    {
        InitializeComponent();

        MainPage = new Shell();
    }
}

For several examples of creating different app variations, see the original GitHub issue.

• Single page
• 2 page with tabs
• 2 page with top and bottom tabs
• 2 page with flyout menu

Definitions

Term	Definition
Flyout	The menu for the application accessible via the hamburger button or swiping off the side. The behavior of the Flyout is set via the FlyoutBehavior on the Shell itself.
FlyoutHeader	The template for content that appears at the top of the Flyout.
MenuItem	A menu item to appear in the Flyout when a ShellContent is the presented page.
Route	The URI segment used to navigate within the app to this page.
Shell	The top level container of your appication. All children are ShellItems.
ShellContent	The Shell representation of a ContentPage.
ShellItem	Represents a top level section of your application. You can have 1 or more. By default these populate the Flyout. ShellItems contain ShellSections.
ShellSection	A grouping of ShellContent within a ShellItem.

Here is an example of a 2 page app with tabs at the bottom:

<Shell xmlns="http://xamarin.com/schemas/2014/forms"
       xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
       xmlns:local="clr-namespace:MyStore"
       FlyoutBehavior="Disabled"
       x:Class="MyStore.Shell">

  <ShellItem>

    <ShellSection Title="Home" Icon="home.png">
      <ShellContent>
        <local:HomePage />
      </ShellContent>
    </ShellSection>

    <ShellSection Title="Notifications" Icon="bell.png">
      <ShellContent>
        <local:NotificationsPage />
      </ShellContent>
    </ShellSection>

  </ShellItem>
</Shell>

Adding Pages

Each page or screen in a Shell app is represented by a ShellContent. The ContentPage is set via a DataTemplate to prevent the pages from being instantiated until they are required

<ShellContent Route="home" Title="Home" ContentTemplate="{DataTemplate local:MainPage}"/>
<ShellContent Route="feed" Title="Feed" ContentTemplate="{DataTemplate local:FeedPage}"/>

This could also be represented as:

<ShellContent Route="home" Title="Home">
    <local:MainPage />
</ShellContent>
<ShellContent Route="feed" Title="Feed">
    <local:FeedPage />
</ShellContent>

Navigation Routes

Navigation through a Shell application is handled via URIs. From the example above, the 2 pages are navigable via different routes, "home" and "feed". By simply naming the routes, Xamarin.Forms can handle all the navigation for you.

[Shell.RouteScheme]://[Shell.RouteHost]/[Shell]/[ShellItem]/[ShellSection]/[ShellContent]/[NavStack1]/[NavStack2]

A More Advanced Example

The Xamarin.Forms shell branch includes a working replica of the Google Play Store navigation model, and then some.

Design and Styling

Shell and related items can be styled like any other Xamarin.Forms control.

<Shell.Resources>
    <Style x:Key="BaseStyle" TargetType="Element">
        <Setter Property="Shell.ShellBackgroundColor" Value="#455A64" />
        <Setter Property="Shell.ShellForegroundColor" Value="White" />
        <Setter Property="Shell.ShellTitleColor" Value="White" />
        <Setter Property="Shell.ShellDisabledColor" Value="#B4FFFFFF" />
        <Setter Property="Shell.ShellUnselectedColor" Value="#95FFFFFF" />
    </Style>
    <Style TargetType="ShellItem" BasedOn="{StaticResource BaseStyle}" />
    <Style x:Key="GreenShell" TargetType="Element" BasedOn="{StaticResource BaseStyle}">
        <Setter Property="Shell.ShellBackgroundColor" Value="#689F39" />
    </Style>
    <Style x:Key="MusicShell" TargetType="Element" BasedOn="{StaticResource BaseStyle}">
        <Setter Property="Shell.ShellBackgroundColor" Value="#EF6C00" />
    </Style>
    <Style x:Key="MoviesShell" TargetType="Element" BasedOn="{StaticResource BaseStyle}">
        <Setter Property="Shell.ShellBackgroundColor" Value="#ED3B3B" />
    </Style>
    <Style x:Key="BooksShell" TargetType="Element" BasedOn="{StaticResource BaseStyle}">
        <Setter Property="Shell.ShellBackgroundColor" Value="#039BE6" />
    </Style>
    <Style x:Key="NewsShell" TargetType="Element" BasedOn="{StaticResource BaseStyle}">
        <Setter Property="Shell.ShellBackgroundColor" Value="#546DFE" />
    </Style>
</Shell.Resources>

At this time Shell is implementing Material Design. Some Material appearance options are available to you now:

<ShellItem.ShellAppearance>
      <MaterialShellAppearance NavBarCollapseStyle="Full" TabBarCollapseStyle="Full" UseSwipeGesture="false">
</ShellItem.ShellAppearance>

In the future we'll be adding an iOS themed Shell, and a Xamarin Shell where iOS and Android adhere to their platform themes by default.

NOTE! Until we implement the full extent of the Drawing spec, the design of controls will still be rooted in the native UI tool kit for each platform. Drawing aims to provide an optional path to easily achieving the same UI design across multiple platforms.

We Want Your Feedback!

After you have some time to explore Shell and take a run at various scenarios, please take a few minutes to complete this survey.

Take the Survey (coming soon)

Find something that isn't working? Could be it's not yet implemented, but file an issue nevertheless. Prefix the title with [Shell] please.