jQuery Library for SharePoint Web Services (SPServices) 2014.02 Released

SPServicesJust in time for the holiday gift-giving season, I’m releasing SPServices 2014.02. This is the second release in 2014 (which you should be able to glean from the release name). If you’re using an earlier version of SPServices, I strongly recommend an upgrade. Read on.

The most important change in this release is due to an egregious error on my part that goes way back to 2013.01. Paul Tavares (@paul_tavares) spotted quite a while back and I was just too dumb to realize how important it was to fix. The net effect of my mistake was that SPServices was always caching requests, regardless how you set cacheXML. On pages where we simply called SPServices a few times on page load, it usually wouldn’t make much of a difference, but a little more memory might be required for the browser. However, in things like Single Page Applications (SPAs) which use SPServices for the data transport layer (See my blog post series: Single-Page Applications (SPAs) in SharePoint Using SPServices), it could make a *huge* difference. It effectively meant that for every unique request, we were caching data whether we should or not. Over a long page lifespan, that could add up to a lot of memory eaten up. Bad news. All better now.

I found out over the last few months the insidious ” Required Field” issue that I thought I had fixed completely in 2014.01 wasn’t totally fixed. For folks on SharePoint 2010 who applied last December’s CU, the markup in the DOM was a little different than the fix I had put into 2014.01. (See: Office 365 Update Changes ‘Display Name’ on Required Fields) This *should* be fixed for everyone now. Please let me know if you see any issues going forward. And Microsoft, please don’t do that again.

There is a handful of new operations in this release, added due to user requests:

  • WebPartPages.SaveWebPart2
  • RecordsRepository.GetRecordRouting
  • RecordsRepository.GetRecordRoutingCollection
  • RecordsRepository.GetServerInfo
  • RecordsRepository.SubmitFile

Finally, I recently moved my SPServices development repository over to Github at sympmarc/SPServices. I’m still getting my feet wet with Github (See: SPServices and Github – This Time I Mean It), but I plan to have my most current work available there going forward. I’ll still be posting the releases over on the Codeplex site, and I’ll monitor the issues there as well. I’m hoping that by using Github, we’ll have more people contributing to SPServices. It’s always been a community-driven project, but I’d love to get more direct contributions.

This release will be, as all of the recent releases have been, available on cdnjs as soon as possible. If you’d like to serve up SPServices from a CDN, cdnjs is the place to get it. cdnjs hosts a lot of JavaScript libraries that don’t have enough coverage to interest the big boy CDNs, so check it out in any case.

Finally, I want to thank Paul Tavares again for his help with SPServices over the years and with this release in particular. Both he and Josh McCarty (@joshmcrty) have also been trying to help get me over onto Github for a long time, but my thick skull just hasn’t gotten it before. I’m using Jetbrains Webstorm as my IDE these days and the Github integration there has finally made Github make sense to me. As we say here in Massachusetts, “light dawns on Marblehead“.

As usual, there are also a number of additional changes to fix existing bugs or improve efficiency (yes, I’m still able to improve on my old code, and I expect that will continue).

You can see the full list of enhancements and improvements on the download page. Note the link to the Issue Tracker items for this release. For posterity, here are links to the release notes showing all the fixes and improvements from the Issue Tracker on Codeplex.

New Functionality

Issue Tracker Item Function Description

 

New Operations

Web Service Operation Options MSDN Documentation Issue Tracker Item
WebPartPages DeleteWebPart pageUrl, storageKey, storage WebPartPagesWebService.DeleteWebPart Method 10273
WebPartPages SaveWebPart2 pageUrl, storageKey, webPartXml, storage, allowTypeChange WebPartPagesWebService.SaveWebPart2 Method 10273
ALPHA6 RecordsRepository GetRecordRouting recordRouting RecordsRepository.GetRecordRouting Method 10257
RecordsRepository GetRecordRoutingCollection NA RecordsRepository.GetRecordRoutingCollection Method 10257
RecordsRepository GetServerInfo NA RecordsRepository.GetServerInfo Method 10257
RecordsRepository SubmitFile fileToSubmit, properties, recordRouting, sourceUrl, userName RecordsRepository.GetRecordRouting Method 10257

 

