Working with Taxonomy and JavaScript in SharePoint 2013

SharePoint 2013 has introduced some nice new features, one of which is the ability to manipulate managed metadata with the JavaScript Object Model. Unlike SharePoint 2010, we can now do a variety of operations with the Taxonomy Items in SharePoint 2013. Unfortunately, at the time of this writing, there is not a lot of documentation available on MSDN with regards to this particular feature.There is some preliminary documentation available for the Taxonomy in .NET Managed Client Object Model but the JavaScript API Reference has not been updated yet. So hopefully this blog will come in handy for someone looking to explore. All right lets get started:

First and foremost, you will have to load the SP.Taxonomy.js on your page explicitly as it is not loaded by default in SharePoint. Also make sure that you have loaded the SP.Runtime.js and SP.js files before continuing with your taxonomy code. Various errors like "SP.Taxonomy is not defined" or "Unable to get property 'TaxonomySession' of undefined or null reference" might come up if you have not loaded all the 3 necessary files on your page.

A simple way to load all the 3 files is with the jQuery.getScript function:

	$(document).ready(function(){
	var scriptbase = _spPageContextInfo.webServerRelativeUrl + "_layouts/15/";
	$.getScript(scriptbase + "SP.Runtime.js", function () {
	$.getScript(scriptbase + "SP.js", function(){
	$.getScript(scriptbase + "SP.Taxonomy.js", execOperation);
	});
	}
	);
	});

view raw sp15tax.js hosted with ❤ by GitHub

Now lets see some actual code which you can use to Manipulate the Taxonomy Items:

1) Query a particular Term Set and get all the Terms under it:

	$(document).ready(function(){
	var scriptbase = _spPageContextInfo.webServerRelativeUrl + "_layouts/15/";
	$.getScript(scriptbase + "SP.Runtime.js",
	function () {
	$.getScript(scriptbase + "SP.js", function(){
	$.getScript(scriptbase + "SP.Taxonomy.js", execOperation);
	});
	}
	);
	});
	function execOperation(){
	//Current Context
	var context = SP.ClientContext.get_current();
	//Current Taxonomy Session
	var taxSession = SP.Taxonomy.TaxonomySession.getTaxonomySession(context);
	//Term Stores
	var termStores = taxSession.get_termStores();
	//Name of the Term Store from which to get the Terms.
	var termStore = termStores.getByName("Taxonomy_Dmxzz8tIBzk8wNVKQpJ+xA==");
	//GUID of Term Set from which to get the Terms.
	var termSet = termStore.getTermSet("b49f64b3-4722-4336-9a5c-56c326b344d4");
	var terms = termSet.getAllTerms();
	context.load(terms);
	context.executeQueryAsync(function(){
	var termEnumerator = terms.getEnumerator();
	var termList = "Terms: \n";
	while(termEnumerator.moveNext()){
	var currentTerm = termEnumerator.get_current();
	termList += currentTerm.get_name() + "\n";
	}
	alert(termList);
	},function(sender,args){
	console.log(args.get_message());
	});
	}

view raw sp15_taxAllTerms.js hosted with ❤ by GitHub

2) Create new Term Group under the Term Store:

	$(document).ready(function(){
	var scriptbase = _spPageContextInfo.webServerRelativeUrl + "_layouts/15/";
	$.getScript(scriptbase + "SP.Runtime.js",
	function () {
	$.getScript(scriptbase + "SP.js", function(){
	$.getScript(scriptbase + "SP.Taxonomy.js", execOperation);
	});
	}
	);
	});
	function execOperation(){
	//Current Context
	var context = SP.ClientContext.get_current();
	//Current Taxonomy Session
	var taxSession = SP.Taxonomy.TaxonomySession.getTaxonomySession(context);
	//Term Stores
	var termStores = taxSession.get_termStores();
	//Term Store under which to create the group.
	var termStore = termStores.getByName("Taxonomy_Dmxzz8tIBzk8wNVKQpJ+xA==");
	//New Group with name and new GUID
	var newGroup = termStore.createGroup("New Group Name","b300304a-1693-4629-a1c0-dff7bda644ff");
	context.load(newGroup);
	context.executeQueryAsync(function(){
	console.log(newGroup.get_name());
	},function(sender,args){
	console.log(args.get_message());
	});
	}

view raw sp15tax_newGroup.js hosted with ❤ by GitHub

