Customizing the property editor for Sharepoint web parts

Published Jan 11, 2010

The thing to do is use .Net 2.0 web parts and override CreateEditorParts or implement IWebEditable on generic controls that are not web parts.

A good link on how to do that (once you know what to look for, duh!) is How to get EditorParts working in your WebParts.

Another link that summarises different solutions for several issues with web parts is WSS 3.0 webparts development. A quote that is relevant to this blog entry:

Toolpanes can be customized in a number of ways. A web part by itself can declare custom toolparts which show up in the toolpane by overriding the GetToolParts method (WSS WebPart) or CreateEditorParts (ASP.NET WebPart).

A developer can also customize the toolpane generically by supporting the ICustomizeToolpane interface (which allows you to redefine the structure of the toolpane UI) or supporting IAddToGallery (which allows you to add new gallery "tabs").

I am still working on clarifying that out as the documentation from MSDN is almost non existent on the subject. It appears that using ICustomizeToolPane is only supported for Sharepoint web parts and not for ASP.Net web parts. I yet know of no other way of changing the toolpane except by using some javascript from the web part editor (which would suck) and it might not even be possible.

Update: The rest of this post is not longer relevant. I believe it is the way it was done in the old Sharepoint days, when Sharepoint web parts were not based on ASP.Net 2.0.

Click to show anyway

After you build a web part and you use it in Sharepoint, you see that there are three types of possible editors for the part's properties: textboxes for strings and numbers, combos for enums and checkboxes for booleans. This post shows how you can create your own property editors.

A normal text editor has a lookup button next to it, which appears when the text editor receives focus. If clicked, the button shows a popup with a larger text editor in it. That is actually a page that is hosted in a dialog, interacting with the textbox via javascript (the zoombldr.aspx page located in the _layouts folder).

Using the HtmlDesigner property attribute, this page can be replaced with one of your own. The downside to this is that the web part must be a Sharepoint web part or use only a static url. There are people on the web that advice on using the System.Web.UI.WebControls.WebParts.WebPart class, not the one in the Sharepoint library, as the latter is kept only for compatibility reasons, however, it becomes obvious that the HtmlDesigner attribute cannot be used with system web parts. (an error of the form InvalidCastException: Unable to cast object of type 'SharepointTests.HtmlDesignerWebPart' to type 'Microsoft.SharePoint.WebPartPages.WebPart'. is thrown).

Also, there is the issue of the lookup style button. That is the only customization you are allowed: at the closing of the custom editor, the resulting value will be stored in the same plain one line textbox.

There are some steps that must be taken in order for a custom property editor to work:

the property must have an XML namespace. This can be declared on the class, using the XmlRoot attribute, or as a Namespace parameter to the XmlElement property attribute
the property must be decorated with the HtmlDesigner attribute. It must feature either the URL for the page used as a custom editor, or the BrowserBuilderType.Dynamic value
considering that BrowserBuilderType.Dynamic was used, the GetCustomBuilder method must be overriden in order to generate the url
the page itself will receive the editor textbox as a parameter in the value of window.dialogArguments, while the selected value should be stored via javascript in window.returnValue

Let's see an example:


using System.ComponentModel;
using System.Web.UI.WebControls.WebParts;
using System.Xml.Serialization;
using Microsoft.SharePoint.WebControls;
using Microsoft.SharePoint.WebPartPages;
using System.Runtime.InteropServices;
//using WebPart=System.Web.UI.WebControls.WebParts.WebPart;
using WebPart=Microsoft.SharePoint.WebPartPages.WebPart;

namespace SharepointTests
{

