SharePoint (and Project Server) Shenanigans

The excellent Knockout.js library is an MVVM (Model, View, ViewModel) library.

Using it you can completely abstract the logic from the presentation in your web applications, allowing dynamic and responsive UIs to be created without having to manage all of the fiddly UI updates directly.

The Knockout site has a great set of tutorials on how to use it, but I thought I would bring them into a SharePoint context.

Specifically, I am going to cover their 5th tutorial, Loading and Saving Data. In this tutorial they give the example of a simple task list that a user can update and delete dynamically. If you do not know Knockout at all, I recommend you go through this tutorial before continuing. Go ahead, I can wait.

Back with us? Excellent. Hopefully by now you have some idea of the power of Knockout, so lets try and reproduce this using a SharePoint list as the data source.

The first thing to do is to create our list. For this I am using a simple custom list named ‘My Tasks’ with an additional Completed Yes/No field, and I have pre-populated it with some entries.

Next we need to consider how we are going to create our view within our site. For my example I have chosen to simply create the view as a file in a document library, then link to it using a Content Editor Web Part. However you could do this a number of ways, you could embed your JavaScript into the master page and put your data bindings directly into a page layout, or you could create a visual web part. The possibilities are endless, this is SharePoint after all!

I put the view, along with the script references to Knockout, the ever useful jQuery and my View Model into a single file and save it into the document library. I have also put some style information in too. Here is the view model as I created it:

<style type="text/css">

	#taskContainer {
		width: 500px;
	}
	
	#errorBox {
		text-align: center;
		border: 1px solid #600;
		margin-bottom: 10px;
		padding: 10px;
		background: #f99;
		color: #600;
	}
	
	#saveBox {
		text-align: center;
		border: 1px solid #060;
		margin-bottom: 10px;
		padding: 10px;
		background: #9f9;
		color: #060;
	}
	
	#taskContainer ul {
		padding: 10px;
		background: #eaeaea;
		padding: 0;
	}
	
	#taskContainer ul li {
		list-style: none;
		padding: 3px;
	}
	
	#taskContainer input[type=text] {
		width: 390px;
	}
	
</style>
<div id="taskContainer">
	<h3>Tasks</h3>
	
	<div id="errorBox" data-bind="text: errorMessage, visible: errorMessage"></div>
	<div id="saveBox" data-bind="text: saveMessage, visible: saveMessage"></div>
	
	Add task: <input data-bind="value: newTaskText" placeholder="What needs to be done?"/>
	<button data-bind="click: addTask">Add</button>
	
	<ul id="myTaskBox" data-bind="foreach: tasks, visible: tasks().length > 0">
	    <li>
	        <input type="checkbox" data-bind="checked: Completed" />
	        <input data-bind="value: Title, disable: Completed" />
	        <a href="#" data-bind="click: $parent.removeTask">Delete</a>
	    </li> 
	</ul>
	
	You have <b data-bind="text: incompleteTasks().length">&nbsp;</b> incomplete task(s)
	<span data-bind="visible: incompleteTasks().length == 0"> - it's beer time!</span>
	
	<button data-bind="click: save">Save</button>
</div>

<script type="text/javascript" src="../webdevdocuments/knockout.js"></script>
<script type="text/javascript" src="../webdevdocuments/jquery-1.9.1.min.js"></script>
<script type="text/javascript" src="../webdevdocuments/ViewModel.js"></script>

Note the addition of some message boxes, the original tutorial does not include them but I felt they were nicer than simple alert boxes.

Also note that, unlike the original, I have not used a form element for the new task area. This is because form elements can cause havoc in SharePoint pages, as the entire page is wrapped in a form for post-backs.

Other than that, our view is mostly unchanged.

Now, on to the JavaScript!

The main differences here lie in the way that we send and receive data from SharePoint. In their examples they use jQuery to query and post data to REST APIs, and while SharePoint 2010 and 2013 do come with their own suite of REST / oData APIs, there are some issues in using them.

• Update and Delete calls can only update or delete one item per call, to do the bulk updating this system indicates we would have to make a request per item. Not ideal!
• Due to the way SharePoint handles concurrency, you have to pass around an eTag so that SharePoint can determine if an item has been updated since requested. While this is great for high concurrency systems with multiple people editing the same data, for a personal tasks list this is not a nice feature.

