This post is migrated from previous hosting provider. There are still some issues with old posts. Please make a comment on this post with any issues.

Web Part Properties - part 1 - introduction

Tags: .NET, C#, SharePoint, Web Parts

I thought that I should kick off this new year with a series of posts on how to make your SharePoint Web Parts editable and how to enhance that out-of-the-box Web Part property editing combined with some tips and tricks.

This first post may be to most of you SharePoint developers somewhat basic, but I have chosen to start from scratch here. Many of this first post topics are repeatedly asked in the MSDN development forums. The documentation in the SharePoint SDK on this topic is really bad; it just says do this and do that, never why you should do it. Often this makes developers unaware of pitfalls or possibilities.

Note: Although I talk about SharePoint Web Parts here, most of these techniques can be used in plain ASP.NET 2.0 Web Parts also.

Sample Web Part - TweetPart

TweetPart I will throughout this series use a sample Web Part which reads information from Twitter and displays the tweets in the Web Part – called TweetPart. This Web Part will allow the users to choose what tweets to see; the public time line, a user time line or a Twitter search feed. Administrators are allowed to set how many tweets to display.

All sample code are written using .NET 3.5.

Properties of a Web Part

A Web Part class can contain properties which can be edited in the web interface or application development environment. To be editable the property has to be marked with a set of attributes which specifies how and who can edit the property.

Our sample Web Part needs four properties to work;

  • Display mode – an enumeration on what type of tweets to show
  • User name – a string, if the user time line mode is chosen
  • Search text – a string, if the Twitter search mode is chosen
  • Tweet Count – the number (integer) of tweets to show

The TweetPart is a Web Part derived from the ASP.NET 2.0 WebPart class, more on this in the coming posts.

Note: When creating editable properties for your Web Part you have to create properties that are read/write, public and called without parameters.

I want all of these four properties to appear when someone modifies the Web Part, so I have to mark all four of these properties as WebBrowsable. This indicates to SharePoint that the property can be edited in the web the tool pane. The system will take care of how the user interface will look like; strings will be text boxes, booleans will be check boxes, enumerations will be dropdowns etc.

Note: A common error here is that the Browsable attribute is used instead, which is used when designing components and controls for visual designers. This attribute was also used when developing Web Parts for SharePoint 2003 with the SharePoint WebPart class.

To make the properties appear there is one more thing you have to do, you have to add the Personalizable attribute and set the personalization scope. This attribute tells the Web Part Manager that this property value is persisted. If you set the scope to User (default), then users (Members) can modify this property and if it’s set to Shared only editors (Owners) are allowed to change the property.

Tip: If you omit this attribute, you cannot change it through the web interface, only through code or tools such as SharePoint Designer. This might be a preferred solution in some cases.

This will make your custom tool pane look like this:

Custom property

Now things work, you can edit and save the value of the property and it is stored in SharePoint. But to further enhance the editing experience you should make it more user friendly.

Make the tool pane more user friendly

You should give it a name and a description, shown as a tooltip, to show in the editing tool pane that are more user friendly than the name of the property. Don’t rely on that your users or administrators interpret your property names correct. This is done with the WebDisplayName and WebDescription attributes.

The tool pane has a set of categories (Appearance, Advanced and Layout) which are reserved for the base class properties. The custom properties will end up in a category called Miscellaneous, if you do not provide your own category with the Category attribute.

Note: You cannot add properties to the reserved categories.

So this is how we should define our custom properties, at the minimum:

[WebBrowsable]
[WebDisplayName("User name")]
[WebDescription("The Twitter Username")]
[Category("Twitter")]
[Personalizable(PersonalizationScope.User)]
public string Username {
    get;
    set;
}

This property now has a friendly name and a description, it’s located under the Twitter category and users can change the value of it, and have their own values.

Note: If you make changes to it in the Shared view, default if you are an admin, it will be the default values for users who have not personalized the Web Part.

The same is done for the other three properties and now the Twitter category looks like this when editing the Web Part:

Shared tool pane view of TweetPart

Shared only properties and storage

I want the Tweet count property to be edited only by those who are allowed to edit the Shared view of the web part, therefore I change the PersonalizationScope of the Personalizable attribute to Shared. This means that this property will not be displayed when editing the personal (My) view of the Web Part.

