# Gastropods

**Repository Path**: alan69alan69/Gastropods

## Basic Information

- **Project Name**: Gastropods
- **Description**: A playground for exploring Xamarin.Forms Shell previews
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2019-04-09
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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](https://github.com/davidortinau/Gastropods/raw/master/Bits/NuGet.zip) 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](https://github.com/xamarin/Xamarin.Forms/issues/2415).
- 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 `ShellItem`s.               |
| 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`. `ShellItem`s contain `ShellSection`s.                  |
| 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 ContentTemplate="{DataTemplate local:HomePage}"/>
    </ShellSection>

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

  </ShellItem>
</Shell>
```

## Adding Pages

Each page or screen in a `Shell` app is represented by a `ShellContent`. The `ContentPage` should be 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](https://github.com/xamarin/Xamarin.Forms/blob/shell/Xamarin.Forms.Controls/XamStore/StoreShell.xaml) 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>
```

# 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](https://www.surveymonkey.com/r/X9CJNRH)

Find something that isn't working? Could be it's not yet implemented, but [file an issue](https://github.com/xamarin/Xamarin.Forms/issues/new) nevertheless. Prefix the title with `[Shell]` please.