Scott Shearer and I were at SharePoint Saturday VA Beach this past weekend, which was an excellent event. Scott did a few different presentations including one on SPEasyForms, which drew a pretty big crowd and was pretty well received. After the presentation Scott opened the floor for questions, which quickly got a little deeper into the implementation details than he was expecting so I got up and fielded some questions. One of the questions was if you pass in request parameters, can SPEasyForms initialize form fields from the values? The answer was no, but it wouldn’t be that hard to implement and this is a very common request in SharePoint forums. In fact, I’m going to need this kind of functionality for some of the improvements I envision for SPEasyForms in the future.
So this week I went ahead and implemented it in the jQuery.SPEasyForms.AddOns v2015.00.04 solution. This post isn’t going to go into the details of the implementation; the code is in the solution and pretty well commented, and if you have questions about that, then post a question in the discussion board on the SPEasyForms CodePlex site and I’ll be happy to answer it. But because of the number of different SPFieldTypes, using it is not entirely intuitive, and since it’s not in my documentation this post will serve as the documentation for the feature until the next major release of SPEasyForms. So in general:
- Parameter names should start with spef_. This tells SPEasyForms that this parameter is intended to initialize a field value.
- The rest of the parameter name should match the internal name of the field you want initialized.
- The parameter value should be URL escaped using the JavaScript function escapeURIComponent(a), or something equivalent if you’re not constructing the URL in JavaScript. If this isn’t done and the value contains special characters like ampersands and newlines, you’re likely to see some undesirable side effects (i.e. bugs).
So, if you go to a form with a URL like:
<formURL>?spef_Title=My New Title&spef_Description=My New Description
SPEasyForms will look for a field with the internal name of Title and set it to ‘My New Title’ and a field with the internal name of Description and set it to the value ‘My New Description’. So you can pretty much stop reading now, right? It’s pretty self explanatory? But how do you set a people picker field? or a boolean? or a date/time? A lot of decisions had to be made during the coding about how to set different field types. You could guess about how those decisions were made, or you could read the table below:
SPFieldType | Example | Description |
SPFieldText | spef_Title=text | Nothing special here, this is the simple case. |
| SPFieldNote SPFieldMultiLine | spef_Description=text | Newlines will have to be escaped, and this only works on fields designated as plain text. Enhanced Rich Text does not work and Rich Text wasn’t actually tested. |
| SPFieldChoice (Dropdown) | spef_Choice=A | A should equal the text of an option in the drop down. If not, A will be inserted into the fill-in input box if there is one. |
| SPFieldChoice (Radio) | spef_Choice=A | A should equal the text of label for a radio button. If not, A will be inserted into the fill-in input box if there is one. |
| SPFieldChoice (Checkboxes) | spef_Choice=A;B;C | A, B, and C should each equal the text in a label for one of the checkboxes. If not, they will be appended to the fill-in input box if there is one, with multiple values separated by a semi-colon. |
| SPFieldDate | spef_DateAndTime=1/2/2015 4:25 PM | The date passed in must be parsable to a JavaScript Date object. This can unfortunately be somewhat browser specific, for instance I originally left out the space before PM which worked fine in IE but not in FireFox. The time may be omitted and will be ignored if the field is date only. |
| SPFieldBoolean | spef_YesNo=NO | You can pass in either 0, no, or false (case insensitive) to uncheck the box. Any other value will check the box. |
| SPFieldURl | spef_HyperLink= http://speasyforms.com|SPEasyForms | Pass in just a URL and it will be used for the URL and the description. To pass a separate description, pass the URL, followed by a pipe, followed by the description. |
| SPFieldUser | spef_User=joe@speasyforms.com | Pass in any value that the people picker can resolve (user name, email, SIP address, even display name if it is unique). If the field accepts groups, you can pass in anything that can be uniquely resolved to a group |
| SPFieldUserMulti | spef_Users= joe@speasyforms.com;SPEasyForms Visitors | Same as above except multiple values are separated by a semi-colon. |
| SPFieldLookup | spef_Lookup=3 | Generally, you should always pass in the ID for a lookup. You can pass the text instead, but if it is not unique the first match as it appear in the dropdown will be selected. |
| SPFieldLookupMulti | spef_LookupMulti=3;7 | Same as above except multiple values are separated by a semi-colon. |
Note that if SPEasyForms is installed and activated on a site collection, you can initialize fields using request parameters in any list even if the list is not configured to use SPEasyForms. That should about do it, hope you find it useful. I’ve tested this on Office 365 and SharePoint 2013 and 2010.