Walkthrough: Creating a Smart Layout Control Extension

  • Article

This walkthrough demonstrates how to create a smart layout control extension for LightSwitch. By using a smart layout control, a LightSwitch user can quickly arrange data on a screen in a predetermined manner. Some smart layout controls are included in the LightSwitch screen designer, for example, the Picture and Text and Text and Picture group controls.

Prerequisites

  • Visual Studio 2013 Professional

  • Visual Studio 2013 SDK

  • LightSwitch Extensibility Toolkit for Visual Studio 2013

Create a Control Extension Project

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

To create an extension project

  1. On the menu bar in Visual Studio, choose File, New, Project.

  2. 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.

  3. In the Name field, enter MySmartLayoutExtension as the name for your extension library. This name will appear on the Extensions tab of the LightSwitch Application Designer.

  4. Choose the OK button to create a solution that contains the seven projects that are required for the extension.

To choose an extension type

  1. In Solution Explorer, select the MySmartLayoutExtension.Lspkg project.

  2. On the menu bar, choose Project, Add New Item.

  3. In the Add New Item dialog box, choose LightSwitch Control.

  4. In the Name field, enter MySmartLayout as the name for your extension. This name will appear in the LightSwitch screen designer.

  5. Choose the OK button. Files will be added to several projects in your solution.

Update the Control Icon

Two image files named MySmartLayout.png were added to your solution, one in the ControlImages folder of the MySmartLayoutExtension.Client.Design project and the other in the ControlImages folder of the MySmartLayoutExtension.Design project. The image in the file is used as an icon. You can replace the default image with one that uniquely identifies your control.

To modify the icon image

  1. In Solution Explorer, open the shortcut menu for the MySmartLayout.png file in the ControlImages folder of the MySmartLayoutExtension.Client.Design project and choose Open With.

  2. In the Open With dialog box, select Paint and then choose the OK button.

  3. In Paint, change the image, for example, change the color or add a shape, and then save the file and return to Visual Studio.

  4. Choose the MySmartLayout.png file, and then on the menu bar, choose Edit, Copy.

  5. Choose the ControlImages folder of the MySmartLayoutExtension.Design project, and then on the menu bar, choose Edit, Paste. In the message that asks whether you want to replace the file, choose the Yes button.

Update the Control Definition in the LightSwitch Metadata File

Metadata that defines the control is contained in the .lsml file in the MySmartLayoutExtension.Common project. For your smart layout control, you can replace some of the default values with values that are appropriate for your control, for example, the control type and the display name. You can also add placeholders for child items and define the behavior of the AttachedLabelPosition settings.