Luckily REST is not our only option. SharePoint has the wonderful Client Side Object Model (CSOM), which can do all of our loading and saving for us!

Here is my View Model, updated to use the CSOM.

(function() {

	function Task(data) {
	    this.Title = ko.observable(data.Title);
	    this.Completed = ko.observable(data.Completed);
	    
	    // An additional reference to store the SharePoint list item id.
	    this.Id = ko.observable(data.Id);
	}
	
	function TaskListViewModel() {
	    // Data
	    var self = this;
	    self.tasks = ko.observableArray([]);
	    self.newTaskText = ko.observable();
	    
	    // Additional bindings to use for error and saved messages.
	    self.saveMessage = ko.observable(false);
	    self.errorMessage = ko.observable(false);
	    
	    self.incompleteTasks = ko.computed(function() {
	        return ko.utils.arrayFilter(self.tasks(), function(task) { return !task.Completed() && !task._destroy});
	    });
	
	    // Operations
	    self.addTask = function() {
	        self.tasks.push(new Task({ Title: this.newTaskText(), Completed: false, Id: "New" }));
	        self.newTaskText("");
	    };
	    
	    self.removeTask = function(task) {
			self.tasks.destroy(task)
	    };
	    
	    self.save = function() {

	    	for (var task in self.tasks()) {
	    	
	    		var createdTasks = [];
	    		
	    		// Build a request up to send with the CSOM.
	    	
	    		if (self.tasks()[task]._destroy) {
					// Handle deleted objects
	    			// Deleted items that are marked "new" have never been saved to SharePoint to start with,
	    			if (self.tasks()[task].Id() != "New") {
			    		var listItem = taskList.getItemById(self.tasks()[task].Id());
			    		listItem.deleteObject();
	    			}
	    		} else if (self.tasks()[task].Id() == "New") {
	    			// Handle new objects to be created.
	    		
	    			var createInfo = new SP.ListItemCreationInformation();
	    			var listItem = taskList.addItem(createInfo);
	    			
	    			listItem.set_item("Title", self.tasks()[task].Title());
	    			listItem.set_item("Completed", self.tasks()[task].Completed());
	    			
	    			listItem.update();
	    			
	    			// Save a reference to both the SP.ListItem object and the KO Object so we can update
	    			// the latter with the former's ID once the object has been created.
	    			createdTasks.push({
	    				spItem: listItem,
	    				koItem: self.tasks()[task]
	    			});
	    			
	    			ctx.load(listItem);
	    		} else {
	    			// The item is neither new nor deleted, handle it as an update.
	    			var listItem = taskList.getItemById(self.tasks()[task].Id());
	    			
	    			listItem.set_item("Title", self.tasks()[task].Title());
	    			listItem.set_item("Completed", self.tasks()[task].Completed());
	    			
	    			listItem.update();
	    		}
	    		
	    	}

			// Nowe we have built our request, send it to the server for processing.	    	
	    	ctx.executeQueryAsync(function() {
	    	
	    		// Our save was successful. Now we need to itterate through our newly
	    		// created items and ensure that Knockout knows that the ID has changed.
	    		for(var item in createdTasks) {
	    			createdTasks[item].koItem.Id(createdTasks[item].spItem.get_id());
	    		}
	    		
	    		// Set our saved message.
	    		self.saveMessage("Saved successfully");
	    		
	    	}, function(sender, args) {
	    	
	    		// Our save failed, set the error message to show then log the actual error
	    		// to the JavaScript console if it exists.
	    		self.errorMessage("Error updating list items");
	    		if (typeof console != "undefined") {
	    			console.log(args.get_message());
	    		}
	    	});
	    	
	    };
	    
	    // Load the data from SharePoint
		// Get a context to the current site.
	    var ctx = new SP.ClientContext(_spPageContextInfo.webServerRelativeUrl);
	    
	    var web = ctx.get_web();
	    var taskList = web.get_lists().getByTitle("My Tasks");
	    
	    // Limit our task list to 50 tasks.
   	    var query = new SP.CamlQuery();
   	    query.set_viewXml("<View><RowLimit>50</RowLimit></View>");
   	    
   	    var taskItems = taskList.getItems(query);
   	    
   	    // Ensure the fields we want to retrieve are returned
   	    ctx.load(taskItems, "Include(ID,Title,Completed)");
   	    
   	    // Send our query to the server for processing.
   	    ctx.executeQueryAsync(function() {
   	    	var tasks = [];
   	    	var taskItemEnumerator = taskItems.getEnumerator();
   	    	
   	    	// Iterate through our retrieved data set and build an array of JSON objects containing
   	    	// the relevent properties.
   	    	while (taskItemEnumerator.moveNext()) {
   	    		tasks.push(
   	    			new Task({
	   	    			Title: taskItemEnumerator.get_current().get_item("Title"),
	   	    			Completed: taskItemEnumerator.get_current().get_item("Completed"),
	   	    			Id: taskItemEnumerator.get_current().get_item("ID")
	   	    		})
	   	    	);
   	    	}
   	    	
   	    	// Update the Knockout tasks array with our data from the server.
   	    	self.tasks(tasks);
   	    });
	    
	}
	
	
	$(document).ready(function() { // I use jQuery for this, but you could add an event listener to the document object instead.
		EnsureScriptFunc("sp.js", "SP.ClientContext", function() {
			ko.applyBindings(new TaskListViewModel());
		});
	});

})();

