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.

  1. In elements.xml, add a property element which contains the description, type, default value, and other information.
  2. 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.
  3. Write JavaScript code to receive the value of the parameter.

When it comes to Client Web Part parameters, there are four types:

  • string
  • boolean
  • int
  • enum

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_&amp;MyEnum=_MyEnum_&amp;{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.

ClientWebPartProperties

The values I selected can then be seen in the web part on the page.

ClientWebPartWithValuesSet

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.

Comments

# My SharePoint links January 5, 2013 | Jeremy Thake&#039;s musingsJeremy Thake&#039;s musings

Pingback from  My SharePoint links January 5, 2013 | Jeremy Thake&#039;s musingsJeremy Thake&#039;s musings

# SharePoint Daily &raquo; Blog Archive &raquo; When SharePoint Governance Lacks Accountability; Business Isn&#8217;t Happy with SharePoint; Design Over Usability

Pingback from  SharePoint Daily  &raquo; Blog Archive   &raquo; When SharePoint Governance Lacks Accountability; Business Isn&#8217;t Happy with SharePoint; Design Over Usability

# When SharePoint Governance Lacks Accountability; Business Isn't Happy with SharePoint; Design Over Usability

Thursday, February 21, 2013 8:03 AM by SharePoint Daily

Do you plan to attend SHARE 2013 Conference in Atlanta? Register now and Bamboo can help you save $300

# re: How to: Pass parameters to a Client Web Part

Thursday, May 9, 2013 3:31 AM by kfrymus

Hi,

Have you tried to change the ChromeType setting it in ClientWebPart\Properties\Property ?

I'm having problems with it.

When I try to set like that:

<property defaultvalue="None" name="ChromeType" requiresdesignerpermission="true" type="ChromeType" webdisplayname="Chrome Type"></property>

It says that type is invalid

I've tried setting Type to string value, and enum without any success, getting error:

ClientWebPart has the Property ChromeType which cannot be used since its declared on a base class

# re: How to: Pass parameters to a Client Web Part

Tuesday, May 14, 2013 2:52 PM by CoreyRoth

@kfrymus I haven't tried that.  It seems to be a limitation of the client web part to set properties like that, but I haven't confirmed it.

# re: How to: Pass parameters to a Client Web Part

Friday, May 9, 2014 7:13 AM by Nagarjuna

Can we edit the client webpart properties through javascript??

# re: How to: Pass parameters to a Client Web Part

Friday, May 9, 2014 9:09 AM by CoreyRoth

@Nagarjuna I don't believe so.  They only come into the page as readonly via the query string.

# re: How to: Pass parameters to a Client Web Part

Friday, May 9, 2014 1:25 PM by Adam

Hi anyone aware of a max length for a strong property

# SharePoint app Pass parameters to a Client Web Part | Share your knowledge

Pingback from  SharePoint app  Pass parameters to a Client Web Part | Share your knowledge

# When SharePoint Governance Lacks Accountability; Business Isn&#8217;t Happy with SharePoint; Design Over Usability &#8211; Bamboo Solutions

Pingback from  When SharePoint Governance Lacks Accountability; Business Isn&#8217;t Happy with SharePoint; Design Over Usability &#8211; Bamboo Solutions

# When SharePoint Governance Lacks Accountability; Business Isn&#8217;t Happy with SharePoint; Design Over Usability &#8211; Bamboo Solutions

Pingback from  When SharePoint Governance Lacks Accountability; Business Isn&#8217;t Happy with SharePoint; Design Over Usability &#8211; Bamboo Solutions

Leave a Comment

(required) 
(required) 
(optional)
(required)