Fear and Loathing

I'm currently setting up a common component repository using SharePoint and was looking at a few ideas for it. One thing that I've always found rather interesting was the Portal Owner QuickStart Guide that gets installed by default when you setup a new portal. This rather lonely web part goes practically unnoticed because it is there as a guide when you setup a portal and, once used, is usually deleted. However it's a powerful user experience tool that you may want to take a second look at.

When I said it was a web part, it is. It's a very specific web part buried deep inside of the Microsoft.SharePoint.WebControls namespace in the SharePoint assembly. It's not just a simple content web part or a data view. It's a full blown web part that can be customized for your use. The problem is that it's undocumented, not very user friendly to configure and even harder to customize.

Basically the web part has a custom property called "LinkHtml" that contains pseudo-HTML that will do three things:

1. Render the text for your link
2. Send the user to the link when they click on it
3. Popup an additional link that you can use for help or information

Here's how you customize the content of your web part:

1. With the web part on your page click on "Edit Page" from the navigation menu
2. Select the QuickStart web part and choose "Modify Shared Web Part"
3. On the tool pane you can specify all the typical web part properties like title, size, etc.
4. Down at the bottom of the tool pane, expand out the Miscellaneous section
5. There you'll find the HTML for links field. This is where the magic happens.

The HTML for links field contains pseudo-HTML that is processed by the web part. Here's a sample that produces one link in a group:

<TABLE class="ms-ls">
<TR>
<TD colspan=2 style="padding-top: 6px;" class="ms-smallheader">
<SPAN class="ms-announcementtitle">Sample Group</SPAN>
</TD>
</TR>
<TR>
<TD valign=top><IMG SRC="%LSTBULETGIF%" alt=""></TD>
<TD width="100%" valign=top class="ms-lsmin ms-vb">
BEGINPOPUP /SamplePopup.htm ENDPOPUP
BEGINNAVIGATE /SamplePortalPage.aspx ENDNAVIGATE
BEGINTEXT Sample Text ENDTEXT
</TD>
</TR>
</TABLE>

The magic that happens are the following keywords:

• BEGINPOPUP [insert link to your popup content here] ENDPOPUP
• BEGINNAVIGATE [insert link to where you want the user to go here] ENDNAVIGATE
• BEGINTEXT [insert text to show the user here] ENDTEXT

Note: All three must be present in the HTML for links for the web part to work. Specifying a blank value will render the text incorrectly.

