HTML Upload Control For LightSwitch SharePoint Apps!

-(And it’s available through NuGet!)

For a while now I’ve been seeing quite a few requests from users for a simple, pluggable, HTML Control that can be used to upload files in a LightSwitch application.

What I’m going to do here is show you how you can use a NuGet package to add an HTML Control to a SharePoint enabled LightSwitch HTML Application.  This post is strictly for those LightSwitch apps that are enabled for SharePoint (also known as Cloud Business Apps now), but in a future post I do plan to do an HTML Upload Control for vanilla LightSwitch apps that aren’t enabled for SharePoint.

Here’s the breakdown on what we are going to do here:

  1. Create a SharePoint enabled LightSwitch HTML Application
  2. Add a simple table and screen
  3. Add a SharePoint List to our project
  4. Add a NuGet Package that I made to make it easier to create our upload control
  5. With the help of the NuGet package, and the SharePoint List, we can then make a screen with a simple upload control

Make a SharePoint enabled LightSwitch app

Launch Visual Studio 2013, and select “File –> New Project”. For this example we’ll use a “Cloud Business App” project. This will make us a SharePoint Enabled LightSwitch App.

image

My project is called “AllMyBooks”. As you might guess, I’m going to use this project to catalogue some books that I own.

I need some way to keep track of my data, so we’ll create a basic entity that will store some information about the books, and then a screen that will allow me to view, add, and edit the list of books (later on we’ll add a control to upload images of the books).

I’ve made an entity that has a few fields to track some data about the book. You’ll notice I have an “ImageUrl” field that we’ll use to track the actual location of the image that we’ll be uploading use the upload control later.

image

I’ll need a couple simple screens to view the data.  Nothing fancy, just a simple Browse screen, and an Add/Edit screen.

Right click on the Screens folder in your HTML Client project, and select “Add Screen…”. Add a Browse screen for the Book entity.  After you do this, in the screen designer, right click on the “Command Bar” and select “Add Button…”.  Then select “Choose an existing method –> Add/Edit”. This will allow you to then create a new Add/Edit screen for the Book entity.

For the Add/Edit screen, I’ve changed the layout a bit so that all the fields are in the “Left” row. And I’ve changed the “Image Url” field so that is of type “Web Address Viewer”. This will make the URL a clickable link.

image

Next we’ll want to add Custom Control to this screen.  We’ll come back to it later, but for now just add it by selecting the “New Custom Control” link in the drop down menu like so:  image

Select the default values for the custom control and hit OK. In the properties pane, change the display name to something like “Image Upload”. 

In the designer, navigate back to your Browse screen, right click on the Command Bar and add another button. Select “Choose an existing method” and select “View Selected”. This will allow us to View our record after creating it. 

This isn’t required, but I’m going to make one small change to the View screen, to make it look a bit cooler. Drag and drop the “ImageUrl” field onto Rows Layout – left. So you should have two “Image Url” fields now.  One will just be the plain URL of the image. The other is going to actually be an image.  You can accomplish that by switching it’s type to “image” like so:image

 

We should have our basic screens done now, so let’s move on to adding the SharePoint List to our project.

Add a List to our SharePoint Project

Adding a SharePoint List is pretty straightforward and useful for all types of scenarios. We’re going to add a Document Library List to our SharePoint project which is where all our “uploaded” images will actually be stored (you can store almost any type of file into a Document Library, but for this example I’m storing images).

To get started, in the Solution Explorer, right click the SharePoint project and select “Add –> New Item –> List”. I’m calling my list “BookList”. The name is important, and we’ll need to remember it for later.

You should be prompted to select what type of list you want. Select “Document Library” for the type.

image

As the name implies, Document Libraries are perfect for storing almost any type of file in SharePoint. 

Now that we’ve added it to the project, we can move onto adding our NuGet package.

Add the NuGet package

You can find the NuGet package here – LightSwitch SharePoint Upload Control. (Hopefully by the time this blog goes live, you should be able to find the package by navigating to Tools –> Library Package Manager –> Manage NuGet Packages, and then searching online for it).

