A first lap around the track

This chapter, ‘A first lap around the track’, guides you through a typical LightSwitch ‘Hello World’ sample application.

LightSwitch is available in Visual Studio 2012 Professional, however I’m using the RC version of Visual Studio 2013 Ultimate to take advantage of some of the latest IDE and project structure improvements. 

If you would get stuck during this chapter or any part of the book, the completed sample application can be downloaded from ===========TBD============= to help out.

Getting started

Like all exciting adventures, you start off with File>New Project. 

The project type that you are looking for is a LightSwitch HTML Application, under the LightSwitch Template folder.   I choose the C# flavor. 

New project wizard

Initially, a LightSwitch solution will contain three projects: your LightSwitch project, the HTML client project and a project for the server. 

A shiny new LightSwitch project in Solution Explorer

If you are wondering why the LightSwitch project itself is so empty, it is because its only role is to make sure that you as a developer don’t need to spend any effort to keep all the other projects stay in sync.  (For example: if you remove a property from one of your entities, it will be removed from the database, from the OData service, and from the screens.  The idea is called DRY (do not repeat yourself), and the LightSwitch project is the implementation.)

LightSwitch Home screen

The LightSwitch Home screen opened automatically, and it is very suggestive as what to do first: Start with data.  Ok, let’s stay in tune with Syncfusion’s company motto and focus on the Customer first.

To add a Customer entity, click the Create new table link in the Home Screen, or right click on the server project in solution explorer and select Add Table.

Select Add Table from the context menu

This will open up the Entity Designer where you can design the customer model (see note 1). 

Creating an entity

At a first glance, the entity designer looks like a SQL database designer on steroids. 

The entity designer isn’t just about designing a backend data model though.  A new SQL or SQLAzure database will be created with a Customer table when you deploy, but the fields of your entity in the entity designer here are more than simple data types.  They are true business types like ‘phone number’, ‘email address’, ‘web address’, ‘person’ or ‘document’ (see note 2), each with built-in specialized validation rules, formatting, preferred controls and extended options.

Additionally you can use the properties in Properties Window to change or add simple validation like setting minimum and maximum values, or even limiting the field to a strict Choice List.

At one point or the other, this won’t suffice in an actual application and you’ll need some custom initialization, validation or authorization, which you can add by clicking the Write Code button from the perspective of the server or any of the clients.

Designing a Customer entity

A little amount of effort spent in the Entity Designer is sufficient to design the Customer entity.  When the project is compiled, this effort will cause the table structure to be created, a web service that exposes the middle tier to be built, and a JavaScript model in the HTML client to be prepared.

Creating some screens

To finish the hello-world application, you’ll need to create a few screens.

Right click on the client project, and select Add Screen from the context menu.

New Screen Wizard

The Add New Screen wizard will open with three built-in screen templates. 

Select the Browse Data Screen template, and select the Customers as the Screen Data from the dropdown.  You can leave the default Screen Name ‘BrowseCustomers’ and hit ok, which will generate the screen and open it in the Screen Designer (see note 1 if you haven’t before).

The Screen Designer

The left hand side of the Screen Designer is called the screen view model (currently consisting only out of a Customer collection), and in the middle you’ll find an abstraction of the view (a Screen with single Tab that has an empty Command Bar and the List of Customers).

Since you start out with an emtpy database, you’ll need to provide the end user some way to add new Customers to the application.

A simple trick to do this is by adding an ‘Add’ button to the Command Bar.

Add button wizard

The wizard that opens gives you the option to write a custom method or to choose an existing method.  The existing method combobox displays a couple of navigation options, and a couple of actions you can perform on your customer collection.  The number of existing methods in this combobox will grow as your application grows and your screens become more complex, for now you can ‘bind’ your new Add button to add a new Customer and show a screen to edit that Customer by selecting the  Customers.addAndEditNew option. 

The existing methods available are highly situational

When executed, the addAndEditNew method will create a new Customer entity, add it to the visual collection on your BrowseCustomer screen, then open up a detail screen to edit it.  Because there is no screen to edit a customer yet, the wizard is suggesting to navigate to a new detail screen.

Got a screen yet?

Hitting OK will open up the Add New Screen wizard to help generating your detail screen. 

After accepting that wizard you now have two screens in your application: an all-Customers-overview screen (BrowseCustomers) and a Customer details screen.  The first overview screen in the application will be the Home screen and opens automatically when the applications starts. 

By the way, now that you have a detail screen to create a Customer, why not reuse that screen to edit a Customer as well?  To do this, you have to ‘bind’ the tab gesture on the list (this occurs when the end user taps or clicks on an item in the list) to open the detail screen.

Open the BrowseCustomers screen in the Screen Designer, select the List of Customers node and from Properties Window click the Item Tap action which is currently set to ‘None’.

Responding to touch gestures

In the Add ItemTap Action dialog that appears there will now be an additional navigation method: opening the AddEditCustomer screen.

Navigating to the newly created screen

This detail screen needs to know which Customer’s details to display, so you need to pass the one under the end user’s fingertips by typing Customers.selectedItem.  Intellisence is provided everywhere in the LightSwitch experience, even in these wizards.

Passing the currently selected item as a Customer parameter

Exploring the application

Hit Ctrl+F5 to build and run the application.

The Browse Customers screen you created first will automatically open up, since there are no Customers in the database it’ll be rather empty though.

An empty but fully functional application.

Hitting the Add Customer button from the Command Bar (the gray footer) will add a new Customer to the list and open up the Add Edit Customer screen as a modal dialog. 

As you proceed to fill in the details of your first customer, you’ll notice how the application respects the way that you have modelled your Customer entity in the Entity Designer.  The Business Type of each property will be used to infer the best way to visualize a particular field.         

Creating a new Customer

Some nerd talk

Congratulations, you just created a fully functional application on about half a cup of coffee worth of energy.  It looks rather good and I’m happy to report that it’s quite the technical masterpiece too.

One of those technical details you might miss at first glance is the responsive design.  Make the browser smaller and larger, and you’ll notice how the application carefully chooses which elements to resize and which to keep at a fixed size, to preserve as much precious screen estate as possible for the content that matters most.  Once you make the browser really small, you’ll notice how the application even reduces the number of columns from two to one, to avoid a messy layout on smaller form factors like smartphones.

The layout is updated to adapt to the device’s screen size.

Program Manager Heinrich Wendel has a post explaining the team’s envisioned strategy for designing an application with an adaptive design for multiple form factors which you can find at http://blogs.msdn.com/b/lightswitch/archive/2013/03/12/designing-for-multiple-form-factors.aspx

A second brilliant technical detail about the application you might miss at first glance, especially with only one record in the database, is its built-in paging mechanism. 

However, using your favorite network traffic capturing tool (like F12 in Internet Explorer) you can see the communication between the Browse Customer screen in the HTML client and the OData service and verify that by default it will only retrieve the first 45 records.  (In the URI you can verify it uses the OData ‘Top’ operator, read more about the OData protocol at http://OData.org. )

The application pages the data

If there would be more records, the next batch of 45 will be fetched asynchronously when the user scrolls/swipes down. 

Filtering is done by the SQL server for best performance and can be turned off or customized (different page size) from Properties Window in the Screen Designer.

Feel free to play around with the application some more, but don’t get too attached to the Customers you create with it as we’ll soon replace them with sample data using a SQL script.  But first, buckle up to start your in-depth LightSwitch training with some vocabulary 101.