  [Guid("28b28c5d-41ca-2603-a937-d6980b5a9aff")]
  [XmlRoot("https://siderite.dev")]
  public class HtmlDesignerWebPart : WebPart,IDesignTimeHtmlProvider
  {
    // Create a custom category in the tool pane.
    [Category("Custom Properties")]
    // Assign the default value.
    [DefaultValue(null)]
    // Make property available in both Personalization
    // and Customization mode.
    [WebPartStorage(Storage.Personal)]
    // The caption that appears in the tool pane.
    [FriendlyNameAttribute("My Custom String")]
    // The tool tip that appears when pausing the mouse pointer over
    // the friendly name in the tool pane.
    [Description("Type a string value.")]
    // Display the property in the tool pane.
    [Browsable(true)]
    [XmlElement(ElementName = "MyString")]
    [HtmlDesignerAttribute(BrowserBuilderType.Dynamic, 
      DialogFeatures = @"center:yes;"+
                          "dialogHeight=40;"+
                          "dialogWidth=51;"+
                          "status=yes;"+
                          "resizable=yes;"+
                          "unadorned=no;")]
    [WebDisplayName("My String")]
    [WebDescription("It's mine, all mine!")]
    [WebBrowsable(true)]
    [Personalizable(PersonalizationScope.Shared)]
    public string MyString
    {
      get;
      set;
    }

    protected override string GetCustomBuilder(string propertyName)
    {
      if (propertyName=="MyString")
      {
        return ReplaceTokens("_WPR_/WebPartHtmlDesigner.aspx");
      }
      return base.GetCustomBuilder(propertyName);
    }

    protected override void Render(System.Web.UI.HtmlTextWriter writer)
    {
      writer.Write(MyString);
    }

    public string GetDesignTimeHtml()
    {
      return MyString;
    }
  }
}

This web part is the simplest you can imagine, with a single text property that it renders. Now, notice the XmlRoot attribute decorating the class, the HtmlDesignerAttribute attribute decorating the property MyString, with its attribute DialogFeatures, and the GetCustomBuilder override returning a string containing a strange _WPR_ after being processed by ReplaceTokens. Follow the links to see why is that.

Now for the editor itself. I created a web site with a page and then copied it in the wpresources/[webpartnamespace] folder in the Sharepoint site. Take care about the web.config file in the wpresources folder which forbids the serving of aspx files. You need to remove or comment out the line <add verb="*" path="*.aspx" type="System.Web.HttpForbiddenHandler, System.Web, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" /> in it. Of course, the folder (in this case SharepointTests, as the namespace of the web part) must be an ASP.Net site, so register it as such.

Of course, this wpresources method is taken from a site that gave me the idea for this post and it is there to demonstrate the use of the ReplaceTokens method. That being said, the override for GetCustomBuilder could use a configuration file as a source for the url or you could even use a hardcoded string in the HtmlDesignerAttribute constructor like /SharepointTests/WebPartHtmlDesigner.aspx and then you just add the site SharepointTests to the root of the sharepoint site. No web.config edits, no bothering with resources folder and so on.

The page does the following: it displays the properties of the received parameter, then it returns the current date in a string and sets the background of the editor textbox to red.

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title></title>
    <script type="text/javascript">
        function OnDesignerLoad() {
            if (!window.dialogArguments) return;
            var s = '';
            for (var k in window.dialogArguments) {
                s += '<br/>' + k + ' = ' + window.dialogArguments[k];
            }
            var lbl = document.getElementById('lblInfo');
            lbl.innerHTML = s;
        }

        function OnDesignerUnload() {
            if (!window.dialogArguments) return;
            window.returnValue = (new Date()).toString();
            window.dialogArguments.style.backgroundColor = 'red';
        }
    </script>
</head>
<body onload="OnDesignerLoad()" onunload="OnDesignerUnload()">
    <form id="form1" runat="server">
    <div>
    <asp:Label runat=server Text="Design this!" ID="lblInfo" />
    </div>
    </form>
</body>
</html>

In order to avoid a lot of grief, add Response.Expires = -1; to the Page_Load of the page, as browsers cache a lot of stuff and you have no "Refresh" option in the editor dialog.

I would have liked to have a javascript event that would replace the editor with something completely different when the editing begins, like a color picker or a calendar. I am not sure if this can be done, not until someone presses the lookup button, anyway. If I find a way I will update the entry.

That should do it. Here is the link from which I draw my inspiration, it has pictures :), so you might like it better.

Notes on Sharepoint development

Published Jan 8, 2010

and has 2 comments

This entry will be sort of unorganised, as I am slowly crawling to the jungle of options and bad documentation for Sharepoint. I will structure it as a list of points that I pass through and the solution for each problem. Hopefully, you will find something useful in it.

