How to: Pass parameters to a Client Web Part
Posted
Friday, January 4, 2013 10:00 AM
by
CoreyRoth
This is one of those posts that I have promised to write but I totally forgot about. What I want to talk about today is passing parameters to SharePoint 2013 Client Web Parts. These parameters are equivalent to the properties on traditional web parts. The process is relatively straight forward, but I thought I would share some of my experiences with it. This article on MSDN will get you started, but I do things a bit differently.
Unfortunately, the updates to the tools with Preview 2 don’t add anything to make this process easier. There are three steps to adding a property to a client web part.
- In elements.xml, add a property element which contains the description, type, default value, and other information.
- In elements.xml, edit the query string of the src attribute of the Content element to pass the parameter to the client web part page.
- Write JavaScript code to receive the value of the parameter.
When it comes to Client Web Part parameters, there are four types:
You will use the above values in the Type attribute of the property you add. It must match exactly. Let’s take a look at the Property element and see what the values do. In this case, we’ll add a string property. In Preview 1, the elements.xml file used to include a commented example, but now that’s gone. Here’s an example.
<Property Name="MyString" Type="string" WebBrowsable="true" WebDisplayName="Ny String" WebDescription="Text description of my string" WebCategory="Configuration" DefaultValue="Default My String" RequiresDesignerPermission="true" />
Aside from the type, the properties that you will probably care about are the following:
- Name – name of the parameter you will query by JavaScript
- Type – data type
- WebDisplayName – name of the parameter displayed to the user in the web part properties
- WebDescription – description of the parameter displayed to the user
- WebCategory – group name in the web part properties
- DefaultValue – the default value if the user does not change it
The Property element looks similar for both boolean and int types as well. However, if you specify enum, the user will see a dropdown list of values. It will contain an EnumItems child element which looks like this.
<Property Name="MyEnum" Type="enum" RequiresDesignerPermission="true" DefaultValue="1" WebCategory="Configuration" WebDisplayName="Enum property">
<EnumItems>
<EnumItem WebDisplayName="Choice 1" Value="1"/>
<EnumItem WebDisplayName="Choice 2" Value="2"/>
<EnumItem WebDisplayName="Choice 3" Value="3"/>
</EnumItems>
</Property>
Once you finished defining your properties, you need to add them to the query string. Effectively, SharePoint passes the values the user specifies by query string to the client web part page. Each parameter comes in two pieces: the value your JavaScript will query and the the name from each Property element. Each parameter looks something like this.
Parameter1=_Parameter1_
The value of the parameter is always enclosed in underscores (_). For the two parameters we added above, here is what our src attribute will look like. I’m using the same app part I created for the Preview 2 blog post.
<Content Type="html" Src="~appWebUrl/Pages/ClientWebPart1.aspx?MyString=_MyString_&MyEnum=_MyEnum_&{StandardTokens}" />
You’ll also notice that I have included {StandardTokens}, this tells SharePoint to provide common useful values such as the URL to the Host Web (SPHostUrl).
Now, we need to add JavaScript to the client web part itself to read the value and do something with it. I use a helper method to help get query string values. I’m pretty sure I got this method from one of the early SharePoint app examples but I’m not sure entirely.
function getQueryStringParameter(urlParameterKey) {
var params = document.URL.split('?')[1].split('&');
var strParams = '';
for (var i = 0; i < params.length; i = i + 1) {
var singleParam = params[i].split('=');
if (singleParam[0] == urlParameterKey)
return decodeURIComponent(singleParam[1]);
}
}
Using this method, we just request a value for the name of our parameters. In my example below I simple assign the value to a div.
$("#myString").text(getQueryStringParameter("MyString"));
$("#myEnum").text(getQueryStringParameter("MyEnum"));
Now, when we add the App Part to the host web, we can configure it. In the case I gave, you can find the values in the Configuration header.
The values I selected can then be seen in the web part on the page.
When you’re ready to add properties to your client web parts, I hope this post helps. It’s not too complicated but it is a bit tedious. Give it a try and see how it works for you.