I recently presented at the Dallas SharePoint TechFest on the topic of building HTML5 Apps for SharePoint 2013 using LightSwitch. This post is the first in a series of posts that further explains how the reference application reviewed during the session was built. The reference application is a mobile facing application used by remote service technicians to track and update logged work orders in a SharePoint issues list.
To begin building the application, I started by downloading and installing the Visual Studio 2012 Update 2 – CTP 4. This package includes the LightSwitch HTML Client Project Templates and must be installed prior to beginning this series.
With the templates installed, I begin by opening up Visual Studio 2012 to create a new project. In the new project dialog, be sure to select the LightSwitch HTML Application from the LightSwitch templates node. (If you are following along, choose either language. I will not be going into server code for this series).
Once I have provided a name and selected a location to store the project, click OK and I am greeted with the data designer.
This is the main screen for working with data and LightSwitch is already indicating it is focused on data-centric applications. To begin, I click on Attach to external Data Source which brings up the Data Source Wizard.
I make sure that I have selected database. (I will attach a sample database that was used during the presentation to the end of the post along with the completed project files). Clicking on next will prompt me to set up my data connection. I am hosting this data in SQL Azure, so I specify my connection properties in the dialog and confirm my connection is successful by clicking on Test Connection (You’ll recognize this as the standard data connection dialog used any time you set up a data connection in a Visual Studio project).
Clicking on OK will begin an interrogation of the data entities in my data source. I simply need to select the tables and views I want to include in this project. I also provided a name that made better sense to me instead of using the default one inferred from the data connection.
Clicking on Finish completes the setup of my data source. (You may receive prompts that tell you of any conditions where LightSwitch may need to make modifications to the data source. If you do, read them carefully to fully understand what the implications of those changes might be. In my case, the Cities view does not make use of a primary key, so LightSwitch is going to treat the data in the view as read only. This is exactly what I want since the view is simply a selection of distinct city names from the stores table.)
Clicking Continue returns me to the data designer with the City view selected. I can access any of the designers for the data sources by double clicking on them in the Solution Explorer. It is important to note there are two perspectives of the data source:
The server perspective is where I will write any server side processing logic for the data (if I were writing any logic in this series, that is). LightSwitch provides several methods that can be overridden with server side code, all accessible by clicking on the write code drop down at the top of the data designer.
The HTMLClient perspective is where code will be written to handle data on the client. At the time of this writing, there is only a single method that can be overridden – the created method.
Now that data has been included into the project, there needs to be a way to query a subset of the data. I want to be able to return all of the stores within a given city. While this database doesn’t contain a huge number of records, displaying all 212 items on a single screen could make it difficult to locate the desired store.
With the Stores table loaded in the data designer and while viewing the Server perspective, I click on Add Query in the toolbar (I could also add a query by right clicking on the table in the solution explorer and choosing add query).
The query designer will be loaded allowing me to specify a query. Before going too much further, now is a good time to provide a name for the query. It took me some time to realize this could be done when the designer is first loaded with a new query.
I want my query to be dynamic, so I decided to use a parameter in the final application. (You can either begin by creating the parameter or you can simply define a new filter. I am going to create a new filter). I click on Add Filter and begin setting up the query. My final query should read Where City = @City. When I arrived in the final drop down, there was an option to add a parameter. I selected this and the City parameter was automatically created.
Now it is time to begin displaying this data to my users, but before I create the first screen I want to point out a few more things about the data designer. By default, the data designer will automatically select a summary view. You can change this by going to the HTMLClient perspective and then locating the summary property drop down. This is valuable if I want the data to be summarized in a different way. In this case, LightSwitch did a good job of selecting the correct column to use in summary views.
The application will need three screens. The first screen should show a list of all available cities. The second screen should show the stores in a selected city and the final should show the properties of a selected store.
I am now going to get started with the first screen, the list of available cities. In the solution explorer, I right click on the HTMLClient node. (Screens can also be added from the HTMLClient perspective of a table in the available data sources.)
The screen setup dialog appears and allows me to set up the properties for the first screen. Incidentally, this will also be the home screen for the application (you can change this later if necessary). I made sure to set the screen up as a Browse Data Screen and selected the ContosoCoffeeDB.Cities entity as my data source.
Clicking on OK takes me to the screen designer. If I wanted, I can immediately build and run this application and I should see a list of cities. However, this leaves a lot of blank space when viewing the data on a widescreen device or in landscape mode on a tablet. To help out, the first change to be made is to change the list of cities to a tile list. In the screen designer, locate the List node and simply change it to a Tile List.
Now, the second screen will need to be added. I repeat the process for creating a screen, but this time I set my screen data to use the query I created earlier. It appears as a child of the ContosoCoffeeDB.Stores entity.
After clicking OK, the screen designer appears and I need to promote my parameter to also be a parameter for this screen. This allows me to pass information from the BrowseCities screen to the BrowseStoresInCity screen. To do this, locate the StoreCity property in the data items panel located on the left of the screen designer. Click on it to view the properties.
Right now, the StoreCity is not set as a parameter for this screen. To change it, I simply click the checkbox in front of Is Parameter.
Now I need to set up the link between these two screens, so I return to the BrowseCities screen and select the Tile List node.
In the properties panel, I need to set up a Tap Event. This is done by clicking on None located next to the Item Tap label.
This will bring up the actions designer. This designer allows me to either create my own methods or to make use of existing methods. Since I am navigating to another screen by tapping an item in the Cities list, I select from the existing methods and choose the showBrowseStoresInCity method.
Since a parameter was defined for this screen, before I can continue I must provide the path to the data that will be passed to the secondary screen. In this case, it is Cities.selectedItem.City1. LightSwitch will provides intellisense as I type.
If I run the application now, I should be able to click on a City in the first screen and go to the second screen containing a list of stores in the city. Notice that I have not written any code at all – I’m focusing on how I want to get the data from the database and present it to the person using the application. LightSwitch is taking care of a lot of the grunt work required to get everything working.
The final screen will show the details of a selected store, so I begin by opening the BrowseStoresInCity screen. Since there are going to be multiple ways to interact with a store, I want to provide these as individual buttons. To do this, I add a button to the command bar. This is done by clicking on Add under the command bar node in the screen designer tree.
Clicking Add brings up the method dialog displayed earlier. This time, I want to choose the method to viewSelected. I am going to have LightSwitch automatically create a new screen for me.
LightSwitch detects that I do not currently have a screen to display a single store, so it is going to allow me to automatically create one after I click OK.
Clicking on OK brings up the Screen Design Dialog, but my options have been reduced only allowing me to create a View Details Screen. This is exactly what I want to do, so I just validate that everything looks good and click on OK.
I now have a new screen that allows me to view the details of the store.
Now is a good time to build and run the application so I can make sure everything is behaving as I expected.
Viewing Stores in a City:
Selecting a store to view the details, bringing in the command bar:
Viewing the details of a store:
Next time, I will begin working with user controls and apply some custom branding to the application.