I also add and specify the WebPartStorage attribute to Shared, this makes the Web Part store only one set of value for this property. Default is the Personal storage mode, which means that every user has it’s own property value.

Tip: If you set the storage to Shared and personalization scope to User then every user can edit the same (shared) value.

Now this property looks like this:

[WebBrowsable]
[WebDisplayName("Tweet count")]
[WebDescription("Number of tweets to show")]
[Category("Twitter")]
[Personalizable(PersonalizationScope.Shared)]
[WebPartStorage(Storage.Shared)]
public int TweetCount {
    get;
    set;
}

if you now open up the shared properties of the Web Part, then it looks the same as above, but if you instead go to the personal view then it looks like this:

Personal tool pane view of TweetPart

As you can see there is no Tweet Count property to edit, it’s only available in shared mode.

Tip: To switch between Shared and Personal mode just add this parameter to the query string PageView=[Shared|Personal].

Run it

Now we have fixed the configuration of the TweetPart, let’s put it into action. As this series focuses on the editing of the properties I don not go into how I have created the actual rendering of the TweetPart using the Twitter API. It’s pretty simple and you can browse the code to see how it works.

Public time line User time line Twitter Search
TweetPart - public time line TweetPart - user time line TweetPart - Twitter Search

The code

Download the code sample below. It’s built using STSDev using Visual Studio 2008. If you prefer to just download the finished solution, it’s also available for download.

Next step…

Using this method of making your Web Part personalizable is fine, but there are some things that does not make it that user friendly or smooth. First of all the custom categories ends up last amongst the categories – your users might miss the properties to edit. Secondly this sample Web Part, has properties depending on each other (username is only required when using user time line and search text only when using search mode). Your own Web Parts may have more advanced dependencies or require that lists are filled during the editing.

This is what I’m going to show during the next part of the series.

Share your experience and stay tuned…

Technorati tags: , ,