First of all, you cannot run Sharepoint on XP. Don't event try it. You need at least a Windows 2003 machine with the free Windows Sharepoint Services (acronym WSS) or with the commercial Microsoft Office Sharepoint Server (acronym MOSS) installed. In order to access the site, you will have to access the http://SharepointComputer URL.

Section: publishing a web part to the Sharepoint site running on WSS.

A web part project is a class library with associated libraries for it. First step is publication, which means copying the library files into the sharepoint site bin folder.
Solution:
1. find the physical location for the Sharepoint site onto the Sharepoint computer(usually wwwroot\wss\VirtualDirectories\80)
2. copy the library files in the bin subfolder
Second step is loading the web parts into the Sharepoint gallery.
Solution:
1. open the http://SharepointComputer url
2. open the Site Actions top-right menu and go to Site Settings
3. open the Galleries - Web Parts link
4. select the New option from the top toolbar
5. the webparts in the library should appear in the list. check the checkbox next to them
6. click Populate Gallery. now the web parts should be available in any page
Last step is adding the web parts to a page.
Solution:
1. go to any page that you can edit
2. go to Site Actions and select Edit Page
3. click the appropriate Add a Web Part header
4. check the checkbox next to the web parts you want added, then click OK

Section: Troubleshooting the published web parts

If you have an error, you probably have a generic error page that says nothing of relevance.
Solution:
1. go to the physical location of the Sharepoint site
2. edit the web.config file and set customErrors to mode="Off"
3. refresh the Sharepoint site page in the browser
Now the error is much clearer and you see permissions errors that show Access Denied.
Solution:
1. go to the physical location of the Sharepoint site
2. edit the Properties of the library files that you copied in the bin folder and set access for the asp.net user or (if you are lazy) for Everyone to read the site
Now the error you see other permissions errors of which you understand nothing, mostly linked to OnPrerender or Render methods.
Solution:
1. go to the physical location of the Sharepoint site
2. edit the web.config file and (if you are lazy) set trust to level="Full" (capital F) or try to create your own security policy (complicated)
3. refresh the Sharepoint site page in the browser
Oh, joy, the ugly error page with lots of information has vanished, leaving instead a nice error page saying nothing useful except File Not Found.
Solution:
1. go to the physical location of the Sharepoint site
2. edit the web.config file and set compilation to debug="true" and SafeMode to CallStack="true"
3. refresh the Sharepoint site page in the browser
Weird and unexplained errors occur.Solution:
1. on the Sharepoint computer go to Administrative Tools and select Sharepoint 3.0 Central Administration
2. that should open a site that is used to configure the Sharepoint site
3. alternatively you can try the same Sharepoint URL in the browser, but using the port that was assigned to the configuration site (you can get the port from the name of the folder in wwwroot: wwwroot\wss\VirtualDirectories\[port that is not 80]
4. go to the Operations section and select Diagnostic Logging
5. In the Trace Log section you should see a Path, copy it to the clipboard
6. Open the said path in Start/Run and it should open the Logs folder
7. Open the latest log file (might need to press Ctrl-R to refresh the folder or to close the log file if already open and reopen it) and look for any cause for the errors

To be continued...

How to make a Visual Studio 2008 Sharepoint project

Published Mar 9, 2009

and has 4 comments

Recently I have been working on this Sharepoint project. I took it more out of curiosity as I didn't know anything about this piece of software. Now I know a lot more, like how hellish it is to code against it :) But it is also not a bad idea.

In case you don't know (as I didn't) Sharepoint is something like an ASP.Net site designed to work within a company, as an internal tool, allowing a lot of customizations and security from the web interface, with no code required. The desired end result is something looking like the IGoogle or Yahoo home pages, with web parts that can be configured, moved around, minimized, closed, made to interact one with another. Sharepoint Services is in itself a free software, but it only works on a Windows 2003 server or higher, so it sucks that way. Also, there is no real Sharepoint support for Visual Studio and most of the tutorials you find online are either too specific (blogs and such) or too vague (Microsoft style).

Also, there is a lot of confusion regarding the use of the interfaces in the Sharepoint dll, most of which have been obsoleted when the web part engine from .Net 2.0 was introduced.

Ok, short list of steps on how to start making a Sharepoint project in Visual Studio, assuming you code in Windows XP:

