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.

Welcome back to my series of posts on SharePoint development!

At the end of lesson one we’d used some basic HTML, javascript and jQuery skills to create a tool for calculating shipping costs, and we’re hosting the tool on our team SharePoint site so that everybody who needs it has access.

This is great and all, but as we noted – it doesn’t exactly feel like our tool is a part of SharePoint. That might be fine if we’d built something extremely complex where having it as a self-contained webapp of sorts made a lot of sense, but it seems wrong for our purposes.

What we need to do is somehow build the tool into the main page of our SharePoint site so our users don’t even have to think if they want to use it – it’s just right there waiting for them.

The Content Editor Web Part

Believe it or not, we laid the groundwork for this in lesson 1 even without knowing it. The final step last time was to add a content editor web part to our page with a link to the tool in it.

The content editor webpart is much more powerful than that though, and we’ve barely scratched the surface. First, let’s take a closer look at what we have there already.

From the web part’s menu, choose the Edit Web Part option. An options pane will appear on the right of the screen.

If you’re using SharePoint 2007 there’s a button in the options pane called Source Editor, and this is where you’ll want to go. On SharePoint 2010 you’ll need to click into the web part first of all so that the ribbon appears at the top of the screen, then select HTML and Edit HTML Source from the Format Text ribbon.

Right now, my source looks like this:

​<a class="ms-rteFontSize-7" href="/web/shipping.aspx">Shipping Cost Calculator</a>

Simple enough, but hopefully you’re beginning to see where I’m going with this. The content of the web part is rendered inline as part of the HTML of the overall page, and we can put whatever we want in there. We can only edit this one snippet of the page where the web part lives, but that’s OK – it’s good enough.

Last time we included a reference to the jQuery library in the <head> section of the page, but does it actually need to be in the head? It may not be semantically great code, but we can put that reference anywhere. And once we have we’ll have all the power of jQuery at our disposal to manipulate the main page of the site however we see fit.

For now, let’s modify the code we used in lesson one to make it appropriate for inclusion in the middle of a page:

/web/js/jquery-1.11.0.min.js

   $(document).ready(function() {
      $('input#calculate').click(function() {
         var shippingcost = 19.99;
         
         if ($('input#itemweight').val() > 20) {
            shippingcost += (Math.ceil(($('input#itemweight').val() - 20) / 5) * 3);
         }
         
         $('span#shippingcost').html(shippingcost);
      });
   });


   
Item weight:

     lbs
     
   

   
   
Shipping cost: $0

Paste that in to the content editor web part’s source, and save. On my installation of SharePoint 2010 a warning pops up telling me my HTML may have been edited. I don’t know why SharePoint feels the need to do this, but it doesn’t seem to matter.

Our shipping cost calculator is now looks like it’s really a part of our site homepage, and we’re done another quick lesson!

Taking it Further

What we’ve done here is great for our purposes, but we’ve actually opened up a world of extra possibility here.

As I noted, the HTML and javascript we’ve pasted into our content editor web part goes directly into the page, inline. In some respects that’s not the best – we have script tags in the middle of the page which isn’t really the correct approach, but in other ways it’s extremely powerful.

We can use our script to manipulate the page however we choose. If the approach we’ve chosen to take is to include our code in a web part then we probably don’t want to go nuts and change everything, but if you want to manipulate, say, the document’s title? Easy!

document.title = 'Site Home and Shipping Calculator'

If you want to include a custom CSS file? Done!

$("head").append("<link rel='stylesheet' href='/web/css/example.css' type='text/css' media='screen'>");

And if you have another web part that you want to use jQuery in, there’s no need to include a second reference to the library – one per page is all you need. You can easily have one content editor web part that influences another.

Conclusion

So, in lesson one we built a simple tool and now in lesson two we’ve integrated it right into our SharePoint page. There’s a lot you can do with this knowledge. In lesson three we’ll go deeper still though, and begin to use data from SharePoint lists in our tool with the help of the SPServices jQuery add-on.