So there you go, once you put it all together you should end up with something looking like this:

Cool, huh? It is by no means perfect. The two biggest issues with the implementation as it stands are:

• Currently I am limiting the entire system to only showing 50 records, which is not ideal. This would be best handled by adding some pagination.
• When you hit save it updates every item in the view model, regardless of whether it needs updating or not. This would be resolvable by subscribing to the Task Knockout object and keeping track of which need updating and which do not.

Additionally you could use some jQuery animation and the animated transitions example on the Knockout site to hide the save and error boxes once they are shown. Currently once they are visible they remain visible indefinitely.

Have fun with it, it’s a neat tool and can give quite powerful results.

via Chris on SharePoint http://spchris.com/2013/04/using-knockout-js-in-a-sharepoint-context/

SharePoint and Project Server Consultant MCITP – SharePoint Administrator 2010 MCTS – Microsoft Project 2010 – Managing Projects, Project Server 2010, Configuration, SharePoint 2010, Configuration Prince 2 – Practitioner This article has been cross posted from spchris.com (original article)

Today I had a requirement to alter the title in the left hand side of the Suite bar in SharePoint 2013.

This is the bar appearing at the very top of the page, by default containing the word SharePoint on the left and links to things like SkyDrive, the Newsfeed and sites you follow on the right.

In this particular scenario I was interested in changing the word SharePoint to something more meaningful, preferably customisable on a per web basis, or based upon the site collection root web’s title.

My first thought on trying to change it was to look into the master page but I could find no reference to it there, so I did a little digging and found some surprising details.

1. The entire bar is a delegate control
2. The left hand part of the bar is stored as a property against the Web Application
3. There is no way of modifying the right hand links without writing a farm solution in .NET, or adding custom JavaScript to each page to modify the links on the fly.

While these problems are not insurmountable, it left me a little nonplussed, especially the idea that it was not possible to modify the branding uniquely per site collection or per web. However I bravely fought on, as I was really quite determined to get that heading working the way I wished.

My first test was to see what the property against the web application was called, and what it contains by default. Let’s break out our trusty SharePoint Management Console and use the following bit of PowerShell.

$webApp = Get-SPWebApplication -Identity "http://mywebapplicationurl"
$webApp.SuiteBarBrandingElementHtml
<div class="ms-core-brandingText">SharePoint</div>

This seems straight forward enough, the property is a string containing the HTML for the heading, so let’s go and update it to something else using the same window from our previous example (Re-do the Get-SPWebApplication call again if you have closed it)

$webApp.SuiteBarBrandingElementHtml = '<div class="ms-core-brandingText">My Custom Branding</div>'
$webApp.Update()

Note the call to the Update() method, without this your changes will not be applied to the Web Application.

Once done, refresh your page and you will see that your branding has updated accordingly.

So to recap, we can modify this string only on the Web application level, but when we do so, we can put HTML tags in directly, and they will be rendered to the page. Interesting!

