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></body> </html>Item weight:
lbsShipping cost: $0
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!
