In this step I want to start filling out the Portal with some business areas from a list that has been defined for us

We're going to use a CSV file in the same way as we did for the users. The start of the file looks like this

AreaURL, AreaName, AreaTitle, AreaDescription, AreaTemplate
"Divisions","Divisions","Divisions Home Page", "This area includes links to content based on divisions in the company.", "BLANKINTERNET#2"
"Divisions/Sales","Sales","Sales Home Page", "This area includes information related to sales.", "BLANKINTERNET#2"
"Divisions/Support","Support","Support Home Page", "This area includes information related to support.", "BLANKINTERNET#2"
"Divisions/HumanResources","Human Resources","Human Resources Home Page", "This area includes information related to human resources.", "BLANKINTERNET#2"
"Divisions/Marketing","Marketing","Marketing Home Page", "This area includes information related to marketing.", "BLANKINTERNET#2"

We have a AreaURL column which is the URL relative to the site collection root and we also have the Area Name, Title and description.
The AreaTemplate field in this example is BLANKINTERNET#2 (format is WebTemplate#Configuration).
Now I know this is the Publishing Site template under the Publishing tab but we could just as easily create a team site, subsites of blogs or WIKI's etc.
The easist way to find out what template and configuration to use is to create a site of the type you want through the UI and use powershell to find out what template is used

Run these commands to get a list of the Templates in use on the portal

$sp=new-object microsoft.sharepoint.spsite("http://sps:2828")
$sp.allwebs | select serverrelativeurl, webtemplate, configuration

also checkout Dan Winter's list of the MOSS 2007 templates on his blog http://blogs.msdn.com/dwinter/archive/2006/07/07/659613.aspx

Now to the PowerShell functions
First a simple wrapper to add a new site to the Site Collection: add-spweb

# Function:         add-spweb
# Description:        Create a new Web
# Parameters:        SiteCollectionURL     URL for the root of the Site Collection
#            WebUrl         relative URl of the sub site
#            Title             Title string
#            Description         Description string
#            Template        Template to use
#
function add-spweb([string]$SiteCollectionUrl, [string]$WebUrl, [string]$Title, [string]$Description, [string]$Template)
{


    # Create our SPSite object
    $spsite=new-object Microsoft.SharePoint.SPSite $SiteCollectionUrl

    # Add a site
    $spsite.Allwebs.Add($WebUrl, $Title, $Description ,[int]1033, $Template, $false, $false)
    
    # Note: The new SPWeb will be returned from this call
}

And then a function that will import the CSV file, create a set of objects for each Area line in the CSV file and pipe the list to add-spweb to add a new site.

# Function:         Import-Sites
# Description:        Create a set of subwebs as listed in the import CSV file
# Parameters:        CSVFile         Location of the CSV file containing the list of webs
#            SiteCollectionURL     URL for the root of the Site Collection    
#    
function Import-Sites([string]$CSVFile, [string]$SiteCollectionURL)
{
    Import-Csv $CSVFile | foreach-object { add-spweb $SiteCollectionURL $_.AreaURL $_.AreaName $_.AreaDescription $_.AreaTemplate } | foreach-object {$_.Navigation.UseShared=$true; $_.Update() }
}

I'm also setting UseShared to true which tells the subareas to use the main portal navigation elements.

Use it like this

import-sites "ContosoAreas.CSV" http://sps:2828

The next step will be to import some content into our Publishing Areas...

Ok now we have the users in AD we can add them to the portal. Again we can use import-csv to add them from the users CSV file

heres the routine

Step 2 in our series is to add some users to Active Directory.

First we need a simple routine to add users to Active Directory

Update 3-11-2006 : The original add-aduser would only work in versions of PowerShell pre RC2. RC2 included some breaking changes to how the DirectoryEntry object handled. I;ve added an RC2 compatible routine.

Pre RC2 version

function add-aduser([string]$LoginName, [string]$DisplayName, [string]$FirstName, [string]$LastName)
{

    $cn=$LoginName
    $sam=$LoginName
    $pw="P@ssword1"


    $ad= new-object System.DirectoryServices.DirectoryEntry
    $u = $ad.get_Children().Find("CN=Users")
    $NewUser = $u.get_Children().add("CN=$cn",'User')

    
    $NewUser.InvokeSet("sAMAccountName",$sam)
    $NewUser.InvokeSet("displayName",$DisplayName)
    $NewUser.InvokeSet("FirstName",$FirstName)
    $NewUser.InvokeSet("LastName",$LastName)
    
    $NewUser.CommitChanges()

    $ad=new-object System.DirectoryServices.DirectoryEntry
    $u = $ad.get_Children().Find("CN=Users")

    $NewUser= $u.get_Children().Find("CN=$cn");
    $NewUser.Invoke("SetPassword",$pw)
    $NewUser.InvokeSet("AccountDisabled",$false)

    # set that the password never expires
    $NewUser.userAccountControl[0] = $NewUser.userAccountControl[0] -bor (65536)

    $NewUser.CommitChanges()

}

