Walkthrough: Creating a Theme Extension

Article
12/08/2014

This walkthrough demonstrates how to create a theme extension for LightSwitch. A theme extension defines a color and font palette for the LightSwitch shell.

To create a theme extension, you must do the following:

Create a theme extension project.
Specify the display name and description.
Define the theme.
Test the theme extension.

Prerequisites

Visual Studio 2013 Professional
Visual Studio 2013 SDK
LightSwitch Extensibility Toolkit for Visual Studio 2013

Create a Theme Extension Project

The first step is to create a project and add a LightSwitch Theme template.

To create an extension project

On the menu bar in Visual Studio, choose File, New, Project.
In the New Project dialog box, expand the Visual Basic or Visual C# node, expand the LightSwitch node, choose the Extensibility node, and then choose the LightSwitch Extension Library template.
In the Name field, enter TestThemeExtension as the name for your extension library. This name will appear on the Extensions tab of the LightSwitch Application Designer.
Choose the OK button to create a solution that contains the seven projects that are required for the extension.

To choose an extension type

In Solution Explorer, choose the TestThemeExtension.Lspkg project.
On the menu bar, choose Project, Add New Item.
In the Add New Item dialog box, choose LightSwitch Theme.
In the Name field, enter TestTheme as the name for your extension.
Choose the OK button. Files will be added to several projects in your solution.

Specify the Display Name and Description

The default name for your theme is “TestTheme” and the default description is “TestTheme description.” Both of these will appear in the Application Designer at design time. Therefore, you will change them to something more meaningful.

To specify the display name and description

In Solution Explorer, choose the TestThemeExtension.Common project.
Expand the Metadata and Themes nodes, open the shortcut menu for the TestTheme.lsml file and choose Open With.
In the Open With dialog box, choose XML (Text) Editor, and then choose the OK button.
In the Theme element, replace the DisplayName value with Test Theme, and replace the Description value with This is my first try at creating a theme. As follows.
```
<Theme Name="TestTheme">
    <Theme.Attributes>
      <DisplayName Value="Test Theme"/> 
      <Description Value="This is my first try at creating a theme."/>
    </Theme.Attributes>
  </Theme>
```
These are the values that developers will see when they select your theme on the General Properties tab of the application designer.

At this point you have created a theme, and you can test it in a LightSwitch application.

Define the Theme

The LightSwitch Theme project template added a TestTheme.xaml file to the TestThemeExtension.Client project. This file contains the resource directory for the LightSwitch shell; the default values and styles define the appearance of the LightSwitch Blue Theme (Default) theme that is the default for LightSwitch applications. You define your own theme by modifying some or all of the values in this file. For more information on the available styles, see Control Elements for LightSwitch Themes.

To define the theme

In Solution Explorer, choose the TestThemeExtension.Client project.
Expand the Presentation and Themes nodes, and open the TestTheme.xaml file.
On the menu bar, choose Edit, Find and Replace, Quick Replace.
In the Find and Replace dialog box, enter Segoe UI, Arial in the Find what field, and enter Segoe Script in the Replace with field.
Choose Current Document in the Look in list, and then choose Replace All.

Eleven occurrences will be replaced, defining Segoe Script for all of the font values.
In the TestTheme.xaml file, locate the TextBoxBackgroundBrush element, and replace <SolidColorBrush x:Key="TextBoxBackgroundBrush" Color="White"/> with <SolidColorBrush x:Key="TextBoxBackgroundBrush" Color="Yellow"/>.
Locate the ToolbarBackgroundBrush element and replace <SolidColorBrush x:Key="ToolbarBackgroundBrush" Color="#FFE9EDF1"/ with <SolidColorBrush x:Key="ToolbarBackgroundBrush" Color="Red"/.

Note that the color values can be entered as either a System.Drawing.Color value or a hexadecimal color value.

Tip

You can also open the .xaml file in Microsoft Expression Blend 4 and change the colors in a visual designer.

At this point you have created a rudimentary theme, and you can test it in a LightSwitch application.

Test the Theme Extension

You can test the theme extension in an experimental instance of Visual Studio. If you have not already tested another LightSwitch extensibility project, you have to enable the experimental instance first.

To enable an experimental instance

In Solution Explorer, choose the BusinessTypeExtension.Vsix project.
On the menu bar, choose Project, BusinessTypeExtension.Vsix Properties.
On the Debug tab, under Start Action, choose Start external program.
Enter the path of the Visual Studio executable, devenv.exe.

By default on a 32-bit system, the path is C:\Program Files\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe; on a 64-bit system, it is C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe.
In the Command line arguments field, enter /rootsuffix Exp.

Note

All subsequent LightSwitch extensibility projects will also use this setting, by default.

To test the theme

On the menu bar, choose Debug, Start Debugging. An experimental instance of Visual Studio opens.
In the experimental instance, on the menu bar, choose File, New, Project.
In the Open Project dialog box, select any existing LightSwitch application project and open it.
On the menu bar, choose Project, ProjectName Properties.
In the project designer, on the Extensions tab, select the TestThemeExtension check box.
Choose the General Properties tab, and in the Theme list, choose Test Theme.
On the menu bar, choose Debug, Start Debugging. Observe the changes in appearance in the running application.

Next Steps

This completes the theme extension walkthrough; you should now have a fully functioning theme extension that you can reuse in any LightSwitch project. Of course, you might want to modify the styles to make the theme a bit more pleasing to the eye; the walkthrough is only intended to show you the necessary techniques.

If you are going to distribute your extension, there are a couple more steps that you must take. To make sure that the information displayed for your extension in the project designer and in Extension Manager are correct, update the properties for the VSIX package. For more information, see How to: Set VSIX Package Properties. In addition, there are several things to consider if you are going to distribute your extension publicly. For more information, see How to: Distribute a LightSwitch Extension.