# Shell

> .NET Multi-platform App UI (.NET MAUI) Shell reduces the complexity of app development by providing the fundamental features that most apps require, including:
>
> * A single place to describe the visual hierarchy of an app.
> * A common navigation user experience.
> * A URI-based navigation scheme that permits navigation to any page in the app.
> * An integrated search handler.

Official documentation:\
<https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/shell/>\
\
MauiReactor sample app:\
<https://github.com/adospace/mauireactor-samples/tree/main/Controls/ShellTestPage>\
<https://github.com/adospace/mauireactor-samples/tree/main/Controls/ShellNavTestPage>

## Shell with ShellContents

The sample code below shows how to create a Shell with some pages using the ShellContent class:

```csharp
class MainPageState
{
    public int Counter { get; set; }
}

class MainPage : Component<MainPageState>
{
    public override VisualNode Render()
        => new Shell
        {
            new ShellContent("Home")
                .Icon("home.png")
                .RenderContent(()=> new HomePage()),

            new ShellContent("Comments")
                .Icon("comments.png")
                .RenderContent(()=> new CommentsPage()),
        };
}

class HomePage : Component
{
    public override VisualNode Render()
    {
        return new ContentPage("Home")
        {
            new Label("Home")
                .VCenter()
                .HCenter()
        };
    }
}

class CommentsPage : Component
{
    public override VisualNode Render()
    {
        return new ContentPage("Comments")
        {
            new Label("Comments")
                .VCenter()
                .HCenter()
        };
    }
}

```

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2F67E29Q8HjHs8HwyOdmlQ%2FShell.gif?alt=media&#x26;token=6cc624a5-ed36-42f0-8cf4-849728049ea2" alt=""><figcaption><p>Shell in action in Android</p></figcaption></figure>

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2FdntawsoOqYrhBQUISx9Y%2FShell2.gif?alt=media&#x26;token=4c1d93a8-1c8f-414f-8def-24959657688b" alt=""><figcaption><p>Shell in action under Windows</p></figcaption></figure>

## Shell with Tab and FlyoutItem (AsMultipleItems)

Following it's another sample of Shell with more items arranged inside a FlyoutItem and Tab:

```csharp
    public override VisualNode Render()
        => new Shell
        {
            new FlyoutItem
            {
                new Tab
                {
                    new ShellContent("Home")
                        .Icon("home.png")
                        .RenderContent(()=> new HomePage()),

                    new ShellContent("Comments")
                        .Icon("comments.png")
                        .RenderContent(()=> new CommentsPage()),
                }
                .Title("Notifications")
                .Icon("bell.png"),


                new ShellContent("Home")
                    .Icon("database.png")
                    .RenderContent(()=> new DatabasePage()),

                new ShellContent("Comments")
                    .Icon("bell.png")
                    .RenderContent(()=> new NotificationsPage()),
            }
            .FlyoutDisplayOptions(MauiControls.FlyoutDisplayOptions.AsMultipleItems)
        };

```

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2FJvg8LtmYkQkKkEfzUvI9%2FShell3.gif?alt=media&#x26;token=b1c4c2fd-071e-4f4c-bf55-9cc04a0bc941" alt=""><figcaption><p>Shell under Windows</p></figcaption></figure>

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2FGOZB3D0aJ1yTznwO3SU6%2FShell4.gif?alt=media&#x26;token=27fcc031-7229-48f8-b32f-77ace3bbf651" alt=""><figcaption><p>Shell under Android</p></figcaption></figure>

## Custom FlyoutItem appearance

In the following code, FlyoutItems appearance is customized:

```csharp
public override VisualNode Render()
    => new Shell
    {
        new ShellContent("Home")
            .Icon("home.png")
            .RenderContent(()=> new HomePage()),

        new ShellContent("Comments")
            .Icon("comments.png")
            .RenderContent(()=> new CommentsPage()),
    }
    .ItemTemplate(RenderItemTemplate);

static VisualNode RenderItemTemplate(MauiControls.BaseShellItem item)
     => new Grid("68", "Auto, *")
     {
         new Image()
            .Source(item.FlyoutIcon)
            .Margin(4),

         new Label(item.Title)
            .GridColumn(1)
            .VCenter()
            .TextDecorations(TextDecorations.Underline)
            .FontAttributes(MauiControls.FontAttributes.Bold)
            .Margin(10,0)
     };
```

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2FSeltrMEcfoELcNueXMIl%2Fimage.png?alt=media&#x26;token=af9de848-84f8-43ff-b54a-bece3b8e0f35" alt=""><figcaption><p>Customized FlyoutItems</p></figcaption></figure>