Another thing the web part does is inject the following javascript onto the page when the portal renders it. This provides the popup window that you specify in each BEGINPOPUP/ENDPOPUP pair (don't worry, you don't have to write this it's included when the web part is added to your page but here for reference):

function PQSDI(helpUrl)
{
  window.open(helpUrl,
    '_blank',
    'scrollbars=yes,
    resizable=yes,
    fullscreen=no,
    channelmode=no,
    status=no,
    toolbar=no,
    menubar=no,
    location=no,
    directories=no,
    width=200,
    height=571');
  return false;
} 
</Script>

Once you setup the HTML for links content, the web part will parse it and render out the right HTML to the end user (creating an ONCLICK event to call the PQSDI function when the link is selected).

Yes, it's ugly to edit and no you cannot change the size/position of the popup window but this does provides a nice alternate facility to present information to the user. Also be careful when editing the content. It's very picky about the formatting and sometimes you'll get it, other times it displays nothing or not quite what you want (I haven't had it invalidate my page or anything). Caveat emptor.

So you may want to export this thing to a DWP file and save it for later use if you have something new to introduce to your users and want a way to provide a sort of self-training guide. Hope this helps!

This is my comment policy for this site. It was inspired (and plagiarized for the most part) from KC Lemson's Comment Policy on her blog (she's an uber-cool release manager for Microsoft Exchange Server, check out her blog if that's your thing).

• I reserve the right to edit, delete, or ignore any comment. I don't delete comments disagreeing with me, but I do delete comments that show offensive or abusive language or behavior, or comments that seem to be from someone misrepresenting him/herself.
• I reserve the right to turn off support for comments at any time. I generally do this after getting an obvious comment spam, and turn it back on a while later.
• I reserve the right to ignore any comments
• I reserve the right to ignore email or phone calls I get via this blog [1]
• I reserve the right to ignore everything (that pretty much covers it)

Guidelines/expectations:

• If you want to ask me a specific question, email me but understand my time is limited so I may not get back to you. I generally don't track all of the comments here.
• If I know the answer to a question off the top of my head, I will generally answer it within a day or so.
• If I don't know the answer to a question, I probably won't research it, and I also won't follow up to say that I don't know the answer (it's just too much work for the amount of questions I get, and I see no need to repeatedly go around saying that I don't know anything :-).
• My deep expertise is in SharePoint, .NET Architecture, Agile Practices, and Software Development and Design. That doesn't mean I know everything about those areas, just that I am much more likely to know the answer or be able to suggest additional areas of investigation for technical problems in those areas.

[1] Unfortunately, just not publishing this information isn't enough to stop some people from contacting me via those methods. Here's a hint: If I don't make it easy to contact me via phone, it's because I don't want to be contacted by phone. I don't even like it when my coworkers call me, let alone people I don't know, asking me for help with a problem to which I don't know the answer.

Bottom line... stop spamming me you screwheads!

Unit Testing support should be included with all versions of Visual Studio 2005 and not just with Team System

This is like the SharePoint version of Freddy vs. Jason (or Aliens vs. Predator if that's your sort of thing). It's a debate that, IMHO, has been asked and answered a thousand times over in the newsgroups and emails but people still are confused. Bill English said it best to me once (and continues with this position which I completely share).

• SharePoint Areas are for aggregation.
• SharePoint Sites are for collaboration.

Read this. Learn this. Live this.

True, you can use the portal to create document libraries, check-in/out and all that good stuff but it becomes a bit of a nightmare in organization from what I've found. Moving it down to a WSS site and letting the user manage access and all that works much better. Also you can create public areas for the information and let users “publish“ information up to the portal into that area which lets them decide what they want to show. They'll go on in their WSS site adding documents and only pushing up to the portal what others need to see.

I've completed a tool to migrate our documents with version histories from 2001 to 2003. I know SPIN/SPOUT do this en-masse but for our needs, there wasn't a 1:1 mapping with old portal directory structure and new portal. There were some other tools in this space, but I had some fun writing an assembly that bridges between the two. Also the new assembly comes in handy when I want to access SharePoint 2003 and do things without having to deploy web parts or executables on the server (everything is done through SharePoint web services).

The tool has gone off to QA for our own migration so I'll put together a small spike project with examples on how to use it. I'll include some samples on using the SharePoint wrapper assembly as it's handy to be able to bring up a treeview of all of your sites. I used it for another tool we created for deploying web parts to all sites or deleting lists. It can easily be extended to perform more functions but this was all we needed right now.

If there's any specific requests for functionality in the assemblies let me know and I'll include them before a release later this week. Just have to package up the code and put together some examples then release everything in a day or so.

This is something that's been bugging me for awhile so I thought I would throw it out there. "Is it really worth keeping version history of documents?". Other than legal reasons, I can't see why any would need version history of a document. Source code. Sure. Absolutely. A document? I'm beginning to think that there's no real reason why history is that important.

Look at a document. Okay, so you'll be able to go back in time and see that Joe added a paragraph or something. If you use Office, this feature is already built into the product. If it's a binary file of some kind (like a PDF) you really can't compare or track revisioning in the document (yes, Adobe had this feature but you need special tools to use it). The only case I can see is a text file where you can do diffs of the versions, but then why would I really care?

Retaining history seems to be so important to some, but I wonder if that's really the case? Maybe take a look at your documents and try to justify why you think you need a complete version history. Is it really worth keeping in the long run?

Things have changed since I started programming back in the 80s. However there are a few truths that are universal. Here's my list of the essential books all programmers, designers, coders, architects, etc. should have in their repository. Also if you're hiring new people out of University or something, giving them this stack would be a good way to introduce them into the world.

Code Complete (2nd Edition!)
Eric Evan's Domain Driven Design
Design Patterns
Kent Beck's Test Driven Development: By Example
Martin Fowler's Refactoring: Improving the Design of Code
UML Distilled

There are a couple of others that are great too (there are more):

Rapid Development
The Pragmatic Programmer

As part of my migration tool that I broke down and wrote, I've created a .NET assembly for accessing both SharePoint 2001 and 2003 systems. It uses PKMCDO internally to talk to the Web Storage System and get information about folder and documents and .NET web services to talk to 2003 servers and sites to perform basic stuff like adding web parts, deleting lists, etc. All you need to do is point it at your SharePoint server so you can build desktop apps or non-SharePoint web apps to do SharePoint functionality. I'll clean up the assembly and make it available this weekend for anyone interested. It's not the perfect solution (using web services it's somewhat limited) but at least you can deal with a SharePoint site as a real object.