To update the control metadata

  1. In Solution Explorer, open the shortcut menu for the MySmartLayout.lsml file in the Controls folder of the MySmartLayoutExtension.Common project and choose Open With.

  2. In the Open With dialog box, choose XML (Text) Editor, and then choose the OK button.

  3. Change the SupportedContentItemKind element to SupportedContentItemKind="Group".

    This tells LightSwitch that it is a group control.

  4. Change the DisplayName element to <DisplayName Value="My Smart Layout" />.

  5. Insert the following code after the Control.Attributes block.

    <Control.PropertySources>
      <!-- Override the AttachedLabelPosition - this is the label that is shown for 
            the smart layout itself.  It should to default to ‘None’. -->
      <ControlPropertySource Property=":RootControl/Properties[AttachedLabelPosition]">
        <ControlPropertySource.Source>
          <ScreenExpressionTree>
            <ConstantExpression ResultType=":String" Value="None" />
          </ScreenExpressionTree>
        </ControlPropertySource.Source>
      </ControlPropertySource>
    </Control.PropertySources>

    This tells LightSwitch that no label should be displayed for the parent control.

  6. Insert the following code after the Control.PropertySources block.

    <Control.ChildItemPropertySources>
      <!-- Sets AttachedLabelPosition to LeftAligned for all of the children. -->
      <ControlPropertySource Property=":RootControl/Properties[AttachedLabelPosition]">
        <ControlPropertySource.Source>
          <ScreenExpressionTree>
            <ConstantExpression ResultType=":String" Value="LeftAligned" />
          </ScreenExpressionTree>
        </ControlPropertySource.Source>
      </ControlPropertySource>
    </Control.ChildItemPropertySources>

    This tells LightSwitch that the child controls should display left-aligned labels.

  7. Insert the following code after the Control.ChildItemPropertySources block.

    <!-- Defines a placeholder for every child item in the smart layout. -->
    <Control.Placeholders>
      <Placeholder DisplayName="$(LeftItem_Template_DisplayName)" Name="LeftItemTemplate" />
      <Placeholder DisplayName="$(RightTopItem_Template_DisplayName)" Name="RightTopItemTemplate" />
      <Placeholder DisplayName="$(RightBottomItem_Template_DisplayName)" Name="RightBottomItemTemplate"/>
    </Control.Placeholders>

    This tells LightSwitch to create a template for every child controls so that a developer can specify the entity fields to display in the control. (In this case, there are three child controls.)

  8. Delete the Control.SupportedDataTypes block. Because a group control cannot directly display data, this block is unnecessary.

  9. The complete code for the MySmartLayout.lsml file should now resemble the following example.

    <?xml version="1.0" encoding="utf-8" ?>
<ModelFragment
  xmlns="https://schemas.microsoft.com/LightSwitch/2010/xaml/model"
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml">

  <Control Name="MySmartLayout"
    SupportedContentItemKind="Group"
    DesignerImageResource="MySmartLayoutExtension.MySmartLayout::ControlImage">
    <Control.Attributes>
      <DisplayName Value="Smart Layout" />
    </Control.Attributes>

    <Control.PropertySources>
      <!-- Override AttachedLabelPosition to None - this is the label that is shown for 
            the smart layout itself.  We want it to default to ‘None’. -->
      <ControlPropertySource Property=":RootControl/Properties[AttachedLabelPosition]">
        <ControlPropertySource.Source>
          <ScreenExpressionTree>
            <ConstantExpression ResultType=":String" Value="None" />
          </ScreenExpressionTree>
        </ControlPropertySource.Source>
      </ControlPropertySource>
    </Control.PropertySources>

    <Control.ChildItemPropertySources>
      <!-- Sets AttachedLabelPosition to LeftAligned for all of the children. -->
      <ControlPropertySource Property=":RootControl/Properties[AttachedLabelPosition]">
        <ControlPropertySource.Source>
          <ScreenExpressionTree>
            <ConstantExpression ResultType=":String" Value="LeftAligned" />
          </ScreenExpressionTree>
        </ControlPropertySource.Source>
      </ControlPropertySource>
    </Control.ChildItemPropertySources>

    <!-- Defines a placeholder for every child item in the smart layout. -->
    <Control.Placeholders>
      <Placeholder DisplayName="$(LeftItem_Template_DisplayName)" Name="LeftItemTemplate" />
      <Placeholder DisplayName="$(RightTopItem_Template_DisplayName)" Name="RightTopItemTemplate" />
      <Placeholder DisplayName="$(RightBottomItem_Template_DisplayName)" Name="RightBottomItemTemplate"/>
    </Control.Placeholders>

  </Control>

</ModelFragment>

Add Resource Strings

The ModuleResources.resx file in the MySmartLayoutExtension.Common project contains resources that are used by the control. You can add string resources for the text that will be displayed for your control in the screen designer.

To add resource strings

  1. In Solution Explorer, expand the Resources node in the MySmartLayoutExtension.Common, and then open the ModuleResources.resx file.

  2. Add the following values to the ModuleResources.resx file.

    Name

    Value

    Comment

    LeftItem_Template_DisplayName

    Left

    Item name that is used inside a designer.

    RightBottomItem_Template_DisplayName

    Right Bottom

    Item name that is used inside a designer.

    RightTopItem_Template_DisplayName

    Right Top

    Item name that is used inside a designer.

    SmartLayout_DisplayName

    Smart Layout Panel

    Display name that is used inside a designer.

