Second Life of a Hungarian SharePoint Geek

July 16, 2017

Find Your Scripts in SharePoint within Seconds – the Effective, but Unsupported Way

Filed under: JavaScript, SP 2013, SQL, Tips & Tricks — Tags: , , , — Peter Holpar @ 18:41

The SharePoint environment I’m working on contains hundreds of webs. I create test sites for various tasks (like prototyping JSLink-based solutions) including the necessary lists, and store the .js and .css files typically in the Site Assets library of that web site to keep the solution artifacts (lists / files) together. It is rather common, that after I’ve finished the proof of concept, I don’t need it for months, then suddenly I should return to it, but I don’t find it anymore, as I don’t remember, which site I used for that solution.

For that kind of search I’ve created a simply SQL query to find the script directly in the content database of the site collection. Yes, I know it is officially unsupported to access the SharePoint databases directly, but I’m OK with that in my test system. Use it on your own risk.

SELECT [Id]
      ,[SiteId]
      ,[DirName]
      ,[LeafName]
      ,[TimeLastModified]
      ,[DeleteTransactionId]
  FROM [dbo].[AllDocs]
  WHERE LeafName LIKE ‘%.js’
  AND DirName LIKE ‘%SiteAssets%’
  ORDER BY TimeLastWritten DESC

This script lists the file name (LeadName) and path (DirName) of the scripts stored in various sites in their Site Assets library. The name of script and the date of last modification (TimeLastModified) is usually enough to identify the script I need. Note, that the records, that have a value other that 0x in the DeleteTransactionId column are recycled and located in the Recycle Bin. Of course, this method works only in the case of on-premise installations, and only as long as you have access to the SharePoint databases.

Advertisements

March 29, 2017

How to Create a Simple “Printer Friendly” Display Form

Filed under: JavaScript, SP 2013, SPD — Tags: , , — Peter Holpar @ 05:44

Our users needed a simply way to print items in SharePoint, that mean only item properties without any ribbon or navigation elements.

Assuming you have a list ‘YourCustomList’ available at the URL http://YourSharePoint/Lists/YourCustomList, the standard display form of a list item (in this case the one with ID 1) would be:

http://YourSharePoint/Lists/YourCustomList/DispForm.aspx?ID=1