If you can’t find the package online, you can download it from the above link, and then tell the NuGet Package Manager where to find it on your machine. Just navigate to Tools->Options->Package Manager->Package Sources. And add an entry for where the NuGet package can be found (e.g. c:\Documents\Downloads).

When you install the package, make sure it’s only installed for the HTML Client project, like so:

image

This NuGet package has 2 JavaScript files that are added to your HTML Client “Scripts” folder. This 2 files have all the code you need to handle uploading and interacting with the SharePoint Document Library list we added earlier.
At this point we just need to “plug” this code into our LightSwitch project.

Write a couple lines of code

Before we can add the code to our custom control, we’ll need to let the default.htm file know where to find these 2 new JavaScript files we’ve added.

In the solution explorer, under your HTML Project, open up the default.htm file, and right below the “<script>” entry for the globalize.min.js file, add these 2 lines:

 

     <script type="text/javascript" src="Scripts/SingleUpload.js"></script>
     <script type="text/javascript" src="Scripts/sharepoint.js"></script>
 
 

Almost there, now we need to update our custom control. So open up the screen designer for the Add/Edit screen we made earlier.

Select the “Custom Control” field on the screen.

Under the properties click the “Edit Render Code” link –>image

This will bring us into the code editor for the render method. This method is called to handle “rendering” this custom control on our HTML screen.

My code for this method looks like so:

 

 /// <reference path="../GeneratedArtifacts/viewModel.js" />
/// <reference path="../Scripts/SingleUpload.js" />

var myUpload;
myapp.AddEditBook.ScreenContent_render = function (element, contentItem) {
    // Write code here.
    myUpload = new SingleUpload(element, "BookList");
};
 
 

 

You can see that I added a “<reference path>” at the top of the file to the SingleUpload.js. This isn’t essential, but I do this to enable intellisense for all the methods and variables that exist in the SingleUpload JavaScript file.

The rest of the code is pretty simple, I’m creating a new “instance” of the SingleUpload “class”, and storing that  in my global variable: “var myUpload”. All I have to pass into SingleUpload() is the current HTML element so that the upload control can be added, and the name of the SharePoint list that we created earlier, which is “BookList”.

On a later post I’ll go over in detail what is happening inside this SingleUpload JS file, but for now just understand that it handles creating the basic HTML control and uploading files to SharePoint’s document library.

One last line of code to write, I want to automatically save the URL of the file we are uploading to the Book.ImageUrl field on my entity. This is easy to accomplish by overriding the “beforeApplyChanges” method for our Add/Edit screen like so (paste this into the same JS file as the render method above):

 

 myapp.AddEditBook.beforeApplyChanges = function (screen) {
    // Write code here.
    // get sp document URL from here
    if (myUpload._fileUrl) {
        screen.Book.ImageUrl = myUpload._fileUrl;
    }
};
 
 

This is a simple method that first verifies that the “_fileUrl” property exists. It may not exist, for example, if we didn’t upload an image. Next we take that URL and store it in the Book.ImageUrl field for this new record we are creating.

GO!

That is that. Now it’s time to “F5” the app and see how it looks in SharePoint at runtime.

(After the app launches the first time it sometimes needs around 20 extra seconds to finish “loading” and initializing the document library list that we added earlier. Otherwise you might get an error when trying to upload a file.)

Now let’s make a record and try everything out.

Click the “Add Book” button to launch the Add/Edit screen. At this point you can fill out some basic information about the book. You’ll see the custom control at the bottom, and it should look like a familiar Browse Files control you’ve probably seen elsewhere.

Once the upload starts you’ll see a message - “Upload has started, please be patient” (uploads can take a while for very large files). During this process, the file is being added to the Document Library. And after it’s completed, and we save, we will store the direct URL to the entry in the Document Library.

And once it has completed, you can save out the record.

You’ll remember that when the record is saved, we also added code to save the URL of the Document Library into our ImageUrl field. You can now view this URL by selecting the record in our list and pressing “View Book”.

And of course the link will re-direct you right to the Document Library entry that contains the image file we uploaded.

 image image

Hope you like it! – Let me know if you have any feedback below.

Thanks – Matt Sampson -

Contact info: Tweet @Me