Let’s talk about JavaScript

The ECMAScript Object Model first came into its own with SharePoint 2010, and with 2013 has gone from strength to strength. Lets see if we can’t use it to meet our requirement of at least customising the Suite bar based on the current Site Collection’s root web title.

To do this is very simple in code, take a look at the following JavaScript example:

(function() {

	// Set a default title to use if we cannot retrieve one.
	var defaultTitle = 'SharePoint';

	// Ensure that both the DOM and the Object Model are ready for us
	document.addEventListener('DOMContentLoaded', function() {
		EnsureScriptFunc('sp.js', 'SP.ClientContext', function() {

			// Instantiate our renamer.
			var t = new titleBarRenamer();

		});
	});


	function titleBarRenamer() {

		// Get and load a reference to the root web of the current site collection.
		var ctx = new SP.ClientContext.get_current();
		var site = ctx.get_site();
		var rootWeb = site.get_rootWeb();

		ctx.load(rootWeb);

		// Send our query off to SharePoint.
		ctx.executeQueryAsync(function() {

			var title = false;

			// Pull the title into a variable.
			// Default to the default title if it fails.

			try {

				title = rootWeb.get_title();

				title = title || defaultTitle;

			} catch (e) {

				title = defaultTitle;

			}

			// Update our title to our results.
			document.getElementById('webTitleContainer').innerHTML = title;

		}, function() {

			// If all else fails, set the title back to our default.
			document.getElementById('webTitleContainer').innerHTML = defaultTitle;

		});
	
	}

})();

That’s cool, wherever this code is run it will set an HTML element with an ID of ‘webTitleContainer’ to the root web’s title.

Putting it all together

So how do we combine these two together?

Again this is pretty simple, take a look at the following PowerShell:

Add-PSSnapIn Microsoft.SharePoint.PowerShell

$containerCode = @"
<div id='webTitleContainer' class='ms-core-brandingText'></div>
<script type='text/javascript'>
(function() {

	// Set a default title to use if we cannot retrieve one.
	var defaultTitle = 'SharePoint';

	// Ensure that both the DOM and the Object Model are ready for us
	document.addEventListener('DOMContentLoaded', function() {
		EnsureScriptFunc('sp.js', 'SP.ClientContext', function() {

			// Instantiate our renamer.
			var t = new titleBarRenamer();

		});
	});


	function titleBarRenamer() {

		// Get and load a reference to the root web of the current site collection.
		var ctx = new SP.ClientContext.get_current();
		var site = ctx.get_site();
		var rootWeb = site.get_rootWeb();

		ctx.load(rootWeb);

		// Send our query off to SharePoint.
		ctx.executeQueryAsync(function() {

			var title = false;

			// Pull the title into a variable.
			// Default to the default title if it fails.

			try {

				title = rootWeb.get_title();

				title = title || defaultTitle;

			} catch (e) {

				title = defaultTitle;

			}

			// Update our title to our results.
			document.getElementById('webTitleContainer').innerHTML = title;

		}, function() {

			// If all else fails, set the title back to our default.
			document.getElementById('webTitleContainer').innerHTML = defaultTitle;

		});
	
	}

})();
</script>
"@

$webApp = Get-SPWebApplication -Identity "http://mywebapplicationurl"
$webApp.SuiteBarBrandingElementHtml = $containerCode
$webApp.Update()

As you can see, the bulk of this is our JavaScript code from above, with the addition of a div for our title to end up in and the required script tags for the code.

Once you have this, you can save it as a .ps1 file and execute it in PowerShell. You may need to set the execution policy to RemoteSigned before you are able to do this.

And there you go. You could do some fairly interesting things with this, particularly as it takes effect right across the entire web application. You also have to be aware that this is stored within the Configuration Database rather than the Content Database, so will not be migrated if you move content databases from one farm to another.

via Chris on SharePoint http://spchris.com/2013/04/mastering-the-sharepoint-2013-suite-bar/

SharePoint and Project Server Consultant MCITP – SharePoint Administrator 2010 MCTS – Microsoft Project 2010 – Managing Projects, Project Server 2010, Configuration, SharePoint 2010, Configuration Prince 2 – Practitioner This article has been cross posted from spchris.com (original article)