Update the Control Xaml File

The MySmartLayout.xaml file in the MySmartLayoutExtension.Client project contains the markup language that defines the Silverlight control. The default control is a TextBox; change it to a container that can display child controls.

To update the xaml

  1. In Solution Explorer, open the MySmartLayout.xaml file in the MySmartLayoutExtension.Client project.

  2. Replace the contents of the file with the following xaml code.

    <UserControl x:Class="MySmartLayoutExtension.Presentation.Controls.MySmartLayout"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:framework="clr-namespace:Microsoft.LightSwitch.Presentation.Framework;assembly=Microsoft.LightSwitch.Client">

    <Grid>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="*" />
            <ColumnDefinition Width="*" />
        </Grid.ColumnDefinitions>

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

        <!-- 
            Use ContentItemPresenter to map a child ContentItem to the SilverLight Control. In the smart layout, child items must follow the order in which the placeholders are defined in the .lsml file. 
            If a placeholder item is not filled, the related ContentItem will be null. ContentItemPresenter handles this correctly.
        -->
        <framework:ContentItemPresenter ContentItem="{Binding ChildItems[0]}" Grid.Column="0" Grid.Row="0" Grid.RowSpan="3" Margin="3" />
        <framework:ContentItemPresenter ContentItem="{Binding ChildItems[1]}" Grid.Column="1" Grid.Row="0" Margin="3" />
        <framework:ContentItemPresenter ContentItem="{Binding ChildItems[2]}" Grid.Column="1" Grid.Row="1" Margin="3" />
    </Grid>
</UserControl>

    The DataContext of a LightSwitch control is always an IContentItem object. The ChildItems property of IContentItem is used to access child content items that are defined in the screen designer. The index of the child matches the index of the placeholder that is defined in the control metadata. When ContentItemPresenter is used, the child items are mapped to the appropriate SilverLight controls.

Test the Smart Layout Control

The smart layout control is now complete. You can test it 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

  1. In Solution Explorer, choose the BusinessTypeExtension.Vsix project.

  2. On the menu bar, choose Project, BusinessTypeExtension.Vsix Properties.

  3. On the Debug tab, under Start Action, choose Start external program.

  4. 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.

  5. 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 smart layout control

  1. On the menu bar, choose Debug, Start Debugging. An experimental instance of Visual Studio opens.

  2. In the experimental instance, on the menu bar, choose File, New, Project.

  3. 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.

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

  5. On the menu bar, choose Project, MySmartLayoutTest Properties.

  6. In the project designer, on the Extensions tab, select the MySmartLayoutExtension check box.

  7. In Solution Explorer, select Data Sources, and then on the menu bar, choose Project, Add Table. Name the new table Contact.

  8. Add the following fields and values to the table.

    Name

    Type

    Required

    ContactName

    String

    Required

    Phone

    PhoneNumber

    Required

    Photo

    Image

    Required

  9. In Solution Explorer, select Screens, and then on the menu bar, choose Project, Add Screen.

  10. In the Add New Screen dialog box, select List and Details Screen and, in the Screen Name field, enter Contacts. In the Screen Data list, select Contacts, and then choose the OK button.

  11. In the screen designer, in the Rows Layout | Contact Details node, change the control type to My Smart Layout.

  12. In the (Left) node, select Photo. In the (Right Top) node, select Contact Name. In the (Right Bottom) node, select Phone.

  13. On the menu bar, choose Debug, Start Debugging to run the application. Enter some data and observe how it is displayed in your My Smart Layout control.

See Also

Tasks

How to: Create a LightSwitch Control

Concepts

Defining, Overriding, and Using LightSwitch Control Properties

LightSwitch Extensibility Toolkit for Visual Studio 2013