Twitter Embedded Timelines

Twitter embedded timelines are a great, interactive way to bring tweets into any webpage.  You can read about them on Twitter’s developer documentation for embedded timelines.  In the “Creating an Embeddable Timeline” section, you can see that using the embedded timelines involves two pieces:

• An HTML anchor “<a />” tag that contains:
• a special “twitter-timeline” class
• a list of “data-“ attributes that provide input into the control, for example the widget id.
• Some JavaScript that loads the “platform.twitter.com/widgets.js” script

When the widgets.js script is loaded it looks through your HTML document and will replace any anchor elements that are marked with class=“twitter-timeline” with an iframe.  The iframe hosts the actual timeline.  The HTML inside the iframe is created by Twitter itself, and is outside the scope of this article to explain.  Just know that whatever HTML is created in the iframe will show the specified tweets correctly.

The last piece to understand about Twitter embedded timelines is how to update them once they have already been loaded.  There is a Twitter JavaScript API that will search through your HTML document and convert any anchor tags with the class=”twitter-timeline” into iframes.  This API hangs off the global “twttr” object: twttr.widgets.load().  Optionally, you can pass a DOM element, and only that DOM element and its descendants will be searched.

Now, you should be able to see the strategy that will be used in order to create a reusable Twitter embedded timeline control.  All that is needed is to generate an anchor tag with the appropriate attributes.  Then call the twttr.widgets.load() function, which will turn the anchor into the appropriate iframe with the necessary HTML that shows the Twitter feed.  When data on the screen is changed:  remove the old iframe, put in a new anchor tag with updated “data-“ attributes, and call twttr.widgets.load() again.

Creating a Custom LightSwitch HTML Control

One goal I had for my custom control was to be as simple as possible for a LightSwitch developer to use.  Ideally, I wish the LightSwitch developer wouldn’t have to write any code at all to use the control.  However, I couldn’t find a way around needing at least one line of code.  To use it, a developer creates a “Custom Control” in the LightSwitch screen designer, clicks the “Edit Render Code” link and writes:

    TwitterControl.render(element, contentItem);

The TwitterControl’s render function gets passed the two parameters that are passed to the developer’s render function:

• element – an HTML DOM element, the <div> where a custom control can add new content
• contentItem – the LightSwitch view model object that provides the context to the control

I feel this is an acceptable solution in order to get this reusable control in an application.  Maybe someday custom HTML controls can be registered as extensions to Visual Studio LightSwitch and a developer would see “Twitter Feed” as an option to when adding new controls in the screen designer.  Maybe I am just wishful thinking.

Another goal I had was that any input value could be changed at any time and this would cause the control to update automatically.  The Twitter Feed Control depends on the LightSwitch runtime for its data binding functionality.  This functionality comes from the LightSwitch “ContentItem” objects.  ContentItem objects have a “stringValue” property.  According to Joe Binder’s excellent custom control blog, “The string value is a formatted string representation of the underlying property value.”  This is the property the Twitter control is using to get the current values for the “data-“ attributes in the anchor tags.  In order to get notified when this value is changed, there is a ‘dataBind’ function on a ContentItem that registers a callback function to be invoked whenever the value is changed.  So the Twitter control calls

    contentItem.dataBind('stringValue', loadFeed);

This tells the LightSwitch runtime to invoke the loadFeed function when the contentItem.stringValue changes.  The loadFeed function gets the current values, rebuilds the anchor tag and calls twttr.widgets.load().

Now here is where a design decision was made.  The Twitter Feed doesn’t just take a single value as an input.  Instead there are 17 possible inputs:

• widgetId (required)
• width
• height
• userId
• theme
• etc  (you can get the full list in the first part of this series)

In a lot of cases, a custom control will display a single value.  Using the built in “Specify the data for the new custom control” dialog

to bind to a single value is great when you only need a single value, or all your inputs comes from a single source.  However, I wanted to be flexible enough that the widgetId could come from one place (like a data property directly on the LightSwitch screen) and the userId could come from another (like the “TwitterId” property on an “Author” entity).

In order to be this flexible, I needed a way for the developer to tell the control where to get the data for each input.  Ideally, all 17 inputs would show up in the “Properties” sheet in Visual Studio.  A developer could bind each property to its source as appropriate.  However, since there is no custom control registration for HTML controls, there is no way to customize the Properties sheet when a developer puts one of these controls on his/her screen.

