Welcome back to my ongoing series on SharePoint development!
I promised last week that Iād follow up lesson three within a week, so here we are! In that previous lesson everything we did was in relation to setting the stage for what weāre going to tackle today, so Iāve got no doubt that youāve been waiting with barely contained anticipation to get back to writing some code.
Because all the steps from last week were fairly standard SharePoint stuff, if youāre pretty familiar with the platform you may well have skimmed through it. Thatās fine, but for everything we do today to be successful weāre going to need to make sure that:
- Weāve created and populated a list of shipping prices, with different shipping profiles (in our example, these different profiles are based on destination).
- Uploaded the SPServices library minified javascript to our āwebā document library.
- Located and noted the GUID of the shipping prices list, so that we can programmatically reference it in our code.
With those steps done everything is in place, so letās not waste any more time!
The HTML
The HTML portion of our code hasnāt changed very much since we wrote it way back in lesson one, and it doesnāt change much today either. That being said, we do have an additional option that forms part of our calculation this time around, so weāll add a form element for that.
Destination province:
Please wait, loading data...
Item weight:
lbs
Shipping cost: $0
As you can see, weāve added a drop-down menu that allows for the selection of the destination province. In the HTML it has a single entry in the list that says āPlease wait, loading dataā¦ā As you might anticipate, weāre going to remove this option later on and replace it with the actual choices, but itās probably good practice to have something there because the SPServices library is going to read from our list with an AJAX HTTP request ā in other words the page will load first (with our āplease waitā message), and the data to populate the list will be loaded afterwards. Hopefully it will all happen so fast that nobody ever really sees the āloadingā message, but you never know.
The JavaScript
OK, now weāre really going to start getting into some changes in functionality! First things first, though. We need to include the external libraries weāre going to be using. jQuery has been there from the start of our journey, but SPServices is new for today.
/web/js/jquery-1.11.0.min.js
/web/js/jquery.SPServices-2014.01.min.js
The other thing Iām going to do at the beginning of my main block is declare a global variable in which to store list data. There are probably better approaches than this, but for the sake of keeping my code relatively simple this is one Iām taking.
var shippingData = false;
Loading Data from our SharePoint List
Next is where the SPServices magic happens. Immediately inside our jQuery document ready function weāre going to call SPServices and grab the data from our list, putting the result of that request inside our shippingData variable. SPServices has many available options that get passed as an object to its main function and more details can be found in the documentation on their website. Like I said though, Iām keeping things simple:
$().SPServices({
operation: 'GetListItems',
listName: '{4883AC18-E2A5-4EAF-8446-23B15B43861A}',
completefunc: function(xData, Status) {
if (Status == 'success' && ($(xData.responseXML).find('ErrorCode').text() == '0x00000000' || $(xData.responseXML).find('ErrorCode').text() == '')) {
shippingData = $(xData.responseXML).SPFilterNode('z:row');
populateDropdown();
} else alert('Something went wrong!');
}
});
Not bad, eh? Ten lines of code and weāve read all the data from our SharePoint list. Letās look at what weāve done in a bit more detail.
The code weāve written can be summarized as:
$().SPServices(obj);
All weāre doing is calling the SPServices plugin and passing in a javascript object that contains all the options it needs to understand what we want it to do. There are many options we could pass to it, and youāll find more detailed documentation on the SPServices homepage. Iāve kept things as simple as possible and passed in the bare minimum.
Operation: āGetListItemsā
In our example weāre dealing with items in a list. GetListItems is the operation we need to read data from a SharePoint list into our webapp. There are many other types of operation related to lists that SPServices could do for us ā creating entirely new lists, adding or removing list fields, deleting lists, etc. Essentially almost anything you could do manually on SharePoint could be done programmatically with SPServices. If we wanted to write data back to a list then UpdateListItems would be the operation weād use.
ListName: '{4883AC18-E2A5-4EAF-8446-23B15B43861A}'
The ListName parameter could take one of several formats. A simple string containing the name of the list will work, but to avoid any kind of confusion between similarly named lists my preference is to pass in the GUID of the list. Remember that the GUID of your list will be different to mine. SPServices can also take a WebURL parameter that tells it which site in your SharePoint collection the list can be found on, but since weāre using a GUID thatās unique across all sites in the collection we donāt need that.
completefunc:Ā function(xData, Status)
This is where the real magic happens. The completefunc parameter represents a callback function that SPServices executes once data has been loaded, and it takes two parameters: xData and Status.
Our completefunc does some basic error handling, and then calls another function to do the dirty work.
if (Status == 'success' && ($(xData.responseXML).find('ErrorCode').text() == '0x00000000' || $(xData.responseXML).find('ErrorCode').text() == ''))ā¦
For the Status parameter thatās passed in to completefunc, weāre looking for it to contain a value of āsuccessā. We have to be a little careful about exactly what this means though: To SPServices success means that itās passed a query to SharePoint and received a response. It doesnāt mean that our query was well formed, or that we received any useful data back. Basically youāll always get a successful status unless SharePoint is down ā in which case our webapp probably wouldnāt be available to users anyway.
To check that our query has truly been executed successfully by SharePoint, we look in the responseXML for an error code. Depending on the version of SharePoint weāre running, that will either be 0x00000000 or blank.
shippingData = $(xData.responseXML).SPFilterNode('z:row');
There are few ways we could approach what happens next. My goal was to keep my code as simple as possible so Iām doing some things that may not be best practice. This is one of them: we take the data SPServices has returned and put it into a global variable.
The data SharePoint has passed back to us is in XML format and contains a wealth of information about our query, metadata about the response, and so on. We donāt really need any of this stuff ā we just want the data itself ā so SPServices has a function called SPFIlterNode that helps us filter the returned data down to what we actually care about. Weāre filtering here by z:row. Each z:row returned represents one entry from our SharePoint list.
populateDropdown();
Now that we have our data in a globally accessible variable, Iām outsourcing the processing of it to another function: populateDropdown. That last step for our completefunc is to call this function.
Populating the Dropdown List
OK! So now we have the data we need loaded from our SharePoint list and resident in memory (in our shippingData global variable) so that we can manipulate it and our users can interact with it. The first step of this process is to populate the relevant options into the select box we created in our HTML. Iām doing that (surprise surprise) with the populateDropdown function.
function populateDropdown() {
$('select#destination option').remove();
for (i = 0; i ' + $(shippingData[i]).attr('ows_Title') + '');
}
}
If you recall, the dropdown list initially contains a single option with the text Please wait, loading dataā¦. At this point in the story our data is loaded, so letās get rid of that option first:
$('select#destination option').remove();
Done! Good. The next step is to loop through each of the items weāve loaded into our shippingData variable, and add them as an option in the dropdown. We do this with a standard for loop:
for (i = 0; i
If youāre not familiar, this construct sets a variable i to zero, then loops through the following block of code multiple times, as long as i is less than shippingData.length, which is the number of items in our shippingData variable. On each iteration i is incremented by one (i++).
On each loop we add an item to our dropdown, using jQuery to append the relevant HTML. Based on the data that exists within our SharePoint list, we end up with these options in our dropdown:
Each $(shippingData[n]) has an attribute for each of the columns in our list. These attributes all have the prefix ows_, and, as mentioned in lesson 3, they are all referenced by the original name of that column (even if itās been renamed since it was created). Thatās why weāre using the attribute ows_Title to get at the data thatās in our Province column: the column was called Title when the list was created, and we renamed it.
Performing the Calculation
With any luck everything in our story up to this point will have happened in a split second, but regardless weāre now ready for user input. The user selects the destination province, inputs the weight of the item being shipped, and hits the calculate button.
The calculation itself is really no different from the one we built in lesson 1, the difference being that our variables are defined by the list data rather than hardcoded in.
We still identify that the Calculate button has been pressed through the use of the jQuery $(āinput#calculateā).click(function() {});, but our first step is now to set some variables based on whatever is selected in the destination province dropdown at the time.
bp = parseFloat($(shippingData[$('select#destination').val()]).attr('ows_BasePrice'));
bw = parseInt($(shippingData[$('select#destination').val()]).attr('ows_BaseWeight'));
ap = parseFloat($(shippingData[$('select#destination').val()]).attr('ows_AdditionalPrice'));
aw = parseInt($(shippingData[$('select#destination').val()]).attr('ows_AdditionalWeight'));
We set each of these variables by reading the relevant attribute (representing the column in our SharePoint list) from $(shippingData[n]), where n is the value of the destination dropdown, $('select#destinationā).val(). After that, itās business as usual:
var shippingcost = bp;
if ($('input#itemweight').val() > bw) {
shippingcost += (Math.ceil(($('input#itemweight').val() - bw) / aw) * ap);
}
$('span#shippingcost').html(shippingcost);
Putting it All Together
And weāre done! The completed code block ā including all the javascript and HTML ā that we copy and paste into our content editor webpart is as follows:
/web/js/jquery-1.11.0.min.js
/web/js/jquery.SPServices-2014.01.min.js
var shippingData = false;
$(document).ready(function() {
$().SPServices({
operation: 'GetListItems',
listName: '{4883AC18-E2A5-4EAF-8446-23B15B43861A}',
completefunc: function(xData, Status) {
if (Status == 'success' && ($(xData.responseXML).find('ErrorCode').text() == '0x00000000' || $(xData.responseXML).find('ErrorCode').text() == '')) {
shippingData = $(xData.responseXML).SPFilterNode('z:row');
populateDropdown();
} else alert('Something went wrong!');
}
});
$('input#calculate').click(function() {
bp = parseFloat($(shippingData[$('select#destination').val()]).attr('ows_BasePrice'));
bw = parseInt($(shippingData[$('select#destination').val()]).attr('ows_BaseWeight'));
ap = parseFloat($(shippingData[$('select#destination').val()]).attr('ows_AdditionalPrice'));
aw = parseInt($(shippingData[$('select#destination').val()]).attr('ows_AdditionalWeight'));
var shippingcost = bp;
if ($('input#itemweight').val() > bw) {
shippingcost += (Math.ceil(($('input#itemweight').val() - bw) / aw) * ap);
}
$('span#shippingcost').html(shippingcost);
});
});
function populateDropdown() {
$('select#destination option').remove();
for (i = 0; i ' + $(shippingData[i]).attr('ows_Title') + '');
}
}
Destination province:
Please wait, loading data...
Item weight:
lbs
Shipping cost: $0
Taking it Further
The next steps with our shipping calculator app would be to add some additional error-checking and handling, and maybe amend the code to avoid using unnecessary global variables. Iāve kept things as simple as possible here for the sake of example.
After that? As I mentioned earlier, thereās a lot of cool stuff we can do with SPServices. Where you go from here is really up to you, but hopefully you can see some possibilities. Even with the basic building blocks of reading from and writing to lists, itās possible to build some really cool stuff on top of SharePoint, possibly even taking the approach of using SharePoint as a database for a webapp that has its own look and feel.
Enjoy!