RC2 Version

function add-aduser([string]$LoginName, [string]$DisplayName, [string]$FirstName, [string]$LastName)

{

   $cn=$LoginName
   $sam=$LoginName
   $pw="P@ssword1"

   # Get an ADSI object for the default domain
   $ad= [ADSI]""

   # Get the Users OU as default
   $ou = $ad.psbase.Children.Find("CN=Users")

   # Add the user
   $NewUser = $ou.psbase.Children.Add("CN=$cn",'User') 

   # Set the basic properties
   $NewUser.Put("sAMAccountName",$sam)
   $NewUser.Put("displayName",$DisplayName)
   $NewUser.Put("givenname",$FirstName)
   $NewUser.Put("sn",$LastName)

   # Commit changes 
   $NewUser.SetInfo() 

   
   # Set our password 
   $NewUser.psbase.Invoke("SetPassword",$pw) 

   # And enable the account
   $NewUser.psbase.InvokeSet("AccountDisabled",$false) 

   # set that the password never expires
   $NewUser.userAccountControl[0] = $NewUser.userAccountControl[0] -bor (65536) 

   # Commit changes
   $NewUser.SetInfo()

}

This gets us a function we can call to add test users. Note we're hardcoding the OU to users, to make this more production you'd want to parameterize the OU, passwords and set the AccountControl flags to Change Password on next login, there's a lot of other resources out there to help with that.

So If we put that in a script file loaded from our Profile we can call it like this

add-aduser "joeb" "joe blogs" "joe" "blogs"

That's nice but with PowerShell we can do better. We really want to data drive this and the built-in import-csv function will parse a CSV and create a collection of objects that match the CSV schema.

Take a simple User's CSV file like this

Now if we run an import-xml command on the CSV file this is the output

Each line has been parsed and an object created. To see this more clearly we can use the get-member command to reflect over the object and see what the object looks like.