So the technique I devised was to use the same approach as any other “Group” control and inspect the child items under the current control.  If the control finds a child ContentItem with a name that looks like one of its inputs, it uses that child ContentItem for the input value.  Looking at the child ContentItems is pretty simple in JavaScript:

    // find the child ContentItem based on a naming convention
    contentItem.children.forEach(function (e) {
        var name = e.name.toLowerCase();

        // inspect the child's name to see if it should be used as an input

        if (name.indexOf(inputName.toLowerCase()) >= 0) {

        ...
    });

When a ContentItem is found to match an input, it gets its “stringValue” registered for data binding.  When any of the bound values change, the feed is rebuilt.

This technique works great when the input value can be changed dynamically.  However, I found many cases where I wanted to hard code a static value to be passed to the control.  Most often this was the most important input value: the widgetId.  When using a “User Timeline” feed where the user being displayed is dynamic, you only need one widget registered with Twitter.  In that case, you want to just say widgetId = 12345, and not mess around with ContentItems.  Although I could have forced a developer to add a screen data item, and hard code the value during “screen.created” function, this was breaking my first goal of making this control as simple as possible.

In order to support easily providing static information to the control, I added an optional parameter to the TwitterControl.render function: “options”.  This options object can contain any of the 17 input values in properties that have the same name as the input.  So, if a developer wanted to statically define the width and height input values, the code they would write would simply be:

    TwitterControl.render(element, contentItem, {
        width: 450,
        height: 600
    });

Internally to the control, these static input values are placed in “FakeContentItem” objects, which allows the rest of the control code to handle both real ContentItem objects and these static values in the same way.  Sometimes this is the best feature of JavaScript and sometimes it is the worst feature: having such a loose typing system.  In this case, it really worked out great.  I didn’t need to try using the real ContentItem “class” for something it wasn’t designed to do.  But I didn’t need to write an “adapter” layer that could support both real and fake ContentItem objects.  My code just uses two things from a ContentItem: the stringValue property and the dataBind function.  So the fake objects just need to expose these two things, and they act like a real ContentItem to the rest of the system.  Obviously there are plenty of cases where you can “shoot yourself in the foot” doing something like this.  But when used at appropriate times, this really simplifies JavaScript coding.

The rest of the Twitter Feed code is pretty self-explanatory.  It uses jQuery to create an anchor tag, add the necessary attributes, and then calls twttr.widgets.load() on the DOM element passed into the render function.

Creating the NuGet Package

I don’t think I can sing my praises of NuGet loud enough to describe how much value I think it adds to the development community.  It is such a simple, yet powerful platform to share components.  Just having a searchable catalogue of things you can use in your applications adds immeasurable value.  But to be able to install them correctly in your Visual Studio projects with a click of a button seriously blows me away.  It is like the first time I experienced a mobile device’s “app store”.  There was no wizard asking me where to install the app.  There wasn’t an archaic README.txt file explaining how to set the app up.  I just searched for an app, clicked a button and I was using the application in seconds.

So deciding to distribute the Twitter Feed control over NuGet was a non-decision.  It was a given.

However, I had never done it before and I was willing to learn.  NuGet has a great set of documentation explaining how to download NuGet.exe, create a NuGet package, and publish it to a NuGet repository.

A question I have gotten asked is “How do you get the twitterControl.js script registered in the default.htm page automatically?”  This relates back to one of my goals above: making this control as simple as possible to use.  Even adding a <script /> line in the default.htm page seemed like too much work for me.

To get the script file automatically added to the application’s HTML, I used a feature that the LightSwitch HTMLClient project uses itself.  During build time, the LightSwitch HTMLClient project looks for all .js files under the “UserCode” folder.  It creates a generated ‘usercode.js’ file under the hidden “GeneratedArtifacts” folder.  This usercode.js file looks like following:

    // Warning: AutoGenerated file, Don't edit.
    document.writeln("<script type=\"text/javascript\" src=\"UserCode/twitterControl.js\"></script>");
    document.writeln("<script type=\"text/javascript\" src=\"Screens/ViewEmployee.lsml.js\"></script>");

The usercode.js file gets added to the DOM by a file named “generatedAssets.js”.  A script tag for the “Scripts/Generated/generatedAssets.js” file is in the default.htm file.  This is how the Twitter Feed control “automatically” gets registered in the application’s default.htm file.  Since it is placed in the “UserCode” folder of a LightSwtich HTMLClient project, LightSwitch will automatically load this .js file at runtime.

Now, will this feature be supported forever?  I don’t know.  Someday there might not be a “UserCode” folder in a LightSwitch HTMLClient project.  Or, the generatedAssets.js file might not get created anymore.  So, just because I used this “hack” doesn’t mean that it is a publicly supported feature.  It could change in a future release.  However, knowing this, I still decided to take advantage of this functionality in order to support my above goals.

To get the .js file installed to the UserCode folder by NuGet, a NuGet package author just needs to put the .js file under “Content\UserCode” in their NuGet folder structure.  When the NuGet package gets installed on an HTMLClient project, the .js file will automatically be put in the project’s “UserCode” folder.

A drawback to this approach is that I don’t ship both a full version and a minified version of the code.  Adding both to the “UserCode” folder would cause problems because they both would be automatically registered in an app.  I didn’t tackle this problem, but if there is enough feedback (probably like one person asking for it) I would ship a minified version of the Twitter Feed control and then have to address this issue.

Conclusion

That’s all for now.  I hope this gives someone insight into how I built the Twitter Feed control.  Feel free to download the code from NuGet and look through it yourself.  Maybe it will give you ideas on how you can build a reusable control for yourself and the rest of the LightSwitch developers out there.

Eric

• Your application maintains a list of people and your users want to see the tweets sent by each of those people.
• Your application has a list of items and your users want to see any tweets about those items.

You get the idea.  Of course, your application could build up hyperlinks to twitter and your users could just click on the link to view this information.  But wouldn’t it be better to display that information directly in your application?

In this article I am going to show you how you can integrate a Twitter feed directly into your Visual Studio LightSwitch application.  I’ve built a reusable Twitter Feed control for LightSwitch HTML projects.  I’ll show you how you can use this control in your application.  This is the first article in a two part series.  In the next article, I’ll discuss the internals of the control.  For now, I’ll just show you how you can use the control.

Get the Control from NuGet

First, you need to get the control’s JavaScript code from NuGet.  You can do this by using the Package Manager Console from Tools –> NuGet Package Manager –> Package Manager Console.  Set the Default project to your application’s HTMLClient project and type “Install-Package Erhardt.LightSwitch.Twitter”.

Or optionally, you can right-click your application’s HTMLClient project, select “Manage NuGet Packages” and search for a package named “LightSwitch Twitter Feed Control”.

Create a Twitter Widget

In order to embed a Twitter feed into an HTML page, someone needs to create a Twitter Widget.  This is easily done by

• Logging into https://twitter.com
• At the top right click the “cog” icon and select “Settings”

• On the left side, select “Widgets”
• Click the “Create new” button

On the “Create a user widget” page, you are given options on the different types of widgets you can create.  At the top of the page is a link to the developer documentation which explains the types of widgets.  The LightSwitch Twitter Feed Control supports all types, but the easiest one to start with is the “User timeline” widget.  Type in the Username of the person whose Tweets you want displayed.  (Don’t worry about which user you pick.  This can be changed later at runtime, as I’ll demonstrate.)  Click the “Create widget” button and you are done.

Now that you have created a widget, you need one very important piece of information – the widget id.  There are two ways to get the widget id:

1. In the address bar of the browser, the URL will look like:  https://twitter.com/settings/widgets/<widgetId>/edit…
2. At the bottom of the page there is an HTML snippet.  Parse that HTML for the “data-widget-id” attribute.

Save this widget id, you’ll need it in the next step.

Put the Twitter Feed Control on a Screen

Now we can get to the fun part – actually using the control.  In your LightSwtich HTML application, add a new Screen and name it “TwitterScreen”.  In the screen designer:

• Add a “New Group” control
• Optionally name it “TwitterFeed”
• Change the group control from a “Rows Layout” to a “Custom Control”
• In the Properties sheet, click the “Edit Render Code” link for your new custom control
• Add the following line of code to the render method:

myapp.TwitterScreen.TwitterFeed_render = function (element, contentItem) {
    TwitterControl.render(element, contentItem, { widgetId: "123456" });
};

Make sure you replace 123456 with the widget Id number you saved above.

That’s it, now F5 your application and your screen will show all the tweets by the user you specified when you created the widget.

I used the “twitterapi” user name and my screen looks like the following:

Client Side Customizations

Now that you have a Twitter feed showing in your application, it is time to customize it.  There are a number of different options on how you can customize it.  See Twitter’s developer documentation for all the different options under “Customization Options”.  To start, I’ll show you how to statically customize the feed.  First, let’s change which user is displayed.  To do this, change the line of code in the TwitterFeed_render function to also pass in a “userId”:

myapp.TwitterScreen.TwitterFeed_render = function (element, contentItem) {
    TwitterControl.render(element, contentItem, {
        widgetId: "123456",
        userId: "microsoft"
    });
};

When you F5 your application, you will see that instead of twitterapi’s tweets being shown, you will see tweets by the official Microsoft account.

Now, say you want to change the size of the feed.  You can easily do this by specifying “width” and “height” properties:

myapp.TwitterScreen.TwitterFeed_render = function (element, contentItem) {
    TwitterControl.render(element, contentItem, {
        widgetId: "123456",
        userId: "microsoft",
        width: 250,
        height: 200
    });
};

Here is a list of the supported properties that can be specified.  See Twitter’s developer documentation on embedded timelines for the explanation of each.  Note that the only required property is the “widgetId” property.

• widgetId
• userId
• theme
• linkColor
• width
• height
• chrome
• borderColor
• language
• tweetLimit
• related
• ariaPolite
• showReplies
• customTimelineId
• favoritesId
• listOwnerId
• listId

Binding to Data Dynamically

I can just hear the conversation happening in your head right now, “This is all well and fine, Eric, but I have a list of people in the application.  Am I supposed to hard code the list of people in my JavaScript code?” 

Luckily the answer is, “Of course not.”  Each one of the properties listed above can also be bound to data in LightSwitch.  So you can dynamically change the feed based on the current data in the running application.

The pattern to do this is simple.  Remember how you first created a “Group” control, and then changed it to a “Custom” control afterwards?  This allows you to add other items underneath your TwitterFeed control.  The TwitterControl.render method looks at all the children directly below the contentItem being passed into it.  If it finds a child whose name contains a property listed above, it binds that property to the data of that child content item.  In other words, it gets the property values from the child content items, and as those values change, the feed is automatically updated with the new data.

So to illustrate this, I have created a simple Table in LightSwitch named “Person”.  A Person has a string Name and a string TwitterUserId.

I then created a Browse Data Screen on the Person table.  On the Browse screen, I added a “New Group” control, and changed it to a “Custom” control.  I then dragged the “TwitterUserId” property underneath the Custom Control.  This added a new child content item named “People_selectedItem_TwitterUserId” to my TwitterFeed control.  (Notice that the name of the content item contains “UserId” – which means it should bind to the userId property.)

And finally, I clicked on the “Edit Render Code” link in the Properties sheet and added the necessary code:

myapp.BrowsePeople.TwitterFeed_render = function (element, contentItem) {
    TwitterControl.render(element, contentItem, { widgetId: "123456" });
};

Now when I run my application, the currently selected Person’s tweets are shown in the Twitter feed.

You can mix and match any number of properties – some can be statically defined and some can be bound to data.  To bind the data dynamically, remember that your child content item’s name needs to contain the associated property’s name.  If a property is both statically defined and bound to a content item, the statically defined value always wins.  And remember that you always need to specify a widgetId (either static or bound).

Conclusion

I hope you are getting wonderful ideas about how you can use an embedded Twitter feed in your application(s).  If so, I’d love to hear them.  Just drop me a comment explaining how you plan to use this control.  Or leave any other feedback you’d like to give.  It is always appreciated.

Eric

The problem is, Visual Studio LightSwitch doesn’t understand how to call stored procedures to insert, update and delete records out of the box.  Thus, any database that only allows stored procedures to update records seems like it is unusable in LightSwitch.

However, LightSwitch can still support these databases, but it just needs a little more work to get it hooked up.  I’ll show you a simple way to manipulate these records in LightSwitch.

General Approach

To work with stored procedures in our data model, we are going to use one of my favorite features in LightSwitch: attaching to a custom WCF RIA Service.  The reasons this is one of my favorite features is because it provides you the flexibility you need to bring any data into your application.  If you have data stored in a text file, a spreadsheet, out on the web, or wherever, you can write a WCF RIA Service to expose that data and LightSwitch will seamlessly work with that data.

Overall, the approach will be:

• Create an Entity Framework .edmx model that can write using the database’s stored procedures
• Create a WCF RIA Service that talks to the Entity Framework model
• Import the WCF RIA Service into LightSwitch and use it as a normal data source

Prerequisites

The stand alone VS LightSwitch 2011 doesn’t have an Entity Framework designer in it.  In order to build the Entity Framework .edmx model, you will need one of the following:

• Visual Studio 11 Beta or later
• Visual Studio 2010 Professional or higher
• Microsoft Visual Studio 2010 Express (I used Visual Web Developer 2010 Express)

I will use the standard Northwind database for this article.  However, I will add 3 standard stored procedures to it: InsertCustomer, UpdateCustomer, and DeleteCustomer.  These will be simple stored procedures that call INSERT, UPDATE, and DELETE TSQL commands respectively.  See the appendix at the end of this article or the MSDN Code Gallery: Updating Records in LightSwitch using Stored Procedures sample for this article for the stored procedures’ definitions.

Entity Framework Model

First start by creating a new Class Library in Visual Studio (not the stand alone Visual Studio LightSwitch, but Visual Studio Pro or Visual Studio Express), name it “NorthwindService”.  In the Solution Explorer, right-click the “NorthwindService” project and select “Add” –> “New Item…”.  Select “ADO.NET Entity Data Model” and name it “Northwind.edmx”.

Select “Generate from database” and enter the connection information to your Northwind database and click “Next”.  Expand the “Tables” node and select “Customers”.  (Note: you could have selected a view if the table isn’t exposed.)    Also expand the “Stored Procedures” node and select “InsertCustomer”, “UpdateCustomer”, and “DeleteCustomer”.  (Note these stored procedures don’t exist in a default Northwind database.  They need to be added.  See the gallery sample for the commands to create them.) 

Click Finish.  This generates you an entity model that contains the Customer entity in it.  We want to insert, update and delete through our stored procedures.  So we need to tell the Entity Framework how to do that.  Right-click the Customer entity and select “Stored Procedure Mapping”.  At the bottom of the screen, you will see a windows with three grid rows:

Click on each of these dropdowns and select the corresponding stored procedure for each action.  The Entity Framework will automatically hook up the parameter mapping if the names match.  If the names don’t match, you can easily map each property to the corresponding parameter.  When you are finished your mapping screen should look like:

You now have an Entity Framework data model that will insert, update and delete records using your stored procedures.

Creating the WCF RIA Service

The next thing we need is a way for LightSwitch to consume this Entity Framework model.  That is where WCF RIA Services fits into the picture.  There are two ways to create a WCF RIA Service.  If you have a Visual Studio Professional installation, you can right-click the project in the Solution Explorer and “Add” –> “New Item…” and select “Web” –> “Domain Service Class”.

Name the file “NorthwindService.cs” (or .vb) and click “Add”.  In the “Add New Domain Service Class” dialog, accept the defaults and click OK.

If you are working with Visual Studio Express, you can do all the steps the above Add New Item template does by hand:

• Add References to the following .NET assemblies:
  • System.ComponentModel.DataAnnotations
  • System.ServiceModel.DomainServices.EntityFramework (Look in %ProgramFiles(x86)%\Microsoft SDKs\RIA Services\v1.0\Libraries\Server if it isn’t under the .Net tab)
  • System.ServiceModel.DomainServices.Server (Look in %ProgramFiles(x86)%\Microsoft SDKs\RIA Services\v1.0\Libraries\Server if it isn’t under the .Net tab)
• Create a new Code File by “Add” –> “New Item…” and select “Code File” named “NorthwindService”

No matter which route you take, copy and paste the following code into your NorthwindService.cs file:

C#:

using System.Data;
using System.Linq;
using System.ServiceModel.DomainServices.EntityFramework;
using System.ServiceModel.DomainServices.Server;

namespace NorthwindService
{
    public class NorthwindService : LinqToEntitiesDomainService<NorthwindEntities>
    {
        [Query(IsDefault = true)]
        public IQueryable<Customer> GetCustomers()
        {
            return this.ObjectContext.Customers;
        }

        public void InsertCustomer(Customer customer)
        {
            if ((customer.EntityState != EntityState.Detached))
            {
                this.ObjectContext.ObjectStateManager.
                    ChangeObjectState(customer, EntityState.Added);
            }
            else
            {
                this.ObjectContext.Customers.AddObject(customer);
            }
        }

        public void UpdateCustomer(Customer currentCustomer)
        {
            this.ObjectContext.Customers.AttachAsModified(currentCustomer,
                this.ChangeSet.GetOriginal(currentCustomer));
        }

        public void DeleteCustomer(Customer customer)
        {
            if ((customer.EntityState != EntityState.Detached))
            {
                this.ObjectContext.ObjectStateManager.
                    ChangeObjectState(customer, EntityState.Deleted);
            }
            else
            {
                this.ObjectContext.Customers.Attach(customer);
                this.ObjectContext.Customers.DeleteObject(customer);
            }
        }
    }
}

VB:

Imports System.ComponentModel.DataAnnotations
Imports System.ServiceModel.DomainServices.EntityFramework
Imports System.ServiceModel.DomainServices.Server

Public Class NorthwindService
    Inherits LinqToEntitiesDomainService(Of NorthwindEntities)

    <Query(IsDefault:=True)>
    Public Function GetCustomers() As IQueryable(Of Customer)
        Return Me.ObjectContext.Customers
    End Function

    Public Sub InsertCustomer(ByVal customer As Customer)
        If ((customer.EntityState = EntityState.Detached) = False) Then
            Me.ObjectContext.ObjectStateManager.
                ChangeObjectState(customer, EntityState.Added)
        Else
            Me.ObjectContext.Customers.AddObject(customer)
        End If
    End Sub

    Public Sub UpdateCustomer(ByVal currentCustomer As Customer)
        Me.ObjectContext.Customers.AttachAsModified(currentCustomer,
            Me.ChangeSet.GetOriginal(currentCustomer))
    End Sub

    Public Sub DeleteCustomer(ByVal customer As Customer)
        If ((customer.EntityState = EntityState.Detached) = False) Then
            Me.ObjectContext.ObjectStateManager.
                ChangeObjectState(customer, EntityState.Deleted)
        Else
            Me.ObjectContext.Customers.Attach(customer)
            Me.ObjectContext.Customers.DeleteObject(customer)
        End If
    End Sub
End Class

You now are ready to import this WCF RIA Service into a LightSwitch application.

LightSwitch Application

Open Visual Studio LightSwitch and create a new LightSwitch application.  Name it “Northwind”.  Make sure the solution is being shown by opening Tools –> Options. Under “Projects and Solutions” ensure that “Always show solution” is checked. Then, in the Solution Explorer, right-click on the solution and say “Add –> Existing Project”. Navigate to the Class Library you created above. (The Open File Dialog may filter only *.lsproj files. Either typing the full path into the dialog or navigating to the folder, typing * and pressing “Enter” into the File name text box will allow you to select the NorthwindService.csproj/vbproj project.)

Now click the “Attach to external Data Source” link in LightSwitch and select “WCF RIA Service”. 

Click Next.  Since the new LightSwitch application doesn’t have any references, no classes are shown.  Click the “Add Reference” button and select the “Projects” tab and double-click the NorthwindService project.

Select the “NorthwindService.NorthwindService” class and click Next.

Select all the Entities check box and click “Finish”.

One last thing needs to happen in order for you to use this data source.  You need to copy the “NorthwindEntities” connection string from the NorthwindService class library’s App.Config into your application’s web.config.  Open the App.config file and copy the line starting with “<add name=”NorthwindEntities”…”.  Paste this line under the <connectionStrings> node in the LightSwitch web.config.  To open the LightSwitch web.config:

Switch your Solution Explorer to “File View”.

Then click on the “Show All Files” tool bar button.

Under the “ServerGenerated” project (or just “Server” project if you are using Visual Studio 11) you will find the “Web.config” file.

That’s it.  Now you have a fully functioning data source that can insert, update and delete records using stored procedures.  You can create your LightSwitch screens and business logic as usual, and quickly and easily make a functioning application using stored procedures.

I have uploaded a sample application in both C# and VB to the MSDN Code Gallery at https://code.msdn.microsoft.com/Updating-Records-in-c88c7997.

Eric

p.s. For more information on what the Entity Framework can do with views and stored procedures, see Julie Lerman’s excellent article: Stored Procedures in the Entity Framework

Stored Procedures Used in This Article

CREATE Procedure [dbo].[InsertCustomer]
    @CustomerID nchar(5),
    @CompanyName nvarchar(40),
    @ContactName nvarchar(30),
    @ContactTitle nvarchar(30),
    @Address nvarchar(60),
    @City nvarchar(15),
    @Region nvarchar(15),
    @PostalCode nvarchar(10),
    @Country nvarchar(15),
    @Phone nvarchar(24),
    @Fax nvarchar(24)
AS
INSERT INTO [Northwind].[dbo].[Customers]
           ([CustomerID]
           ,[CompanyName]
           ,[ContactName]
           ,[ContactTitle]
           ,[Address]
           ,[City]
           ,[Region]
           ,[PostalCode]
           ,[Country]
           ,[Phone]
           ,[Fax])
     VALUES
           (@CustomerID
           ,@CompanyName
           ,@ContactName
           ,@ContactTitle
           ,@Address
           ,@City
           ,@Region
           ,@PostalCode
           ,@Country
           ,@Phone
           ,@Fax)

CREATE PROCEDURE [dbo].[UpdateCustomer]
    @CustomerID nchar(5),
    @CompanyName nvarchar(40),
    @ContactName nvarchar(30),
    @ContactTitle nvarchar(30),
    @Address nvarchar(60),
    @City nvarchar(15),
    @Region nvarchar(15),
    @PostalCode nvarchar(10),
    @Country nvarchar(15),
    @Phone nvarchar(24),
    @Fax nvarchar(24)
AS
UPDATE [Northwind].[dbo].[Customers]
   SET [CompanyName] = @CompanyName
      ,[ContactName] = @ContactName
      ,[ContactTitle] = @ContactTitle
      ,[Address] = @Address
      ,[City] = @City
      ,[Region] = @Region
      ,[PostalCode] = @PostalCode
      ,[Country] = @Country
      ,[Phone] = @Phone
      ,[Fax] = @Fax
 WHERE CustomerID=@CustomerID 

CREATE PROCEDURE [dbo].[DeleteCustomer]
    @CustomerID nchar(5)
AS

DELETE FROM [Northwind].[dbo].[Customers]
 WHERE CustomerID=@CustomerID

Many existing databases make use of stored procedures (or stored procs). There are advantages that stored procedures have over other types of database interaction as listed in MSDN at https://msdn.microsoft.com/en-us/library/aa214299(SQL.80).aspx.  This makes them very popular with database administrators. So it is very common that existing databases already have stored procedures in them that you will want to take advantage of in your LightSwitch application.

This article is the first in a two part series that will show you how to execute a stored procedure in your LightSwitch application. The second part will describe displaying and editing data from a stored procedure in your LightSwitch screens.

Business Scenario

Our customer wants an application that can track employee information. One of the pieces of information is to track if the employee is married or not, which is used for tax purposes. The application should also allow the user to update the marital status (going from single to married, and married to single).

The Database

For this example, we are going to use the AdventureWorks sample database. The AdventureWorks database has a “HumanResources” schema that stores information about your company’s organization, employees, and job candidates. The AdventureWorks database has a stored procedure that allows an application to update an Employee’s personal information. One of these pieces of information is the employee’s marital status. Here is what the stored procedure looks like:

CREATE PROCEDURE [HumanResources].[uspUpdateEmployeePersonalInfo]
@EmployeeID [int], 
@NationalIDNumber [nvarchar](15), 
@BirthDate [datetime], 
@MaritalStatus [nchar](1), 
@Gender [nchar](1)
WITH EXECUTE AS CALLER
AS
BEGIN
SET NOCOUNT ON;
UPDATE [HumanResources].[Employee] 
SET [NationalIDNumber] = @NationalIDNumber 
,[BirthDate] = @BirthDate 
,[MaritalStatus] = @MaritalStatus 
,[Gender] = @Gender 
WHERE [EmployeeID] = @EmployeeID;
END;

This is a very simple stored procedure that takes in five parameters and updates the Employee record with the matching EmployeeID with the other 4 parameters’ values.  The specific parameter we are interested in is @MaritalStatus.

The Application

I’m going to use Visual Studio LightSwitch 2011 for this post, but these same steps will work with Visual Studio 11 Beta or later.

Start by creating a new LightSwitch application named AdventureWorks and click “Attach to external Data Source”.  Select Database and enter the connection information to your AdventureWorks database.  Select all tables and hit Finish.

Next create a new Search Data Screen and select “AdventureWorksData.Employees” as the data source:

We should now have a functioning Employee Search screen.  Hit F5 just to make sure everything is hooked up correctly.  Your app should look like this:

Notice the far right column “Marital Status” has values ‘M’ and ‘S’.  This isn’t the best UI, because my user would like to see “Married” and “Single”.  There is a super simple way to do this in LightSwitch.  Open the Employees table, and select the MaritalStatus property.  Notice in the Properties sheet, there is a link to Choice List…  Click that link.

This presents you with a Choice List dialog that allows you to map values in the database with values to display on the screen.  Fill out the dialog as shown below.  (Note that Choice List can be used for other data types, like boolean, integers, etc.)

Now you can run your application again and see that it correctly displays marital status as a user would expect.

Invoking the stored procedure

Now we are ready to write the code to update the employee’s marital status.  However, if we are writing code in a button on the screen, the issue we hit is the button code will execute on the client tier.  But there is no way to access the database from the client.  Instead we need to make a call from the client to get onto the middle tier.  A simple way to do this is to take advantage of the save pipeline built into LightSwitch.  Whenever a record is inserted, updated or deleted, LightSwitch will invoke methods (Inserting, Updating, Deleting, etc.) on the middle tier.  This allows you to write business logic that is ensured to run, no matter what client is making the request.  We will use this functionality to invoke our stored procedure.  To start, create a new Table and name it “UpdatePersonalInfoOperation”.  Add a property for each input parameter of the stored procedure.  (Keep in mind that adding a new table will create an intrinsic ApplicationData database that will need to be deployed along with your application.)

To invoke this ‘operation’, we will create a new UpdatePersonalInfoOperation record, set all the properties and save the record.  This will execute the UpdatePersonalInfoOperations_Inserting method on the middle tier.  So let’s write our inserting logic by dropping down the Write Code button at the top right of the designer and selecting “UpdatePersonalInfoOperations_Inserting”.  Here is the code:

C#:

using System.Configuration;
using System.Data;
using System.Data.SqlClient;
    
public partial class ApplicationDataService
{
    partial void UpdatePersonalInfoOperations_Inserting(UpdatePersonalInfoOperation entity)
    {
        using (SqlConnection connection = new SqlConnection())
        {
            string connectionStringName = this.DataWorkspace.AdventureWorksData.Details.Name;
            connection.ConnectionString =
                ConfigurationManager.ConnectionStrings[connectionStringName].ConnectionString;

            string procedure = "HumanResources.uspUpdateEmployeePersonalInfo";
            using (SqlCommand command = new SqlCommand(procedure, connection))
            {
                command.CommandType = CommandType.StoredProcedure;

                command.Parameters.Add(
                    new SqlParameter("@EmployeeID", entity.EmployeeID));
                command.Parameters.Add(
                    new SqlParameter("@NationalIDNumber", entity.NationalIDNumber));
                command.Parameters.Add(
                    new SqlParameter("@BirthDate", entity.BirthDate));
                command.Parameters.Add(
                    new SqlParameter("@MaritalStatus", entity.MaritalStatus));
                command.Parameters.Add(
                    new SqlParameter("@Gender", entity.Gender));

                connection.Open();
                command.ExecuteNonQuery();
            }
        }

        this.Details.DiscardChanges();
    }
}

VB:

Imports System.Configuration
Imports System.Data
Imports System.Data.SqlClient

Namespace LightSwitchApplication
    Public Class ApplicationDataService
        Private Sub UpdatePersonalInfoOperations_Inserting(entity As UpdatePersonalInfoOperation)
            Using connection = New SqlConnection
                Dim connectionStringName = Me.DataWorkspace.AdventureWorksData.Details.Name
                connection.ConnectionString =
                    ConfigurationManager.ConnectionStrings(connectionStringName).ConnectionString

                Dim procedure = "HumanResources.uspUpdateEmployeePersonalInfo"
                Using command = New SqlCommand(procedure, connection)
                    command.CommandType = CommandType.StoredProcedure

                    command.Parameters.Add(
                        New SqlParameter("@EmployeeID", entity.EmployeeID))
                    command.Parameters.Add(
                        New SqlParameter("@NationalIDNumber", entity.NationalIDNumber))
                    command.Parameters.Add(
                        New SqlParameter("@BirthDate", entity.BirthDate))
                    command.Parameters.Add(
                        New SqlParameter("@MaritalStatus", entity.MaritalStatus))
                    command.Parameters.Add(
                        New SqlParameter("@Gender", entity.Gender))

                    connection.Open()
                    command.ExecuteNonQuery()
                End Using
            End Using

            Me.Details.DiscardChanges()
        End Sub
    End Class
End Namespace

You will have to add a reference from your Server project to the System.Configuration assembly in order to use the ConfigurationManager class.  (In the Solution Explorer toolbar, drop down the View toggle and select “File View”.  Then right-click the Server project and say “Add Reference”.  In the .NET tab, select System.Configuration.)

This code creates a SqlConnection and gets the connection string from the web.config.  Note that since we are attached to an external database, the name of the connection string setting is the name of the data source.  If we needed to get the connection string of the intrinsic “ApplicationData” database, the name of the setting would be hard-coded to “_IntrinsicData”.

Then, the code creates a SqlCommand object with the required command text, adds the parameter values, and executes the command.  Notice the “Using” statements.  These statements are important because if an exception occurs while processing this code, we are guaranteed that the connection to the database will get cleaned up in a timely manner.

Finally, the code calls DiscardChanges().  This call is needed because we don’t really want to insert an UpdatePersonalInfoOperation record in the intrinsic database.  We created and saved the record only as a mechanism to execute code on the middle tier.  Saving a record for every call to this operation isn’t necessary.  On the other hand, if you want an easy way to log whenever the operation is invoked, then remove the call to DiscardChanges() and the record will be inserted, recording the parameter values to the operation.

Note that you can use any of your favorite frameworks for invoking stored procedures (Entity Framework, Linq To SQL, etc.).  I just showed SqlClient since it has been around since .Net 1.0 and pretty simple with nothing else to setup.

Creating a Button to Call Our Operation

Now let’s invoke this middle tier operation.  We wish to add a button to our application that will mark a Single employee as Married. First, open the SearchEmployees screen and add a new button to the ribbon. At the top of the screen designer, right-click the “Screen Command Bar” content item and select “Add Button…”.

Name the button “MarkAsMarried”. We only want this button to be enabled for single employees, so right-click the button and select “Edit CanExecute Code”. Enter in the following code:

C#:

partial void MarkAsMarried_CanExecute(ref bool result)
{
    result = this.Employees.SelectedItem != null && 
        this.Employees.SelectedItem.MaritalStatus == "S";
}

VB:

Private Sub MarkAsMarried_CanExecute(ByRef result As Boolean)
    result = Me.Employees.SelectedItem IsNot Nothing And
        Me.Employees.SelectedItem.MaritalStatus = "S"
End Sub

Back in the screen designer, right-click on the button again and select “Edit Execute Code”.  Enter the following code:

C#:

partial void MarkAsMarried_Execute()
{
    DataWorkspace dataWorkspace = new DataWorkspace();
    Employee employee = this.Employees.SelectedItem;

    UpdatePersonalInfoOperation operation = 
        dataWorkspace.ApplicationData.UpdatePersonalInfoOperations.AddNew();
    operation.EmployeeID = employee.EmployeeID;
    operation.NationalIDNumber = employee.NationalIDNumber;
    operation.BirthDate = employee.BirthDate;
    operation.MaritalStatus = "M";
    operation.Gender = employee.Gender;

    dataWorkspace.ApplicationData.SaveChanges();
}

VB:

Private Sub MarkAsMarried_Execute()
    Dim dataWorkspace = New DataWorkspace
    Dim employee = Me.Employees.SelectedItem

    Dim operation =
        dataWorkspace.ApplicationData.UpdatePersonalInfoOperations.AddNew()
    operation.EmployeeID = employee.EmployeeID
    operation.NationalIDNumber = employee.NationalIDNumber
    operation.BirthDate = employee.BirthDate
    operation.MaritalStatus = "M"
    operation.Gender = employee.Gender

    dataWorkspace.ApplicationData.SaveChanges()
End Sub

This code first creates a new DataWorkspace.  This is needed because we don’t want to modify the current change set on the screen.  Instead, we will make an independent change set that only contains the operation entity we wish to invoke.  When it is complete, we discard the DataWorkspace and operation entity.

Next, we create a new UpdatePersonalInfoOperation making sure to use our newly created DataWorkspace’s ApplicationData.  We grab the currently selected employee’s information and set it on the operation, but we tell the operation to change the MaritalStatus to “M”.  Finally, we invoke the operation by calling SaveChanges.

That’s it.  Now you can run your application, select a single employee, and click on the Mark As Married button.  The stored procedure will be invoked.

Advanced topics

Refreshing your screen

After invoking the UpdatePersonalInfoOperation, you will notice that your screen is not updated with the latest data – the selected employee still says “Single”.  You can fix this by issuing a query in your button code to read the updated results.  However, note that this only works if the records being refreshed don’t already have changes made to them.  If a record is currently modified, it is not possible to refresh its values by executing a query.

To refresh the screen, you can either call “Employees.Refresh()” or “DataWorkspace.AdventureWorksData.Employees_Single(operation.EmployeeID)” at the end of the button’s Execute method.  Note that Employees.Refresh() will refresh all the records where Employees_Single will just refresh the selected item.

Allowing certain users to update personal information

A lot of times, you only want specific people to be able to invoke the stored procedure.  Using the pattern above, it is very simple to enable this in your application.  First, start by creating a Permission by navigating to the Application’s Properties (right-click on the application in the Solution Explorer and select “Properties” or double click the “Properties” item under the application).  On the “Access Control” tab, enable authentication and enter a new Permission in the grid.

Now, to only allow users with the UpdatePersonalInfo permission to invoke the stored procedure, we just need to say that only these users are allowed to “insert” the UpdatePersonalInfoOperation records.  So go back to the UpdatePersonalInfoOperation entity and drop down “Write Code” –> UpdatePersonalInfoOperations_CanInsert and enter the following code:

C#:

partial void UpdatePersonalInfoOperations_CanInsert(ref bool result)
{
    result = this.Application.User.HasPermission(Permissions.UpdatePersonalInfo);
}

VB:

Private Sub UpdatePersonalInfoOperations_CanInsert(ByRef result As Boolean)
    result = Me.Application.User.HasPermission(Permissions.UpdatePersonalInfo)
End Sub

Now if a user isn’t granted the UpdatePersonalInfo permission, and they try invoking this operation, it will throw a PermissionException and not allow the user to perform the operation.  This isn’t a great user experience, so the last thing to change in the application is the button’s CanExecute code to check if the current user has permission to insert UpdatePeronalInfoOperation records.  Change your button’s CanExecute method as follows:

C#:

partial void MarkAsMarried_CanExecute(ref bool result)
{
    result = this.Employees.SelectedItem != null &&
        this.Employees.SelectedItem.MaritalStatus == "S" &&
        this.DataWorkspace.ApplicationData.UpdatePersonalInfoOperations.CanInsert;
}

VB:

Private Sub MarkAsMarried_CanExecute(ByRef result As Boolean)
    result = Me.Employees.SelectedItem IsNot Nothing And
        Me.Employees.SelectedItem.MaritalStatus = "S" And
        Me.DataWorkspace.ApplicationData.UpdatePersonalInfoOperations.CanInsert
End Sub

For more information on securing your LightSwitch applications, be sure to check out this excellent MSDN Magazine article: Securing Access to LightSwitch Applications.

Passing Result Parameters from a Stored Procedure

There are plenty of cases where the stored procedure will return values (rows modified, success/failure info, the result of the procedure, etc.).  There is a very simple way to pass these values back to the client button code so it can be relayed to the user.  Start by adding an extra property to the UpdatePersonalInfoOperation entity.  Be sure to uncheck “Required” as this will cause validation to fail because the value won’t be set before calling SaveChanges() to invoke the operation.  This extra property will be used as the “result” of the operation.

Inside the UpdatePersonalInfoOperations_Inserting middle tier method, set the record’s “result” property to the value you wish to pass back to the button code.

In the button code, after the call to SaveChanges(), you can get the “result” property off of the UpdatePersonalInfoOperation record, which will now be set to result of the operation.

Note that you can add multiple “result” properties to the UpdatePersonalInfoOperation entity to suit your needs.

Passing result parameters works even if you are calling DiscardChanges() in your UpdatePersonalInfoOperations_Inserting method.  The result properties are still serialized to the client on the record.

Conclusion

So you can see, even though LightSwitch doesn’t support executing stored procedures out of the box, there are plenty of hooks that allow you to invoke the stored procedures you need to create your application.

I have uploaded this example application in both VB and C# to the MSDN Code Gallery: https://code.msdn.microsoft.com/Executing-a-Simple-Stored-b43fe7e5.

Eric