Bug Fixes and Efficiency

Issue Tracker Item Function Description
10267 $().SPServices.SPComplexToSimpleDropdown Possible bug in SPComplexToSimpleDropdown
10253 $().SPServices.SPFindMMSPicker SPFindMMSPicker missing from 2014.01
10279 $().SPServices.SPGetListItemsJson SPGetListItemsJson Doesn’t Handle Attachments Correctly
10284 $().SPServices.SPFilterDropdown SPFilterDropdown Not filtering dropdown column.
10272 $().SPServices.SPGetCurrentSite $().SPServices.SPGetCurrentSite Documentation
ALPHA5 10277 $().SPServices.SPGetCurrentUser fix for SPGetCurrentUser at webUrl /
10248 $().SPServices.SPGetCurrentUser Trouble with SPSservices and Sharepoint Form
10265 $().SPServices.SPGetCurrentUser $().SPServices.SPGetCurrentUser isn’t returning ID
10254 $().SPServices.SPDisplayRelatedInfo SPDisplayRelatedInfo – DIV named improperly with Required field
10256 $().SPServices.SPCascadeDropdowns SPCascadeDropdowns Required Lookup issue
10262 $().SPServices.SPComplexToSimpleDropdown SPComplexToSimpleDropdown – required fields get renamed without the ‘Required Field’ appended to the field name
10146 $().SPServices ResolvePrincipals with addToUserInfoList=true requires SOAPAction
10271 $().SPServices.SPGetListItemsJson SPGetListItemsJson not using defaults.webURL
10283 $().SPServices.SPGetListItemsJson CAMLViewName not working?
ALPHA7 10182 $().SPServices async on version 2013.01 and caching
10298 $().SPServices GetTermSets argument names are slightly wrong
10299 $().SPServices WebUrl not working

Using the Signature Pad jQuery Plugin with SharePoint & InfoPath

Have you ever needed to capture signatures in SharePoint forms? What about InfoPath forms? I’m betting many people have seen a need to do this but have balked at the cost or complexity of the available solutions.

A client of mine named Cody Sellers (@codyjsellers), who works for Mercom Corporation had just such a need. Mercom is a smallish company that didn’t want to spend tens of thousands of dollars on a “real” eSig solution. Cody did some research and found a great jQuery plugin and turned to me for help implementing it. In this case we’re working with SharePoint 2013 on premises, but this should work with any version of SharePoint with some modification.

2014-06-18_13-38-20

The Signature Pad plugin comes from a clearly smart guy named Thomas J Bradley. Based on the work I’ve done with it so far, it’s well written with good documentation. Even better: it just plain works.

Signature Pad: A jQuery plugin for assisting in the creation of an HTML5 canvas based signature pad. Records the drawn signature in JSON for later regeneration.

The plugin allows you to capture signatures based on typed or drawn input and can be saved as JSON or a PNG image.

In our case, we wanted to be able to add a signature block at the bottom of multiple InfoPath forms. To make this work well, we decided that we would add the script into the master page. Yes, that may seen foolhardy, but a large majority of the work that is going to be happening in this Site Collection is filling out these forms.

Because of this, we needed a clear convention to follow in every form so that we could locate all of the signature fields (some forms have more than one) and add the signature pad capability reliably.

One of the hardest things about working with InfoPath forms client-side is that there are almost no sensible hooks in the emitted DOM. Everything is a .NET-like element id, like

ctl00_ctl33_g_3782ce51_9259_4854_80a0_e6355e54b690_FormControl0_V1_I1_T6

Since those ids can change anytime you change the form, you really want to give yourself something more solid to hook into. (At least we know that InfoPath won’t change anymore and the basic form elements are constant!)