(Note: it will be PSCustomObject not MshCustomObject in post RC0 builds , I'm running Exchange 2007 on this VPC which requires PowerShell RC0)

As you can see the CSV columns have been added as a NoteProperty property (this is part of the extensible type system).

So now we can create a really simple function to import a CSV file of users, pipe the output to a foreach loop and add each user to Active Directory.

# Function:         Import-Users
# Description:        Create users in active directory as listed in the import CSV file
# Parameters:        UserFile         Location of the CSV file containing the users
#
function Import-Users([string]$UserFile)
{
    Import-Csv $UserFile | foreach-object { add-aduser $_.LoginName $_.DisplayName $_.FirstName $_.LastName }
}

Note that when you receiving a collection of objects in the pipeline in a scriptblock you have to loop over each object. The $_ is a special variable that gives you the current object in the loop which you can use to access properties and methods.

To call we just do

Import-Users Users.CSV

With this power 500 users are as easy as 1 user.

We're not limited to just using CSV files, I've just picked that format as I'm always amazed at the amount of data I get given in Excel spreadsheets and word documents and CSV is the easiest intermediate format to work with. There is also an import-xml command which we will use later to import an XML file containing portal content. As Powershell can call any .Net library the System.Data set of classes could also be used to pull information from databases.

The next entry will be adding our users to SharePoint.

Hi,

Just like to thank all those who attended the Presentation last Thursday on controlling SharePoint with PowerShell and Extending the Administration Object model.

I know it was pretty fast paced and technical so I plan to follow it up with a series of blogs entries recapping the steps and scripts in greater detail.

Some of the topics covered were:

   Powershell Basics

   Exchange produces PowerShell samples from the new UI console

   Creating a new SharePoint WebApplication and applying a portal template

   Adding users defined in a CSV file to Active Directory

   Adding those users defined in a CSV file to SharePoint roles

   Adding in webs as defined in a CSV file

   Adding content in an XML file to a Publishing Web

   Uploading a directory of files in 4 lines of Script.

   Creating a custom STSAdm command

   Creating an application to sync User Profile properties back to Active Directory

I've attached the PowerShell scripts and PowerPoint Slides.

I'm not able to post the sample code of the AD Sync application as parts of the code is proprietary but I will post a sample application that does a scheduled backup using exactly the same template.

Presentation-SPPowerShell.zip (46.78 KB)

Flexnet Consultants

A quickie.

Heres 4 lines of code to upload a whole directory of files, in this case pictures, to a SharePoint document or image library.

The directory pictures contains the images.

The destination is the image library SiteCollectionImages for the portal running on port 2828

$wc = new-object System.Net.WebClient
$wc.Credentials = [System.Net.CredentialCache]::DefaultCredentials
function getdestname($filename){ "http://sps:2828/sitecollectionimages/" + $(split-path -leaf $filename)}
dir "pictures" | % { $uploadname=getdestname $_; $wc.UploadFile($uploadname,"PUT", $_.FullName) }

Have I mentioned PowerShell just rocks?

In this PowerShell and SharePoint series I'd thought I'd spin through, in order of use, the commands used to create the demo Portal site in the SUGUK user group presentation.

First step: Creating a Web Application using the API.

The new SPWebApplicationBuilder object makes this easy. This object creates a Web Application using a default port and the default settings, you can override any settings you like in your script but for simplicity I'm just changing the default timezone.

SPWebApplicationBuilder also creates an AppPool to go along with the new IIS Website which has Network Service as the user. In Beta 2TR that account doesn't have the correct permissions so you need to change it to a local administrator. I tend to dev on a Virtual machine DC so I'd use the domain admin.

So we have three routines

   new-SpWebApplication - Create the IIS Website and SharePoint settings

   set-apidentity   - set the Application Pool credentials

   get-defaulttimezoneid   - returns the Greenwich Meantime TimeZone ID (adjust this one to suit)

We also then need to create the set of webs that will live inside the Web Application, this is done by calling the Add Method on the Sites method of the Web Application passing it various parameters the most important of which is the template ID, in this case SPSPORTAL to give us the default SharePoint Intranet portal look.

The Powershell commands to tie all this together are

$webapp=new-SPWebApplication

set-apIdentity "http://sps:yourportnumber" "contoso\administrator" "password"

#Create Portal Site Collection

$webapp.Sites.Add("/", "SUGUK Intranet","SUGUK Intranet",1033, "SPSPORTAL", "contoso\administrator", "administrator", "administrator@contoso.com")

Here's new-SPWebApplication

# Function:         new-SPWebApplication    
# Description:        Create and return a new SPWebApplication object
#             Use the default values which will create the web site at a random port
# Parameters:        none
#
function new-SPWebApplication()
{

    # Get our local SPFarm object
    $spfarm = [Microsoft.SharePoint.Administration.SPfarm]::Local

    # Use the new SPWebApplicationBuilder
    $appbuilder= new-object Microsoft.SharePoint.Administration.SPWebApplicationBuilder $spfarm

    # Create Web Application with the default settings
    
    $webapplication = $appbuilder.Create()

    # Set the timezone to Greenwich Mean Time
    $timezone=get-defaulttimezoneid
    $webapplication.DefaultTimeZone = $timezone.ID
    $webapplication.Update()

    # Actually queue the application for creation
    $webapplication.Provision()

    # return the SPWebApplication object
    $webapplication

}

# Return the Default TimeZone as used for the majority of our sites
#
function get-defaulttimezoneid
{
    [Microsoft.SharePoint.SPregionalSettings]::Globaltimezones | where-object { $_.Description -like "*greenwich*" }
}

Now to change the Credentials for the AppPool is also really simple in V3. The SPWebApplication object exposes a ApplicationPool property which you can use to set its credentials

# Function:         set-apidentity    
# Description:        Set the credentials for the application pool for the given Web Application
# Parameters:        Url        Site Collection URL
#            UserName     UserName
#            Password     Password
function set-apidentity([string]$SiteCollectionURL, [string]$UserName, [string]$Password)
{

        
    $webapp=get-spwebapplication $SiteCollectionURL
    
    
    $webapp.ApplicationPool.CurrentIdentityType= [Microsoft.SharePoint.Administration.IdentityType]::SpecificUser
    $webapp.ApplicationPool.UserName= $Username
    $webapp.ApplicationPool.Password= $Password
    
    # Save the settings
    $webapp.ApplicationPool.Update()

    # Roll the settings out via a Admin Job
    $webapp.ApplicationPool.Provision()


}

To me this is way easier than using the UI.

Hi,

I'm about to start off a new series of entries about using Powershell to control SharePoint.  There's a big gap in the ability to script SharePoint between stsadm commands and custom .net programs and PowerShell fills it nicely.

All my entries from now on will focus on SharePoint version 3.

PowerShell is 'DOS for the .NET generation' (c)  and its a fantastic way to both interactively control SharePoint via its Object Model from a command line and to create scripts that can be run in a batch. Its currently at version RC2 and is available from here http://support.microsoft.com/kb/925228
It installs as a windows update package rather than a separate install as it used to in earlier betas, thats a sign of its being a core element of Windows going forward.

Ok lets do some Powershell SharePoint basics.

First although Powershell can call any .net class the assembly must be loaded first.
By default Powershell loads a small list of assemblies, this command will get the list of loaded assemblies:

[System.AppDomain]::CurrentDomain.GetAssemblies()

The syntax for calling a .NET class's static method is for the brackets go around the Class name and the double colon between the class and the static method

The output from that is a little hard to read lets just list the files involved

[AppDomain]::CurrentDomain.GetAssemblies() | foreach-object { split-path $_.Location -leaf } | sort

Here's the list of files the above command gives on my machine

Microsoft.PowerShell.Commands.Management.dll
Microsoft.PowerShell.Commands.Utility.dll
Microsoft.PowerShell.Commands.Utility.resources.dll
Microsoft.PowerShell.ConsoleHost.dll
Microsoft.PowerShell.ConsoleHost.resources.dll
Microsoft.PowerShell.Security.dll
Microsoft.PowerShell.Security.resources.dll
mscorlib.dll
System.Configuration.Install.dll
System.Data.dll
System.DirectoryServices.dll
System.dll
System.Management.Automation.dll
System.Management.Automation.resources.dll
System.Management.dll
System.ServiceProcess.dll
System.Xml.dll

As you can see SharePoint is not one of those in the list, also missing that could be useful is the System.Web assembly

There are a few ways to load an assembly onto your AppDomain but the easiest is to call the static method LoadWithPartialName on the Assembly class.

[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint")

LoadWithPartialName is great because you dont need to specify the full name to the assembly which in SharePoint v3 would be

[System.Reflection.Assembly]::Load("Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c")

and for MOSS

[System.Reflection.Assembly]::Load("Microsoft.SharePoint.Portal, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c")

Now a lot of people will cry LoadWithPartialName has been deprecated as MS have got concerned how it has to make to many guesses over locating the assembly.
Personally I want to see a method that will simply load the latest version of the assembly I've told it to load, in a controlled environment like a SharePoint server thats exactly the behaviour I want to see. <rant> MS for god's sake just document the method properly and let devs choose whether to use it or not. </rant>

Anyway if you want to use the Load method take a look at this blog entry: http://www.leeholmes.com/blog/HowDoIEasilyLoadAssembliesWhenLoadWithPartialNameHasBeenDeprecated.aspx

Now you don't want to type the load commands each time so put them in your Powershell Profile script.
This changes location a lot depending on which version of Powershell your running so see this entry for the full details http://www.leeholmes.com/blog/TheStoryBehindTheNamingAndLocationOfPowerShellProfiles.aspx

So now what can we do with this?

Well first lets get a site collection we can play with

First create an SPSite object and pass it a valid site url

      $spsite= Microsoft.SharePoint.SPSite("http://portal.contoso.com")

to see the contents of the object just type the object on the command line

$spsite

To just get a list of the methods on the SPSite object

   $spsite | get-member -membertype method

To just get a list of the properties on the SPSite object

   $spsite | get-member -membertype property

To get a list of all sub sites

   $spsite.AllWebs

Get a list of webs ordered by the last time that the contents have been changed

   $spsite.allwebs | select LastItemModifiedDate, URL , Created | sort LastItemModifiedDate

There's lots more that you can do and I'll post them as I go.

Whoa, its been a while since I've blogged but sundry projects and SharePoint v3 has taken up all my time.

Just to let you know that I'm presenting at the UK SharePoint users group meeting this Thursday the 26th October.

I'm doing 2 sessions; one on using Powershell with SharePoint v3 in which I'll go through Powershell basics and how to use it to control SharePoint. Then I will attempt to build a portal without touching any settings in the UI! Wish me luck.

The second one will explore the new extensible admin object model.
This will demonstrate creating custom stsadm commands along with creating an application that syncs changed MOSS User profile information back to Active Directory.
It will be a small application integrated into SharePoint and built using the new SPService, SPServiceInstance and SPJobDefinition classes.
I'll be describing how they work together, its cool stuff.

Everybody is welcome (you just need to register on the suguk site) so if you are in London this Thursday it would be great to see you.  The meeting kicks off at 6.30pm

If you plan to attend just register on the SUGUK site and leave your name on this list
http://suguk.org/forums/thread/1490.aspx

cheers,
Colin

Flexnet Consultants have just released a brand new free Web Part.

The PhotoGrid WebPart will show a nXn grid of Picture Library images with a each image randomly chosen to be enlarged. This is similar to the Flikr Photobadge.

You can set the number of pictures on each row and the number of rows along with the time the enlarged picture is displayed (Display time).

Our Web Parts page uses a Flash embedded demo to show you how it would look.

http://www.flexnetconsult.co.uk/WebParts/WebParts.htm

Version 1.2 of our free Flash Slideshow Web Part is released.

The Slideshow Web Part will show a rotating display of all the pictures in the Picture Library with an adjustable fade transition between each picture.

This version has better support for SharePoint sites running on non standard http ports.

It now also supports all the image formats that the Picture Library does.

http://www.flexnetconsult.co.uk/WebParts/WebParts.htm

Sometimes when working in client-side javascript you'd like to know your Windows username for instance to add to the root Outlook Web Access URL for say a contacts search i.e. http://flexnetowa/exchange/colinb/contacts/?cmd=search 

Now the stock answer whenever this comes up in the SharePoint newsgroups is: it can't be done, use server side code to render it out.

Thats fair enough and easy to do, I've created a WebPart that stores a users details as a JavaScript object so it can be referenced in code. But what if I don't want to install yet another server-side Web Part.

In the interests of providing code you won't get anywhere else here's the tip.

Now its true the SharePoint Web Services provide no method to tell you who you are (side-note: I suspect you may be able to do this by creating a CAML query against the userinfo table but I've not managed to get that working) but you can get your username by using the FrontPage RPC and calling author.dll, this is how Word displays who you are on its TaskPane when you open a Word document in a document library.

When you call the author.dll ISAPI DLL with the 'open service' method name it returns a host of information about the server and the services it provides.

I'm using the XmlHttpRequest object again which despite the name can also be used to retrieve a text document not just an XML one.

heres the returned information

<html><head><title>vermeer RPC packet</title></head>
<body>
<p>method=open service:6.0.2.6356
<p>service=
<ul>
<li>service_name=
<li>meta_info=
<ul>
<li>vti_defaultlanguage
<li>SW|en-us
<li>vti_usernames
<li>VR|
<li>vti_servercharsets
<li>VX|windows-1257 big5 windows-1252 windows-874 utf-8 windows-1251 windows-1256 euc-kr gb2312 windows-1253 windows-1258 koi8-r iso-8859-1 gb18030 iso-2022-jp ks_c_5601-1987 windows-1250 windows-1255 us-ascii euc-jp unicode unicodeFFFE windows-1254 iso-8859-2 iso-8859-15 shift_jis
<li>vti_scnoprompt
<li>IX|1
<li>vti_toolpaneurl
<li>SX|http://sharepoint.flexnet.ds/_layouts/1033/toolpane.aspx
<li>vti_assemblyversion
<li>SX|Microsoft.SharePoint, Version&#61;11.0.0.0, Culture&#61;neutral, PublicKeyToken&#61;71e9bce111e9429c
<li>vti_webtemplate
<li>IR|1
<li>vti_hasonetlayoutfiles
<li>BR|true
<li>vti_navbuttonnextlabel
<li>SR|Next
<li>vti_casesensitiveurls
<li>IX|0
<li>vti_htmlextensions
<li>SX|.html.htm.shtml.shtm.stm.htt.htx.asp.aspx.alx.asa.hta.htc.jsp.cfm.odc.dwt.php.phtml.php2.php3.php4.
<li>vti_approvallevels
<li>VR|Approved Denied Pending&#92; Review
<li>vti_themedefault
<li>SR|none
<li>vti_welcomenames
<li>VX|default.htm default.aspx
<li>vti_servertz
<li>SX|+0100
<li>vti_adminurl
<li>SX|http://sharepoint.flexnet.ds/_layouts/1033/settings.aspx
<li>vti_showhiddenpages
<li>IW|1
<li>vti_categories
<li>VR|Business Competition Expense&#92; Report Goals/Objectives Ideas In&#92; Process Miscellaneous Planning Schedule Travel VIP Waiting
<li>vti_featurelist
<li>VX|vti_RulesScript vti_ServerIndexServer vti_TimedDocEvents vti_ServiceMarkUrlDirExec vti_DocSaveToDB vti_ServiceMarkUrlDirBrowse vti_ACAll vti_ServerODBC vti_ServerASP vti_ServiceMarkUrlDirScript
<li>vti_hasfulltextsearch
<li>IX|1
<li>vti_defaultcharset
<li>SR|windows-1252
<li>vti_navbuttonuplabel
<li>SR|Up
<li>vti_httpdversion
<li>SX|Microsoft-IIS/6.0
<li>vti_serverlanguages
<li>VX|en-us
<li>vti_sourcecontrolproject
<li>SX|&#60;STS-based Locking&#62;
<li>vti_doclibwebviewenabled
<li>IX|1
<li>vti_extenderversion
<li>SR|6.0.2.6361
<li>vti_ignorekeyboard
<li>IR|0
<li>vti_navbuttonprevlabel
<li>SR|Back
<li>vti_longfilenames
<li>IX|1
<li>vti_sourcecontrolsystem
<li>SX|lw
<li>vti_username
<li>SX|FLEXNET&#92;colinb
<li>vti_navbuttonhomelabel
<li>SR|Home
<li>vti_sourcecontrolcookie
<li>SX|fp_internal
<li>vti_sitecollectionurl
<li>SX|/
<li>vti_language
<li>IR|1033
</ul>
</ul>
</body>
</html>

Notice my windows username is listed against the vti_username item.

Using the XmlHttpRequest object to call author.dll synchronously (we're going to wait for the call to return)

xmlrequest = "method=open service:6.0.2.6356&service_name=";

if (!xmlhttp) xmlhttp=GetHTTPObject();

xmlhttp.open("POST", "/_vti_bin/_vti_aut/author.dll ",false);
xmlhttp.setRequestHeader("Content-Type","application/x-www-form-urlencoded");
xmlhttp.setRequestHeader("X-Vermeer-Content-Type","application/x-www-form-urlencoded");

xmlhttp.send(xmlrequest);

The responseText property on xmlhttp contains the returned document.

The hardest bit is parsing the result to extract the username.

Once that is done I show the username in a DIV element.

So the next time someone asks this question we'll be able to give them some options.

ClientSideUsername.dwp (2.92 KB)

In part 1 we have got to the point where we have called the SharePoint lists.asmx Web Service and retrieved the list of all Lists on our SharePoint site.
We now need to filter down to only those lists that are based on the links list template, this is template type 103, we can use an Xpath expression to filter the items.

// Filter for the Links lists items
links_lists=ajaxsp_GetSoapResponseItems(xmlhttpLists.responseXML, "//sp:List[@ServerTemplate='" + ListTemplate + "']", moz_NSResolver1 );

We loop through the list items and use the getAttribute of the XML Dom node to retrieve the fields we are interested in and concatenate a string of <LI> items which we then set to the innerHTML property of a DIV element.

Each list item on the left is a hyperlink that calls the javascript function GetLinkItems when clicked.
This function is passed three parameters - the list Guid, list Title and the Default View URL which normally is the full list of links.

function GetLinkItems(ListGuid, ListName, ListDefaultView)

On my personal SharePoint site I use the SharePoint Links type lists a huge amount, I have at least 20 of these and I like to flick between them a lot, having the links to hand is a great productivity booster.
I find the standard navigation just too slow and although the double-click minimize/restore Web Part helps what I really wanted was a windows application usability for these lists.

This is a perfect job for client-side JavaScript making SOAP calls to the SharePoint WebServices using DHTML to display the items. This kind of code now has the nifty name of AJAX although this is really AJAX-lite as the size of our framework is tiny and doesn’t need to handle complex object serialization/deserialization or data binding.

The goal is to have a WebPart that lists the Links based lists (must be an easier way to say that) and with a click display the items on the list, I also wanted to have an easy way to add items into the list. All code would be client-side javascript and also needed to work in Mozilla based browsers such as FireFox as I also use that a lot. Once the initial page has been rendered as normal by SharePoint there are no other postbacks or page refreshes needed so response times are very fast.

The Javascript will be initially be hosted in a Content Editor Web Part but I plan to create a server side WebPart also. Here’s a screen shot.

List of Lists

Add a new Item

 
SharePoint already does some AJAX already, albeit in a limited fashion, to handle getting and setting Web Part properties while editing the Properties of Web Parts. It posts to the WebPartPages.asmx SOAP service using the SaveWebPart and GetWebPart SOAP methods. Note the built-in SharePoint SOAP calls are only made if the browser is IE 5 and up. This and the fact that the library calls are hard-coded to use the WebPartPages web service only meant I had to create my own routines.

Soap requests by hand

Ok down to the nitty-gritty.
I’m going to assume you already have some understanding of what SOAP is but basically it is the method of sending an XML formatted request to a URL via HTTP and getting back a XML formatted response.
The first thing our Web Part needs is the list of Links type lists on the SharePoint site we are on.
To do this we will call the GetListCollection method of the Lists.ASMX web Service.
If you add /_vti_bin/lists.asmx page to your site URL you will see the methods this service exposes. Click the GetListCollection method to see the format of the SOAP request it expects.

The function GetLinksList populates the list of links and is the entry point into our code. We hook into the windows load event like this:

if (window.addEventListener)
window.addEventListener('load', _WPQ_AjaxObject.GetLinksList, false);
else
window.attachEvent("onload",_WPQ_AjaxObject.GetLinksList);

Note the use of the _WPQ_ token, this is replaced by our Web Part ID by the CEWP at runtime so avoiding duplicate global variables when there are two instances of the same Web Part on a page.

So we send a POST request to the URL /_vti_bin/Lists.asmx?op=GetListCollection and make sure we have a SOAPAction header set to the correct operation which is http://schemas.microsoft.com/sharepoint/soap/GetListCollection.
This will give use a list of all lists which we can filter for the Links’s type.

The body of the request will look like this:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body>
<GetListCollection xmlns="http://schemas.microsoft.com/sharepoint/soap/"/>
</soap:Body>
</soap:Envelope>

This is a very simple request string and notice the majority of the text is the boilerplate SOAP XML envelope that will never change, so in the code I’ve created vars that contain this text called SoapPrefix and SoapPostFix

To submit the request we create a XMLHttpRequest object and use its send method asynchronously, the function that calls the List Web Service looks like this

function ajaxsp_GetLinksList()
{
var xmlrequest;

xmlrequest = aSoapPrefix+ '<GetListCollection xmlns="http://schemas.microsoft.com/sharepoint/soap/"/>'
xmlrequest += SoapPostfix;

if (!xmlhttpLists) xmlhttpLists= GetHTTPObject();

xmlhttpLists.open("POST, "_vti_bin/Lists.asmx?op=GetListCollection",true);
xmlhttpLists.setRequestHeader("Content-Type","text/xml; charset=utf-8");
xmlhttpLists.setRequestHeader("SOAPAction","http://schemas.microsoft.com/sharepoint/soap/GetListCollection");
xmlhttpLists.setRequestHeader("Content-Length", xmlrequest.length);


// set the callback event
xmlhttpLists.onreadystatechange=ajaxsp_GetLinksListEvent;
// Send the request
xmlhttpLists.send(xmlrequest);

return true;

}

Two important functions are GetHTTPObject which returns the HttpRequest object for both IE and Mozilla based browsers and the ajaxsp_GetLinksListEvent which does the heavy lifting of processing the returned XML

GetHTTPObject needs to create different objects for IE and Mozilla because Mozilla has a built-in native Javascript object called XMLHttpRequest whereas IE uses the ActiveX XMLHTTP  object contained in MSXML libraries, there a quite a few versions of this library and the ProgID changes with each one but I just use either Msxml2.XMLHTTP  of Microsoft.XMLHTTP which should cover most modern machines with IE5.0 and up, interestingly IE 7 has now gained the native XMLHttpRequest object.

Heres a snippet of the returned XML.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body><GetListCollectionResponse xmlns="http://schemas.microsoft.com/sharepoint/soap/">
<GetListCollectionResult>
<Lists>
<List DocTemplateUrl="" DefaultViewUrl="/Lists/Company Links/AllItems.aspx" ID="{60E01147-6A7A-47F0-8CA1-4D88426280DE}" Title="1 Company Links" Description="" ImageUrl="/_layouts/images/itlink.gif" Name="{60E01147-6A7A-47F0-8CA1-4D88426280DE}" BaseType="0" ServerTemplate="103" Created="20050225 11:43:06" Modified="20060222 09:58:24" LastDeleted="20060220 17:42:54" Version="1" Direction="none" ThumbnailSize="" WebImageWidth="" WebImageHeight="" Flags="4105" ItemCount="16" AnonymousPermMask="" RootFolder="" ReadSecurity="1" WriteSecurity="1" Author="3" EventSinkAssembly="" EventSinkClass="" EventSinkData="" EmailInsertsFolder="" AllowDeletion="True" AllowMultiResponses="False" EnableAttachments="False" EnableModeration="False" EnableVersioning="False" Hidden="False" MultipleDataList="False" Ordered="True" ShowUser="True" />
<List DocTemplateUrl="" DefaultViewUrl="/Lists/Links/AllItems.aspx" ID="{233585BA-5972-40BB-85C8-67F793F22F67}" Title="2 Links" Description="Use the Links list for links to Web pages that your team members will find interesting or useful." ImageUrl="/_layouts/images/itlink.gif" Name="{233585BA-5972-40BB-85C8-67F793F22F67}" BaseType="0" ServerTemplate="103" Created="20041008 14:10:07" Modified="20060224 10:43:07" LastDeleted="20050302 08:40:12" Version="1" Direction="none" ThumbnailSize="" WebImageWidth="" WebImageHeight="" Flags="4105" ItemCount="26" AnonymousPermMask="" RootFolder="" ReadSecurity="1" WriteSecurity="1" Author="3" EventSinkAssembly="" EventSinkClass="" EventSinkData="" EmailInsertsFolder="" AllowDeletion="True" AllowMultiResponses="False" EnableAttachments="False" EnableModeration="False" EnableVersioning="False" Hidden="False" MultipleDataList="False" Ordered="True" ShowUser="True" />

As you can see a large amount of information is returned for each list but I’m most interested in four attributes of each list:

Name –List Name for display
ServerTemplate – for filtering
DefaultViewURL – to allow jumping to the standard SharePoint links page
Hidden - for hiding hidden lists.

The ServerTemplate is used to filter out only those lists that are Links based list which have a list template of 103. I use the constant LISTTEMPLATE_LINKS which is defined in ows.js.

The routines for parsing this XML into DOM nodes brings out the second major difference between IE and Mozilla : IE uses the MSXML ActiveX objects whereas Mozilla has the XML parsing javascript objects built-in.
I’ve encapsulated the conversion of the response XML into a set of DOM nodes into the GetSoapResponseItems routine

// Cross Browser helper to filter the XML results
// Returns array of Node objects
function ajaxsp_GetSoapResponseItems(SoapResponseXML, XPathFilter, NSResolver)
{
var m_Items=[];

// Mozilla
if (window.addEventListener)
{
    var aItems = xmlhttpLists.responseXML.evaluate(XPathFilter, SoapResponseXML, NSResolver, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
    for( var i = 0; i < aItems.snapshotLength; i++){m_Items[i] = aItems.snapshotItem(i);}
}
else
{ // IE
    var xmlDom=new ActiveXObject("MSXML2.DOMDocument.3.0");
    xmlDom.async=false;
    xmlDom.loadXML(SoapResponseXML.xml);
    m_Items=xmlDom.selectNodes(XPathFilter.replace("sp:",""));
}

return m_Items;

}

In IE you create a MSXML.DomDocument ActiveX object and use its LoadXML method to load the XML and use selectNodes with an XPath expression to get back the list of items
Mozilla has support for a lot of the DOM Level 3 XPath  (http://www.w3.org/TR/DOM-Level-3-XPath/xpath.html)  which allows XPath expression to be run against the XML data. The responseXML property is actually an object that has parsed the XML but unfortunately it doesn’t have support for selectNodes so you have to use the evaluate function to get a XpathResult and with that you can add the individual Dom nodes to an array.
One wrinkle with Mozilla is that’s its very picky about NameSpaces so you must specifiy a prefix in your XPath filter for default namespaces and also you need a routine that converts the prefix to the full Namespace, there are a couple of ways of doing this but a simple function returning a string is the easiest.

function moz_NSResolver1(NSPrefix)
{
switch(NSPrefix)
{
case "soap" : return "http://schemas.xmlsoap.org/soap/envelope/"; break;
default : return "http://schemas.microsoft.com/sharepoint/soap/";
}
}

As this function needs to vary depending on the XML I pass this in as function pointer in parameter NSResolver.
IE does some guessing for you so we can strip the prefix from the XPath filter.

Now once we have the Links Lists I create a set of ListItems (LI) in an Unordered List (UL) and display them by setting the innerHTML of a DIV element.

Whew, thats enough for one entry, In part 2 I’ll delve into displaying the actual links and creating a form for adding a new item using the client-side OWS Field objects and post the DWP file that contains all the code and which can be imported into your Web Part page.