in

Dot Net Mafia

Group site for developer blogs dealing with (usually) .NET, SharePoint 2013, SharePoint 2010, Office 365, SharePoint Online, and other Microsoft products, as well as some discussion of general programming related concepts.

This Blog

Syndication

Archives

Corey Roth [MVP]

A SharePoint MVP bringing you the latest time saving tips for SharePoint 2013, Office 365 / SharePoint Online and Visual Studio 2013.

How to: Pass parameters to a Client Web Part

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's musingsJeremy Thake's musings said:

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

January 5, 2013 1:17 PM
 

SharePoint Daily » Blog Archive » When SharePoint Governance Lacks Accountability; Business Isn’t Happy with SharePoint; Design Over Usability said:

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

February 21, 2013 7:56 AM
 

SharePoint Daily said:

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

February 21, 2013 8:03 AM
 

kfrymus said:

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

May 9, 2013 3:31 AM
 

CoreyRoth said:

@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.

May 14, 2013 2:52 PM
 

Nagarjuna said:

Can we edit the client webpart properties through javascript??

May 9, 2014 7:13 AM
 

CoreyRoth said:

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

May 9, 2014 9:09 AM
 

Adam said:

Hi anyone aware of a max length for a strong property

May 9, 2014 1:25 PM
 

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

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

July 18, 2014 2:45 PM

Leave a Comment

(required)  
(optional)
(required)  
Add

About CoreyRoth

Corey Roth is an independent SharePoint consultant specializing in ECM, Apps, and Search.
2012 dotnetmafia.
Powered by Community Server (Non-Commercial Edition), by Telligent Systems