3) Create new Term Set under a Term Group:

	$(document).ready(function(){
	var scriptbase = _spPageContextInfo.webServerRelativeUrl + "_layouts/15/";
	$.getScript(scriptbase + "SP.Runtime.js",
	function () {
	$.getScript(scriptbase + "SP.js", function(){
	$.getScript(scriptbase + "SP.Taxonomy.js", execOperation);
	});
	}
	);
	});
	function execOperation(){
	//Current Context
	var context = SP.ClientContext.get_current();
	//Current Taxonomy Session
	var taxSession = SP.Taxonomy.TaxonomySession.getTaxonomySession(context);
	//Term Stores
	var termStores = taxSession.get_termStores();
	//Term Store under which to create the Term Set.
	var termStore = termStores.getByName("Taxonomy_Dmxzz8tIBzk8wNVKQpJ+xA==");
	//Get group by GUID
	var peopleGroup = termStore.getGroup("97eaa7b8-9778-4f61-acb3-7f47abba13c3");
	//Create New Term Set in Group with Name, New GUID and LCID
	var newTermSet = peopleGroup.createTermSet("New TermSet Name","49dac247-d315-4065-8718-e8c3f50e7dcd",1033);
	context.load(newTermSet);
	context.executeQueryAsync(function(){
	console.log(newTermSet.get_name());
	},function(sender,args){
	console.log(args.get_message());
	});
	}

view raw sp15tax_newTermSet.js hosted with ❤ by GitHub

4) Create new Term under a Term Set:

	$(document).ready(function(){
	var scriptbase = _spPageContextInfo.webServerRelativeUrl + "_layouts/15/";
	$.getScript(scriptbase + "SP.Runtime.js",
	function () {
	$.getScript(scriptbase + "SP.js", function(){
	$.getScript(scriptbase + "SP.Taxonomy.js", execOperation);
	});
	}
	);
	});
	function execOperation(){
	//Current Context
	var context = SP.ClientContext.get_current();
	//Current Taxonomy Session
	var taxSession = SP.Taxonomy.TaxonomySession.getTaxonomySession(context);
	//Term Stores
	var termStores = taxSession.get_termStores();
	//Term Store under which to create the term.
	var termStore = termStores.getByName("Taxonomy_Dmxzz8tIBzk8wNVKQpJ+xA==");
	//Term Set under which to create the term.
	var termSet = termStore.getTermSet("b49f64b3-4722-4336-9a5c-56c326b344d4");
	//Name of the term, LCID and a new GUID for the term.
	var newTerm = termSet.createTerm("India", 1033, "b49f64b3-4722-4336-9a5c-56c326b344a9");
	//newTerm.set_isAvailableForTagging(true);
	context.load(newTerm);
	context.executeQueryAsync(function(){
	alert("Term Created: " + newTerm.get_name());
	},function(sender,args){
	console.log(args.get_message());
	});
	}

view raw sp15tax_newTerm.js hosted with ❤ by GitHub

5) Get Value of a Single Value Taxonomy Column in a List:

	$(document).ready(function(){
	var scriptbase = _spPageContextInfo.webServerRelativeUrl + "_layouts/15/";
	$.getScript(scriptbase + "SP.Runtime.js",
	function () {
	$.getScript(scriptbase + "SP.js", function(){
	$.getScript(scriptbase + "SP.Taxonomy.js", execOperation);
	});
	}
	);
	});
	function execOperation(){
	var context = SP.ClientContext.get_current();
	var list = context.get_web().get_lists().getByTitle('TaxonomyCustomList');
	var listItem = list.getItemById(1);
	context.load(listItem);
	context.executeQueryAsync(function(){
	//Single Value Taxonomy Column
	//Label
	var label = listItem.get_item("MyTaxColumn").get_label();
	//Term GUID
	var termGUID = listItem.get_item("MyTaxColumn").get_termGuid();
	//Type ID
	var typeID = listItem.get_item("MyTaxColumn").get_typeId();
	//WSS ID
	var wssID = listItem.get_item("MyTaxColumn").get_wssId();
	},function(sender,args){
	console.log(args.get_message());
	});
	}

view raw sp15tax1.js hosted with ❤ by GitHub

6) Get Values of a Multi Value Taxonomy Column in a List:

	$(document).ready(function(){
	var scriptbase = _spPageContextInfo.webServerRelativeUrl + "_layouts/15/";
	$.getScript(scriptbase + "SP.Runtime.js",
	function () {
	$.getScript(scriptbase + "SP.js", function(){
	$.getScript(scriptbase + "SP.Taxonomy.js", execOperation);
	});
	}
	);
	});
	function execOperation(){
	var context = SP.ClientContext.get_current();
	var list = context.get_web().get_lists().getByTitle('TaxonomyCustomList');
	var listItem = list.getItemById(1);
	context.load(listItem);
	context.executeQueryAsync(function(){
	//Multivalue Taxonomy Column
	var taxEnumerator = listItem.get_item("MyTaxColumn").getEnumerator();
	while(taxEnumerator.moveNext()){
	//Label
	var currentTerm = taxEnumerator.get_current();
	//Label
	var label = currentTerm.get_label();
	//Term GUID
	var termGUID = currentTerm.get_termGuid();
	//Type ID
	var typeID = currentTerm.get_typeId();
	//WSS ID
	var wssID = currentTerm.get_wssId();
	}
	},function(sender,args){
	console.log(args.get_message());
	});
	}

view raw sp15tax2.js hosted with ❤ by GitHub

Hopefully you found this helpful. Happy SharePointing!