## Custom FlyoutContent

You can also provide custom content for the Flyout as shown below:

```csharp
public override VisualNode Render()
    => new Shell
    {
        new ShellContent("Home")
            .Route(nameof(HomePage))
            .Icon("home.png")
            .RenderContent(()=> new HomePage()),

        new ShellContent("Comments")
            .Route(nameof(CommentsPage))
            .Icon("comments.png")
            .RenderContent(()=> new CommentsPage()),
    }
    .FlyoutContent(RenderFlyoutContent());


VisualNode RenderFlyoutContent()
{
    return new ScrollView
    {
        new VStack(spacing: 5)
        {
            new Button("Home")
                .OnClicked(async ()=> await MauiControls.Shell.Current.GoToAsync($"//{nameof(HomePage)}")),

            new Button("Comments")
                .OnClicked(async ()=> await MauiControls.Shell.Current.GoToAsync($"//{nameof(CommentsPage)}")),
        }
    };
}

```

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2FCz9C8IxSjDx1F7oYhGqm%2Fimage.png?alt=media&#x26;token=43d48451-9951-4ff0-818b-03ae9553bff9" alt=""><figcaption><p>Custom Shell FlyoutContent</p></figcaption></figure>

## Shell menu items

You can also create a simple menu item inside the shell with a custom command:

```csharp
public override VisualNode Render()
    => new Shell
    {
        new ShellContent("Home")
            .Route(nameof(HomePage))
            .Icon("home.png")
            .RenderContent(()=> new HomePage()),

        new ShellContent("Comments")
            .Route(nameof(CommentsPage))
            .Icon("comments.png")
            .RenderContent(()=> new CommentsPage()),

        new MenuItem("Click me!")
            .OnClicked(async ()=> await ContainerPage.DisplayAlert("MauiReactor", "Clicked!", "OK"))
    };
```

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2FV4CaX49mm2AWKMpx0kWA%2Fimage.png?alt=media&#x26;token=08272ec9-03fa-4c43-b7f1-e9942fc49f22" alt=""><figcaption></figcaption></figure>

In the following sample code, we're going to customize the MenuItems:

```csharp
public override VisualNode Render()
    => new Shell
    {
        new MenuItem("Click me!")
            .IconImageSource("gear.png")
            .OnClicked(async ()=> await ContainerPage.DisplayAlert("MauiReactor", "Clicked!", "OK"))
    }
    .MenuItemTemplate(menuItem =>
        new Grid("65", "Auto, *")
        {
            new Image()
                .Source(menuItem.IconImageSource)
                .VCenter(),

            new Label(menuItem.Text)
                .TextColor(Colors.Red)
                .VCenter()
                .Margin(10,0)
                .FontAttributes(MauiControls.FontAttributes.Bold)
                .GridColumn(1)
        }
        .Padding(10,0)
        );
```

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2F41qnEYTbw5LCoEx1q7XG%2Fimage.png?alt=media&#x26;token=2d0ac7c9-e356-4d44-bc05-f148bc4a8411" alt=""><figcaption><p>Custom MenuItem</p></figcaption></figure>

## Flyout Header and Footer

You can customize the flyout header and footer as well:

{% hint style="info" %}
The following code uses the LinearGradient class provided by the MauiReactor framework ideal for describing a linear gradient brush in a single line
{% endhint %}

