For years people have been asking me how they could upload files using SPServices. I’ve dodged the questions every time because I simply didn’t know how.
On a current client project, I’m building a slick Single Page Application (SPA) to manage tasks in SharePoint 2010. It’s basically a veneer over the clunky out-of-the-box task list experience. Rather than hopping from page to page, the team using the application can accomplish everything they need to do on a single page.
Every project has specific needs, and for this one I’m using KnockoutJS. But the code snippets I give below are generic enough that you should be able to use them in any context with a little thinking.
It’s been going well, but I had been putting off implementing adding attachments because…well, as I said, I didn’t know how.
In this case, there were two excellent posts, one from James Glading and one from Scot Hillier. (See the Resources section below for links.)
The first step is to enable HTML5 capabilities in IE10. This requires two small changes to the master page. This seems simple, but it can have effects that you don’t expect. In other words, don’t consider this just a “no brainer”. You need to plan for the change across your Site Collection and any impacts it may have.
The first change is to switch from using “XHTML 1.0″ to “HTML” as the DOCTYPE. This is what “turns on” HTML5.
Then, in this project we set the content meta tag to IE=10 because we want to aim for IE10.
If your browser base is different, you can, of course, set this differently. In this project, we will require all users of the application to be running IE10 or greater. Firefox and Chrome have supported the bits of HTML5 we need for so long, that there’s little concern about people who choose to use those browsers.
Once we have those two small changes in the master page (we are using a copy of v4.master with no other customizations at the moment), we “have HTML5″. It’s most obvious because some of the branding flourishes I’ve put in like rounded corners show up in IE10 now, rather than just square boxes.
Once we have HTML5 enabled, we can start to use the File
API, a.k.a. the FileReader. This is such a simple little thing, that it’s hard to believe it gives us the capability it does.
That’s it. That simple HTML gives us a file picker on the page. Depending on your browser, it will look something like this:
When you make a file selection with this very familiar widget, you can query the element using jQuery.
Note that we’re after a single file, so we grab the first object in the file list array. We get an object that looks something like this screen shot from Firebug:
Once we have the file object, we can look at what the Lists
SOAP Web Service needs to get in order to upload the file. Again, it’s pretty simple. Here is the list of inputs and output from the MSDN documentation page for the Lists.AddAttachment
The first three inputs are straightforward. We pass in the name of the SharePoint list, the ID of the list item, and the name of the file we want to attach. It’s that last input parameter called “attachment” that’s a bit tricky.
When we upload a file via an HTTP POST operation – which is what all of the SOAP Web Services use – we have to pass text. But the files we want to upload are as likely as not to be binary files. That’s where the Base64 format comes in. Believe me, you don’t need to know exactly what the format actually is, but you should probably understand that it enables us to send binary files as text bytes. Those bytes are then decoded on the server end so that the file can be stored in all of its original, pristine glory.
Here’s the code I ended up with, skinnied down as much as possible to make it a little clearer to follow. I draw heavily from Scot and James’ posts for this, but nuanced for SPServices. I’ve also stripped out all of the error handling, etc.
- First, the getFileBuffer function reads the contents of the file into the FileReader buffer. readAsArrayBuffer is an asynchronous method, so we use a jQuery Deferred (promise) to inform the calling function that the processing is done.
- The contents of the buffer are then converted from an ArrayBuffer – which is what the FileReader gives us – into a Base64EncodedByteArray. This works by passing the buffer through a Uint8Array along the way.
- Finally, we use the toBase64String method to convert the SP.Base64EncodedByteArray to a Base64String.
Yeah, that’s a lot to swallow, but again, you don’t really need to understand how it works. You just need to know that it does work. See http://en.share-gate.com/?utm_source=OnlineAdvertising&utm_medium=Winter13&utm_campaign=SharepointAds
Finally, we call Lists.AddAttachment using SPServices to do the actual upload.
Very cool! And as I tweeted yesterday, far easier than I ever would have expected. Yes, it took me a good chunk of a day to figure out, but it definitely works, and pretty fast, too.
If you use this example as a base, you could fairly easily build out some other file uploading functions. Combined with the other attachment-oriented methods in the Lists Web Services, you can also build the other bits of the attachment experience:
- GetAttachmentCollection – Returns a list of the lit item’s attachments, providing the full path to each that you can use in a list of links.
- DeleteAttachment – Once you’ve uploaded an attachment and realized it was the wrong one, this method will allow you to delete it.
Moral of the story: Fear not what you do not know. Figure it out.
What’s the Story for HTML5 with SharePoint 2010? by Joe Li
Uploading Files Using the REST API and Client Side Techniques by James Glading
Uploading Files in SharePoint 2013 using CSOM and REST by Scot Hillier
This article was originally published in Marc Anderson's blog: http://sympmarc.com/2014/05/27/uploading-attachments-to-sharepoint-lists-using-spservices/