To ensure that we could easily add the signature pad to any existing signature fields, we wrapped each signature field in an InfoPath section with its ScreenTip set to “==Signature==”.

InfoPath section with its ScreenTip set to ==Signature==

InfoPath section with its ScreenTip set to ==Signature==

The logic works like this:

  • Check to see if there’s a div with its id ending in ‘XmlFormView’ – this is the container for an InfoPath form. If there isn’t one, do nothing.
  • Find sections in the form that have their ScreenTip set to “==Signature==”. Sections have a fieldset container, and the title is set to the ScreenTip value. In other words, any section with its ScreenTip set to “==Signature==” will be treated as a signature area by the code.
  • Find the input element inside that section. This is the field where we want to store the JSON representation of the signature.
  • If the input element has no value, render the signature pad for signing (new forms)
  • If the input element already has a value, show the signature it contains (edit and display forms)

We decided to store the JSON representation of the signature in a field in each InfoPath form. Since the JSON represents the vectors from an HTML5 canvas, it’s a nice, standard way to store it. Images would require some separate repository or further encoding to be stored in a text field. Since the plugin can both emit and reconstitute the JSON into a signature, it’s a good way to go.

We ended up with the code below for the simplest case. (It’ll get more complicated as we get into the business rules, but this post is about the technology to capture and display the signatures.) When we create a new item in the newifs.aspx form, the Signature column will be empty and thus we will show the signature pad. If there’s already a value in the field, then we’re on the edit or display form, and signing has already happened so we just display the signature we have.

I’ve added comments that hopefully make the code simple enough to follow. As with all code you read on the Web, this isn’t just a drop-it-in-and-it’ll-work thing – you’ll end up tailoring it for sure. (One would think I wouldn’t need these caveats, but…)

$(document).ready(function() {
    // Find the guts of the InfoPath form in the page
    var infoPathContainer = $("div[id$='XmlFormView']");
    // if there's no InfoPath form, then we have nothing to do here (escape early)
    if (infoPathContainer.length !== 0) {
        setupSignatures(infoPathContainer);
    }
});
// There's an InfoPath form in the page, so look for signature fields and set them up
function setupSignatures(infoPathContainer) {
    // The Signature "signature" in the form. This makes it easy to select the proper form elements
    var signatureSignature = "==Signature==";
    // The signature field should be inside a section with its tooltip=signatureSignature
    var signatureContainer = infoPathContainer.find("fieldset[title='" + signatureSignature + "']");
    // The Signature field is the lone input element in the section
    var signatureBox = signatureContainer.find("input");
    // We may have multiple signature fields in the form
    signatureBox.each(function() {
        var thisSignatureBox = $(this);
        // We need a reference to the fieldset which represents the section several times
        var thisSignatureFieldset = thisSignatureBox.closest("fieldset");
        // Clean up the display by hiding the field we're using to store the JSON
        thisSignatureBox.hide();
        // The signature data is the value of the signatureBox
        var signatureData = thisSignatureBox.val();
        // If there's no signature yet...
        if (signatureData === "") {
            // Add the appropriate markup to the page
            thisSignatureBox.before(buildSignatureBox());
            // Bind to the click event for the 'Ready to Sign' button
            thisSignatureFieldset.find(".signature-ready").click(function() {
                $(this).toggle();
                $(this).next("div").toggle();
            });
            // Activate the signature pad in drawOnly mode
            var signatureArea = thisSignatureFieldset.find(".signature-box").signaturePad({
                drawOnly: true,
                lineTop: 125,
                output: thisSignatureBox,
                onBeforeValidate: function(context, settings) {
                    thisSignatureBox.focus(); // Needed to fire the change events bound to the field
                    thisSignatureBox.blur(); // Needed to fire the change events bound to the field
                    thisSignatureBox.hide(); // In case it becomes visible again
                }
            });
            // When the user clicks the button below the signature pad, validate
            thisSignatureFieldset.find(".signature-done").click(function() {
                thisSignatureFieldset.find("p.error").remove();
                signatureArea.validateForm();
            });
            // If we already have signature data, just show the existing signature
        } else {
            // Add the appropriate markup to the page
            thisSignatureBox.before(buildSignatureDisplay());
            // Activate the signature pad in displayOnly mode
            thisSignatureFieldset.find(".sigPad").signaturePad({
                displayOnly: true
            }).regenerate(signatureData);
        }
    });
}
// Function to emit the markup for the signature pad in signing mode
function buildSignatureBox() {
    var signatureBox = "<div class='signature-box'>" +
        "<input class='signature-ready' type='button' value='Ready to sign'/>" +
        "<div style='display:none;'>" +
        "<ul class='sigNav'>" +
        "<li class='drawIt'><a href='#draw-it'>Sign Here</a></li>" +
        "<li class='clearButton'><a href='#clear'>Clear</a></li>" +
        "</ul>" +
        "<div class='sig sigWrapper'>" +
        "<canvas class='pad' width='700' height='150'></canvas>" +
        "<input type='hidden' name='output' class='output'>" +
        "</div>" +
        "<input class='signature-done' type='button' value='Capture signature'/>" +
        "</div>" +
        "</div>";
    return signatureBox;
}
// Function to emit the markup for the signature pad in display mode
function buildSignatureDisplay() {
    var signatureDisplay = "<div class='sigPad signed'>" +
        "<div class='sigWrapper'>" +
        "<canvas width='700' height='150' class='pad'></canvas>" +
        "</div>" +
        "</div>";
    return signatureDisplay;
}

