Welcome back to my continuing series on SharePoint development!

If you’ve been following along with lesson one and lesson two then this post has probably been a long time coming, but we’re now at the point where we’ve built a pretty useful tool for calculating shipping costs, and we’ve integrated it into our existing SharePoint site to make it easily accessible to everyone in our team who might benefit from it.

Here’s the thing, though. If your organization is anything like mine, then SharePoint is a tool that they’ve made available to everybody. You’re using it for some cool stuff, but writing code probably isn’t your day job – you’re the techy guy or gal in your group who’s found an opportunity to make everybody’s life a little easier with technology, and the beautiful part is that you can do it all without needing to engage your company’s IT team (who are busy with large-scale projects involving a contribution to your company’s bottom line, which your idea for a shipping calculator would need to be prioritized against).

There’s nothing wrong with any of that. Something like this really shouldn’t be a thing that your company’s IT team get involved with in the exact same way that helping you craft an especially complex excel formula shouldn’t be a job for them either. If you’ve ever crafted an especially complex excel formula in a workbook that’s shared throughout your group though then you may already have identified the downside to this approach: things change.

Our tool is built on a fixed model for calculating shipping costs of $19.99 for the first 20lbs and $3 for every 5lbs (or part thereof) over and above that. That rule is embedded within your code now, you’re the only one around with the necessary technical knowledge to update it when shipping costs change, and you have a day job to worry about too. If updating SharePoint tools is not how you like to spend your weekends, then we need a different approach.

What we need, then, is a solution where the average SharePoint user can make changes to key pieces of data, and our tool needs to be smart enough to read that data so that it can be used in calculations. And, while we’re at it, let’s expand the tool so that it can handle a few different shipping profiles (which could represent different couriers or, in our example, destinations).

Enter the SPServices library. SPServices is a jQuery plugin that’s used to expose SharePoint data to our jQuery apps, including (amongst other functions) reading from and writing to SharePoint lists in SharePoint 2007, 2010 and 2013.

This is a significant step up from where we were at the end of lesson two (which is probably why I’ve been procrastinating over writing it for so many weeks). I’ve split it into parts. Today we’re going to set the stage and prepare our data, and this time next week (I promise!) we’re going to get our hands dirty with some code.

Nevertheless, both this post and its successor are probably going to be longer than those that have gone before, so be forewarned, go grab yourself a cup of coffee, and let’s dive in!

Creating the List

First things first, we need a list to hold our data. This list is where our less-technical colleagues will come when changes need to be made and we’ll keep it fairly straightforward.

Much like we did to create our document library in lesson one, go to Site Actions > View All Site Content and hit the Create button. This time we’re going to choose Custom List as the type of entity we’re going to create. We need to give the list a name, so let’s call it “Shipping Prices.” For the time being we’ll leave the description blank, and we’ll hide our list from the Quick Launch bar. We can always change these options later.

When you hit the Create button the list will be created and will have a single column (“Title”). We need to add a few more columns, so choose List Settings from the toolbar or the Actions menu (depending on your version of SharePoint). The first thing we’re going to do is rename the “Title” column to “Province” by clicking it in the list, then we’re going to add four more columns by clicking the Create Column link and adding them one by one. Here’s where we want to end up:

An Important Note Regarding Column Names

With this the basic framework for our data is in place. You may notice that none of our column names have spaces in them. That’s because SharePoint in the backend does strange things with spaces. As you’ll see later we can programmatically read from a column called “BasePrice” by referring to it exactly in that way, whereas a column called “Base Price” would need to be referred to in our code as “Base_x0020_Price.”

That being said, we can leverage a bit of trick here if want to improve readability for people who will interact with this list directly (our less-technical colleagues, remember). Behind the scenes (and in our code) SharePoint will always know the column by its original name, even if it’s subsequently been renamed. If we go back and spaces now, the internal name of the “BasePrice” column will remain “BasePrice,” even if its display name is changed to “Base Price.”

This is helpful in this scenario, but can easily be a bit of a gotcha – you need to remember the original name of all your columns, because that’s how your code will reference them. Remember the “Title” column we renamed to “Province?” It’s still “Title” behind the scenes.

Populating the Data

There are many ways to get data into a SharePoint list, and I’m not going to go into a great amount of detail here. You can add each item row by row with the built-in list forms, you can use SharePoint’s datasheet view to edit many rows at once, or you can use a third party tool. Our example is probably a little basic to warrant breaking out a special third-party tool for, but nevertheless as you do more complex stuff in the future I’m a fan of SharePoint List Item Editor. It does exactly what its name suggests, gives you a spreadsheet-like interface for editing items in SharePoint lists, and makes it easy to copy and paste many rows at once.

Regardless of how we do it, here’s the data I’m going to put into my list for the purposes of this example.

With this data in place you’re probably starting to get a sense of where things are going with this example. The BasePrice is the cost of shipping the first BaseWeight pounds, and the AdditionalPrice is the cost of each AdditionalWeight pounds or part thereof.

In many ways it’s no different from what we’d created by the end of lesson two, but with one critical difference – none of these variables are going to live in our code anymore. They’re all factored out into the list where they’re easily editable when things need adjusting in the future.

Find The GUID of the List

Everything we’ve done so far is fairly standard SharePointy stuff, but you’ll notice we’ve had one eye on the end goal of programmatically interfacing with this data throughout. Finding the GUID of the list we’ve created is an important step in this process.

A GUID is a globally unique identifier, and every SharePoint list (or calendar, or document library, etc) on our SharePoint site collection has one. There are several ways we can connect our front-end custom interface to our back-end data, but the GUID is probably the most reliable because as the name implies, it’s globally unique. It’s also not affected if our list gets renamed later.

There are several ways to find it, but my favourite is to use a simple tool I found for the purpose. Open the app and plug in the URL of your SharePoint site. Hit the Display List Titles and IDs button, and grab the relevant ID (including the opening and closing braces).

For me {4883AC18-E2A5-4EAF-8446-23B15B43861A} is what I need. For you it will be different. You may notice that the tool can also find the GUID of a list view. We don’t need this because we’re going to use the default view. I’m not going to get into it right now, but if you’re unfamiliar SharePoint views define things like the sort order and filter that’s applied to a list, and each list can have multiple views defined. If you want to programmatically access data that’s filtered out of your default view then the simplest method is probably to create a new, unfiltered, public view and reference it by its GUID in your code. The documentation for SPServices will tell you more.

…and Talking of SPServices

Now is probably a good time to download the library and place the minified javascript file in the “web” document library we created in lesson one, in the “js” subfolder alongside the jQuery library that’s already there. At the time of writing this file is called jquery.SPServices-2014.01.min.js. With that our stage is set and we’re ready to rewrite the code in our content editor web part to interface with it, but that was a lot to take in so we’ll get to that next week.