Install Windows Server 2003 on another machine (virtual or not)
Download and install Sharepoint Services 3.0 SP1 on it
Get the Microsoft.Sharepoint.dll file and copy it on your XP machine somewhere
Download and install the Sharepoint SmartTemplates for Visual Studio
Update the WSPBuilder application and some batch files in the template files
Start Visual Studio and create new project from installed templates
Add a reference to the Microsoft.Sharepoint.dll library
Code!

.

Now for the long list.
In order to install Sharepoint Services 3.0 SP1 you need to also install .Net 3.5 SP1. Actually it is a good idea to install this as well as the Visual Studio 2008 SP1 before you do anything (Sharepointy or not). Here is a link.

The Sharepoint SmartTemplates actually create a folder structure that is then used by the WSPBuilder utility to create the WSP file that installs a web part in Sharepoint. You can either import it in the site (upload) or use the setup that is provided with the templates. The problems I met when using it are linked primarily with the version of WSPBuilder that is included in the templates I've downloaded (version 0.2).
So first locate the installed template files: you can usually find them in My Documents/Visual Studio 2008/Templates/Project Templates/ as two zip files. First step is to download the latest WSPBuilder and replace it in the archives. The next step is to change the WSP/createwsp.bat file like this:

@ECHO OFF
DEL .\$safeprojectname$.wsp
ECHO Copying DLL ...
XCOPY /Y ..\BIN\$safeprojectname$.dll .\80\BIN\
ECHO Copying ASCX files ...
XCOPY /Y ..\*.ascx .\12\TEMPLATE\CONTROLTEMPLATES\$safeprojectname$\
ECHO Building WSP ...
..\WSPBuilder\WSPBuilder.exe -WSPName $safeprojectname$.wsp -BuildCAS false -SolutionID $guid2$ -DLLReferencePath "[the folder path where you copied Microsoft.Sharepoint.dll]" -TraceLevel Verbose
ECHO Copying WSP file ...
XCOPY /Y .\$safeprojectname$.wsp ..\SETUP\

The bold parts you must add to the file. The delete because otherwise you might be able to compile the project using the old WSP file if the WSPBuilder run fails. The others is in order to be able to compile the WSP using the sharepoint library and see any errors that might occur.
Alternatively, you can change the WSPBuilder/WSPBuilder.exe.config file with the DLLReferencePath and TraceLevel options.
Ok, now repack the folders into the archives and copy them back.

Now, after you build the project, you will have a Setup folder in the bin folder. That you must copy to the Windows 2003 computer and run. It will install the web part(s) in the project. In order to add more webparts to the project and make them compile in the setup project you need to alter the WSP\12\TEMPLATE\FEATURES\SmartPartTemplate\manifest.xml file and describe the files you add to the project.

After you run the setup project, you have to open the Sharepoint site and go to Site Settings -> Site collection features and activate the web part. Only then you can actually add it to a page.

Sounds complicated? Well, read more :)

Make sure that when you have finished with a web part you DO NOT DELETE THE SETUP PROJECT, but run it to remove the web part first! In order to remove an install web part from a Sharepoint site you must delve into the hell of command line utilities! Well, it's natural to me, but I am an old guy! ;)

Just supposing that you have done the undoable and you managed to delete a setup project with the part still installed, you must use the stsadm tool.
First find it on the Windows 2003 computer (with Find Files) then add the containing folder to the path. Then run cmd in the Start/Run menu and use the following commands:

stsadm -o enumsolutions

will enumerate the installed solutions. Remember the name of the solutions you want to remove.

stsadm -o retractsolution -name "[name of solution]" -immediate

will retract the web part project and allow you to delete it.

stsadm -o deletesolution -name "[name of solution]" -override

retracting doesn't always work, so the override option will force a delete.

Sometimes you manage to change the GUID of the project and you get an error like A solution with the same name "SomeName.wsp" or id "Some GUID" already exists in the solution store.. You delete it, but you still have this error. Try to install the solution with the setup project. Wait for the error, exit the setup project. Use stsadm -enumsolutions to see what the GUID of the project is, copy it, replace the SolutionId GUID in the setup.exe.config file with this one. The setup should then work.

This is about it. I've wasted a few hours to learn all of this. I know it's not terribly organized, but writing something is better than sharing nothing.