Here are some screenshots from our proof of concept:

The form when it loads

The form when it loads

Ready to sign

Ready to sign

Signed

Signed

Signature displayed on the display form

Signature displayed on the display form

Snippet of the data that is stored for a signature

Snippet of the data that is stored for a signature

SPServices Stories #21 – Redirect If User Clicked a Button Previously

This entry is part 22 of 21 in the series SPServices Stories

Introduction

teylynIngeborg Hawighorst (@IngeborgNZ) is a long-time SPServices user who has come up with any number of intriguing uses for the library. I’d recommend her blog anytime if you’d like to learn about interesting things you can do with SharePoint, but even more so if Excel is your bag. Ingeborg has been an Excel MVP for years running (see her profile on the MVP site). Some of the best solutions using SPServices come out of discussions in various SharePoint-oriented forums. In this case, Ingeborg spotted some suggestions from Eric Alexander (@ejaya2 aka PirateEric) and decided to build it out. Without further ado, here is Ingoborg’s article, reposted from her blog cheers, teylyn.

Redirect If User Clicked a Button Previously

I just came across this question in sharepoint.stackexchange.com. When a user visits a SharePoint site, they are presented with a splash screen and need to accept the policy before they can proceed. Upon subsequent visits, the splash screen does not show, because SharePoint will remember the  user. PirateEric outlined a possible solution: Use a SharePoint list to save the user name when the button is clicked. When the page loads, look up the user in the list. If they already exist, redirect the page, if not, show the splash page with the button to accept the policy. If the policy changes and users need to be made aware of that, simply remove all items in the list that tracks the users. All this can be done with jQuery and web services. That intrigued me and I had a go at actually building this, using Marc Anderson’s SPServices.

How to set it up

Create a SharePoint custom list with two fields, Title and UserName. The former is the out of the box field, the latter is a simple text field. Create two pages, the Splash page with the button and the page that is the desired destination page for all visitors. In my sample these are called Splash.aspx and MainContent.aspx On the Splash page the code that you can see below will be loaded before any other web part. If you use a Content Editor Web Part to load the code with a content link, make sure that it’s the first web part on the page. In many cases, JavaScript and jQuery will be placed in the last web part of the page and run after the DOM has loaded. But in this case this would mean that the Splash page appears briefly, even if it is followed by a redirect to a different page. The Splash page provides the policy (or terms and conditions) that the user must accept, and a link or a button that the user can click to accept. This link or button must then trigger a JavaScript function. That is very easy to do. I used a button and put the html straight into a CEWP like this:

<button onclick="PolicyButtonClick()" type="submit">
   I accept the policy
</button>

So the user clicks the button and the JavaScript function PolicyButtonClick() will run. This function can be found in the code below. First, the jQuery library and the SPServices library are loaded. Then the user name of the current user is retrieved with the SPServices call using SPGetCurrentUser. It returns a text string in the format DOMAIN\Account.  Next, the SPServices call uses the GetListItem. In the call, a CAML query is constructed that will return only list items where the column UserName equals the current user.  The items returned by that query are then counted. Since the user account is a unique value, we can safely assume that the query will either return one result or no result at all. If the query returned an item, this means that the user has previously accepted the policy and the script will redirect to the MainContent.aspx page.  If the query did not return anything, the current page will continue to be displayed. When the user clicks the button to accept the policy,  the user name is written into a variable. Then the SPServices operation to UpdateListItem is called and will create a new item in the list “PolicyAccepted”, storing the previously established account name in the column UserName. Then the MainContent.aspx page is loaded. The next time the user opens the Splash page, their account name will be found in the PolicyAccepted list and they will not see the Splash page again, unless the entry in the list is deleted. Here is the complete script:

<script type="text/javascript" src="/path/jquery-1.10.2.min.js" language="javascript"></script><script type="text/javascript" src="/path/jquery.SPServices-2013.02a.min.js" language="javascript"></script><script type="text/javascript">// <![CDATA[
// start the code even before the DOM is loaded, so not waiting for document ready
//$(document).ready( function() {
// get the user name
 var userName= getUserName();
// find the user name in the list
 var userAccepted = matchUserName(userName);
 if (userAccepted == 1 )
 {
 // redirecting page
 window.location.replace("http://path/Documents/MainContent.aspx");
 }
//});

function getUserName() {
 var thisUserAccount= $().SPServices.SPGetCurrentUser({
 fieldName: "Name",
 debug: false
 });
 return(thisUserAccount);
}

function createNewItem(theTitle, theUser) {
 $().SPServices({
 operation: "UpdateListItems",
 async: false,
 batchCmd: "New",
 listName: "PolicyAccepted",
 valuepairs: [["Title", theTitle], ["UserName", theUser]],
 completefunc: function(xData, Status) {
 }
 });
}

function matchUserName(userName) {
 var queryText = "<Query><Where><Eq><FieldRef Name='UserName'/><Value Type='Text'>" + userName + "</Value></Eq></Where></Query>";
 $().SPServices({
 operation: "GetListItems",
 listName: "PolicyAccepted",
 async: false,
 CAMLQuery: queryText,
 completefunc: function (xData, status) {
 itemCount = $(xData.responseXML.xml).find("rs\\:data, data").attr("ItemCount");
 }
 });
 return(itemCount);
}

function PolicyButtonClick() {
 var userName= getUserName();
 var theTitle= "Accepted";
 createNewItem(theTitle, userName);
 window.location.href = "http://path/Documents/MainContent.aspx";
}
// ]]></script>

The MOSS Show SharePoint Podcast: Episode 87 – Talking JavaScript with Marc Anderson

The MOSS ShowBack in late January, I sat down – in the virtual sense, as usual – with Hilton Giesenow (@hiltongiesenow or the slightly more active @TheMossShow) to have a chat about JavaScript for his MOSS Show SharePoint Podcast. At the time, we were in the throes of trying to figure out what had happened on Office365 with some breaking DOM changes. Breaking for us JavaScript folks, anyway. We covered a number of topics like improving the user experience in SharePoint, what’s been going on with JavaScript over the years in the SharePoint community, and more.

From Hilton’s intro to Episode 87 – Talking JavaScript with Marc Anderson:

The entire web development world seems to have had a love-hate-love-hate relationship with JavaScript over the many years of its existence, and it’s no different in the SharePoint world, albeit a few years behind in many cases. In this episode we speak with many-year industry veteran and long time SharePointer Marc Anderson about his experiences with JavaScript and SharePoint over the years, his wildly successful SPServices library, Single-Page Applications (SPAs) and lots more.

Head on over to Episode 87 – Talking JavaScript with Marc Anderson and have a listen.

2014-03-18_22-53-36

KnockoutJS with SharePoint: Fixing ‘Error: You cannot apply bindings multiple times to the same element.’

KnockoutJS LogoI’ve been using KnockoutJS to build functionality into SharePoint pages for a while now. (In case you’ve ever wondered, yes, it’s the same thing people mean when they simply say “Knockout” or “KO”.)

Setting everything up with KnockoutJS can take a bit longer than hard-wiring things with jQuery – depending on what you are trying to accomplish and what your background may be – but once it’s all in place, changes to functionality become much easier. Some people naturally think in the Model-View-View Model (MVVM) pattern, but it took some time for me to get my head around the idea. Early on it felt like not just a separation of church and state, but also separation of the apse from the nave and Arkansas from middle, lower Arkansas.

I’ve probably run into every newbie error in the book, and this one has gotten me multiple times.

Error: You cannot apply bindings multiple times to the same element.

Error: You cannot apply bindings multiple times to the same element.

The screen snippet above is from my favorite debugger, Firebug. The error message itself doesn’t give you much to go on. It makes basic sense, since multiple bindings on the same element would seem to be a bad idea, but it doesn’t tell you anything about why it’s happening or what you’ve done to trigger the error. It just kills the page load.

Let’s take a simple example. In one of the sets of pages I’m working on, we want to have a header section driven by one view model and a body section driven by another. The two bindings are in separate .js files because the header logic is reused across pages, while the body section is unique to individual pages. (We’re using SharePoint 2010 more as a back-end repository and identity management provider in this application and replacing virtually all the UI with custom pages.) Each of the .js files performs the binding for which it is responsible.

The markup – at a high level – looks something like this:

<div id="abc-page-header">
...
</div>
<div id="abc-page-body">
...
</div>

and the bindings occur in the JavaScript looking something like this:

ko.applyBindings(new HeaderViewModel(), document.getElementById("abc-page-header"));
...
ko.applyBindings(new BodyViewModel(), document.getElementById("abc-page-body"));

As you can see, each binding is scoped to the container for which it has responsibility. Using document.getElementById is straighforward: we should get a JavaScript object reference to the containing element with that id.

All well and good, right? The problem in this case comes in when you have no second argument, or even worse, a typo in the id. For instance, I ran myself silly with document.getElementById("ab-page-body"). Because the document.getElementById function returned null (the id wasn’t in the page), the binding occurred on the entire document, and therein arises the problem. Elements with data-bind now become bound twice, throwing the error.

It would be much better if the error told us a little more about what was happening, of course. For instance, the error might mention which binding is currently applied to the particular element where the issue arises. Even better would be some sort of warning when you attempt to apply bindings with a null parameter. Alas, this is not the case.

The simple fix is to find the place in your code where a ko.applyBindings is applied incorrectly. It’s not so hard if you know that’s the right thing to do. If you don’t, you may end up tearing down your code and starting afresh, which is rarely productive.

See Creating view models with observables for the [rather sparse] documentation on ko.applyBindings. Note that the second parameter must be a JavaScript DOM node, not a jQuery object. If you try to get fancy like this:

ko.applyBindings(new HeaderViewModel(), $("#abc-page-header"));

You’ll get a very clear error:

rror: ko.applyBindings: first parameter should be your view model; second parameter should be a DOM node

Error: ko.applyBindings: first parameter should be your view model; second parameter should be a DOM node

Moral of the story: always scope your bindings carefully!