This page contains however the site navigation elements and the ribbon as well. Appending the query string parameter IsDlg=1 (like http://YourSharePoint/Lists/YourCustomList/DispForm.aspx?ID=1&IsDlg=1) helps to remove the navigation parts, but the ribbon remains.

Our solution to remove the ribbon was to add this very simple JavaScript block via a Script Editor Web Part to the display form page (DispForm.aspx). I suggest to insert the Script Editor Web Part after the existing List Form Web Part on the page.

// http://stackoverflow.com/questions/901115/how-can-i-get-query-string-values-in-javascript
function getParameterByName(name, url) {
    if (!url) url = window.location.href;
    name = name.replace(/[\[\]]/g, “\\$&”);
    var regex = new RegExp(“[?&]” + name + “(=([^&#]*)|&|#|$)”),
        results = regex.exec(url);
    if (!results) return null;
    if (!results[2]) return ”;
    return decodeURIComponent(results[2].replace(/\+/g, ” “));
}

if (getParameterByName(‘IsPrint’) == ‘1’) {
  var globalNavBox = document.getElementById(‘globalNavBox’);
  if (globalNavBox) {
    globalNavBox.style.display = ‘none’;
  }
}

Note: You can switch the display form to page edit mode via the ToolPaneView=2 query string parameter (see more useful hints here), for example:

http://YourSharePoint/Lists/YourCustomList/DispForm.aspx?ToolPaneView=2

The main part of the solution, the getParameterByName method was borrowed from this forum thread. It helps to get a query string parameter value by its name. Using this method we check, if there is a parameter IsPrint, and if it is there having a value of 1, the we make the globalNavBox HTML element, that is actually a placeholder for the ribbon, invisible.

It means, if we call the display form by the URL http://YourSharePoint/Lists/YourCustomList/DispForm.aspx?ID=1&IsDlg=1&IsPrint=1 then there is no ribbon or other navigation element on the page. Using this URL format you can even add a custom action, for example, a new button to the ribbon or an edit control block (ECB) menu-item (see example later in the post), or refer a print form directly from a document or from an e-mail.

In the above case, the users can then print the page via right-clicking with the mouse and selecting Print… from the pop-up menu. Alternatively we could inject a Print button on the form itself. This technique will be demonstrated below.

In this case we use JQuery, and our JavaScript code is a bit more complex, so we store it into a separate file in the Site Assets library of the site, and refer only the files in the Script Editor Web Part:

/font/ema%20href=
http://../../SiteAssets/js/printForm.js

Our JavaScript code (printForm.js) would be in this case:

// http://stackoverflow.com/questions/901115/how-can-i-get-query-string-values-in-javascript
function getParameterByName(name, url) {
    if (!url) url = window.location.href;
    name = name.replace(/[\[\]]/g, "\\$&");
    var regex = new RegExp("[?&]" + name + "(=([^&#]*)|&|#|$)"),
        results = regex.exec(url);
    if (!results) return null;
    if (!results[2]) return ”;
    return decodeURIComponent(results[2].replace(/\+/g, " "));
}

// https://davidwalsh.name/add-rules-stylesheets
var sheet = (function() {
    // Create the <style> tag
    var style = document.createElement("style");

    // Add a media (and/or media query) here if you’d like!
    style.setAttribute("media", "print")

    // WebKit hack 😦
    style.appendChild(document.createTextNode(""));

    // Add the <style> element to the page
    document.head.appendChild(style);

    return style.sheet;
})();

$(document).ready(function() {
  if (getParameterByName(‘IsPrint’) == ‘1’) {
    sheet.insertRule("#globalNavBox { display:none; }", 0);
    sheet.insertRule("input { display:none; }", 0);

    $(‘input[value="Close"]’).closest(‘tr’).closest(‘tr’).append(‘<td class="ms-toolbar" nowrap="nowrap"><table width="100%" cellspacing="0" cellpadding="0"><tbody><tr><td width="100%" align="right" nowrap="nowrap"><input class="ms-ButtonHeightWidth" accesskey="P" onclick="window.print();return false;" type="button" value="Print"></input></td></tr></tbody></table></td><td class="ms-separator">&nbsp;</td>’);
  }
});

In this case we inject a Print button dynamically and don’t hide the ribbon, but use the technique illustrated here to add CSS styles to hide UI elements (ribbon and the buttons) only in the printed version via the media attribute of the style sheet.

Note: The above code is for a SharePoint site with English UI. Since the value of the Close button is language dependent, you should change the code if you have a SharePoint site with another culture settings. For example, in a German version the JQuery selector would be:

input[value="Schließen"]

In this case you should have to save the script using Unicode encoding instead of ANSI to prohibit the loss of special character ‘ß’.

Finally, I show you how to create a shortcut to the form in the ECB menu using SharePoint Designer (SPD).

Select your list in SPD, and from the Custom Actions menu select the List Item Menu.

image

Set the fields as illustrated below:

image

The full value of the Navigate to URL field:

javascript:OpenPopUpPageWithTitle(ctx.displayFormUrl + ‘&ID={ItemId}&IsDlg=1&IsPrint=1′, RefreshOnDialogClose, 600, 400,’Print Item’)

We use the OpenPopUpPageWithTitle method and a custom made URL to show the printer friendly display form with the necessary query string parameters. See this article on more details of the OpenPopUpPageWithTitle method.

After saving the custom action, you can test it in your list:

image

This is the customized form having the extra Print button on it:

image

And that is the outcome of the print:

image

August 29, 2016

Permission-based Rendering Templates, Part 2: The Synchronous Solution

Filed under: CSR, JavaScript, jQuery, REST, SP 2013 — Tags: , , , , — Peter Holpar @ 22:14

In my recent post I’ve illustrated how can you implement a permission-based custom rendering template using the JavaScript client object model (JSCOM)  and jQuery. That rendering template was implemented using the standard asynchronous JavaScript patterns via a callback method to not block the UI thread of the browser. In a fast network (in a LAN, for example) however, a synchronous implementation can function as well. Although there are some unsupported methods to make a JSCOM request synchronously, the JavaScript client object model was designed for asynchronous usage (see its executeQueryAsync method). To send our requests synchronously, we utilize the REST / OData interface in this post, and send the requests via the ajax function of jQuery.

To understand the original requirements and the configuration (field and list names, etc.), I suggest to read the first part first.

To enable using of jQuery selectors containing the dollar sign ($), we use the same escapeForJQuery helper function that we’ve created for the first part.

  1. var restrictedValues1 = ['Approved', 'Rejected'];
  2. var restrictedValues2 = ['Resubmit'];
  3.  
  4. var custom = custom || {};
  5.  
  6. custom.controlId = null;
  7.  
  8. var adminGroup = "MyGroup";
  9.  
  10. custom.escapeForJQuery = function (value) {
  11.     var newValue = value.replace(/\$/g, "\\$");
  12.     return newValue;
  13. }

Instead of simply wrapping the standard display template of choice fields (SPFieldChoice_Edit), the editFieldMethod function is responsible to get the HTML content of the field control, as it would be rendered without the customization by invoking the SPFieldChoice_Edit function, then we determine the group membership of the user by calling the synchronous isCurrentUserMemberOfGroup function (more about that a bit later), finally we alter the HTML content by hiding the adequate options by calling the hideOptions function (see it later as well).

  1. custom.editFieldMethod = function (ctx) {
  2.     var fieldSchema = ctx.CurrentFieldSchema;
  3.     custom.controlId = fieldSchema.Name + '_' + fieldSchema.Id + '_$DropDownChoice';
  4.     var html = SPFieldChoice_Edit(ctx);
  5.  
  6.     var isCurrentUserInGroup = custom.isCurrentUserMemberOfGroup(adminGroup);
  7.     if (isCurrentUserInGroup) {
  8.         html = custom.hideOptions(html, custom.controlId, restrictedValues1);
  9.     }
  10.     else {
  11.         html = custom.hideOptions(html, custom.controlId, restrictedValues2);
  12.     }
  13.  
  14.     return html;
  15. }

The hideOptions function loads the HTML source of the control into the DOM and removes the options that should be hidden for the given group. Finally it returns the HTML source of the altered control:

  1. custom.hideOptions = function (html, ctrlId, restrictedValues) {
  2.     var parsedHtml = $(html);
  3.     restrictedValues.forEach(function (rv) {
  4.         var selector = "#" + custom.escapeForJQuery(ctrlId) + " option[value='" + custom.escapeForJQuery(rv) + "']";
  5.         $(parsedHtml).find(selector).remove();
  6.     });
  7.     var result = $(parsedHtml).html();
  8.  
  9.     return result;
  10. }

The isCurrentUserMemberOfGroup function sends a synchronous REST request via the the ajax function of jQuery to determine the group membership of the current user:

  1. var serverUrl = String.format("{0}//{1}", window.location.protocol, window.location.host);
  2.  
  3. custom.isCurrentUserMemberOfGroup = function (groupName) {
  4.     var isMember = false;
  5.  
  6.     $.ajax({
  7.         url: serverUrl + "/_api/Web/CurrentUser/Groups?$select=LoginName",
  8.         type: "GET",
  9.         async: false,
  10.         contentType: "application/json;odata=verbose",
  11.         headers: {
  12.             "Accept": "application/json;odata=verbose",
  13.             "X-RequestDigest": $("#__REQUESTDIGEST").val()
  14.         },
  15.         complete: function (result) {
  16.             var response = JSON.parse(result.responseText);
  17.             if (response.error) {
  18.                 console.log(String.format("Error: {0}\n{1}", response.error.code, response.error.message.value));
  19.             }
  20.             else {
  21.                 var groups = response.d.results;
  22.                 groups.forEach(function (group) {
  23.                     var loginName = group.LoginName;
  24.                     console.log(String.format("Group name: {0}", loginName));
  25.                     if (groupName == loginName) {
  26.                         isMember = true;
  27.                     }
  28.                 });
  29.             }
  30.         }
  31.     });
  32.  
  33.     return isMember;
  34. }

In this case we simply register the editFieldMethod for both the ‘EditForm’ and for the ‘NewForm’ mode of the Status field, there is no need for the OnPostRender method:

  1. var customOverrides = {};
  2. customOverrides.Templates = {};
  3.  
  4. customOverrides.Templates.Fields = {
  5.     'Status': {
  6.         'EditForm': custom.editFieldMethod,
  7.         'NewForm': custom.editFieldMethod
  8.     }
  9. };
  10.  
  11. SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customOverrides);

The full source code of the rendering template introduced in this post:

  1. 'use strict';
  2.  
  3. (function () {
  4.  
  5.     var restrictedValues1 = ['Approved', 'Rejected'];
  6.     var restrictedValues2 = ['Resubmit'];
  7.  
  8.     var custom = custom || {};
  9.  
  10.     custom.controlId = null;
  11.  
  12.     var adminGroup = "MyGroup";
  13.  
  14.     custom.escapeForJQuery = function (value) {
  15.         var newValue = value.replace(/\$/g, "\\$");
  16.         return newValue;
  17.     }
  18.  
  19.     custom.hideOptions = function (html, ctrlId, restrictedValues) {
  20.         var parsedHtml = $(html);
  21.         restrictedValues.forEach(function (rv) {
  22.             var selector = "#" + custom.escapeForJQuery(ctrlId) + " option[value='" + custom.escapeForJQuery(rv) + "']";
  23.             $(parsedHtml).find(selector).remove();
  24.         });
  25.         var result = $(parsedHtml).html();
  26.  
  27.         return result;
  28.     }
  29.  
  30.     custom.editFieldMethod = function (ctx) {
  31.         var fieldSchema = ctx.CurrentFieldSchema;
  32.         custom.controlId = fieldSchema.Name + '_' + fieldSchema.Id + '_$DropDownChoice';
  33.         var html = SPFieldChoice_Edit(ctx);
  34.  
  35.         var isCurrentUserInGroup = custom.isCurrentUserMemberOfGroup(adminGroup);
  36.         if (isCurrentUserInGroup) {
  37.             html = custom.hideOptions(html, custom.controlId, restrictedValues1);
  38.         }
  39.         else {
  40.             html = custom.hideOptions(html, custom.controlId, restrictedValues2);
  41.         }
  42.  
  43.         return html;
  44.     }
  45.  
  46.     var serverUrl = String.format("{0}//{1}", window.location.protocol, window.location.host);
  47.  
  48.     custom.isCurrentUserMemberOfGroup = function (groupName) {
  49.         var isMember = false;
  50.  
  51.         $.ajax({
  52.             url: serverUrl + "/_api/Web/CurrentUser/Groups?$select=LoginName",
  53.             type: "GET",
  54.             async: false,
  55.             contentType: "application/json;odata=verbose",
  56.             headers: {
  57.                 "Accept": "application/json;odata=verbose",
  58.                 "X-RequestDigest": $("#__REQUESTDIGEST").val()
  59.             },
  60.             complete: function (result) {
  61.                 var response = JSON.parse(result.responseText);
  62.                 if (response.error) {
  63.                     console.log(String.format("Error: {0}\n{1}", response.error.code, response.error.message.value));
  64.                 }
  65.                 else {
  66.                     var groups = response.d.results;
  67.                     groups.forEach(function (group) {
  68.                         var loginName = group.LoginName;
  69.                         console.log(String.format("Group name: {0}", loginName));
  70.                         if (groupName == loginName) {
  71.                             isMember = true;
  72.                         }
  73.                     });
  74.                 }
  75.             }
  76.         });
  77.  
  78.         return isMember;
  79.     }
  80.  
  81.     var customOverrides = {};
  82.     customOverrides.Templates = {};
  83.  
  84.     customOverrides.Templates.Fields = {
  85.         'Status': {
  86.             'EditForm': custom.editFieldMethod,
  87.             'NewForm': custom.editFieldMethod
  88.         }
  89.     };
  90.  
  91.     SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customOverrides);
  92.  
  93. })();

Assuming your custom list is called PermBasedField, and both jQuery (in my case it is jquery-1.9.1.min.js) and our custom JavaScript rendering template (in my case it’s called permissionBasedFieldTemplate2.js) are stored in the root of the Site Assets library of the root web, you can register the template using the following PowerShell script:

$web = Get-SPWeb http://YourSharePointSite
$list = $web.Lists["PermBasedField"]

$field = $list.Fields.GetFieldByInternalName("Status")
$field.JSLink = "~sitecollection/SiteAssets/jquery-1.9.1.min.js|~sitecollection/SiteAssets/permissionBasedFieldTemplate2.js"
$field.Update()

Note, that (in contrast to the script introduced in the first part of this post) there is no need for the JSCOM JavaScript files (sp.runtime.js and sp.js) in this case.

Permission-based Rendering Templates, Part 1: The Asynchronous Solution

Filed under: CSR, JavaScript, jQuery, JSCOM, SP 2013 — Tags: , , , , — Peter Holpar @ 21:49

Recently I read a question on SharePoint StackExchange about how one can restrict the available options in a choice field based on the group membership of the current user. My answer was to create a custom client rendering templates (CSR) and set it via the JSLink property of the choice field. If you are new in the usage of custom rendering templates, you can find several superb introduction on the topic on the web, like this one. At the time of my answer I had no sample code ready to publish (honestly, I was rather surprised that I have not found any such example on the web), but in the meantime I prepared two various implementations for the same problem. In this post I describe the first possible approach, an asynchronous solution based on the JavaScript client object model (JSCOM) and jQuery. The other solution will be discussed in a later post.

Both approaches share the same custom list: it is a list having a standard Title field and choice field called Status that has three state options: ‘Approved’, ‘Rejected’ and ‘Resubmit’. If the current use is member of a specific SharePoint group (let’s say ‘MyGroup’), the options ‘Approved’ and ‘Rejected’ should be displayed in the editable mode (that means on ‘EditForm’ and on ‘NewForm’), otherwise only the option ‘Resubmit’.

In our JavaScript rendering template we define the custom namespace, that includes the member properties and methods of the template. The same editFieldMethod function will be used in both editable modes. It’s simply a wrapper around the standard display template of choice fields (SPFieldChoice_Edit), the single extra work it performs is to store the ID of the corresponding HTML element (select in this case) into a member property called controlId. The standard format of the Id is NameOfTheChoiceField_GuidOfTheChoiceField__$DropDownChoice, for example in my case it is Status_fb5a9aac-5fdb-442e-96ac-ab7161cc4208_$DropDownChoice. We store its value to be able to find the HTML element and it children option elements via jQuery later in our asynchronous callback method.

  1. var restrictedValues1 = ['Approved', 'Rejected'];
  2. var restrictedValues2 = ['Resubmit'];
  3.  
  4. var custom = custom || {};
  5.  
  6. custom.controlId = null;
  7.  
  8. custom.editFieldMethod = function (ctx) {
  9.     var fieldSchema = ctx.CurrentFieldSchema;
  10.     custom.controlId = fieldSchema.Name + '_' + fieldSchema.Id + '_$DropDownChoice';
  11.     var html = SPFieldChoice_Edit(ctx);
  12.     return html;
  13. }

We created a simple escapeForJQuery helper function to escape the dollar sign ($) in the ID, as I found IE 11 and  jQuery have issues with that character when used in selectors.

  1. custom.escapeForJQuery = function (value) {
  2.     var newValue = value.replace(/\$/g, "\\$");
  3.     return newValue;
  4. }

Note: you might have problems with the underscore (_) as well, especially if you use old browser versions, however I have not experienced such problems.In this case you should extend the escapeForJQuery helper function. See this guide:

Given this fact, authors who write CSS often attempt to employ the underscore in a similar fashion when creating class and ID names. This should not be done. Although underscores are, as of this writing, technically permitted in class and ID names, there are many historical and practical reasons why they should be avoided.

We utilize the escapeForJQuery function in our next helper function. The hideOptions method hides those options of a specific HTML element with ID specified in the ctrlId parameter that have any of the the values specified in the restrictedValues array parameter:

  1. custom.hideOptions = function (ctrlId, restrictedValues) {
  2.     restrictedValues.forEach(function (rv) {
  3.         var selector = "#" + custom.escapeForJQuery(ctrlId) + " option[value='" + custom.escapeForJQuery(rv) + "']";
  4.         $(selector).remove();
  5.     });        
  6. }

We use a third helper function called isCurrentUserMemberOfGroup to determine via CSOM if the current user is member of a group. This function – borrowed from this answer – has two parameters: the name of the group (groupName) and a callback method (OnComplete).

  1. custom.isCurrentUserMemberOfGroup = function (groupName, OnComplete) {
  2.  
  3.     var clientContext = new SP.ClientContext.get_current();
  4.     var currentUser = clientContext.get_web().get_currentUser();
  5.  
  6.     var userGroups = currentUser.get_groups();
  7.     clientContext.load(userGroups);
  8.  
  9.     clientContext.executeQueryAsync(OnSuccess, OnFailure);
  10.  
  11.     function OnSuccess(sender, args) {
  12.         var isMember = false;
  13.         var groupsEnumerator = userGroups.getEnumerator();
  14.         while (groupsEnumerator.moveNext()) {
  15.             var group = groupsEnumerator.get_current();
  16.             if (group.get_title() == groupName) {
  17.                 isMember = true;
  18.                 break;
  19.             }
  20.         }
  21.  
  22.         OnComplete(isMember);
  23.     }
  24.  
  25.     function OnFailure(sender, args) {
  26.         OnComplete(false);
  27.     }
  28. }

The isCurrentUserMemberOfGroup function is invoked by the applyPermissions function. In the callback function we hide the adequate options based on the group membership of the user.

  1. var adminGroup = "MyGroup";
  2.  
  3. custom.applyPermissions = function (ctx) {
  4.     custom.isCurrentUserMemberOfGroup(adminGroup, function (isCurrentUserInGroup) {
  5.         console.log("Current user is member of group '" + adminGroup + "': " + isCurrentUserInGroup);
  6.  
  7.         if (custom.controlId) {
  8.             if (isCurrentUserInGroup) {
  9.                 custom.hideOptions(custom.controlId, restrictedValues1);
  10.             }
  11.             else {
  12.                 custom.hideOptions(custom.controlId, restrictedValues2);
  13.             }
  14.         }
  15.     });
  16. };

In our rendering template we register the custom editing method editFieldMethod, and set the applyPermissions function to be called as OnPostRender:

  1. var customOverrides = {};
  2. customOverrides.Templates = {};
  3.  
  4. customOverrides.Templates.Fields = {
  5.     'Status': {
  6.         'EditForm': custom.editFieldMethod,
  7.         'NewForm': custom.editFieldMethod
  8.     }
  9. };
  10.  
  11. customOverrides.Templates.OnPostRender = custom.applyPermissions;
  12.  
  13. SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customOverrides);

The full source code of the rendering template introduced in this post:

  1. 'use strict';
  2.  
  3. (function () {
  4.  
  5.     var restrictedValues1 = ['Approved', 'Rejected'];
  6.     var restrictedValues2 = ['Resubmit'];
  7.  
  8.     var custom = custom || {};
  9.  
  10.     custom.controlId = null;
  11.  
  12.     custom.editFieldMethod = function (ctx) {
  13.         var fieldSchema = ctx.CurrentFieldSchema;
  14.         custom.controlId = fieldSchema.Name + '_' + fieldSchema.Id + '_$DropDownChoice';
  15.         var html = SPFieldChoice_Edit(ctx);
  16.         return html;
  17.     }
  18.  
  19.     custom.isCurrentUserMemberOfGroup = function (groupName, OnComplete) {
  20.  
  21.         var clientContext = new SP.ClientContext.get_current();
  22.         var currentUser = clientContext.get_web().get_currentUser();
  23.  
  24.         var userGroups = currentUser.get_groups();
  25.         clientContext.load(userGroups);
  26.  
  27.         clientContext.executeQueryAsync(OnSuccess, OnFailure);
  28.  
  29.         function OnSuccess(sender, args) {
  30.             var isMember = false;
  31.             var groupsEnumerator = userGroups.getEnumerator();
  32.             while (groupsEnumerator.moveNext()) {
  33.                 var group = groupsEnumerator.get_current();
  34.                 if (group.get_title() == groupName) {
  35.                     isMember = true;
  36.                     break;
  37.                 }
  38.             }
  39.  
  40.             OnComplete(isMember);
  41.         }
  42.  
  43.         function OnFailure(sender, args) {
  44.             OnComplete(false);
  45.         }
  46.     }
  47.  
  48.     custom.escapeForJQuery = function (value) {
  49.         var newValue = value.replace(/\$/g, "\\$");
  50.         return newValue;
  51.     }
  52.  
  53.     custom.hideOptions = function (ctrlId, restrictedValues) {
  54.         restrictedValues.forEach(function (rv) {
  55.             var selector = "#" + custom.escapeForJQuery(ctrlId) + " option[value='" + custom.escapeForJQuery(rv) + "']";
  56.             $(selector).remove();
  57.         });        
  58.     }
  59.  
  60.     var adminGroup = "MyGroup";
  61.  
  62.     custom.applyPermissions = function (ctx) {
  63.         custom.isCurrentUserMemberOfGroup(adminGroup, function (isCurrentUserInGroup) {
  64.             console.log("Current user is member of group '" + adminGroup + "': " + isCurrentUserInGroup);
  65.  
  66.             if (custom.controlId) {
  67.                 if (isCurrentUserInGroup) {
  68.                     custom.hideOptions(custom.controlId, restrictedValues1);
  69.                 }
  70.                 else {
  71.                     custom.hideOptions(custom.controlId, restrictedValues2);
  72.                 }
  73.             }
  74.         });
  75.     };
  76.     
  77.     var customOverrides = {};
  78.     customOverrides.Templates = {};
  79.  
  80.     customOverrides.Templates.Fields = {
  81.         'Status': {
  82.             'EditForm': custom.editFieldMethod,
  83.             'NewForm': custom.editFieldMethod
  84.         }
  85.     };
  86.  
  87.     customOverrides.Templates.OnPostRender = custom.applyPermissions;
  88.  
  89.     SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customOverrides);
  90.     
  91. })();

Assuming your custom list is called PermBasedField, and both jQuery (in my case it is jquery-1.9.1.min.js) and our custom JavaScript rendering template (in my case it’s called permissionBasedFieldTemplate.js) are stored in the root of the Site Assets library of the root web, you can register the template using the following PowerShell script:

$web = Get-SPWeb http://YourSharePointSite
$list = $web.Lists["PermBasedField"]

$field = $list.Fields.GetFieldByInternalName("Status")
$field.JSLink = "~sitecollection/_layouts/15/sp.runtime.js|~sitecollection/_layouts/15/sp.js|~sitecollection/SiteAssets/jquery-1.9.1.min.js|~sitecollection/SiteAssets/permissionBasedFieldTemplate.js"
$field.Update()

Stay tuned, the second part of the post including a synchronous approach should come soon.

August 20, 2016

Why can’t We Send E-Mails from the SharePoint JavaScript Client Object Model, and How to Enable this Feature

Filed under: JavaScript, JSCOM, Mails, SP 2013 — Tags: , , , — Peter Holpar @ 22:43

As you might know, we can send e-mails from the SharePoint managed client object model (see code sample below), but not from the JavaScript version of the client object model.

Note: This feature has its own limitations. For example, you can not send mails to any arbitrary external mail addresses, only to the SharePoint users, and you can not add attachments to the mails, just to name a few.

  1. using (var clientContext = new ClientContext("http://YourSharePointServer/&quot;))
  2. {
  3.     var ep = new EmailProperties();
  4.     ep.To = new List<string> { "user1@company.com", "user2@company.com" };
  5.     ep.From = "user3@company.com";
  6.     ep.Body = "body";
  7.     ep.Subject = "subject";
  8.     Utility.SendEmail(clientContext, ep);
  9.     clientContext.ExecuteQuery();
  10. }

However, if you would like to send mails using the JavaScript client object model, you find quickly, that there is no sendEmail method defined under the methods of the SP.Utilities.Utility class. That means, if you really have to send a mail from your web page using JavaScript, and would like to work only with the out-of-the-box features of SharePoint, you have to use the OData / REST interface, as illustrated by the code sample in this forum thread or see this one if you need additional mail headers.

But wait a minute. As far as I know, both the managed client object model and its JavaScript counterpart use the same server-side components and the same communication protocol between the server and client side. So what is that limitation in this case? Personally, I prefer to useing the JavaScript client object model to invoking the REST methods. Why should I mix them if my other components are written for the JavaScript client object model?

After having several questions on SharePoint StackExchange in the previous days regarding e-mail sending from JavaScript, I’ve decided to look behind the scenes.

As a first step, I searched for the JavaScript implementation of the SP.Utilities.EmailProperties and the SP.Utilities.Utility classes and found them in SP.debug.js (and in SP.js, of course), and really, there is no sendEmail method defined for the SP.Utilities.Utility class.

The mail sending for the client components is implemented on the servers side in the internal static SendEmail_Client method of  the Microsoft.SharePoint.Utilities.SPUtility class (Microsoft.SharePoint assembly). This method has the ClientCallableMethod attribute as follows:

[ClientCallableMethod(Name="SendEmail", OperationType=OperationType.Read, ClientLibraryTargets=ClientLibraryTargets.RESTful | ClientLibraryTargets.Silverlight | ClientLibraryTargets.DotNetFramework)]

You can see, that as the value of the ClientLibraryTargets property it does not define either ClientLibraryTargets.JavaScript or ClientLibraryTargets.All. It means, that it is not intended to be used from JavaScript.

In the rest of the post I show you a few alternatives, how to enable this missing functionality.

Note: The workarounds included in the post are provided “as is”, without any responsibility. Whether they work for you or not may depend on the patch level of your SharePoint environment, and any new installed patch may make a solution build on these workaround unusable. So I suggest you to not use this approach in a productive environment.

I’ve created a new web part page on my site, and added a Script Editor Web Part to it. I set the following content for the new web part:

/_layouts/15/sp.runtime.js
/_layouts/15/sp.js
/SiteAssets/sendMail.js

<button onclick="sendMail()" type="button">Send mail</button>

In the Site Assets library of the site I’ve created a new text file called sendMail.js, and edited its content.

After studying the existing static methods of the SP.Utilities.Utility class in SP.debug.js it was easy to implement the sendEmail method as well. We should have wait, while the loading of  the SP.js file has been finished, then extend the (at this time already) existing SP.Utilities.Utility class with the new method. The next snippet shows our code at this point:

  1. 'use strict';
  2.  
  3. function main() {  
  4.     SP.Utilities.Utility.sendEmail = function SP_Utilities_Utility$resolvePrincipal(context, properties) {
  5.         if (!context) {
  6.             throw Error.argumentNull('context');
  7.         }
  8.         var $v_0 = new SP.ClientActionInvokeStaticMethod(context, '{16f43e7e-bf35-475d-b677-9dc61e549339}', 'SendEmail', [properties]);
  9.  
  10.         context.addQuery($v_0);
  11.     };
  12. }
  13.  
  14. function sendMail() {
  15.     var ctx = SP.ClientContext.get_current();
  16.  
  17.     var emailProperties = new SP.Utilities.EmailProperties();
  18.     emailProperties.set_to(['user1@company.com', 'user2@company.com']);
  19.     emailProperties.set_from('user3@company.com');
  20.     emailProperties.set_body('body');
  21.     emailProperties.set_subject('subject');
  22.  
  23.     SP.Utilities.Utility.sendEmail(ctx, emailProperties);
  24.  
  25.     ctx.executeQueryAsync(
  26.                 function () {
  27.                     console.log("Mail sent");
  28.                 },
  29.                 function (sender, args) {
  30.                     console.log('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
  31.                 }
  32.             );
  33.  
  34. }
  35.  
  36.  
  37. SP.SOD.executeOrDelayUntilScriptLoaded(main, "sp.js");

Unfortunately, if you try out the page, and clicks the “Send mail” button, this code sends no mail, but you get an error instead:

Object doesn’t support property or method ‘get_bCC

The corresponding stack trace:

SP.DataConvert.invokeGetProperty [Line: 2, Col: 18240], sp.runtime.js
SP.DataConvert.writePropertiesToXml [Line: 2, Col: 11813], sp.runtime.js
SP.Utilities.EmailProperties.prototype.writeToXml [Line: 2, Col: 441169], sp.js
SP.DataConvert.writeValueToXmlElement [Line: 2, Col: 14393], sp.runtime.js
SP.ClientActionInvokeStaticMethod.prototype.$i_1 [Line: 2, Col: 30238], sp.runtime.js
SP.ClientActionInvokeStaticMethod [Line: 2, Col: 29671], sp.runtime.js
SP_Utilities_Utility$resolvePrincipal [Line: 8, Col: 9], sendMail.js
sendMail [Line: 23, Col: 5], sendMail.js
onclick [Line: 610, Col: 18], SendMailTest.aspx

If you check the property names of the SP.Utilities.EmailProperties class, you see that there are properties like BCC and CC. The corresponding getter and setter method definitions of the same class in the SP.debug.js file according to it have the name get_BCC / set_BCC and get_CC / set_CC.

The problem is, that the SP.DataConvert.invokeGetProperty mehtod calls a private method of the SP.DataConvert class, that – due to the name convention used in the JavaScript client object model – converts the property name BCC to bCC (and CC to cC), converting the first letter to lower case.

SP.DataConvert.$2V=function(a){ULSnd3:;return a.substr(0,1).toLowerCase()+a.substr(1)}    function(a){ULSnd3:;return a.substr(0,1).toLowerCase()+a.substr(1)}

What can we do? There are fortunately several options!

In the fist case, we simply create a new SP.Utilities.EmailProperties instance as earlier, then decorate the new instance in the AddMethods method with the getter / setter methods required by the SP.DataConvert.invokeGetProperty mehtod before sending the mail via the sendEmail method. In these new methods we simply wrap the original methods (the ones with the full uppercase property names).

  1. 'use strict';
  2.  
  3. function main() {  
  4.     SP.Utilities.Utility.sendEmail = function SP_Utilities_Utility$resolvePrincipal(context, properties) {
  5.         if (!context) {
  6.             throw Error.argumentNull('context');
  7.         }
  8.         var $v_0 = new SP.ClientActionInvokeStaticMethod(context, '{16f43e7e-bf35-475d-b677-9dc61e549339}', 'SendEmail', [properties]);
  9.  
  10.         context.addQuery($v_0);
  11.     };
  12. }
  13.  
  14. function AddMethods(emailProps) {
  15.     emailProps.get_bCC = function SP_Utilities_EmailProperties$get_bCC() {
  16.         return emailProps.get_BCC();
  17.     };
  18.     emailProps.set_bCC = function SP_Utilities_EmailProperties$set_bCC(value) {
  19.         emailProps.get_BCC(value);
  20.         return value;
  21.     };
  22.     emailProps.get_cC = function SP_Utilities_EmailProperties$get_cC() {
  23.         return emailProps.get_CC()
  24.     };
  25.     emailProps.set_cC = function SP_Utilities_EmailProperties$set_cC(value) {
  26.         emailProps.get_CC(value)
  27.         return value;
  28.     };
  29. }
  30.  
  31. function sendMail() {
  32.     var ctx = SP.ClientContext.get_current();
  33.  
  34.     var emailProperties = new SP.Utilities.EmailProperties();
  35.     AddMethods(emailProperties);
  36.  
  37.     emailProperties.set_to(['user1@company.com', 'user2@company.com']);
  38.     emailProperties.set_from('user3@company.com');
  39.     emailProperties.set_body('body');
  40.     emailProperties.set_subject('subject');
  41.  
  42.     SP.Utilities.Utility.sendEmail(ctx, emailProperties);
  43.  
  44.     ctx.executeQueryAsync(
  45.                 function () {
  46.                     console.log("Mail sent");
  47.                 },
  48.                 function (sender, args) {
  49.                     console.log('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
  50.                 }
  51.             );
  52.  
  53. }
  54.  
  55. SP.SOD.executeOrDelayUntilScriptLoaded(main, "sp.js");

This approach works, but you should invoke the AddMethods method for each of the SP.Utilities.EmailProperties instance you create.

As another option, we can take the source code of SP.Utilities.EmailProperties class from the SP.debug.js file, copy it to our own sendMail.js file, then replace the EmailProperties with EmailPropertiesCustom. Finally, fix the wrong method names.

  1. 'use strict';
  2.  
  3. SP.Utilities.EmailPropertiesCustom = function SP_Utilities_EmailPropertiesCustom() {
  4.     SP.Utilities.EmailPropertiesCustom.initializeBase(this);
  5. };
  6. SP.Utilities.EmailPropertiesCustom.prototype = {
  7.     $1u_1: null,
  8.     $22_1: null,
  9.     $C_1: null,
  10.     $24_1: null,
  11.     $2T_1: null,
  12.     $31_1: null,
  13.     $36_1: null,
  14.     get_additionalHeaders: function SP_Utilities_EmailPropertiesCustom$get_additionalHeaders() {
  15.         return this.$1u_1;
  16.     },
  17.     set_additionalHeaders: function SP_Utilities_EmailPropertiesCustom$set_additionalHeaders(value) {
  18.         this.$1u_1 = value;
  19.         return value;
  20.     },
  21.     get_bCC: function SP_Utilities_EmailPropertiesCustom$get_bCC() {
  22.         return this.$22_1;
  23.     },
  24.     set_bCC: function SP_Utilities_EmailPropertiesCustom$set_bCC(value) {
  25.         this.$22_1 = value;
  26.         return value;
  27.     },
  28.     get_body: function SP_Utilities_EmailPropertiesCustom$get_body() {
  29.         return this.$C_1;
  30.     },
  31.     set_body: function SP_Utilities_EmailPropertiesCustom$set_body(value) {
  32.         this.$C_1 = value;
  33.         return value;
  34.     },
  35.     get_cC: function SP_Utilities_EmailPropertiesCustom$get_cC() {
  36.         return this.$24_1;
  37.     },
  38.     set_cC: function SP_Utilities_EmailPropertiesCustom$set_cC(value) {
  39.         this.$24_1 = value;
  40.         return value;
  41.     },
  42.     get_from: function SP_Utilities_EmailPropertiesCustom$get_from() {
  43.         return this.$2T_1;
  44.     },
  45.     set_from: function SP_Utilities_EmailPropertiesCustom$set_from(value) {
  46.         this.$2T_1 = value;
  47.         return value;
  48.     },
  49.     get_subject: function SP_Utilities_EmailPropertiesCustom$get_subject() {
  50.         return this.$31_1;
  51.     },
  52.     set_subject: function SP_Utilities_EmailPropertiesCustom$set_subject(value) {
  53.         this.$31_1 = value;
  54.         return value;
  55.     },
  56.     get_to: function SP_Utilities_EmailPropertiesCustom$get_to() {
  57.         return this.$36_1;
  58.     },
  59.     set_to: function SP_Utilities_EmailPropertiesCustom$set_to(value) {
  60.         this.$36_1 = value;
  61.         return value;
  62.     },
  63.     get_typeId: function SP_Utilities_EmailPropertiesCustom$get_typeId() {
  64.         return '{fab1608d-fdfb-4c8c-bb0a-9b9cc3618a15}';
  65.     },
  66.     writeToXml: function SP_Utilities_EmailPropertiesCustom$writeToXml(writer, serializationContext) {
  67.         if (!writer) {
  68.             throw Error.argumentNull('writer');
  69.         }
  70.         if (!serializationContext) {
  71.             throw Error.argumentNull('serializationContext');
  72.         }
  73.         var $v_0 = ['AdditionalHeaders', 'BCC', 'Body', 'CC', 'From', 'Subject', 'To'];
  74.  
  75.         SP.DataConvert.writePropertiesToXml(writer, this, $v_0, serializationContext);
  76.         SP.ClientValueObject.prototype.writeToXml.call(this, writer, serializationContext);
  77.     },
  78.     initPropertiesFromJson: function SP_Utilities_EmailPropertiesCustom$initPropertiesFromJson(parentNode) {
  79.         SP.ClientValueObject.prototype.initPropertiesFromJson.call(this, parentNode);
  80.         var $v_0;
  81.  
  82.         $v_0 = parentNode.AdditionalHeaders;
  83.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  84.             this.$1u_1 = SP.DataConvert.fixupType(null, $v_0);
  85.             delete parentNode.AdditionalHeaders;
  86.         }
  87.         $v_0 = parentNode.BCC;
  88.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  89.             this.$22_1 = SP.DataConvert.fixupType(null, $v_0);
  90.             delete parentNode.BCC;
  91.         }
  92.         $v_0 = parentNode.Body;
  93.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  94.             this.$C_1 = $v_0;
  95.             delete parentNode.Body;
  96.         }
  97.         $v_0 = parentNode.CC;
  98.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  99.             this.$24_1 = SP.DataConvert.fixupType(null, $v_0);
  100.             delete parentNode.CC;
  101.         }
  102.         $v_0 = parentNode.From;
  103.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  104.             this.$2T_1 = $v_0;
  105.             delete parentNode.From;
  106.         }
  107.         $v_0 = parentNode.Subject;
  108.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  109.             this.$31_1 = $v_0;
  110.             delete parentNode.Subject;
  111.         }
  112.         $v_0 = parentNode.To;
  113.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  114.             this.$36_1 = SP.DataConvert.fixupType(null, $v_0);
  115.             delete parentNode.To;
  116.         }
  117.     }
  118. };
  119.  
  120. SP.Utilities.EmailPropertiesCustom.registerClass('SP.Utilities.EmailPropertiesCustom', SP.ClientValueObject);
  121.  
  122. function main() {  
  123.     SP.Utilities.Utility.sendEmail = function SP_Utilities_Utility$resolvePrincipal(context, properties) {
  124.         if (!context) {
  125.             throw Error.argumentNull('context');
  126.         }
  127.         var $v_0 = new SP.ClientActionInvokeStaticMethod(context, '{16f43e7e-bf35-475d-b677-9dc61e549339}', 'SendEmail', [properties]);
  128.  
  129.         context.addQuery($v_0);
  130.     };
  131. }
  132.  
  133. function sendMail() {
  134.     var ctx = SP.ClientContext.get_current();
  135.  
  136.     // note: we use our custom class in this case!
  137.     var emailProperties = new SP.Utilities.EmailPropertiesCustom();
  138.  
  139.     emailProperties.set_to(['user1@company.com', 'user2@company.com']);
  140.     emailProperties.set_from('user3@company.com');
  141.     emailProperties.set_body('body');
  142.     emailProperties.set_subject('subject');
  143.  
  144.     SP.Utilities.Utility.sendEmail(ctx, emailProperties);
  145.  
  146.     ctx.executeQueryAsync(
  147.                 function () {
  148.                     console.log("Mail sent");
  149.                 },
  150.                 function (sender, args) {
  151.                     console.log('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
  152.                 }
  153.             );
  154.  
  155. }
  156.  
  157. SP.SOD.executeOrDelayUntilScriptLoaded(main, "sp.js");

This approach works either, however you must not forget to create an instance of the SP.Utilities.EmailPropertiesCustom class instead of an SP.Utilities.EmailProperties instance, and pass it as a parameter when invoking the sendEmail method.

In the last approach we take the source code of SP.Utilities.EmailProperties class from the SP.debug.js file, copy it to our own sendMail.js file again. This time, however, we don’t change the class name. As this class is already registered earlier in the SP.js, we would get an error like this:

SCRIPT5022: Sys.InvalidOperationException: Type SP.Utilities.EmailProperties has already been registered. The type may be defined multiple times or the script file that defines it may have already been loaded. A possible cause is a change of settings during a partial update.

To avoid this error, we should first remove the existing registration. This is possible by this line of code:

Sys.__registeredTypes[‘SP.Utilities.EmailProperties’] = false;

The code snippet for the third option:

  1. 'use strict';
  2.  
  3. SP.Utilities.EmailProperties = function SP_Utilities_EmailProperties() {
  4.     SP.Utilities.EmailProperties.initializeBase(this);
  5. };
  6. SP.Utilities.EmailProperties.prototype = {
  7.     $1u_1: null,
  8.     $22_1: null,
  9.     $C_1: null,
  10.     $24_1: null,
  11.     $2T_1: null,
  12.     $31_1: null,
  13.     $36_1: null,
  14.     get_additionalHeaders: function SP_Utilities_EmailProperties$get_additionalHeaders() {
  15.         return this.$1u_1;
  16.     },
  17.     set_additionalHeaders: function SP_Utilities_EmailProperties$set_additionalHeaders(value) {
  18.         this.$1u_1 = value;
  19.         return value;
  20.     },
  21.     get_bCC: function SP_Utilities_EmailProperties$get_bCC() {
  22.         return this.$22_1;
  23.     },
  24.     set_bCC: function SP_Utilities_EmailProperties$set_bCC(value) {
  25.         this.$22_1 = value;
  26.         return value;
  27.     },
  28.     get_body: function SP_Utilities_EmailProperties$get_body() {
  29.         return this.$C_1;
  30.     },
  31.     set_body: function SP_Utilities_EmailProperties$set_body(value) {
  32.         this.$C_1 = value;
  33.         return value;
  34.     },
  35.     get_cC: function SP_Utilities_EmailProperties$get_cC() {
  36.         return this.$24_1;
  37.     },
  38.     set_cC: function SP_Utilities_EmailProperties$set_cC(value) {
  39.         this.$24_1 = value;
  40.         return value;
  41.     },
  42.     get_from: function SP_Utilities_EmailProperties$get_from() {
  43.         return this.$2T_1;
  44.     },
  45.     set_from: function SP_Utilities_EmailProperties$set_from(value) {
  46.         this.$2T_1 = value;
  47.         return value;
  48.     },
  49.     get_subject: function SP_Utilities_EmailProperties$get_subject() {
  50.         return this.$31_1;
  51.     },
  52.     set_subject: function SP_Utilities_EmailProperties$set_subject(value) {
  53.         this.$31_1 = value;
  54.         return value;
  55.     },
  56.     get_to: function SP_Utilities_EmailProperties$get_to() {
  57.         return this.$36_1;
  58.     },
  59.     set_to: function SP_Utilities_EmailProperties$set_to(value) {
  60.         this.$36_1 = value;
  61.         return value;
  62.     },
  63.     get_typeId: function SP_Utilities_EmailProperties$get_typeId() {
  64.         return '{fab1608d-fdfb-4c8c-bb0a-9b9cc3618a15}';
  65.     },
  66.     writeToXml: function SP_Utilities_EmailProperties$writeToXml(writer, serializationContext) {
  67.         if (!writer) {
  68.             throw Error.argumentNull('writer');
  69.         }
  70.         if (!serializationContext) {
  71.             throw Error.argumentNull('serializationContext');
  72.         }
  73.         var $v_0 = ['AdditionalHeaders', 'BCC', 'Body', 'CC', 'From', 'Subject', 'To'];
  74.  
  75.         SP.DataConvert.writePropertiesToXml(writer, this, $v_0, serializationContext);
  76.         SP.ClientValueObject.prototype.writeToXml.call(this, writer, serializationContext);
  77.     },
  78.     initPropertiesFromJson: function SP_Utilities_EmailProperties$initPropertiesFromJson(parentNode) {
  79.         SP.ClientValueObject.prototype.initPropertiesFromJson.call(this, parentNode);
  80.         var $v_0;
  81.  
  82.         $v_0 = parentNode.AdditionalHeaders;
  83.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  84.             this.$1u_1 = SP.DataConvert.fixupType(null, $v_0);
  85.             delete parentNode.AdditionalHeaders;
  86.         }
  87.         $v_0 = parentNode.BCC;
  88.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  89.             this.$22_1 = SP.DataConvert.fixupType(null, $v_0);
  90.             delete parentNode.BCC;
  91.         }
  92.         $v_0 = parentNode.Body;
  93.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  94.             this.$C_1 = $v_0;
  95.             delete parentNode.Body;
  96.         }
  97.         $v_0 = parentNode.CC;
  98.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  99.             this.$24_1 = SP.DataConvert.fixupType(null, $v_0);
  100.             delete parentNode.CC;
  101.         }
  102.         $v_0 = parentNode.From;
  103.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  104.             this.$2T_1 = $v_0;
  105.             delete parentNode.From;
  106.         }
  107.         $v_0 = parentNode.Subject;
  108.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  109.             this.$31_1 = $v_0;
  110.             delete parentNode.Subject;
  111.         }
  112.         $v_0 = parentNode.To;
  113.         if (!SP.ScriptUtility.isUndefined($v_0)) {
  114.             this.$36_1 = SP.DataConvert.fixupType(null, $v_0);
  115.             delete parentNode.To;
  116.         }
  117.     }
  118. };
  119.  
  120. // re-register the type
  121. // to avoid the error
  122. // SCRIPT5022: Sys.InvalidOperationException: Type SP.Utilities.EmailProperties has already been registered. The type may be defined multiple times or the script file that defines it may have already been loaded. A possible cause is a change of settings during a partial update.
  123. // we should first remove the existing registration
  124. Sys.__registeredTypes['SP.Utilities.EmailProperties'] = false;
  125. SP.Utilities.EmailProperties.registerClass('SP.Utilities.EmailProperties', SP.ClientValueObject);
  126.  
  127. function main() {  
  128.     SP.Utilities.Utility.sendEmail = function SP_Utilities_Utility$resolvePrincipal(context, properties) {
  129.         if (!context) {
  130.             throw Error.argumentNull('context');
  131.         }
  132.         var $v_0 = new SP.ClientActionInvokeStaticMethod(context, '{16f43e7e-bf35-475d-b677-9dc61e549339}', 'SendEmail', [properties]);
  133.  
  134.         context.addQuery($v_0);
  135.     };
  136. }
  137.  
  138. function sendMail() {
  139.     var ctx = SP.ClientContext.get_current();
  140.     
  141.     var emailProperties = new SP.Utilities.EmailProperties();
  142.     emailProperties.set_to(['user1@company.com', 'user2@company.com']);
  143.     emailProperties.set_from('user3@company.com');
  144.     emailProperties.set_body('body');
  145.     emailProperties.set_subject('subject');
  146.  
  147.     SP.Utilities.Utility.sendEmail(ctx, emailProperties);
  148.  
  149.     ctx.executeQueryAsync(
  150.                 function () {
  151.                     console.log("Mail sent");
  152.                 },
  153.                 function (sender, args) {
  154.                     console.log('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
  155.                 }
  156.             );
  157.  
  158. }
  159.  
  160. SP.SOD.executeOrDelayUntilScriptLoaded(main, "sp.js");

Although it is possible the less supported option (if there are different levels of supportability at all) from the three options discussed in the post, I prefer this last one, as its usage is the most transparent for the developer. One can use the SP.Utilities.EmailProperties class and there is no need for invoking helper methods.

Note: Be aware, that when using one of the last two options, you should call the get_bCC / set_bCC and get_cC / set_cC methods instead of the get_BCC / set_BCC and get_CC / set_CC methods if you need to read / set the BCC / CC properties. In the case of the first option however, you can call both of the methods with first uppercase letter, and the methods with first lowercase letter.

July 26, 2016

Creating Project Server Enterprise Resources via REST

Filed under: Enterprise Resources, JavaScript, PS 2013, REST — Tags: , , , — Peter Holpar @ 21:27

Recently I’ve got a question on this blog about how to create Project Server enterprise resources using the REST interface. Although I consider this task to be a rather common requirement, there are really very few (if any) practical information about that on the web.

In this post I show you how to perform this operation using C# and JavaScript as well.

In the C# example I assume you have the following using statement in your code:

using System.Net;

Furthermore, it is assumed you have a string field called baseUrl in your class that contains the URL of your PWA site.

private readonly string baseUrl = "http://YourProjectServer/PWA&quot;;

I’m using some helper methods, a few of them are borrowed from the code of this SharePoint StackExchange forum thread.

First we need to get a form digest value we will use in our later POST requests. This task is performed by the GetFormDigestValue method.

  1. private string GetFormDigestValue()
  2. {
  3.     string digest = null;
  4.  
  5.     HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(this.baseUrl + "/_api/contextinfo");
  6.     request.Method = "POST";
  7.     request.ContentType = "application/json;odata=verbose";
  8.     request.UseDefaultCredentials = true;
  9.     var postBody = string.Empty;
  10.     request.ContentLength = postBody.Length;
  11.  
  12.     byte[] postData = Encoding.ASCII.GetBytes(postBody);
  13.  
  14.     using (Stream requestStream = request.GetRequestStream())
  15.     {
  16.         requestStream.Write(postData, 0, postData.Length);
  17.         requestStream.Close();
  18.  
  19.         HttpWebResponse response = (HttpWebResponse)request.GetResponse();
  20.         using (Stream responseStream = response.GetResponseStream())
  21.         {
  22.             var encoding = ASCIIEncoding.ASCII;
  23.             using (var reader = new StreamReader(response.GetResponseStream(), encoding))
  24.             {
  25.                 // parse the ContextInfo response
  26.                 var resultXml = XDocument.Parse(reader.ReadToEnd());
  27.  
  28.                 // get the form digest value
  29.                 var d = from e in resultXml.Descendants()
  30.                         where e.Name == XName.Get("FormDigestValue", "http://schemas.microsoft.com/ado/2007/08/dataservices&quot;)
  31.                         select e;
  32.                 digest = d.First().Value;
  33.             }
  34.         }
  35.     }
  36.  
  37.     return digest;
  38. }

The POST requests will be prepared by the PreparePostRequest method before execution:

  1. private HttpWebRequest PreparePostRequest(string requestPath, string formDigestValue, string postBody)
  2. {
  3.     HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(this.baseUrl + requestPath);
  4.     request.Method = "POST";
  5.     request.ContentType = "application/json;odata=verbose";
  6.     request.Accept = "application/json;odata=verbose";
  7.     request.Headers.Add("X-RequestDigest", formDigestValue);
  8.     request.UseDefaultCredentials = true;
  9.     request.ContentLength = postBody.Length;
  10.  
  11.     byte[] postData = Encoding.ASCII.GetBytes(postBody);
  12.  
  13.     System.IO.Stream requestStream = request.GetRequestStream();
  14.     requestStream.Write(postData, 0, postData.Length);
  15.     requestStream.Close();
  16.  
  17.     return request;
  18. }

The ExecuteAuthorizedPostRequest gets the form digest and prepares the request using the other two methods, finally sends the request and reads the response returned by the server.

  1. private HttpWebResponse ExecuteAuthorizedPostRequest(string requestPath, string postBody)
  2. {
  3.     string formDigestValue = GetFormDigestValue();
  4.     HttpWebRequest request = PreparePostRequest(requestPath, formDigestValue, postBody);
  5.  
  6.     HttpWebResponse response = (HttpWebResponse)request.GetResponse();
  7.  
  8.     return response;
  9. }

Using the methods above, we can concentrate on the actual “mission”, creating a new enterprise resource. In the code below I’ve included three different versions (the first two of them are commented out).

The first one creates an enterprise resource by setting its Name property only. By default, the new resources are created having EnterpriseResourceType.Work as their ResourceType property.

In the second example we create an enterprise resource by setting its Name property and its ResourceType property to EnterpriseResourceType.Material.

In the third case we create an enterprise resource by setting its Name property and its CostCenter property.

  1. public void CreateEnterpriseResource()
  2. {
  3.     string requestPath = "/_api/ProjectServer/EnterpriseResources";
  4.     // creating a new resource setting only its name
  5.     //string postBody = "{ '__metadata': { 'type': 'PS.EnterpriseResource' }, 'Name':'New Resource' }";
  6.     // creating a new resource setting its name and type ('Material' in this case)
  7.     //string postBody = string.Format("{{ '__metadata': {{ 'type': 'PS.EnterpriseResource' }}, 'Name':'New Material Resource', 'ResourceType': '{0}' }}", (int)EnterpriseResourceType.Material);
  8.     // creating a new resource setting its name and cost center
  9.     string postBody = string.Format("{{ '__metadata': {{ 'type': 'PS.EnterpriseResource' }}, 'Name':'New CC Resource', 'CostCenter': '{0}' }}", "Your Cost Center");
  10.     
  11.     var resp = ExecuteAuthorizedPostRequest(requestPath, postBody);
  12. }

Note, that the type of the object we use in the examples is PS.EnterpriseResource and not PS.EnterpriseResourceCreationInformation one would use to create a new resource via the client object model. Since the EnterpriseResourceCreationInformation object has only a limited set of properties provided by the EnterpriseResource object, we can set a lot more properties on creating the resource, than we could using the client object model. For example, in the last example above we set the cost center of the enterprise resource when creating it. It would not be possible via the EnterpriseResourceCreationInformation object.

If you need to create the resources from JavaScript on a web page instead of C#, it is possible as well.

First, we define a String.format helper function:

  1. String.format = (function () {
  2.     // The string containing the format items (e.g. "{0}")
  3.     // will and always has to be the first argument.
  4.     var theString = arguments[0];
  5.  
  6.     // start with the second argument (i = 1)
  7.     for (var i = 1; i < arguments.length; i++) {
  8.         // "gm" = RegEx options for Global search (more than one instance)
  9.         // and for Multiline search
  10.         var regEx = new RegExp("\\{" + (i – 1) + "\\}", "gm");
  11.         theString = theString.replace(regEx, arguments[i]);
  12.     }
  13.  
  14.     return theString;
  15. });

The JavaScript equivalent (using jQuery) our three examples we saw above in C# the code:

  1. var serverUrl = String.format("{0}//{1}", window.location.protocol, window.location.host);
  2. var pwaServerRelUrl = "/PWA";
  3.  
  4. function startScript() {
  5.     $.ajax({
  6.         url: serverUrl + pwaServerRelUrl + "/_api/ProjectServer/EnterpriseResources",
  7.         type: "POST",
  8.         contentType: "application/json;odata=verbose",
  9.         //data: JSON.stringify(item),
  10.         // creating a new resource setting only its name
  11.         //data: "{ '__metadata': { 'type': 'PS.EnterpriseResource' }, 'Name':'New Resource JS' }",
  12.         // creating a new resource setting its name and type ('Material' in this case)
  13.         //data: "{ '__metadata': { 'type': 'PS.EnterpriseResource' }, 'Name':'New Material Resource JS', 'ResourceType': '2' }",
  14.         // creating a new resource setting its name and cost center
  15.         data: "{ '__metadata': { 'type': 'PS.EnterpriseResource' }, 'Name':'New CC Resource JS', 'CostCenter': 'Your Cost Center' }",
  16.         headers: {
  17.             "Accept": "application/json;odata=verbose",
  18.             "X-RequestDigest": $("#__REQUESTDIGEST").val()
  19.         },
  20.         complete: function (result) {
  21.             var response = JSON.parse(result.responseText);
  22.             if (response.error) {
  23.                 console.log(String.format("Error: {0}\n{1}", response.error.code, response.error.message.value));
  24.             }
  25.             else {
  26.                 console.log(String.format("Resource created with ID: {0}", response.d.Id));
  27.             }
  28.         }
  29.     });
  30. }
  31.  
  32. $(document).ready(startScript);

Assuming this script is saved in the file CreateResource.js in the Site Assets library of the PWA site, and the jquery-1.9.1.min.js can be found in that library as well, you can add a Script Editor web part to your page, and include these two lines in the web part to inject the resource creation functionality into the page:

/PWA/SiteAssets/jquery-1.9.1.min.js
/PWA/SiteAssets/CreateResource.js

Of course, you typically don’t want such automatic resource creation on page load in a real-world scenario. Instead that, you should probably add some text fields for the resource properties (like name, cost center) and a button a page, to submit the data and create the resources using the parameters the user entered in the text fields. The plain goal of the example above is to show how the request for creating a new enterprise resource looks like, and how to send it to the server.

May 29, 2016

Reference Default Calendar Scopes in a URL

Filed under: JavaScript, SP 2013, Views — Tags: , , — Peter Holpar @ 05:41

As you know, you can create calendar views with various default scopes (e.g. Day / Week / Month, see screenshot below).

image

It means a single .aspx page per view, for example CalendarDay.aspx, CalendarWeek.aspx, CalendarMonth.aspx. You can then link these pages in HTML hyperlinks or send a link in mail by referring the given page.

But if you try to avoid creating and administering these three views for each of your calendars, is it possible to have only a single, universal page (like Calendar.aspx), and still have the ability to create a URL for the page that determines, with which scope the calendar would be displayed by default?

Unfortunately, it is not possible out-of-the-box, but with some scripting we can find a way.

Add a Script Editor Web Part (category: Media and Content) to the calendar view page after the calendar itself. Include the following script in the web part:

  1. <script type="text/javascript">
  2.  
  3. function getQueryStringParameter(paramToRetrieve) {
  4.     var params =
  5.     document.URL.split("?")[1].split("&");
  6.     var strParams = "";
  7.     for (var i = 0; i < params.length; i = i + 1) {
  8.         var singleParam = params[i].split("=");
  9.         if (singleParam[0] == paramToRetrieve)
  10.             return singleParam[1];
  11.     }
  12. }
  13.  
  14. var timer;
  15.  
  16. function registerMoveView() {
  17.  
  18.     var cirInstance = SP.UI.ApplicationPages.CalendarInstanceRepository.firstInstance();
  19.  
  20.     if (cirInstance) {
  21.         MoveView(startView);
  22.         window.clearInterval(timer);
  23.     }
  24.     else if (!timer) {
  25.         timer = window.setInterval(registerMoveView, 100);
  26.     }
  27. }
  28.  
  29. var viewNames = ["month", "week", "day"];
  30.  
  31. var startView = getQueryStringParameter("StartView")
  32.  
  33. if (viewNames.indexOf(startView) != -1) {
  34.     SP.SOD.executeOrDelayUntilScriptLoaded(registerMoveView, "sp.ui.applicationpages.calendar.js");
  35. }
  36.  
  37. </script>

After you save the changes on the page, one can access the calendar with the daily scope using a URL like this:

http://YourSharePoint/subweb/Lists/Calendar/calendar.aspx?StartView=day

One can access the monthly and weekly scopes as well via URL, simply by using the StartView query string values “month” and “week” respectively.

Note 1: The query string values “month”, “week” and “day” are strictly case sensitive, using a value like “Day” displays the default scope defined for the view (see the screenshot above).

Note 2: The sample above assumes you had a single calendar view on your you page. If you happen to have more, it would affect only the first one, see call to the firstInstance method in the script.

Note 3: The calendar instance is first available in the script after the real default scope completely rendered by the browser. We introduced a timer to overcome that issue, but if your browser is slow, you can still experience a blinking effect when switching to the new “default” scope, the one you selected via the StartView query string parameter.

February 15, 2016

Highlighting Closed Risks by Setting Their Color

Filed under: Client-side rendering, JavaScript, SP 2013 — Tags: , , — Peter Holpar @ 23:48

Just after I implemented a solution to display closed risks using strikethrough text, the users suddenly had a new idea. They meant it would be even better, if the whole row, I mean the text of each fields would be displayed grayed out for the closed risks in the list view.

First I thought it should be rather easy, as in the case we should set the background color of the row depending of a field value as described here and here, but I was wrong. So what’s the difference between setting the background color vs. setting the text color, what makes it to be a bit more complicated the latter one?

The problem is, that the cells of the table (the TD HTML elements) that build up the list view already have typically a color defined in the CSS classes they are decorated with (like ms-vb2, ms-vb-title for the Title field, ms-vb-user for the field type Person or Group, etc.). And since the color defined in the style of the elements itself (in this case TD) has a priority, we cannot override it simply by defining a style in the parent (in this case TR) element. In the case of the background color samples referenced above, the background color defined on the row level (TR) was simply inherited to the cell level (TD), as it was not explicitly defined on the TD level.

The following screenshot illustrates the list view before the customizations:

image

How to solve the situation? We could still define the CSS rules necessary to override the default colors for the selected rows. Let’s see how to achieve that!

In this case I utilized jQuery to simplify DOM search and manipulation.

I decorated the rows representing closed risk items with a custom class closedRiskRow:

if (rows[i]["Status"] == "(3) Closed") {
    var rowId = GenerateIIDForListItem(ctx, rows[i]);
    jQuery(jq(rowId)).addClass("closedRiskRow");
}

In the above code I use the jq helper function (see description here), since the Ids of the TR elements contain commas, that is interpreted as CSS notation:

function jq(myid) {
    return "#" + myid.replace(/(:|\.|\[|\]|,)/g, \\$1);
}

I injected the styles dynamically on document load:

jQuery(document).ready(function () {
    jQuery("<style>" + closedRiskRowStyle + "</style>").appendTo("head");

});

The styles are defined using the MultiString helper function, borrowed from Muawiyah Shannak, see this example.

var MultiString = function (f) {
    return f.toString().split(‘\n’).slice(1, -1).join(‘\n’);
}

var closedRiskRowStyle = MultiString(function () {/**
.closedRiskRow > td {
    color: lightgray; 
}

.closedRiskRow > td a.ms-subtleLink {
    color: lightgray; 
}

.closedRiskRow > td a.ms-listlink {
    color: lightgray;
    text-decoration: line-through;  
}
**/
});

The first CSS rule above formats the standard cells, the second one the field type Person or Group, in this case Assigned To field, and the last one is responsible for the Title field, including the strikethrough formatting we already had in the last post.

The full code is included here for your convenience:

  1. var MultiString = function (f) {
  2.     return f.toString().split('\n').slice(1, -1).join('\n');
  3. }
  4.  
  5. var closedRiskRowStyle = MultiString(function () {/**
  6. .closedRiskRow > td {
  7.     color: lightgray;  
  8. }
  9.  
  10. .closedRiskRow > td a.ms-subtleLink {
  11.     color: lightgray;  
  12. }
  13.  
  14. .closedRiskRow > td a.ms-listlink {
  15.     color: lightgray;
  16.     text-decoration: line-through;   
  17. }
  18. **/
  19. });
  20.  
  21. function jq(myid) {
  22.     return "#" + myid.replace(/(:|\.|\[|\]|,)/g, "\\$1");
  23. }
  24.  
  25. (function () {
  26.     if (typeof window.CompletedRiskTemplate == "object") {
  27.         return;
  28.     }
  29.  
  30.     window.CompletedRiskTemplate = {
  31.         HighLightRow: function (inCtx) {
  32.             jQuery(document).ready(function () {
  33.                 jQuery("<style>" + closedRiskRowStyle + "</style>").appendTo("head");
  34.  
  35.                 var rows = inCtx.ListData.Row;
  36.                 if (rows) {
  37.                     for (var i = 0; i < rows.length; i++) {
  38.                         if (rows[i]["Status"] == "(3) Closed") {
  39.                             var rowId = GenerateIIDForListItem(ctx, rows[i]);
  40.                             jQuery(jq(rowId)).addClass("closedRiskRow");
  41.                         }
  42.                     }
  43.                 }
  44.             });
  45.         }
  46.     };
  47.     function _registerCompletedRiskHighLightRowTemplate() {
  48.         var HighLightRowContext = {
  49.             "OnPostRender": window.CompletedRiskTemplate.HighLightRow
  50.         };
  51.  
  52.         SPClientTemplates.TemplateManager.RegisterTemplateOverrides(HighLightRowContext);
  53.     }
  54.     ExecuteOrDelayUntilScriptLoaded(_registerCompletedRiskHighLightRowTemplate, 'clienttemplates.js');
  55. })();

I deployed the .js file to a path under the layout folder as /YourHive/js/highlightClosedRisks.js, and the jquery-1.9.1.min.js to the same folder, then registered the scripts using the following PowerShell code:

$web = Get-SPWeb http://YourProjServer/PWA/Proj1
$list = $web.Lists["Risks"]

$field = $list.Fields.GetFieldByInternalName("LinkTitle")
$field.JSLink = "~sitecollectionlayouts/YourHive/js/jquery-1.9.1.min.js|~sitecollectionlayouts/YourHive/js/highlightClosedRisks.js"
$field.Update()

After the customizations the closed risk is displayed in gray, the title of the risk is with a strikethrough:

image

February 9, 2016

Display Closed Risks Using Strikethrough Text on Project Server

As you probably have already seen, the name of the closed tasks (the ones having 100% completeness) is displayed using a strikethrough text in the All Tasks view of a task list in SharePoint. For example, from the tasks below, only Task 2 is 100 % complete.

image

Our users would like to have the same functionality in the Risks list on Project Server project sites, but out of the box, the title of the closed risks (ones having Status = "(3) Closed") is displayed without strikethrough, using the same formatting as any other risks:

image

Note: I assume you are familiar with client-side rendering. If not, and would like to understand how our solution works, I suggest you to read about it first, for example in the excellent post of Chris O’Brien.

After a short research, I found that this functionality of the Task lists is implemented in 15\TEMPLATE\LAYOUTS\hierarchytaskslist.debug.js. See the CompletedTitleTemplate template in that .js file.

Based on that template it was easy to implement the required functionality:

  1. (function () {
  2.     if (typeof window.CompletedRiskTitleTemplate == "object") {
  3.         return;
  4.     }
  5.     window.CompletedRiskTitleTemplate = {
  6.         RenderTitleField: function (inCtx, field, listItem, listSchema) {
  7.             var titleHtml = ComputedFieldWorker[field.Name](inCtx, field, listItem, listSchema);
  8.  
  9.             var result = (listItem["Status"] == "(3) Closed") ?
  10.                  '<span style="text-decoration: line-through">' + titleHtml + '</span>' :
  11.                  titleHtml;
  12.  
  13.             return result;
  14.         }
  15.     };
  16.     function _registerCompletedRiskTitleTemplate() {
  17.         var TitleFieldContext = {
  18.             Templates: {
  19.                 Fields: {
  20.                     'LinkTitle': {
  21.                         'View': window.CompletedRiskTitleTemplate.RenderTitleField
  22.                     }
  23.                 },
  24.                 ListTemplateType: 1101
  25.             }
  26.         };
  27.  
  28.         SPClientTemplates.TemplateManager.RegisterTemplateOverrides(TitleFieldContext);
  29.     }
  30.     ExecuteOrDelayUntilScriptLoaded(_registerCompletedRiskTitleTemplate, 'clienttemplates.js');
  31. })();

Note, that in this case we are using ListTemplateType 1101 for the Risks list instead of the value 171 for the original Task list type (Tasks with Timeline and Hierarchy to be exact). We get this list template value using the BaseTemplate property of our Risks list.

To ensure that the script is loaded on all views that include the Title field, we should set the JSLink property of the field with InternalName LinkTitle”.

Assuming you deployed your .js file to a path under the layout folder as /YourHive/js/strikeThroughClosedRisks.js, you can register your script using the following PowerShell code:

$web = Get-SPWeb http://YourProjServer/PWA/Proj1
$list = $web.Lists["Risks"]

$field = $list.Fields.GetFieldByInternalName("LinkTitle")
$field.JSLink = "~sitecollectionlayouts/YourHive/js/strikeThroughClosedRisks.js"
$field.Update()

Of course, this script affects only the web site of the project Proj1. If you would like to deploy it to all of your projects, you should iterate through the project web sites, but even better, you can prepare a project web site template based on this PWS in advance as described in my post last year, and use this template for your projects.

After successfully deploying our script, the text of the Title field of the closed risk is display using a strikethrough:

image

July 6, 2015

Accessing and Manipulating Property Bags via the ECMAScript Client Object Model

Recently I work a lot with web applications implemented on the client side with JavaScript, mostly using the AngularJS library. Rather often should I build the application logic on the values stored in the property bags of the web objects, so I decided to sum up the experience I made in this field.

Note: A similar blog entry discussing the same topic can be found here. It might be useful to read that one as well, but I include additional info in my entry as well.

Note 2: The code samples in my post are borrowed from our custom AngularJS service, but the bulk of them should be reusable for any kind of JavaScript solution.

The first example shows how to retrieve the property values:

  1. this.readSettings = function ($scope) {
  2.     var deferred = $q.defer();
  3.  
  4.     var ctx = SP.ClientContext.get_current();
  5.  
  6.     var web = ctx.get_web();
  7.     var props = web.get_allProperties();
  8.     ctx.load(props);
  9.  
  10.     ctx.executeQueryAsync(
  11.         function () {
  12.             // you receive an error if the property is not defined for the web:
  13.             // The property or field has not been initialized. It has not been requested or the request has not been executed. It may need to be explicitly requested.
  14.             var yourProperty = props.get_item("YourProperty");
  15.             // or alternativelyyou can use
  16.             //var allProps = props.get_fieldValues();
  17.             //var yourProperty = allProps.YourProperty;
  18.             // in this second case you can  check, if the property is defined …
  19.             //if (typeof (yourProperty) == "undefined") {
  20.             //    console.log("The property is undefined");
  21.             //}
  22.             //…or iterate through all the properties
  23.             //for (var property in allProps) {
  24.             //    if (allProps.hasOwnProperty(property)) {
  25.             //        console.log(String.format("{0}: {1}", property, allProps[property]));
  26.             //    }
  27.             //}
  28.  
  29.             deferred.resolve(
  30.                 {
  31.                     projectId: projectId
  32.                 });
  33.         },
  34.         function (sender, args) {
  35.             deferred.reject('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
  36.         }
  37.     );
  38.  
  39.     return deferred.promise;
  40. };

If you trace the network traffic with Fiddler, you will capture the following (or similar) request-response:

image

As you can see, all of the properties from the bag are returned by the server, they are in the form of simple property name – property value pairs (see response for Query with Id=6).

When you already have the response from the server, there are two different methods to get the value of a specific property. There is a very important difference between the two versions (get_item method vs. get_fieldValues method). If the property is undefined in the property bag, you receive an error, if you would like to read the value via props.get_item("YourProperty"):

The property or field has not been initialized. It has not been requested or the request has not been executed. It may need to be explicitly requested.

However, if you access the property via the get_fieldValues method, you don’t get the exception, even if there is no such property in the property bag. In this case the property remain simply undefined, so you can check its existence via

var allProps = props.get_fieldValues();
if (typeof (allProps.YourProperty) == "undefined") {
  console.log("The property is undefined");
}

In this case the properties from the bag are available as simple JavaScript properties from code:

image

You can dump (or process) all properties defined in the bag via this code (taken from this thread):

var allProps = props.get_fieldValues();
for (var property in allProps) {
  if (allProps.hasOwnProperty(property)) {
    console.log(String.format("{0}: {1}", property, allProps[property]));
  }
}

A sample output of the script in the debugging console:

image

Unfortunately, I have not found any way to limit the scope of properties returned by the query to specific properties. All of the properties in the property bag are returned by the request. The GetProperty method of the SPWeb class, that on the server side makes it possible to access the value of a single property, is not implemented in the client object model.

If you try this one:

var props = web.get_allProperties();
ctx.load(props, "Include(YourProperty)");

you will receive an exception complaining about the invalid request, as you call the executeQueryAsync method.

Saving the value back to the web properties is a straightforward operation:

  1. this.saveSettings = function ($scope) {
  2.     var deferred = $q.defer();
  3.  
  4.     var ctx = new SP.ClientContext();
  5.  
  6.     var web = ctx.get_web();
  7.     var props = web.get_allProperties();        
  8.     props.set_item("YourProperty", $scope.propValue);
  9.     web.update();
  10.  
  11.     ctx.executeQueryAsync(
  12.         function () {
  13.             deferred.resolve();
  14.         },
  15.         function (sender, args) {
  16.             deferred.reject('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
  17.         }
  18.     );
  19.  
  20.     return deferred.promise;
  21. }

Older Posts »

Blog at WordPress.com.