8 Comments

  • Trackback said

    This is the second part of the Web Part Properties series. The last post walked through the basics on how to make editable properties on a Web Part. As a sample I used a Web Part that displayed tweet...

  • Trackback said

    To end my series of Web Part properties I would like to show how to store more complex values than just strings or integers. What happens if you would like to store a more complex object; an array or ...

  • Vater Abraham said

    Great example, thank you very much! I do miss an example how the webpart code itself can store values into the WebPart Storage via custom properties. Till now the values for the custom properties do come from user input in the tool pane. But the WebPart code itself shall story values in those custom properties. How it that done? There are situations where WebParts have to store data for later use. Custom properties seem to be the solution, but in the whole Internet I only find examples for custom properties with user input, and not with input from the webpart code.

  • bas lijten said

    Wictor, do you know anything about performance issues when 10000+ users make use of webpart personalization? bas dott lijten @ gmail dot com

  • Toro 4s said

    <a href="http://responsiblefatherhood.com/">Nike Lebron 10</a>AI <a href="http://www.pinterest.com/VenomJordan10/">Jordan 10 Venom Green</a>EL<a href="http://www.decoymuseum.com/">Barons 9s</a>GN<a href="http://www.ovostudios.com/">Jordan 9</a> FK<a href="http://www.childrenmuseum.org/">Jordan 9 Barons</a>AI<a href="http://www.nawgj.org/">Barons 9s</a>BN<a href="http://ecatalina.com/">Barons 9s</a>GN<a href="http://www.valweb.org/">Jordan 9 Barons</a>CL<a href="http://catskillscenictrail.org/">Jordan 9 Barons</a>EN<a href="http://www.radhaz.com/">Jordan retro 9</a>FH<a href="http://www.scitechinc.com/">Jordan 9 Barons</a>GL<a href="http://www.restorationeconomy.com/">Barons 9s</a>CN<a href="http://www.pinterest.com/iyoarthoru/">Sport Blue 6s</a>BN<a href="http://www.pinterest.com/osolyarell/">Jordan sport blue</a>BI <a href="http://www.pinterest.com/osolyarell/">sport bule 6s</a>EL <a href="http://www.pinterest.com/uncubreya/">Sport Blue 6s</a><a href="http://www.pinterest.com/sambule/">Jordan Retro 6</a>EL <a href="http://www.pinterest.com/flysport/">Jordan 6 Sport Blue</a>FH<a href="http://www.pinterest.com/xuhgreenm/">Jordan 6 Sport Blue</a> <a href="http://www.pinterest.com/nacynike/">Jordan 6 Sport Blue</a>BK <a href="http://www.pinterest.com/johnsport/">Jordan Retro 6</a>FJ <a href="http://www.pinterest.com/likesport/">Sport Blue 6s</a>EJ<a href="http://www.pinterest.com/egortadhan/">Venom Green 10s</a>AJ<a href="Jordan Venom Green 10">Jordan Venom Green 10</a> <a href="http://www.pinterest.com/Blue6s/">Sport Blue 6s</a>A|B|C|D|E|F|G}M<a href="http://www.pinterest.com/SaleBlue11s/">Jordan 11 Gamma Blue</a>CI<a href="http://www.pinterest.com/11Gamma/">Jordan 11 Gamma Blue</a>A|B|C|D|E|F|G}I <a href="http://www.pinterest.com/SaleJordan11/">Gamma Blue 11s</a>GM<a href="http://www.pinterest.com/newstylejordan/">barons 9s</a>EH<a href="http://www.pinterest.com/realjordan9/">{jordan 9 birmingham barons</a>BJ<a href="http://www.pinterest.com/Jordan9forsale/">jordan 9 birmingham barons</a>BI<a href="http://www.pinterest.com/barons9s2014/pre-order-jordan-low-concord-11s-free-shipping/">jordan 11 concord</a>DJ<a href="http://www.pinterest.com/barons9s2014/65-off-jordan-white-carmine-6s-for-sale-2014/">jordan 6 carmine</a>BJ<a href="http://www.pinterest.com/barons9s2014/cheap-jordan-sport-blue-3s-retro-for-sale/">Jordan Retro 3</a>GN<a href="http://www.pinterest.com/barons9s2014/105-jordan-space-jam-low-11s-2014-for-sale/">Space jam 11s </a>AI<a href="http://www.pinterest.com/barons9s2014/108-jordan-green-snakeskin-11s-low-full-size/">Green Snakeskin 11s</a>GH<a href="http://www.pinterest.com/barons9s2014/109-top-quality-jordan-sport-blue-6s-for-sale/">Sport Blue 6s</a>FL<a href="http://www.pinterest.com/barons9scheap/">Barons 9s</a>BN<a href="http://www.pinterest.com/barons9scheap/62-off-order-jordan-retro-barons-9s-2014-online/">Jordan Retro 9 Barons<a href="http://www.pinterest.com/barons9scheap/65-off-discount-jordan-retro-1-barons-online-2014/">barons 1s</a>EM<a href="http://www.pinterest.com/barons9scheap/big-discount-jordan-concord-low-11s-online-free-sh/">concord low 11s</a>FH<a href="http://www.pinterest.com/barons1s2014/buy-jordan-green-snakeskin-11s-low-disount-online/">Jordan 11 low Green Snakeskin</a>BL<a href="http://www.pinterest.com/barons1s2014/hot-jordan-11-low-concord-2014-for-sale-online/">Jordan 11 low concord</a>EL<a href="http://www.pinterest.com/barons1s2014/order-hot-jordan-white-carmine-6s-low-price-sale/">white carmine 6s</a>GJ<a href="http://www.pinterest.com/orderbarons1s/jordan-concord-11s-low-2014-free-shipping-sale/">Concord 11s</a>CI<a href="http://www.pinterest.com/orderbarons1s/jordan-green-snakeskin-11s-low-save-62-off-online/">Jordan 11 low</a>FN<a href="http://www.pinterest.com/orderbarons1s/100-authentic-jordan-white-carmine-6s-for-sale-201/">jordan 6 carmine</a>BJ<a href="http://www.innovationdelivery.com">jordan 4 green glow</a>FI<a href="http://www.paperreeds.com">Jordan 4 Fire Red Toro</a>CH<a href="http://www.thoughteater.com">Jordan 4 2014</a>AK<a href="http://www.mangetoutorganic.com">Jordan Green Glow 4</a>EN<a href="http://www.provoiceartists.com">Jordan 4 Green Glow</a>DI<a href="http://www.terracyclery.com">Green Glow 4s</a>FL<a href="http://www.clickabledesigns.com">Green Glow 4s 2014</a>EI<a href="http://www.sargescomics.com">jordan retro 4</a>CN<a href="http://www.gilbertroadimprovements.com">Jordan 4 Green Glow</a>CJ<a href="http://capitolnh.com">jordan 4 for sale</a>FL<a href="http://www.ukdnaforensictesting.com">babyliss</a>BH<a href="http://www.warrantise.com">babyliss</a>GN<a href="http://www.thebusinessmentor.net">babyliss pro</a>DJ<a href="http://www.kslocks.co.uk">babyliss hair dryer</a>CN<a href="http://www.uksurety.co.uk?">babyliss pro</a>AL<a href="http://www.allanpilch.co.uk">babyliss for men</a>EL<a href="http://www.mcallisterbros.com">babyliss big hair</a>CH<a href="http://www.tmwsecurity.com">babyliss pro</a>GM<a href="http://www.lebanondaleel.com">babyliss</a>DN<a href="http://www.staldates.org.uk">babyliss pro perfect curl</a>EJ<a href="http://www.pinterest.com/torobravo4/">Toro Bravo 4s</a>FJ<a href="http://www.pinterest.com/torobravo4/65-off-order-jordan-toro-bravo-4s-for-sale-2014">Toro Bravo 4s for sale</a>FN<a href="http://www.pinterest.com/torobravo4/hot-jordan-green-glow-4s-retro-for-sale-full-size/">jordan retro 4</a>FI<a href="http://www.pinterest.com/torobravo4/top-quality-jordan-gamma-blue-11s-for-sale-online/">gamma blue 11s</a>EH<a href="http://www.pinterest.com/torobravo4/new-jordan-11-low-concord-for-sale-low-price/">jordan 11 concord</a>CL<a href="http://www.pinterest.com/torobravo4/real-jordan-white-carmine-6s-2014-for-sale-online/">carmine 6s</a>CI<a href="http://www.pinterest.com/greenglow4sale/">Jordan Green Glow 4</a>BH<a href="http://www.pinterest.com/greenglow4sale/buy-cheap-jordan-green-glow-4s-for-sale-online/">Green Glow 4s For Sale</a>BI<a href="http://www.pinterest.com/greenglow4sale/hot-jordan-toro-bravo-4s-retro-for-sale-2014/">jordan 4 toro bravo</a>CJ<a href="http://www.pinterest.com/greenglow4sale/big-discount-jordan-concord-low-11s-2014-online/">low concord 11s</a>CM<a href="http://www.pinterest.com/greenglow4sale/new-arrival-jordan-11-low-space-jam-2014-for-sale/">Space jam 11s </a>FK<a href="http://www.pinterest.com/greenglow4sale/authentic-jordan-sport-blue-3s-for-sale-full-size/">Jordan Sport Blue 3</a>BJ<a href="http://www.planmaster.co.uk">michael kors bags</a>AI<a href="http://www.polarponies.com">michael kors uk</a>CI<a href="http://www.prhurt.com">michael kors london</a>BK<a href="http://rachelnacer.com">michael kors purses</a>BJ<a href="http://www.custom-group.co.uk">michael kors purses</a>GJ<a href="http://www.restaurant23warrenpoint.com">michael kors uk</a>GK<a href="http://robmaslin.co.uk">michael kors uk</a>DH<a href="http://www.roomh2o.co.uk">michael kors handbags</a>DL<a href="http://www.safetyadvicecentre.com">michael kors bags</a>AM<a href="http://www.salasdearte.org">michael kors bags</a>EL

Add a Comment

AWS Tracker

About Wictor...

Wictor Wilén is a Director and SharePoint Architect working at Connecta AB. Wictor has achieved the Microsoft Certified Architect (MCA) - SharePoint 2010, Microsoft Certified Solutions Master (MCSM) - SharePoint  and Microsoft Certified Master (MCM) - SharePoint 2010 certifications. He has also been awarded Microsoft Most Valuable Professional (MVP) for four consecutive years.

And a word from our sponsors...

SharePoint 2010 Web Parts in Action