When stepping off the beaten path with SharePoint, you never know what you're going to encounter. This time I ended up in the tundra with no compass and labyrinthitis.
The goal was simple: When a web part is dropped on a page, allow the user to configure it through a custom form rather than the toolpane.
The approach quickly became apparent: Web Part Page Services Component (WPSC)
The amount of time it took to figure out the correct incantation was ridiculous: about four hours - brace yourself from some bitching and moaning. It's one of those things which look simple once you know the answer, but there were so many false leads that it made my head spin.
So to get to the point, here are the magic two lines of code. In this example I'm simply setting the title of the current web part to "New Title".
varPart_WPQ_.Properties.Item(
"http://schemas.microsoft.com/WebPart/v2#Title").Value = "New Title";
varPart_WPQ_.Save(false, SavedWebPart_WPQ_);
Let's look at what we have here:
varPart_WPQ_.Properties
This will get you the collection of properties for the current web part. You may think that you can get there by using WPSC.WebPartPage.Parts, but that's one of those false leads.
Item("http://schemas.microsoft.com/WebPart/v2#Title")
Here I'm getting the title property of the web part, then setting it. Of course knowing the answer, I now see it right here. If you want to get the rest of the properties' names, it's a simple for loop over the Properties collection, and for each item you pull out the... well, smartypants? How do you get the name of the property? .ID, .name? It's actually it's .NamespaceURN. Obvious, don't you think?
OK, we changed the value, and now it's time to save our changes.
"Well, that's easy, there is a Save function listed right on this page. So just call WPSC.Save() and..."
Nope, another false lead. Alright, alright, you get the point and my complaints are getting annoying. I'll stop.
varPart_WPQ_.Save(false, SavedWebPart_WPQ_);
This takes care of the saving. The callback function can look something like this:
function SavedWebPart_WPQ_( saveWorked, exceptionMessage) {
if (saveWorked) { alert("Saved!"); }
else { alert("Save Failed: "+ exceptionMessage); }
window.location.reload();
}
If you want to see a case where saveWorked is false, just try using this in Firefox. And that brings me to another point. The MSDN page for WPSC says:
The WPSC is available as two Microsoft JScript files—one that supports Internet Explorer 5.0, and another that supports Internet Explorer 5.5 and later. At run time, the Web Part infrastructure detects the browser type and provides the appropriate version during Web Part Page rendering.
I guess this is their way of saying that it's only supported in IE. Maybe setting the user agent would make it work, but since we only rely on this functionality when the web part is being added to the page and configured, we can live with giving non-IE users a message that they are not loved.
So, the final touch is to actually see the change which was just made by reloading the page:
window.location.reload();
And there you have it. Open your Content Editor Web Part and give it a shot.
Last two words of advice:
1. Be careful not to get into a situation where the user doesn't have the permissions to update the property.
2. If you want something to happen after the page loads, use
WPSC.RegisterForEvent("urn:schemas-microsoft-com:dhtml","onload", YouFunctionToCallOnLoad_WPQ_);
OK, let's make that three words of advice:
3. Always use _WPQ_ to uniquely identify your web part on the page.