How To : Use the CSOM to Update SharePoint Web Part Properties

I wanted to share two methods I developed for retrieving and updating web part properties from JavaScript using CSOM in SharePoint 2013 (I haven’t seen a reference for getting a page’s web part manager through REST).

The web part ID should be available through the “webpartid” attribute included in the page markup.

The methods use the jQuery deferred object, but that could easily be replaced with anything else to handle the asynchronous events. Using this I’m hoping to create configurable client side web parts which is a problem I’ve recently had to tackle.

View on GitHub

app.js

1. //pass in the web part ID as a string (guid)
2. function getWebPartProperties(wpId) {
3. var dfd = $.Deferred();
4.  
5. //get the client context
6. var clientContext =
7. new SP.ClientContext(_spPageContextInfo.webServerRelativeUrl);
8. //get the current page as a file
9. var oFile = clientContext.get_web()
10. .getFileByServerRelativeUrl(_spPageContextInfo.serverRequestPath);
11. //get the limited web part manager for the page
12. var limitedWebPartManager =
13. oFile.getLimitedWebPartManager(SP.WebParts.PersonalizationScope.shared);
14. //get the web parts on the current page
15. var collWebPart = limitedWebPartManager.get_webParts();
16.  
17. //request the web part collection and load it from the server
18. clientContext.load(collWebPart);
19. clientContext.executeQueryAsync(Function.createDelegate(this, function () {
20. var webPartDef = null;
21. //find the web part on the page by comparing ID’s
22. for (var x = 0; x < collWebPart.get_count() && !webPartDef; x++) {
23. var temp = collWebPart.get_item(x);
24. if (temp.get_id().toString() === wpId) {
25. webPartDef = temp;
26. }
27. }
28. //if the web part was not found
29. if (!webPartDef) {
30. dfd.reject(“Web Part: “ + wpId + ” not found on page: “
31. + _spPageContextInfo.webServerRelativeUrl);
32. return;
33. }
34.  
35. //get the web part properties and load them from the server
36. var webPartProperties = webPartDef.get_webPart().get_properties();
37. clientContext.load(webPartProperties);
38. clientContext.executeQueryAsync(Function.createDelegate(this, function () {
39. dfd.resolve(webPartProperties, webPartDef, clientContext);
40. }), Function.createDelegate(this, function () {
41. dfd.reject(“Failed to load web part properties”);
42. }));
43. }), Function.createDelegate(this, function () {
44. dfd.reject(“Failed to load web part collection”);
45. }));
46.  
47. return dfd.promise();
48. }
49.  
50. //pass in the web part ID and a JSON object with the properties to update
51. function saveWebPartProperties(wpId, obj) {
52. var dfd = $.Deferred();
53.  
54. getWebPartProperties(wpId).done(
55. function (webPartProperties, webPartDef, clientContext) {
56. //set web part properties
57. for (var key in obj) {
58. webPartProperties.set_item(key, obj[key]);
59. }
60. //save web part changes
61. webPartDef.saveWebPartChanges();
62. //execute update on the server
63. clientContext.executeQueryAsync(Function.createDelegate(this, function () {
64. dfd.resolve();
65. }), Function.createDelegate(this, function () {
66. dfd.reject(“Failed to save web part properties”);
67. }));
68. }).fail(function (err) { dfd.reject(err); });
69.  
70. return dfd.promise();
71. }