Thursday, January 30, 2014

Change of approval status in SharePoint edit form

In one of my previous posts I have described how to customize toolbar buttons in SharePoint forms and how to add Approve and Reject buttons to the bottom of Workflow tasks in particular. Geir Mathisen commented on this post that it would be nice if Approve and Reject buttons could be used for changing approval status in the lists and libraries with content approval enabled. In this article I would like to cover this case.

First, we have to enable content approval feature which allows to make items or documents visible only to submitters and users with special permission (Approve/reject items) unless they are approved by these users. Go to the list settings and choose Version Settings section. Here, we should set 'Require content approval for submitted items' option to 'Yes'.

Now that we enabled content approval feature in our list, new columns - Approver Comments and Approval Status were added automatically but they do not appear in the list of fields in settings and in Forms Designer. We will add them to forms with help of HTML-control. Open Forms Designer, choose Edit form and place HTML-control with the following content:

Comments: <br />
<SharePoint:FormField id="_ModerationCommentsField" 
FieldName="_ModerationComments" 
runat="server" 
ControlMode="Edit" 
__designer:bind="{ddwrt:DataBind('u','_ModerationCommentsField','Value','ValueChanged','ID',ddwrt:EscapeDelims(string(@ID)),'@_ModerationComments')}" />

FormField is SharePoint component which renders control for a specific field and form mode. In our case it will be Approver Comments field whose internal name is _ModerationComments in edit mode. So if you wish to place Approver Comments field in display or new form, you have to specify the appropriate mode in ControlMode property: Display or New. As you may have guessed, the most valuable part of this code is __designer:bind attribute with ddwrt:DataBind function. I will not get deeper into technical aspects of this SharePoint control, just say that this property is required to map control and field and define control event that will notify SharePoint that field is changed. You can omit __designer:bind attribute if ControlMode of your field is Display. If ControlMode is New you have to set the first parameter of ddwrt:DataBind function to 'i' which means 'Insert'. You can get more information on SharePoint data binding in the following article: http://www.bryancook.net/2009/09/understanding-sharepoints-ddwrtdatabind.html

Ok, next we have to set CDATA property of HTML-control to False. This property has become available since 2.8.6 version of Forms Designer. If it is 'True', __designer:bind attribute will be ignored by SharePoint and entered data will not be saved.

Great, now we can modify Approver Comments fields directly in edit form. Unfortunately, SharePoint does not support controls for Approval Status in edit or new modes so, we have to define them ourselves. Put a new HTML-control with the following content to your form:

<div class="moderation-status-field">
<asp:HiddenField id="_ModerationStatusField" 
runat="server"
Value="{@_ModerationStatus}"
__designer:bind="{ddwrt:DataBind('u','_ModerationStatusField','Value','Load','ID',ddwrt:EscapeDelims(string(@ID)),'@_ModerationStatus')}" />
</div>

Here, I put a hidden field and bound its value to Approval Status field. It could be text box as well as drop down, but I am going to set value of this control via JavaScript when user clicks the appropriate button: Approve or Reject, so the hidden field is the most suitable for my needs. As you can see, I wrapped the hidden field into DIV container to get it in JavaScript by CSS class. Approval Status field accepts the following values:
0 — Approved
1 — Rejected
2 — Pending
3 — Draft
4 — Scheduled

Do not forget to set CDATA of HTML-control to False.

Now, we should enable buttons feature of Forms Designer and put two additional Save buttons at the bottom of our form: Approve and Reject. Here is my form in Forms Designer:

SharePoint form field data binding

Next, we should implement OnClick handler of Approve and Reject buttons to set the appropriate value of Approval Status.

Code for Approve button:

$('.moderation-status-field > input').val(0)

Code for Reject button:

$('.moderation-status-field > input').val(1)

Here is my final form:

SharePoint Content Approval Status on Edit form

When user clicks Approve button the current item is saved and turned to Approve state, since Reject button turns item to Rejected state.

Should you have any difficulty following these instructions, feel free to leave your questions.

Tuesday, January 28, 2014

Publish the designed form to any page within the current site

In this article I am glad to present a new feature which allows to publish the designed forms to wiki, publishing and web part pages within the current site. It was implemented in SharePoint Forms Designer 2.8.6 which has been available for downloading since January, 27. I will now demonstrate how to use it in a real scenario.

Let us say that we have a helpdesk system and wish to create a compact homepage with the most important information and actions for our requestors. This page will contain the list of issues created by the current user, and a form on the right side for creating a new issue with essential fields only. For this case we should create a new page '/SitePages/Requestor.aspx' based on 'One column with sidebar' layout and place the list of issues filtered by the current user and grouped by status in the main column. Now, let us design a form for creating new issues for the sidebar. Go to the list of issues and open Forms Designer from the ribbon.

I designed a compact form with two tabs, the first for the most valuable fields whereas the second for additional information, e.g. category of an issue and attachments. At the bottom of my page I left Save button only and renamed it to 'Create request'. You can enable customization of bottom panel containing Save/Cancel buttons via 'Buttons' command in the ribbon.

As you can see, my form is small enough to distribute it at the sidebar of our homepage for requestor:

SharePoint Forms Designer

In the ribbon of Forms Designer you can see a new button 'General' in Settings section. Click it.

SharePoint Forms Designer General Settings button

Here you can find settings to change visibility of the contextual tab of the ribbon and the toolbar of actions which duplicate those in the ribbon, e.g. attach, delete, etc. Next, there are two inputs for URLs where the current user will be redirected after submission or cancellation. By default, users go to the default view of list. So, I hid the ribbon, made the toolbar visible to allow users to attach files and set URL for redirecting after submission to '/SitePages/Requestor.aspx':

SharePoint Forms Designer General Settings

Now, we have to export the designed form into a file:

Export SharePoint Form

Ok, let us go to the requestor homepage and open it in edit mode:

SharePoint edit page

Put the cursor into the sidebar and select Insert tab in the ribbon:

Add SharePoint form

Click New Form and choose the exported form in the dialog:

Import SharePoint form

Click Publish. Your designed form will appear right under the cursor in the sidebar. Here is my requestor homepage:

Publish SharePoint form to page

In the example above I have demonstrated how to publish the designed forms to wiki pages, but you can also distribute your forms on publishing and web part pages in absolutely the same way. Also note that you do not have to save the designed form in Forms Designer, just export it into a file. So, you can have different forms for creating items from multiple pages and from the list itself. If you need to modify the published form, you can import it into Forms Designer, make changes, export into a file and publish into the page as described above. The existing form will be replaced.

Please, leave your questions.