First we’ll go over the basics.
Installing the Treeview Control
To install the control into your environment, unzip the file you downloaded and double-click the file named VBLSTreeviewControl.vsix.
This will install the control and allow LightSwitch to find it. You should have LightSwitch and Visual Studio closed when performing the above step. You must open a fresh instance of LightSwitch after you have installed the extension.
Enabling the Treeview Control in Your LightSwitch Project
After installing the control following the above procedure, open a new or existing LightSwitch project. For the purposes of this tutorial, we will create a new project named TestVBLSTreeviewControl.
Double-click on the Properties of the project. This will open the Properties designer of the project where you should select the Extensions tab on the left side of the window.
Depending on what other LightSwitch Controls you have installed, your list of extensions will vary. You should see the VBLSTreeviewControl in the list. Check the checkbox to the left of the control name. That’s all there is to it. You are ready to use the control.
Adding a Data Source
Now we need to add a hierarchical data source. Right-click on the Data Sources folder in the Solution Explorer window and select Add Table. Name the table Product Category and add two string fields named Name and Description to the table.
Next, in the strip above the table, select Add Relationship. In the dropdown under To, select Product Category for Name and Zero or One for Mulitplicity as in the screenshot below.
Next, we will name the two ends or Navigation Properties of the relationship. Rename the singular navigation property (ProductCategory1) to Parent. Rename the plural navigation property (ProductCategories) to Children. The Add New Relationship dialog should look like the following:
And the table definition will look like the following:
Adding a Screen
Now that we have a hierarchical data source, we can add a screen to our project. Right-click on the Screens folder in Solution Explorer and select Add Screen. In the Add New Screen Dialog, select a List and Details Screen for the Screen Template and ProductCategories for the Screen Data.
Press OK to generate the screen.
Adding the Treeview Control to the Screen
When the screen designer first opens after creating the screen, it should look like this:
Notice that the default List control is being used to display the collection of Product Categories. Click on the dropdown arrow to the right of the List and select the Treeview.
If the Properties window is not visible, press F4 or Select View….Properties Window from the main menu. The properties of the Treeview should be displayed in the window. Notice the default values for some of the properties are set. Parent Property Path to Parent, Children Property Path to Children and Display Member Name to Name. When dealing with existing data that you did not define, you may need to change these properties to the names of the correct fields in the data you are using. Since we defined our own data table and named the fields correctly, the default field names will work for us.
You may want to scroll down and review the rest of the Properties.
Running the Test Application
Now you can run the project and see the Treeview in action. The application will look like the following.
Notice the command buttons underneath the control. These are generated by LightSwitch and can be removed since we have the built-in command buttons in the control. Select the Design Screen button in the upper right corner of the Application Ribbon and you will go into Design Mode as follows:
Open the Command Bar element under the Treeview Control to expose the Command Buttons.
Press the Delete Key for each of the three buttons and then press Save in the upper right corner of the Design Panel. Now your application should look like:
Notice the buttons above the control. The first button (a green plus sign) is used to add an item to the Treeview at the same level as the selected item, or if no item is selected, to the root of the tree.
The second button (a hierarchy with a plus sign) is used to add a child element to the selected element. Note that it is grayed out because no item is currently selected.
The third button (a pencil) is used to place the selected item into edit mode. It too is grayed out.
The fourth and final button is an “X” that is used to delete the currently selected item. It is grayed out as well.
Try pressing the Add Item button on the left. A new item is added to the root of the tree.
Also, notice that the three buttons that were disabled before are now enabled since the new item is automatically selected.
Try editing the name of the New Item. This can be done by changing the name in the details panel to the right of the control, or by double clicking the item in the Treeview and editing it in-place. When done editing, press the Return or Enter key and the name will be updated.
To save changes, press the Save button in the upper left of the Application Ribbon.
Now try adding a child element. Press the second button from the left in the control’s command bar that looks like a hierarchy. A new element will be added below the selected one. The new element will be selected and the screen should look something like the following:
You should be able to add, edit and delete elements in the tree as you wish. Go ahead and experiment a little on your own. For the sample, I’ve begun a Bicycle Product Hierarchy as below:
Update: Turn Data Paging Off
If you expect to have more items in the tree than the paging size, you need to turn data paging off. To do this, select the collection that is the item source for the tree (ProductCategories in our case) and in the properties window, uncheck the box named Supports Paging. Otherwise, the tree will only load the first page of data.
Deleting Child Elements
UPDATE: A new property has been added to allow automatic deletion of children. Delete Child Items
Checking “Delete Child Items” will automatically delete children of a deleted Parent item. If you do not want this behavior, just leave that option unchecked.
Using the Basic Treeview Properties
Up until this point, we have been able to do quite a bit using all default settings. Now we will see the effect of changing some of the basic settings in the Properties Window.
Tool Tip, New Item and Auto Edit Properties
Open the Screen Designer and select the Treeview control. In the Properties window, scroll down to ToolTip Member Path and select Description from the drop-down. Notice you can select any property from the element type in the collection (Product Category in our case).
Just below the ToolTip Member Path, change the New Item Name to New Category. This will give the user of your application a better idea of what they should be entering as values.
Finally, scroll down further and check the Auto Edit New Item checkbox. This will place a newly added item into edit mode and allow the user to type a new name immediately after adding a new item. Your designer screen should look something like the following:
Now run the application and notice how the control behavior has changed. Add a new item at the root level by pressing the Plus sign button. Notice that this adds a new item named New Category and places it in edit mode automatically.
You can type a new value without touching the mouse. This makes for more rapid and easy entry of new items. Try naming this category Bicycle Parts.
Now enter a brief description for Bicycle Parts in the details pane to the right of the control. Press enter after you do this or select the name field. This will update the description field in the database.
Next, hover over the new item and you will notice that the Description is displayed as a ToolTip.
Drag and Drop
Now let’s try out the Drag and Drop features of the control. Start by selecting any child element. In our case we selected Girl’s Mountain Bikes. Notice that the Parent field in the details pane of the application shows that Girl’s Mountain Bikes parent is Girl’s Bikes. Hold down the left mouse button and drag the item to any item other than its parent. In our case, we’ll drag it to Bicycle Parts.
Then release the left mouse button, dropping the item on the newly selected parent. The application will now look something like this:
Notice that Girl’s Mountain Bikes now shows up in the Treeview as a child of Bicycle Parts and Parent property in the Details Pane also shows Bicycle Parts. The Drag and Drop worked.
If you want an item to become a root element in the tree (no Parent) then simply drag it to a blank area in the Treeview. It will then show up at the root level and its Parent property will be set to Nothing.
Try saving the data and then select Refresh. This will save the changes to the database and then Refresh the Screen data. Notice that our changes were saved and the relationships display correctly.
Close the application and we’ll try out some other settings for our Treeview.
Changing the Button Images
Scroll to the bottom of the Appearance Property Settings in the Properties window. You will see four “Choose Image…” links, one for each of the command buttons.
Try choosing a new image for the Delete button. An image import wizard will open and you can import any image you like. You should select a 16X16 pixel image of type png or bmp.
Press OK and you will notice that your new image name is listed next to the Delete Button Image: as Resources\delete.png or whatever your image name is.
Read Only List
At times, you may want a read-only hierarchical list that allows users to make selections, but not to alter the contents of the tree. To accomplish this, scroll to the bottom of the General settings in the Properties window and check the Read-Only List checkbox.
Run the application and you will notice that the command buttons have been removed.
You can still expand and collapse the hierarchy and select any of the items. However, you are unable to Add, Edit or Delete items inside the Treeview. The user can, however, edit the names in the Details pane to the right of the control because we did not make that text field read-only. If you want your users to not be able to alter an item, set the fields in the detail pane to Read-Only.
Changing the Border Color and Width
Two properties in the Appearance section allow you to select a color for the border and set the width. If you do not want the border to show, set the BorderWidth to 0. For a color, select any of the colors in the drop-down for Border Color. If you want the default color, leave that property set to <Enter Value>.
Using the Checkboxes
The check box feature of the Treeview is an advanced, and somewhat complicated, feature of the Treeview that allows you to display a checkbox next to one or more items in the Treeview. You can respond to the checked or unchecked events to perform custom actions, or set the Treeview up to add or delete a relationship.
Using Checkboxes to Add or Remove Relationships
First let’s take a look at the Many-to-Many relationships feature that allows your users to select an item from the Treeview and have it associated to another item. Enabling this capability requires the creation of a Many-to-Many Join table in your database and the setting of some additional properties on the Treeview Control.
Setting up the Data
For our example, let’s assume we want to have Products that can be part of one or more categories. Let’s add a Product table to our Data Sources:
Notice that we are not setting up a direct relationship to the ProductCategory table. LightSwitch cannot handle a direct Many-to-Many relationship. We will have to create a Join table named Product_ProductCategories instead:
Now we will set up a relationship from our Product_ProductCategory table to both the Product and ProductCategory tables. For the Product table, the Wizard will look like:
We set the To side of the relationship to Product and changed the On Delete Behavior to Cascade so that if a Product is deleted, all its associated Product_ProductCategory entries will also be deleted.
Repeat this for the ProductCategory relationship:
Adding a Product Screen
For our example, we will add a Product List and Details Screen that will allow the user to add Products. In the Details Pane of the screen, we’ll have a Treeview with our Product Categories and allow the user to assign each product to one or more Product Categories.
The initial Screen Designer will look like:
Notice the “Add Product_ProductCategories” entry in the SelectedItem of Products. Click on that line and a collection of Product_ProductCategories will be added to the Screen’s Data Model. This will contain only those records associated with the Selected Product.
Next we’ll need to add a list of all the Categories. Select “Add Data Item…” at the top of the Designer and then select the “Query” radio button.
Select Product Categories and press OK. This will add the full ProductCategory collection to our screen.
We will want to display these in the Details Pane of our new Product Screen. Select the Product Details Rows Layout element in the Visual Tree of the Screen Designer. Drag the Product Categories collection from the Data pane over to the visual tree, just under the Description element. The location is indicated by a light blue line. See the screenshot below:
By Default, the collection is displayed as a DataGrid. Change this to a Treeview.
Now let’s run the application to be sure our new screen works properly before we customize the Treeview. Select the Products List Detail screen in the Tasks menu in the left pane of the application and your screen should look like the screenshot below. Not exactly what we want, but it looks like it will work after a few edits.
Close the app and get back to the Screen Designer.
To avoid having to switch screens every time we run the application, let’s set our new screen to the default. Double click on the Properties tab of our TestVBLSTreeviewControl application in the Solution Explorer window to expose the Application Properties Designer Window.
Select the Screen Navigation tab on the left and notice that the Product Categories List Detail Screen is bold. That is because it is currently Set as the default Screen.
Select the Products List Detail screen under the Tasks folder and press the Set button at the bottom of the screen. This will make our new screen the default screen for the application.
Setting Treeview Properties for Many-To-Many Relationships
Now open our Products List Detail Screen Designer again and select the Product Categories Treeview in the visual tree. Scroll down to the bottom of the General Properties and check “Show CheckBoxes” and “Read-Only List”.
Now scroll up and select Product_ProductCategories from the drop-down for Target ManyToMany Collection Path. If the name of the ManyToMany Collection on the source entity is the same as the target, you may leave it blank. Otherwise, type in the name of the Source ManyToMany Collection Path. Also, enter ProductCategory for Checked Target Item Property Name and Product for Checked Source Item Property Name. Finally, select Products in the Many to Many Source Collection Name drop-down. This will give the Treeview the information it needs to create and delete entries in the Join table.
Before we run the application again, let’s delete the Command Bar buttons that appear below our Treeview, as we did on the first screen. Now run the application and our Products List Detail screen looks like:
Now add a product or two and set the category for one of them.
Now select the other product.
Notice the problem we have. The checkmarks are not refreshed. Our Treeview control has no way of knowing when the selected Product is changed. We will need to refresh our Product Category collection each time the selected Product changes, forcing the checkmarks to be updated.
Close the application and return to the Screen Designer. Select the Products collection in the Screen’s Data Model and click on the “Write Code” dropdown in the upper right corner of the designer. In the drop-down, select Products_SelectionChanged.
This will open a code window for the method that is called any time the Products collection Selected Item is changed. Add the one line of code shown in the screenshot below and it will refresh our Treeview each time the Product SelectedItem is changed.
The screen should now operate as expected!
Responding to Checkbox Checked and Unchecked Events
Instead of or in addition to setting up relationships when items are checked, you can define a method that will execute when an item is checked or unchecked. Return to the Screen Designer and select our Treeview. About halfway down the General properties you will notice three properties: Checked Method Name, Unchecked Method Name and Checked Item Property Name. In order to respond to the checked and unchecked events, you will need to add a Method for each and a Property of the correct type (Product Category in our case).
First, lets add the two methods. We’ll call them CategoryChecked and CategoryUnchecked. Press Add Data Item and in the wizard, select the radio button for method and change the name to CategoryChecked. Press OK and you’ll notice a new item in the Screen Data Model.
Repeat this for another method and call it CategoryUnchecked. Your Screen Designer will look like:
Now we can add a new Property. Click on Add Data Item again, but this time select the Local Property Radio Button. In the Type drop-down, select Product Category. (Notice that all our entity types along with the native data types are available.) Name the Property CheckedProductCategory.
Now your screen should contain a new property:
Now right-click on the CategoryChecked method and select Edit Execute Code. A code window will open and we can write code that will execute whenever an item is checked. As a demo, let’s open a message box with the name of the item that was checked.
Enter similar code for the unchecked method.
Now we need to enter our methods and property into the Treeview. Go to the Screen Designer, select the Treeview and set the three properties like:
Now let’s run the code and see what happens when we check or uncheck an item. While this sample is very simplistic, you can see how this could be a very powerful capability.
Single Checkbox Option
If you want to limit your users to only being able to check a single item at a time, simply check the property Single Check in the General Properties.
When an item is checked and the user checks another item, the original check is removed. Run the application and try to check a second item in the list.
That should cover it. Please use the control in your own project and let me know how it goes!