I ran across this SPServices Story in a post on the blog at CTS. The author of the post, Matt Ingle, is a Senior Consultant at CTS in Birmingham, AL. According to Matt, he is a team lead for a group called the SharePoint Factory. The SharePoint Factory team roles correspond to the various areas of the SharePoint family of products. This role-based approach allows for technical depth and specialization within the SharePoint functional areas.
SPServices has a function called SPRedirectWithID, but it’s problematic in SharePoint 2010 due to the dialogs that SharePoint uses to show the list forms. You can ensure that the function works just fine by turning off the dialogs, but that’s not always desirable. I’d turn them all off if I had my druthers because most list forms require more screen real estate than the dialogs provide without a lot of scrolling. They also don’t obviate the need for a ca-chunk postback when you save the item.
Given this state of things, Matt came up with a way to accomplish a similar thing in a different way. Here’s Matt’s take on the task. It’s a nice way to go if your information architecture is very clear and you know that your forms won’t change much, if at all, since Matt is bypassing the simple NewForm we get for “free” from SharePoint. On the other hand, this type of approach may become more common as we move forward with SharePoint and HTML5 compatibility.
Using SPServices and jQuery to Perform a Redirect from a SharePoint List NewForm to EditForm
Problem: In SP 2010, you have a parent list and multiple child lists connected through Lookup columns. You have created the custom Display and Edit forms for the parent list containing XsltListView web parts for the child lists filtered through query string view parameters. Refer to this article for more information on this solution.
Now you need a way to redirect the user from the NewForm to the EditForm after saving the parent list item while passing the newly created item ID as a query string parameter. The problem is there is no way to do this out-of-the-box (OOB).
Note: Be sure to read the IMPORTANT NOTES on the SPServices Home page about supported versions. This example will use the (“[nodeName=’z:row’]“) syntax which no longer works with jQuery 1.7. I will be using jQuery 1.6.2 and SPServices 0.6.2 in my example. However, if you want to use 1.7, an alternative solution to using this syntax can be found here by Steve Workman. [ed: Use the SPFilterNode function, which will work with any version of jQuery:
.SPFilterNode("z:row") and ensures cross-browser compatibility.]
By using the SPServices operation to create the new list item you will be bypassing the OOB Save process for the SharePoint list form. This means that you will lose the validation on the form and will need to create your own validation logic using jQuery. In the following example I will be implementing the required field validation for my list fields.
Example: At this point you should already have a custom NewForm for your parent list.
Below each field to be displayed on the form, add some text wrapped in a <span> tag with unique ids that will be used to display our custom validation message. I worded mine the same as the text displayed by SharePoint. Notice my id for the <span> tag below is ‘valBU’. We will use jQuery later to select this element by the id.
Additionally, we will need to add a custom button to our form in place of the OOB Save button. This will allow us to attach our custom code to the Save button’s click event.
Next, add a Content Editor WebPart (CEWP) directly below the DataFormWebPart. This will hold our jQuery/SPServices script.
In the CEWP, add the script references to the jQuery and SPServices libraries. I uploaded mine in a new ‘Scripts’ folder stored in the ‘Style Library’ folder so that it is accessible to other pages in the site as needed.
To begin the script, add code to hide the text containing our custom validation messages. Place this code in the $(document).ready function. Next, add a line to attach the method CreateNewItem to the Save button’s click event.
Next, we can implement our custom validation logic. The following method will be called in our CreateNewItem method to validate our form before creating the new item. It starts by using jQuery selectors to obtain the values of the list fields on the form. We can use the ‘title’ attribute for the selectors which contains the name of the list field. In my example, I have 2 drop-down list boxes so I am looking for select elements. For a normal text field you would look for input elements.
For a PeoplePicker, the selector used is a little different. There are different ways to obtain this value, but for our purposes (looking for a single PeoplePicker on the page) you can just look for a textarea element with the title ‘People Picker’. If you have multiple PeoplePickers on the form then you would need to research a way to be more selective. [ed: You can use the SPFindPeoplePicker function in SPServices for this.]
When you have an empty PeoplePicker value you will get ’ ’ which is the HTML code for a non-breaking space. Simply check for this value versus an empty string as done for the other fields.
This method counts the number of empty fields and toggles display of the custom validation messages. If there are no empty required fields then it returns true, false otherwise.
Now we can implement the CreateNewItem method. First, use jQuery to select the form fields and obtain the values.
Again, we need to do something different for the PeoplePicker. The value of the PeoplePicker contains a lot of stuff we don’t really need so we have to parse through it to find the user login name.
With this value stored in the ‘buFinContollerPerson’ variable, we will supply it to the ‘userLoginName’ parameter for the GetUserInfo operation. This will be a value like ‘EXT\mingle’.
We are calling the GetUserInfo operation in order to get the correct format needed to save the PeoplePicker value to the list. This format is ’37;#Matt Ingle’ (<UserID>;#<UserName>).
To complete the CreateNewItem method we will call the UpdateListItems method. To specify the creation of a new list item you need to specify “New” for the batchCmd parameter. In addition, supply the list display name (one shown in UI) for the listName parameter. The values to be submitted for the new list item are specified as value pairs in the valuepairs parameter.
Note:We are supplying the fullUserName obtained from the GetUserInfo operation as the value for the PeoplePicker field BUFinContollerPerson.
Once the operation has completed we will parse the XML response to find the newly created item ID. This is where we use the (“[nodeName=’z:row’]“) syntax. This value is supplied for the ID query string parameter to redirect the user to the EditForm.
Also notice the <div> tag below the <script> tag. This is where you can specify the location of the debug output for the SPServices operations. Simply uncomment the calls to SPDebugXMLHttpResult to see the operation results displayed. Be sure to comment out the redirect though when debugging, otherwise you will not stay on the page to see the results. :-)