Walkthrough: Creating a Detail Control Extension

In Solution Explorer, in the Controls folder of the DetailControlExtension.Client project, open the DetailControl.xaml.vb or DetailControl.xaml.cs file.

Add the following Imports statements to the DetailControl.xaml.vb file, or using statements to the DetailControl.xaml.cs file.

Add a EntityProperty property inside the DetailControl class, as follows.

In Solution Explorer, in the Controls folder of the DetailControlExtension.Client project, open the DetailControl.xaml file.

Replace the existing XAML code with the following code.

<UserControl x:Class="DetailControlExtension.Presentation.Controls.DetailControl"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Name="DetailRoot"
             HorizontalAlignment="Stretch"
             >
    <!-- 
        The DataContext of the control is a ContentItem.  However, you defined several DependencyProperties inside your control to expose necessary data to be shown on the UI.
        Here, set the DataContext of the internal implementation to your control itself, so you can use short DataBindings inside.
    -->
    <Grid DataContext="{Binding ElementName=DetailRoot}" HorizontalAlignment="Stretch">
        <!-- 
        That is the TextBox you show the property value.  The EntityProperty is a dependency property that will bind to the property to be shown on the UI.
        Bind its Value and IsReadOnly properties to the text box.
        -->
        <TextBox Name="DetailTextBox"
                 HorizontalAlignment="Stretch"
                 VerticalAlignment="Stretch"
                 Text="{Binding EntityProperty.Value, Mode=TwoWay}" 
                 IsReadOnly="{Binding EntityProperty.IsReadOnly}" />
    </Grid>
</UserControl>

In Solution Explorer, in the Controls folder of the DetailControlExtension.Client project, open the DetailControl.xaml.vb or DetailControl.xaml.cs file.

Add the following code for the dependency properties after the EntityProperty code block:

You also have to set the binding for DisplayPropertyName and ContentItem when the ControlName is created.

Add the following code inside the DetailControl constructor after the InitializeComponent call.

You also have to add a SetContentDataBinding function to the class.

Add the following code to the DetailControl class after the OnContentItemChanged block.

The implementation of the detail control is now complete, and you can test it in LightSwitch.

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.

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 New Project dialog box, expand the Visual Basic or Visual C# node, choose the LightSwitch node, and then choose the LightSwitch Desktop Application template.

In the Name field, enter DetailControlTest, and then choose the OK button to create a test project.

On the menu bar, choose Project, DetailControlTest Properties.

In the Project Designer, on the Extensions tab, select the DetailControlExtension check box.

Create a basic LightSwitch application that has a table that contains several String fields, or connect to an external data source.

Add a List and Details screen, and then in the screen designer, change the Summary control below the first Rows Layout element to My Detail Control.

In the Properties window, select the Display Property property, and then enter the name of a field in the table.

On the menu bar, choose Debug, Start Debugging. Observe the behavior of the My Detail Control control in the application and verify that the data for the field is properly displayed.

In Solution Explorer, open the shortcut menu for the DetailControl.Design project, and then choose Add Reference.

In the Add Reference dialog box, add a reference to Microsoft.LightSwitch.Design.Designer.dll.

You can find the assembly in the PrivateAssembly folder under the Visual Studio IDE folder.

Open the shortcut menu for the DetailControl.Design node, and then choose Add Existing Item.

Choose the Common project in your solution, and then select the ModelUtilities file.

Expand the drop-down list on the Add button, and then choose Add As Link.

In Solution Explorer, open the shortcut menu for the DetailControl.Design project, and then choose Add New Folder. Name the new folder Editors.

In the Editors folder, open the shortcut menu and choose Add New Item.

In the Add New Item dialog box, expand the WPF node, and choose User Control (WPF).

In the Name field, enter EntityPropertyPicker, and then click Add.

A EntityPropertyPicker.xaml file and a EntityPropertyPicker.xaml.vb or EntityPropertyPicker.xaml.cs file will be added to the Editors folder.

In the Editors folder, open the shortcut menu and choose Add New Item.

In the Add New Item dialog box, expand the Code node and choose Class.

