Theme And Branding

Grial offers a simple way to customize the look and feel by providing an easy and extensible theme architecture. It provides several colors and styles that will ease your UI tweaks through platforms and achieving a consistent look and feel for your app.

To start customizing your app's look and feel, please refer to App.xaml file located on the Grial (.Net Standard) folder project:

Grial
    |_ App.xaml

Inside the file you will find basically two main things:

• Theme colors (through merged dictionaries, these are the resources you will be mostly working with)
• Theme styles, measures, images, etc. and other resources

    <Application.Resources> 

        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
            
                <!-- 
                Choose from one of the available prebuilt themes:
                
                <local:BlackboardTheme />
                <local:BlackSunTheme />
                <local:DarkTheme />
                
                <local:LightTheme />
                <local:CabernetLightTheme />
                <local:HazeTheme />
                -->
                
                <local:MyAppTheme />
                
                <local:LTRTheme />
            </ResourceDictionary.MergedDictionaries>

            <ResourceDictionary Source="/Styles/AppFontFamilies.xaml" />

            ...
        </ResourceDictionary>

    </Application.Resources>

A single resource dictionary (local:LightTheme, is the Grial default theme for Grial 4) is actually being loaded and merged with the theme "base" resources.

Available Themes

There are 6 available Modern themes in the Grial themes folder you can use for your app:

LightTheme (Grial Default Theme)

DarkTheme

KubrickTheme

KubrickDarkTheme

CapellaTheme

CapellaDarkTheme

If you pick the Classic themes, you can use the 6 available themes in the Grial themes folder for your app:

LightTheme (Grial Default Theme)

DarkTheme

BlackboardTheme

BlackSunTheme

CabernetLightTheme

HazeTheme

An additional theme (MyAppTheme.xaml) -which is actually a copy of Grial Default theme (LightTheme.xaml)- is also provided so you can start working on that theme without changing the original ones.

tip

When you download your Grial project from Grial Web Admin you will get the MyAppTheme.xaml as your main theme. It will include the changes you made while working with the Grial Themes Builder

Working with colors

The most important color is the AccentColor followed by the BaseTextColor, which are used across the whole theme/app. Basically changing these values will affect the overall look and feel of your App.

The theme is made with a "Top Down" approach, so the deeper you go into the theme styles the more specific tweaks are made.

Compiling Themes

Important: Due to some limitations on Xamarin.Forms it is not possible to style everything right from App.xaml. That is the reason why when running our sample you can see most of the colors change when you change the current theme at runtime, but not the ListView selected items and some custom renderers.

Since Grial 2.0 we added an easier and reliable mechanism to compile theme colors on iOS and Android projects.

This is made through a Build Task so the process is transparent. This build task is automatically added to your project when you include UXDivers.Grial nuget packages in your project.

All you need to do is to set the theme on App.xaml, then the build task will:

• find the theme and propagate the theme's colors to
• Colors.xml on the Android project
• ThemeColors.cs on the iOS project

That way you will have everything in sync and only need to focus on the theme colors.

Advanced Theme Synchronization Configuration

Theme synchronization task can be configured using Themes.json file.

This file is just a JSON file that must be created in the same folder as the .csproj that contains the task resides. The task will read that file looking for settings.

It must be placed in the platform specific projects. If you want to configure both Android and iOS you will need to add two Themes.json independent files for each project.

Themes.json may contain one or more of these properties (the values reflect the default value of the property if not specified at all):

{
    "ThemeSyncEnabled": true,
    "AppXamlPath": null,
    "AppXamlProjectPath": null,
    "iOSColorsFileName": "ThemeColors.cs",
    "AndroidColorsFile": "Resources\\values\\Colors.xml",
    "iOSColorsNamespace": null,
    "ThemesFolder":"Themes"
}

• ThemeSyncEnabled (boolean).

  • Default value: true.
  • If set to false, theme sync will not happen at all for the projects in the folder.

• AppXamlPath (string).

  • Default value: null.
  • The full path to the App.xaml, if specified the task will not try to infer it.

• AppXamlProjectPath (string).

  • Default value: null.
  • This parameter is only considered if AppXamlPath was specified.
  • The parameter specifies the full path to the project that contains the App.xaml.
  • If only AppXamlPath is specified, the task will try to infer AppXamlProjectPath.
    • If you specify both it will just stick to them.

• iOSColorsFileName (string)

  • Default value: "ThemeColors.cs".
  • Name of the Colors file in iOS, just in case someone need to change its name.

• AndroidColorsFile (string)

  • Default value: "Resources\\values\\Colors.xml".
  • Path of the Android.Colors.xaml, just in case the default one is changed.

• iOSColorsNamespace (string)

  • Default value: null.
  • Namespace used for the ThemesColor class. If not specified the default root namespace of the project will be used.

• ThemesFolder (string)

  • Default value: "Themes".
  • Specifies the name of the Folder where Themes are stored.
  • This is just to optimize performance.
    • We try to resolve the Theme XAML against the XAMLs within this folder first.
    • If we don't find it we will look across the whole project.

One final comment:

• Now by default if the task fails for some reason it will report a Warning, not an Error.
• If you still want to report an Error, simply add a property to your .csproj called GrialFailOnError and set it to true:

<GrialFailOnError>true</GrialFailOnError>

For example:

<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <PropertyGroup>
        <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
        <Platform Condition=" '$(Platform)' == '' ">iPhoneSimulator</Platform>
        <ProjectTypeGuids>{FEACFBD2-3405-455C-9665-78FE426C6842};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>
        <ProjectGuid>{45DA7B47-C579-4BC1-B1E5-97EEA0C669CD}</ProjectGuid>
        <OutputType>Exe</OutputType>
        <RootNamespace>UXDivers.Grial</RootNamespace>
        <IPhoneResourcePrefix>Resources</IPhoneResourcePrefix>
        <AssemblyName>UXDiversGrialiOS</AssemblyName>
        <ReleaseVersion>3.0</ReleaseVersion>

        <GrialFailOnError>true</GrialFailOnError>

    </PropertyGroup>
</Project>

Notice this flag only affects the project where it is specified. You need to set it in the iOS and Android projects if you want to change the behavior in both platforms.

Brand Image

We also provide an easy way to replace your app's logo by modifying an specific resource on ThemeDictionary, called "BrandImage". Simply locate the resource and point it to your image file.

Additionally, we provide a specific XAML view to help your branding needs, the "BrandBlock.xaml", which can be found on the following location:

Grial
    |_ Controls
        |_ SharedViews
            |_ BrandBlock.xaml