Working with views

Working with ContentViews

Content views brings modularity and reuse to your application. They are built from a mixture of XAML and code. Gorilla knows how to handle them, but since it will only consider the XAML part when rendering the preview there are certain aspects of how to build those views that you need to know to maximize your preview experience.

The solution named ContentView located within the HowTo samples contains a couple of samples of content views that you can take a look.

Adding a simple Content View

Let's review how to include a simple content view. First we need to add a new Xamarin Forms ContentView XAML file to our solution (e.g. in Xamarin Studio File > New > File... and choosing Forms ContentView XAML). Then let's add some content on it, for example:

<?xml version="1.0" encoding="UTF-8"?>
<ContentView xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="UXDivers.Artina.Player.Samples.Template">
    <ContentView.Content>
        <Grid WidthRequest="100" HeightRequest="100" BackgroundColor="Green">
            <Label Text="Hi" />
        </Grid>
    </ContentView.Content>
</ContentView>

Now let's create a new ContentPage where we will reference the previous. In order to reference the content view we need to define a XML namespace that states where the view is located. In the case of the ContentView sample project the definition is as follows:

 xmlns:local="clr-namespace:UXDivers.Artina.Player.Samples;assembly=ContentView">

Typically a XML namespace definition involves three parts:

1. the name that will be used in the container XAML file to reference this namespace (local in the sample)
2. the CLR namespace where the content view is located (UXDivers.Artina.Player.Samples in the sample)
3. ...and the name of the assembly where the content view is located (ContentView in the sample).

Finally let's include the view within the content of the Page, as follows:

<ContentPage ...
             xmlns:local="clr-namespace:UXDivers.Artina.Player.Samples;assembly=ContentView">
    <StackLayout>
        <local:Template />
        <local:Template />
        <local:Template />
    </StackLayout>
</ContentPage>

When you preview this with Gorilla (or execute the app) you will see a stack of three rectangles with the word "Hi" within.

Custom Properties

Content views usually defines custom properties to customize them. Usually these custom properties are defined in the code using BindablePropertys. Continuing with our sample now we will define a property to control the background color of the grid that contains the "Hi".

In the sample solution a new Content View, named TemplateCustomProperty, was created to illustrate this. The custom property is defined in the TemplateCustomProperty.xaml.cs code file as follows:

public static BindableProperty TemplateBackgroundColorProperty =
    BindableProperty.Create<TemplateCustomProperty, Color>( ctrl => ctrl.TemplateBackgroundColor,
        defaultValue        : Color.Default,
        defaultBindingMode    : BindingMode.TwoWay);

public Color TemplateBackgroundColor {
    get { return (Color) GetValue( TemplateBackgroundColorProperty ); }
    set { SetValue ( TemplateBackgroundColorProperty, value ); }
}

Now this property must be integrated with the XAML part of the content view for the property to fulfill it purpose. This can be done in multiple ways.

One alternative could be to add code so each time the property changes we look for the Grid and set its background.

Another way to do this is by using bindings in the XAML, as follows:

<ContentView ...
             x:Name="Root">
    <Grid WidthRequest="100" HeightRequest="100"
       BackgroundColor="{Binding Source={x:Reference Root}, Path=TemplateBackgroundColor}">
        <Label Text="Hi" />
    </Grid>
</ContentView>

In order to reference the ContentView root element we will give it a name (Root on the sample) and we will create a binding from the Grid.BackgroundColor property to the TemplateBackgroundColor property of the Root element.

Finally, the TemplateWithProperty page shows how the this new content view is referenced and how to set custom property.

<ContentPage ...
             xmlns:local="clr-namespace:UXDivers.Artina.Player.Samples;assembly=ContentView">
    <StackLayout>
        <local:TemplateCustomProperty TemplateBackgroundColor="Red" />
        <local:TemplateCustomProperty />
        <local:TemplateCustomProperty TemplateBackgroundColor="Yellow"/>
    </StackLayout>
</ContentPage>

Following bindings approach for custom properties will make Gorilla render the preview.

On the other hand, the code approach will make Gorilla ignore those properties.