In the Name field, enter EntityPropertyPickerEditor and then click Add.

Open the EntityPropertyPickerEditor class file and replace the contents with the following code:

This code implements a component that can be loaded by a LightSwitch designer based on its name inside a PropertyValueEditorName attribute. When a LightSwitch designer displays a property marked to use an editor with the same name, it will create a WPF control with the DataTemplate and host it in the property sheet. The DataContext of the control will be set to an IBindablePropertyEntry object, where the control can get or set the value of the property.

The next step is to change the control property metadata in the .lsml file for the extension.

In the Common project, open the DetailControl.lsml file.

Add the UIEditorID property to the ControlProperty element, as follows.

<ControlProperty Name="DisplayProperty"
                       PropertyType=":String"
                       CategoryName="Appearance"
                       UIEditorId="DetailControlExtension:EntityPropertyPicker"
                       EditorVisibility="PropertySheet">

In the Design project, open the EntityPropertyPicker.xaml file, and replace the default code with the following code to implement the control.

<UserControl x:Class="DetailControlExtension.Editors.EntityPropertyPicker"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
             xmlns:d="http://schemas.microsoft.com/expression/blend/2008" 
             mc:Ignorable="d" 
             >
    <!-- 
    DesignTimeFontSize and DesignTimeFontFamily are design-time public resource items.  
    Use them to ensure that you use the same font inside different controls on the property sheet.
    -->
    <Grid TextBlock.FontSize="{DynamicResource DesignTimeFontSize}"
          TextBlock.FontFamily="{DynamicResource DesignTimeFontFamily}"
>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="Auto" />
        </Grid.RowDefinitions>

        <!-- 
            That is the label to show the property name.  
            The DataContext of this control is an IBindablePropertyEntry object. Use its Entry property to get the IPropertyEntry.
        -->
        <TextBlock x:Name="ComboBoxLabel"
                   Text="{Binding Entry.DisplayName, Mode=OneWay}"
                   TextWrapping="WrapWithOverflow"
                   ToolTip="{Binding Entry.Description, Mode=OneWay}"
                   Margin="0,0,0,2"/>

        <!-- 
            This is the ComboBox to pick up the value.  The DataContext of this control is an IBindablePropertyEntry object. Use its Entry property to get the IPropertyEntry.
            Use the 'GetTextPropertiesConverter' to collect all valid choices.  The PropertyValue.Value is the value of the DisplayProperty of the control.
        -->
        <ComboBox x:Name="ComboBox" 
                  Grid.Row ="1"
                  SelectedItem="{Binding Entry.PropertyValue.Value}"
                  >
        </ComboBox>
    </Grid>
              
</UserControl>

The XAML code adds a Label to show the property name, and a ComboBox to show the current value. Next, you will add some code to get the list for the ComboBox. To do so, you must know the exact entity type that is bound to the control.

In the screen designer, the context of the property is exposed by IPropertyValue.ModelItem. For a control property, ModelItem is always the instance of IContentItemDefinition where the control is being used. There, a single property, IContentItemDefinition.DataType, defines which entity type is bound to the control. For the ComboBox, a list of the names of all properties in that entity type is needed. This list can be generated by creating a converter.

Close and save the EntityPropertyPicker.xaml file.

Expand the EntityPropertyPicker.xaml node, open the EntityPropertyPicker.xaml.vb or EntityPropertyPicker.xaml.cs file, and replace the contents with the following.

Close and save the EntityPropertyPicker.xaml.vb or EntityPropertyPicker.xaml.cs file.

In the Common project, open the ModelUtilities class file.

Add a new method to the class.

This method retrieves a collection of properties that can be represented as a string inside a data type, including an entity type.

In the Editors folder of the Design project, open the shortcut menu and choose Add New Item.

In the Add New Item dialog box, expand the Code node, and choose Class.

In the Name field, enter GetTextPropertiesConverter, and then click Add.

Open the GetTextPropertiesConverter class file and add the following code.

This converter takes the IContentItemDefinition, which can be accessed from IPropertyValue, and returns a collection of valid property names plus an empty string, which represents the default value of the property, meaning nothing has been chosen.

