Creating A LightSwitch HTML Screen Extension

Nov 20

Written by: Michael Washington
11/20/2013 4:44 AM

Extending LightSwitch HTML Client

The LightSwitch Extensibility Toolkit for Visual Studio 2013 allows you to create reusable HTML client screen templates. This is a very powerful feature in that you have full control of the generated HTML and JavaScript. In your screen template code you have the ability to interrogate the (optional) entity or collection specified by the end user, and create a screen design based on what they select.

Creating the Extensibility Project

The following is required in order to create LightSwitch extensions:

Visual Studio 2013 Professional (or higher)
Visual Studio 2013 SDK
LightSwitch Extensibility Toolkit for Visual Studio 2013

Create a new project in Visual Studio.

Use the Extensibility template (if you don’t see it you must have Visual Studio 2013 SDK, and LightSwitch Extensibility Toolkit for Visual Studio 2013 installed).

Right-click on the .Lspkg project and select Add then New Item.

Create a screen template.

Note, see the article, Creating a LightSwitch Screen Template, for information on what is being created in the project and how to customize it.

Add the following using statement to the file at HelloWorldExtension.Design\ScreenTemplates\HelloWorldScreenTemplate.cs:

using Microsoft.LightSwitch.DesignTime;

Update the class decorators to:

[Export(typeof(IScreenTemplateFactory))]
[Template(HelloWorldScreenTemplate.TemplateId, ScreenEditMode.Browse)]
[TargetPlatform(TargetPlatformNames.MobileWeb)]

Update the #region IScreenTemplate Members section to:

        public void Generate(IScreenTemplateHost host)
        {
            ContentItem tabContentItem;
            tabContentItem = host.AddContentItem(host.ScreenTabPagesContentItem, "Group",
                ContentItemKind.Group);
            // Set screen to use view controls by default
            host.SetControlPropertyValue(
                host.ScreenTabPagesContentItem, "Microsoft.LightSwitch.MobileWeb:RootControl", "BrowseOnly", "True");
            // Add CustomControl to screen
            string MyCustomControlName = "MyCustomControl";
            host.AddContentItem(tabContentItem, MyCustomControlName, ContentItemKind.ScreenContent);
            // Create JavaScript code for Utility function
            string UtilityTemplate = "";
            UtilityTemplate = UtilityTemplate + "{0}myapp.{2}" + ".{3}_render = function (element, contentItem) {{";
            UtilityTemplate = UtilityTemplate + "{0}element.innerHTML = '<h1>Hello World!</h1>';";
            UtilityTemplate = UtilityTemplate + "{0}}};";
            // Call AddScreenCodeBehind for UtilityTemplate
            host.AddScreenCodeBehind(String.Format(UtilityTemplate,
                                                       Environment.NewLine,
                                                       host.ScreenNamespace,
                                                       host.ScreenName,
                                                       MyCustomControlName));
        }

Click on the .Vsix project and then run the project.

A testing instance of Visual Studio will open.

Create or open a LightSwitch HTML Client project.

If you have not already enabled the extension for the project, go into Properties…

Select Extensions and check the box next to the extension to enable it.

Right-click on the Screens folder and select Add Screen.

Select the Hello World Screen Template.

The screen will be created.

Run the project…

The content will show.

In the Extensibility project, select Stop Debugging to close the testing version of Visual Studio and to stop debugging.

Handling Data

To allow the user to select one of their collections to display using the screen template, we replace the following line:

tabContentItem = host.AddContentItem(host.ScreenTabPagesContentItem, "Group", ContentItemKind.Group);

With:

            if (null != host.PrimaryDataSourceProperty)
            {
                // Get the data type of our property
                ScreenCollectionProperty collectionProperty = 
                    (ScreenCollectionProperty)(host.PrimaryDataSourceProperty);
                IDataType primaryDataType = 
                    host.FindGlobalModelItem<ISequenceType>(collectionProperty.PropertyType).ElementType as IDataType;
                string tabName = primaryDataType.Name + "TileList";
                // Add a screen tab content item
                tabContentItem = 
                    host.AddContentItem(host.ScreenTabPagesContentItem, tabName, ContentItemKind.Group);
                // Add the query parameters to the tab content item
                if (null != host.PrimaryDataSourceParameterProperties)
                {
                    foreach (ScreenPropertyBase parameter in host.PrimaryDataSourceParameterProperties)
                    {
                        ContentItem contentItem = 
                            host.AddContentItem(tabContentItem, parameter.Name, parameter);
                    }
                }
                // Add a ValueCustomControl control to the tab content item
                ContentItem listContentItem = 
                    host.AddContentItem(tabContentItem, primaryDataType.Name, host.PrimaryDataSourceProperty);
                listContentItem.View = "Microsoft.LightSwitch.MobileWeb:TileList";
                // Populate the child content items
                host.ExpandContentItem(listContentItem, disableNavigationPropertyGeneration: false, 
                    disableGeneratedPropertyGeneration: false);
            }
            else
            {
                // No data source was specified; just add a screen tab content item
                tabContentItem = host.AddContentItem(host.ScreenTabPagesContentItem, "Group", 
                    ContentItemKind.Group);
            }