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.

Welcome to lesson 1 of my mini-series on SharePoint development! This is the first post where we really dive in and get our hands dirty, although I did previously write about installing SharePoint in a Virtual Machine. Anyway, I’ve been threatening to write about this stuff for quite some time now, so it’s probably about time I got started.

I’m going to assume as I write this that you already have at least a little familiarity with SharePoint and it’s capabilities, as well as some experience with HTML, javascript and jQuery. With these assumptions in place what I’m going to help you do is tie everything together to create some cool SharePoint-based tools, but don’t worry – we’re going to start off slowly.

SharePoint Document Libraries

Document libraries are a feature of SharePoint that you probably already know about. They’re a great way to store Microsoft Office documents that should be shared with a wider audience throughout a team or an organization. You can enable version control, and there are features to prevent clashes in situations where multiple users may try to work on the same document at once.

For our purposes we don’t care about most of that, but SharePoint document libraries can contain any type of file – not just office documents. For today, we’re going to use a document library simply as storage for an HTML document and the jQuery library, and we’re going to build a simple tool to calculate shipping costs. Over time we’re going to integrate this same tool more tightly into our SharePoint site, and begin to leverage more and more of SharePoint’s functionality.

But like I said, we’re starting slowly.

Creating a Document Library

Creating a new document library is a fairly simple affair. Some versions of SharePoint (2010 onward) have a shortcut for it in the Site Actions menu, but regardless of the version you’re running if you to Site Actions > View All Site Content and then hit the Create button you’ll find what you need. Select Document Library from the list of things that you can create.

Next, give the document library a name. It really doesn’t matter what you call it because we’re not going to send people to the document library itself – just to content within it. The name will feature in the URL of files that we store though, so for simplicity I’d recommend a name without any spaces. I always call mine “web,” but that’s just personal preference.

Under Display this document library on the Quick Launch? we’re going to select No. Choosing yes places a link to the library on the main page of the site, but as I noted – we don’t really want people to visit the library directly.

For Create a version each time you edit a file in this document library? you can select No here also – as we move through successive lessons in this series we’ll end up using the library only to store assets like scripts and images, so we don’t really need this feature. You can leave the Document Template drop-down at it’s default value – this setting won’t be relevant to us either.

Finally, hit the Create button at the bottom of the window.

The document library is now created. The first thing we’re going to do is create a folder for javascript files. Hit the New Folder button and create a folder called js. For today, this is the only folder we’re going to need. Download the jQuery library from the web, and upload the javascript file to the js folder.

Creating the HTML Page

I’m not going to dwell too much on this section because you can find much better tutorials out there for this than I could write, but I’m going to create a simple tool that asks for an item’s weight and then spits out a shipping cost.

For the sake of the example, I’m going to calculate shipping costs as follows: costs are $19.99 for anything up to 20lbs, and then an extra $3 per 5lbs (or part thereof) for anything heavier.

I’ve kept the code extremely simple with no error checking or any such niceties (in a real world tool you’d want to be more robust), and here it is:

<!DOCTYPE html>
<html>
<head>
   <title>Shipping Cost Calculator</title>
   /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);
         });
      });
   
</head>
<body>
   <h1>Shipping Calculator</h1>
   

      
Item weight:

        lbs

      


      
Shipping cost: $0
   
</body>
</html>

The only really notable part here is that we’re linking to the javascript file we uploaded earlier:

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

Save the file as shipping.aspx, upload it to the root of the web document library, and that’s pretty much it!

Why the “aspx” File Extension?

On SharePoint 2007 and earlier linking to an html file in a document library will open the file (which is what we want to happen), but on 2010 onward the file will be downloaded instead. Using the aspx file extension solves this problem.

Linking to the Tool

OK, so we’ve created a useful tool and we’ve made it available on SharePoint, but it’s in a document library that’s hidden from view – a typical user would never find it.

So how do we make this available to a wider audience? Well there are several ways, but I’m going to add a new webpart to the main page of my SharePoint site and put a big, bold link in it.

Back on the main page of our SharePoint site choose Edit Page from the Site Actions menu and click the Add a Web Part button. We’re going to add a Content Editor webpart. You’ll get a word-style editor where you can insert text, images, tables, etc… and crucially links. I’m going to insert a link to the HTML file we’ve just uploaded, and increase the font size to make it stand out on the page. If you’ve been following along exactly then the address of the uploaded file will be /web/shipping.aspx.

You’ll probably also want to go to the Appearance section of the webpart properties and give it a custom title.

Conclusion

So, we’ve built a simple webpage with some javascript in there to calculate things for us and we’ve deployed it SharePoint, making it available to site visitors. This is great and all, but it doesn’t really feel like the page is a part of SharePoint. It doesn’t look or feel the same, and from a user experience point of view it seems as though we’re leaving the SharePoint site when we use our calculator tool.

That’s OK though! Today was just about getting started. In part two we’ll take the functionality we’ve just built and integrate it much more tightly into SharePoint itself. Stay tuned!