In the Editors folder, open the EntityPropertyPicker.xaml file.

Add the following namespace mapping to the control.

xmlns:e="clr-namespace:DetailControlExtension.Editors"

Add a resource to create the new converter.

<UserControl.Resources>
        <e:GetTextPropertiesConverter x:Key="GetTextPropertiesConverter" />
    </UserControl.Resources>

Note
At this point you might notice an error in the designer. This error will be resolved when you build the Client project.

Update the ComboBox element with the new Converter by setting the ItemsSource property:

<ComboBox x:Name="ComboBox" 
                  Grid.Row ="1"
                  SelectedItem="{Binding Entry.PropertyValue.Value}"
                  ItemsSource="{Binding Entry.PropertyValue.ModelItem, Mode=OneWay, Converter={StaticResource GetTextPropertiesConverter}}"
                  >
        </ComboBox>

In the Editors folder of the Design project, open the shortcut menu and choose Add New Item.

In the Add New Item dialog box, expand the Code node, and choose Class.

In the Name field, enter DisplayNameConverter, and then click Add.

Open the DisplayNameConverter class file and add the following code.

This code formats the String with the “:” notation, which is a shortcut for "Microsoft.LightSwitch:".

In the Editors folder, open the EntityPropertyPicker.xaml file.

Add a resource to create the new converter.

<UserControl.Resources>
        <e:GetTextPropertiesConverter x:Key="GetTextPropertiesConverter" />
        <e:DisplayNameConverter x:Key="DisplayNameConverter" />
    </UserControl.Resources>

On the menu bar, choose Build, DetailControlExtension.Design.

Add a converter block to the TextBlock element.

<TextBlock x:Name="ComboBoxLabel"
                   Text="{Binding Entry.DisplayName, Mode=OneWay, Converter={StaticResource DisplayNameConverter}}"
                   TextWrapping="WrapWithOverflow"
                   ToolTip="{Binding Entry.Description, Mode=OneWay}"
                   Margin="0,0,0,2"/>

In the Resources folder of the Design project, open the shortcut menu and choose Add New Item.

In the Add New Item dialog box, expand the General node, and choose Resources file.

In the Name field, enter DesignResources, and then click Add.

In the DesignResources.resx file, add a string named “DefaultProperty_DisplayName”, and assign it a value of <Summary>.

This resource string will be used by the converter when no value has been specified by the application developer.

In the Editors folder of the Design project, open the shortcut menu and choose Add New Item.

In the Add New Item dialog box, expand the Code node and choose Class.

In the Name field, enter PropertyNameToDisplayNameConverter, and then click Add.

In the PropertyNameToDisplayNameConverter class file, add the following code.

This code checks to see whether the value of the ComboBox is a null String, and if it is, it replaces it with the DefaultProperty_DisplayName resource string.

In the Editors folder, open the EntityPropertyPicker.xaml file.

Add a resource to create the new converter, as follows.

<UserControl.Resources>
        <e:GetTextPropertiesConverter x:Key="GetTextPropertiesConverter" />
        <e:DisplayNameConverter x:Key="DisplayNameConverter" />
        <e:PropertyNameToDisplayNameConverter x:Key="PropertyNameToDisplayNameConverter" />    
</UserControl.Resources>

Add an ItemTemplate block inside the ComboBox element, as follows.

<ComboBox.ItemTemplate>
                <DataTemplate>
                    <!-- The 'PropertyNameToDisplayNameConverter' is used to convert the empty string to a developer friendly string. -->
                    <TextBlock Text="{Binding Converter={StaticResource PropertyNameToDisplayNameConverter}}" />
                </DataTemplate>
            </ComboBox.ItemTemplate>

In the Resources folder of the DetailControlExtension.Client.Design project, open the shortcut menu and choose Add New Item.

In the Add New Item dialog box, expand the General node, and choose Resources file.

In the Name field, enter DesignResources, and then click Add.

In the DesignResources.resx file, add a string named “DefaultProperty_DisplayName”, and assign it a value of <Summary>.

