Merge pull request unoplatform#6161 from unoplatform/dev/sb/material-…

…docs docs(Material): Update Material docs for new XAML init method
jeromelaban · Jun 8, 2021 · 4e65797 · 4e65797
2 parents 3b7fc4e + 2412947
commit 4e65797
Show file tree

Hide file tree

Showing 2 changed files with 67 additions and 29 deletions.
diff --git a/doc/articles/features/uno-material.md b/doc/articles/features/uno-material.md
@@ -18,26 +18,58 @@ For complete instructions on using Uno Material in your projects, including a se
                 <!-- Load WinUI resources -->
                 <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
 
+                <!-- Load Material Color Palette with optional ColorPaletteOverrideSource -->
+                <MaterialColors xmlns="using:Uno.Material"
+								ColorPaletteOverrideSource="ms-appx:///ColorPaletteOverride.xaml" />
+
+                <!-- Load the Material control resources -->
+				<MaterialResources xmlns="using:Uno.Material" />
+
                 <!-- Application's custom styles -->
                 <!-- other ResourceDictionaries -->
             </ResourceDictionary.MergedDictionaries>
         </ResourceDictionary>
     </Application.Resources>
     ```
-1. Initialize the material library in `App.xaml.cs`:
-    ```cs
+
+For complete instructions on using Uno Material in your projects, check out this walkthrough: [How to use Uno.Material](../guides/uno-material-walkthrough.md).
+
+> [!NOTE]
+> Certain controls require [additional setup steps](uno-material-controls-extra-setup.md).
+
+## Migrating From Previous Resource Initialization Method
+Prior to the `1.0` release, the initialization of Material resources was required to be done through code-behind within the `App.xaml.cs` file. Resource initialization has now been moved to XAML-only. Follow the steps below to migrate from the old method of initialization to the new one:
+
+1. Remove the following code from `App.xaml.cs` 
+    ```diff
     protected override void OnLaunched(LaunchActivatedEventArgs e)
     {
-         Uno.Material.Resources.Init(this, null);
+    -    Material.Resources.Init(this, colorPaletteOverride: new ResourceDictionary() { Source = new Uri("ms-appx:///ColorPaletteOverride.xaml") });
 
-        // [existing code...]
+        // App init...
     }
+
     ```
+1. Add `MaterialColors` and `MaterialResources` to `App.xaml`:
+    ```diff
+    <Application.Resources>
+        <ResourceDictionary>
+            <ResourceDictionary.MergedDictionaries>
+                <!-- Load WinUI resources -->
+				<XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls"/>
 
-For complete instructions on using Uno Material in your projects, check out this walkthrough: [How to use Uno.Material](../guides/uno-material-walkthrough.md).
+    +           <!-- Load Material Color Palette with optional ColorPaletteOverrideSource -->
+    +           <MaterialColors xmlns="using:Uno.Material" ColorPaletteOverrideSource="ms-appx:///ColorPaletteOverride.xaml" />
 
-> [!NOTE]
-> Certain controls require [additional setup steps](uno-material-controls-extra-setup.md).
+    +            <!-- Load the Material control resources -->
+	+			<MaterialResources xmlns="using:Uno.Material" />
+
+                <!-- Application's custom styles -->
+                <!-- other ResourceDictionaries -->
+            </ResourceDictionary.MergedDictionaries>
+        </ResourceDictionary>
+    </Application.Resources>
+    ```
 
 ## Features
 

diff --git a/doc/articles/guides/uno-material-walkthrough.md b/doc/articles/guides/uno-material-walkthrough.md
@@ -98,23 +98,19 @@ This guide will walk you through the necessary steps to setup and to use the [`U
                 <!-- Load WinUI resources -->
                 <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
 
+                <!-- Load Material Color Palette -->
+                <MaterialColors xmlns="using:Uno.Material" />
+
+                <!-- Load the Material control resources -->
+				<MaterialResources xmlns="using:Uno.Material" />
+
                 <!-- Application's custom styles -->
                 <!-- other ResourceDictionaries -->
             </ResourceDictionary.MergedDictionaries>
         </ResourceDictionary>
     </Application.Resources>
     ```
 
-1. Initialize the material library in `App.xaml.cs`:
-    ```cs
-    protected override void OnLaunched(LaunchActivatedEventArgs e)
-    {
-         Uno.Material.Resources.Init(this, null);
-
-        // [existing code...]
-    }
-    ```
-
 ### Section 2: Using Uno.Material library
 1. Let's add a few controls with the Material style to `MainPage.xaml`:
     ```xml
@@ -189,7 +185,7 @@ This guide will walk you through the necessary steps to setup and to use the [`U
 1. Replace the content of that res-dict with the source from: https://github.com/unoplatform/Uno.Themes/blob/master/src/library/Uno.Material/Styles/Application/ColorPalette.xaml
 1. Make a few changes to the color:
     > Here we are replacing the last 2 characters with 00, essentially dropping the blue-channel
-    ```
+    ```xml
     <!-- Light Theme -->
     <ResourceDictionary x:Key="Light">
         <Color x:Key="MaterialPrimaryColor">#5B4C00</Color>
@@ -208,7 +204,7 @@ This guide will walk you through the necessary steps to setup and to use the [`U
         <Color x:Key="MaterialOnErrorColor">#000000</Color>
         <Color x:Key="MaterialOverlayColor">#51000000</Color>
 
-        <!-- ... --->
+        <!-- ... -->
     </ResourceDictionary>
 
     <!-- Dark Theme -->
@@ -229,20 +225,30 @@ This guide will walk you through the necessary steps to setup and to use the [`U
         <Color x:Key="MaterialOnErrorColor">#000000</Color>
         <Color x:Key="MaterialOverlayColor">#51FFFFFF</Color>
 
-        <!-- ... --->
+        <!-- ... -->
     </ResourceDictionary>
 
-    <!-- ... --->
+    <!-- ... -->
     ```
     > You may also use this for picking colors: https://material.io/design/color/the-color-system.html#tools-for-picking-colors
-1. In `App.xaml.cs`, update the line that initializes the material library to include the new palette:
-    ```cs
-    protected override void OnLaunched(LaunchActivatedEventArgs e)
-    {
-         Uno.Material.Resources.Init(this, new ResourceDictionary { Source = new Uri("ms-appx:///Styles/Application/ColorPaletteOverride.xaml") });
-
-        // [existing code...]
-    }
+1. In `App.xaml`, update the line that initializes the `MaterialColors` to include the new palette override:
+    ```xml
+    <Application.Resources>
+        <ResourceDictionary>
+            <ResourceDictionary.MergedDictionaries>
+                <!-- ... -->
+
+                <!-- Load Material Color Palette with ColorPaletteOverrideSource -->
+				<MaterialColors xmlns="using:Uno.Material"
+								ColorPaletteOverrideSource="ms-appx:///ColorPaletteOverride.xaml" />
+
+                <!-- Load the Material control resources -->
+				<MaterialResources xmlns="using:Uno.Material" />
+                
+                <!-- ... -->
+            </ResourceDictionary.MergedDictionaries>
+        </ResourceDictionary>
+    </Application.Resources>
     ```
 1. Run the app, you should now see the controls using your new color scheme.