Adding an XsltListViewWebPart With a Custom View Using JavaScript

I was building a SharePoint Hosted App, and one of the requirements was to add a List View web part to the home page of a site. Lucky for us SharePoint devs, there is no documentation on this stuff, only bits and pieces here and there. Needless to say, after some trial and error, I was finally able to get it working!

**Disclaimer: If you are using a Wiki Page this tutorial will not work! Adding a web part to a Wiki Page is a bit trickier and not covered in this article.

Okay, so now that we have that out of the way... let's begin the tutorial.

Web Part XML

The first step is to create the XML for the XsltListViewWebPart. This is what the basic XML looks like:

[code language="xml"]
<?xml version='1.0' encoding='utf-8' ?>
<webParts>
<webPart >
<metaData>
<type name='Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c' />
<importErrorMessage>Cannot import this Web Part.</importErrorMessage>
</metaData>
<data>
<properties>
<property name='ListUrl' type='string'>MyList</property>
</properties>
</data>
</webPart>
</webParts>
[/code]

I am using the ListUrl property and passing it the name of my list, alternately you could use the ListId if you know the GUID. You can also add other properties to the data section of the XML, such as InplaceSearchEnabled or DisableViewSelectorMenu (I tried them at they work!). Check out this page for more properties. I haven't tried them all, but I know that a bunch of them get ignored when using JSOM. For example, setting the ViewGuid or the Toolbar properties don't do anything! So hopefully you don't need to configure the hell out of the web part.

Ok so now that we have our valid XML we can go ahead and add it to our page.

Add Web Part to Page

Adding the web part to the page is pretty straight forward once you have your valid XML. You simply need to import the web part XML into the web part manager, then add it to it. Here is the code to do that.

[code language="javascript"]
var file = web.getFileByServerRelativeUrl("sites/someSite/default.aspx"),
wpm = file.getLimitedWebPartManager(SP.WebParts.PersonalizationScope.shared),
wpd = wpm.importWebPart(webPartXml),
wp = wpd.get_webPart();

wpm.addWebPart(wp, "Left", 1);
[/code]

Pretty straight forward so far! However, I hope that the next part will blow your mind!

Customize Web Part View

Wouldn't it be nice if you could just set the ViewGuid property of the web part and everything would just work? Well, we are dealing with SharePoint... and things don't always work as expected! So how do we set the web part view? The trick is to call update on the list that the web part is configured to use! Updating the list will create the default view used by the web part. If you don't call update, you cannot access the hidden view in order to customize it.

So after adding the web part to the webpart manager, simply get your list and call the update method.

[code language="javascript"]
var list = web.get_lists().getByTitle("MyList");
list.update();
[/code]

Now, we can go ahead and retrieve all the list views, which should contain the hidden view used by the web part.

[code language="javascript"]
var listViews = list.get_views();
[/code]

Once everything is successfully loaded, we can loop through all the views and find the view with an empty string for the title. This is the view used by the web part! Nice right? So now that we have a handle to the view, we can customize the view as we like and we are done! I am not going to walk through how to loop over the views and how to customize the view, however the full code below shows how it's done!

[code language="javascript"]
var addListViewWebPartWebPart = function(options) {
var dfd = new $.Deferred();

var webPartXml = "<?xml version='1.0' encoding='utf-8' ?>" +
"<webParts>" +
"<webPart >" +
"<metaData>" +
"<type name='Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c' />" +
"<importErrorMessage>Cannot import this Web Part.</importErrorMessage>" +
"</metaData>" +
"<data>" +
"<properties>" +
"<property name='ListUrl' type='string'>" + options.listTitle + "</property>" +
"<property name='InplaceSearchEnabled' type='boolean'>false</property>" +
"<property name='DisableViewSelectorMenu' type='boolean'>true</property>" +
"</properties>" +
"</data>" +
"</webPart>" +
"</webParts>";

var context = new SP.ClientContext.get_current(),
web = context.get_web(),
list = web.get_lists().getByTitle(options.listTitle),
file = web.getFileByServerRelativeUrl(options.pageUrl),
wpManager = file.getLimitedWebPartManager(SP.WebParts.PersonalizationScope.shared),
wpDefinition = wpManager.importWebPart(webPartXml),
wp = wpDefinition.get_webPart();

wpManager.addWebPart(wp, "Left", 1);
list.update();

var listViews = list.get_views();

context.load(wp);
context.load(list);
context.load(listViews);
context.executeQueryAsync(Function.createDelegate(this, addWebPartSuccess), Function.createDelegate(this, addWebPartFail));

function addWebPartSuccess(sender, args) {
var enumerator = listViews.getEnumerator(),
webPartView;

while (enumerator.moveNext()) {
var view = enumerator.get_current();

if (view.get_title() === '') {
webPartView = view;
break;
}
}

if (webPartView) {
webPartView.get_viewFields().removeAll();
webPartView.get_viewFields().add('DocIcon');
webPartView.get_viewFields().add('LinkFilename');
webPartView.get_viewFields().add('Editor');
webPartView.get_viewFields().add('_UIVersionString');

webPartView.set_title('Recently Updated Home Page');
webPartView.set_viewQuery('<OrderBy><FieldRef Name="Modified" Ascending="FALSE" /></OrderBy>');
webPartView.set_hidden(false);
webPartView.set_rowLimit(5);

webPartView.update();

context.load(webPartView);
context.executeQueryAsync(Function.createDelegate(this, updateViewSuccess), Function.createDelegate(this, updateViewFail));
} else {
dfd.resolve();
}

function updateViewSuccess(sender, args) {
dfd.resolve();
}

function updateViewFail(sender, args) {
dfd.reject({
errorMessage: args.get_message(),
options: options
});
}
}

function addWebPartFail(sender, args) {
dfd.reject({
errorMessage: args.get_message(),
options: options
});
}

return dfd.promise();
};
[/code]