This resource string will be used by the converter when no value has been specified by the application developer.

In Solution Explorer, open the shortcut menu for the DetailControl.Client.Design project, and then choose Add New Folder. Name the new folder Editors.

Open the shortcut menu for the DetailControl.Client.Design node, and then choose Add Existing Item.

Choose the Common project in your solution, and then choose the ModelUtilities file.

Expand the drop-down list on the Add button, and then choose Add As Link

Select the Editors node, open the shortcut menu, and then choose Add Existing Item.

In the Add Existing Item dialog box, locate the Editors folder in the DetailControl.Client.Design project and then choose the DisplayNameConverter, GetTextPropertiesConverter, and PropertyNameToDisplayNameConverter files.

Expand the drop-down list on the Add button, and then choose Add As Link.

In Solution Explorer, open the shortcut menu for the Editors node in the DetailControl.Client.Design project, and then choose Add New Item.

In the Add New Item dialog box, expand the Silverlight node, and choose Silverlight User Control.

In the Name field, enter ClientEntityPropertyPicker, and then click Add.

An EntityPropertyPicker.xaml file and an EntityPropertyPicker.xaml.vb or EntityPropertyPicker.xaml.cs file will be added to the Editors folder.

Replace the existing XAML with the following implementation for the control.

<UserControl x:Class="DetailControlExtension.Editors.ClientEntityPropertyPicker"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:e="clr-namespace:DetailControlExtension.Editors;assembly=DetailControlExtension.Client.Design"
    mc:Ignorable="d"
    >
    <UserControl.Resources>
        <e:PropertyNameToDisplayNameConverter x:Key="PropertyNameToDisplayNameConverter" />
        <e:DisplayNameConverter x:Key="DisplayNameConverter" />
        <e:GetTextPropertiesConverter x:Key="GetTextPropertiesConverter" />
    </UserControl.Resources>

    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="Auto" />
        </Grid.RowDefinitions>

        <!-- That is the label to show the property name.  Use a converter to show a ':' behind the name. -->
        <TextBlock x:Name="EditorLabel" 
                   Text="{Binding Path=DisplayName, Converter={StaticResource DisplayNameConverter}}"/>

        <!-- 
            This is the ComboBox to pick up the value.  The DataContext of this control is an IPropertyEntry object.
            Use the 'GetTextPropertiesConverter' to collect all valid choices.  The PropertyValue.Value is the value of the DisplayProperty of the control.
            In SilverLight, ItemsSource needs to be set before SelectedItem to ensure that the control will work correctly.
        -->
        <ComboBox Margin="0,1,0,0" Grid.Row="1"
                  ItemsSource="{Binding Path=PropertyValue.ModelItem, Converter={StaticResource GetTextPropertiesConverter}}"
                  SelectedItem="{Binding Path=PropertyValue.Value, Mode=TwoWay}"
                  AutomationProperties.LabeledBy="{Binding ElementName=EditorLabel}"
                  HorizontalAlignment="Stretch"
                  >
            <ComboBox.ItemTemplate>
                <DataTemplate>
                    <!-- The 'PropertyNameToDisplayNameConverter' is used to convert the empty string to a developer friendly string. -->
                    <TextBlock Text="{Binding Converter={StaticResource PropertyNameToDisplayNameConverter}}" />
                </DataTemplate>
            </ComboBox.ItemTemplate>
        </ComboBox>

    </Grid>

</UserControl>

Close and save the ClientEntityPropertyPicker.xaml file.

In the Editors folder, open the shortcut menu and choose Add New Item.

In the Add New Item dialog box, expand the Code node, and choose Class.

In the Name field, enter ClientEntityPropertyPickerEditor and then click Add.

Add the following code to the class.

Again, this code resembles the code you added in the WPF project.

Expand the ClientEntityPropertyPicker.xaml node, open the ClientEntityPropertyPicker.xaml.vb or ClientEntityPropertyPicker.xaml.cs file, and replace the contents with the following.

Close and save the ClientEntityPropertyPicker.xaml.vb or ClientEntityPropertyPicker.xaml.cs file.