```csharp
public override VisualNode Render()
    => new Shell
    {
        new ShellContent("Home")
            .Route(nameof(HomePage))
            .Icon("home.png")
            .RenderContent(()=> new HomePage()),

        new ShellContent("Comments")
            .Route(nameof(CommentsPage))
            .Icon("comments.png")
            .RenderContent(()=> new CommentsPage()),
    }
    .FlyoutBackground(new LinearGradient(45.0, new Color(255, 175, 189), new Color(100, 216, 243)))
    .FlyoutHeader(RenderHeader())
    .FlyoutFooter(RenderFooter())
    ;

private VisualNode RenderHeader()
{
    return new VStack(spacing: 5)
    {
        new Label("MauiReactor")
            .TextColor(Colors.White)
            .FontSize(24)
            .HorizontalTextAlignment(TextAlignment.Center)
            .FontAttributes(MauiControls.FontAttributes.Bold)
    };
}

private VisualNode RenderFooter()
{
    return new Image("dotnet_bot.png");
}

```

This is the resulting effect:

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2FNy24vmsuDwCdtC14vvN1%2FShell5.gif?alt=media&#x26;token=d22d0530-5a8b-44c6-9db7-0fdc9c875cd6" alt=""><figcaption><p>Custom Flyout Header and Footer + custom background</p></figcaption></figure>

## Tabs

You can create Tabs on top and bottom; just nest shell contents within Tab and TabBar objects as shown in the below example:

```csharp
public override VisualNode Render()
    => new Shell
    {
        new TabBar
        {
            new ShellContent("Home")
                .Icon("home.png")
                .RenderContent(()=> new HomePage()),

            new Tab("Engage")
            {
                new ShellContent("Notifications")
                    .RenderContent(()=> new NotificationsPage()),

                new ShellContent("Comments")
                    .RenderContent(()=> new CommentsPage()),
            }
            .Icon("comments.png")
        }
    };
```

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2FKWrYwkpvvDeq3CEU8Nqy%2FShell6.gif?alt=media&#x26;token=01c2b8a8-4715-4110-b8d6-3804ac8ac889" alt=""><figcaption><p>Shell top and bottom tab bar</p></figcaption></figure>

You can also change tab bar properties like the background color or select a specific tab. The following code shows how to:

```csharp
private MauiControls.ShellContent _notificationsPage;

public override VisualNode Render()
    => new Shell
    {
        new TabBar
        {
            new ShellContent("Home")
                .Icon("home.png")
                .RenderContent(()=> new HomePage()),

            new Tab("Engage")
            {
                new ShellContent(pageRef => _notificationsPage = pageRef)
                    .Title("Notifications")
                    .RenderContent(()=> new NotificationsPage()),

                new ShellContent("Comments")
                { 
                    new ContentPage
                    {
                        new Button("Go to notifications")
                            .VCenter()
                            .HCenter()
                            .OnClicked(()=> MauiControls.Shell.Current.CurrentItem = _notificationsPage)
                    }
                }
            }
            .Icon("comments.png")
        }
        .Set(MauiControls.Shell.TabBarBackgroundColorProperty, Colors.Aquamarine)
    };
```

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2FZ6ptWZ2On3H6rFdBMYb9%2FShell7.gif?alt=media&#x26;token=ab203792-6427-479b-91c9-aa6451eb9e11" alt=""><figcaption><p>Custom tab bar color and selection of tab</p></figcaption></figure>

{% hint style="info" %}
To set an attached dependency property for a control in MauiReactor you have to use the Set() method.

For example, to set the `TabBarIsVisible` for a `ShellContent` use a code like this:

`Set(MauiControls.Shell.TabBarIsVisibleProperty, true)`
{% endhint %}

## Navigation

> .NET Multi-platform App UI (.NET MAUI) Shell includes a URI-based navigation experience that uses routes to navigate to any page in the app, without having to follow a set navigation hierarchy. In addition, it also provides the ability to navigate backwards without having to visit all of the pages on the navigation stack.

MauiReactor allows the registration of components with routes just like you do with Page in normal Maui applications.\
To register a route you have to use the `Routing.RegisterRoute<Component>("page name")` method.

The following example shows how to register a few routes and how to navigate to them:

```csharp
class MainPage : Component
{
    protected override void OnMounted()
    {
        Routing.RegisterRoute<Page2>(nameof(Page2));
        Routing.RegisterRoute<Page3>(nameof(Page3));

        base.OnMounted();
    }


    public override VisualNode Render()
        => new Shell
        {
            new Page1()
        };
}

class Page1 : Component
{
    public override VisualNode Render()
    {
        return new ContentPage("Page1")
        {
            new VStack
            {
                new Button("Goto Page2")
                     .OnClicked(async ()=> await MauiControls.Shell.Current.GoToAsync(nameof(Page2)))
            }
            .HCenter()
            .VCenter()
        };
    }
}

class Page2 : Component
{
    public override VisualNode Render()
    {
        return new ContentPage("Page2")
        {
            new VStack
            {
                new Button("Goto Page3")
                    .OnClicked(async ()=> await MauiControls.Shell.Current.GoToAsync(nameof(Page3)))
            }
            .HCenter()
            .VCenter()
        };
    }
}

class Page3 : Component
{
    public override VisualNode Render()
    {
        return new ContentPage("Page3")
        {
            new VStack
            {
                new Button("Open ModalPage")
                    .OnClicked(async () => await Navigation.PushModalAsync<ModalPage>())
            }
            .HCenter()
            .VCenter()
        };
    }
}

class ModalPage : Component
{
    public override VisualNode Render()
    {
        return new ContentPage("Modal Page")
        {
            new VStack
            {
                new Button("Back")
                    .OnClicked(async () => await Navigation.PopModalAsync())
            }
            .HCenter()
            .VCenter()
        };
    }
}
```

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2FEjKGSxtH58Zhj1w76WWt%2FShell8.gif?alt=media&#x26;token=903164c3-e35a-4d43-b03a-92b2b1350db6" alt=""><figcaption><p>Shell navigation in action</p></figcaption></figure>

Passing arguments to pages (components) would mean creating a Props class for the target page and using an overload of the GotoToAsync as shown below:

```csharp
class Page2 : Component
{
    public override VisualNode Render()
    {
        return new ContentPage("Page2")
        {
            new VStack
            {
                new Button("Goto Page3")
                    .OnClicked(async ()=> await MauiControls.Shell.Current.GoToAsync<PageWithArgumentsProps>(nameof(PageWithArguments), props => props.ParameterPassed = "Hello from Page2!"))
            }
            .HCenter()
            .VCenter()
        };
    }
}


class PageWithArgumentsState
{ }

class PageWithArgumentsProps
{
    public string ParameterPassed { get; set; }
}

class PageWithArguments : Component<PageWithArgumentsState, PageWithArgumentsProps>
{
    public override VisualNode Render()
    {
        return new ContentPage("PageWithArguments")
        {
            new VStack(spacing: 10)
            {
                new Label($"Parameter: {Props.ParameterPassed}")
                    .HCenter(),

                new Button("Open ModalPage")
                    .OnClicked(async () => await Navigation.PushModalAsync<ModalPage>())
            }
            //.HCenter()
            .VCenter()
        };
    }
}
```

<figure><img src="https://877538538-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh1eh1igwiwRzrw2kbxSp%2Fuploads%2FVzIhLaIuF3bG6pc2PVeU%2FShell9.gif?alt=media&#x26;token=f69cf5b4-6d0c-4a94-8aa7-39bac5151938" alt=""><figcaption><p>Passing arguments to pages</p></figcaption></figure>

{% hint style="info" %}
If you want to pass arguments to a modal page, use the overload of the `Navigation.PushModalAsync<Page, Props>()` method.
{% endhint %}

## Shell TitleView

Shell control enables any `View` to be displayed in the navigation bar using the TitleView. In MauiReactor, you can set up a custom view using the TitleView fluent method of the ContentPage.

```csharp
public override VisualNode Render()
    => ContentPage(
        ....
    )
    .TitleView(RenderTitleView);

Grid RenderTitleView()
    => Grid(
        Label("Title View")
            .VCenter()
            .FontSize(18)
            .FontAttributes(MauiControls.FontAttributes.Bold)
            .Margin(10, 0)
    );    
```

{% hint style="warning" %}
ContentPage must be installed inside a Shell to enable the TitleView
{% endhint %}

{% hint style="info" %}
You can also customize the Window title with custom content. For more info, refer to the [Window control page](https://adospace.gitbook.io/mauireactor/components/window).
{% endhint %}