Friday, June 20, 2008

Get a SharePoint list (SPList) Root Folder Name and Display Name (Title)

Summary

1. Introduction
2. Samples
1.1. Getting List names programmatically in c#
1.2. Retrieving a list by its names programmatically in C#
1 - Document Library
2 - Standard Lists
3. Warnings
1. Special characters
2. File Not Found exception

1.Introduction

Reading MSDN for SPList Class , it seems it's not very obvious to:
get the name of a SharePoint list.
look for a list in a SharePoint web site using its name.
Here is the only excerpt of the SPList Class Library Reference in MSDN speaking of the list name:
 
[...]
Use an indexer to return a single list from the collection. For example, if the collection is assigned to a variable named collLists, use collLists[index] in C#, or collLists(index) in Visual Basic 2005, where index is the index number of the list in the collection, the display name of the list, or the GUID of the list.
[...]

For instance SPList class has no Name property or GetName method.
Furthermore, a SharePoint list will have TWO names if you had renamed it!
The Root Folder Name (like the Internal Name for a SPList Field ) is the one you have set when you have created the list.
This name will be always present in your browser Address Bar when you display the list
The display name (the one you have used if you have renamed the list).
This name will appear as your list Title, when you display the list and the as a link to the list in your QuickLaunch menu if you have added to. (If you have not renamed your List, the root folder name and the display name are the same).

2.Samples

1.1 Getting List names programmatically in c#

So, how to get a SharePoint list Root Folder Name and Display Name (Title) in C# programming.
The following code sample will display these two names for all lists of a SharePoint web site:

                            SPWeb myWeb = SPContext.Current.Web;

                            Debug.WriteLine("MyWeb lists : ");

                            foreach (SPList aList in myWeb.Lists)

                            {

                                Debug.WriteLine("************************************");

                                Debug.WriteLine("list Title (Display Name): " + aList);

                                Debug.WriteLine("list Title (Display Name): " + aList.Title);

                                Debug.WriteLine("list Root Folder Name: " + aList.RootFolder.Name);

                                Debug.WriteLine("************************************");

                            }


2.2 Retrieving a list by its names programmatically in C#

And now, how to retrieve a SharePoint list using Root Folder Name or Display Name:
Notice that:
Document Libraries URL finishes by "/Website/DocLibRootFolderName"
Other Lists URL finishes by "/Website/Lists/OtherListsRootFolderName"

1 - Document Library

Assume we need to instantiate a SPList object corresponding to a Document Library with,
Root Folder Name: mycustomdoclib1
Display Name: Invoices
the following code sample will illustrate that:

  • Root Folder Name:

                            SPWeb myWeb = SPContext.Current.Web;

                            //SPList myList = myWeb.GetList("sites/my-collaboration-portal/docs/mycustomdoclib1");

                            SPList myList = myWeb.GetList(SPUrlUtility.CombineUrl(myWeb.ServerRelativeUrl, "mycustomdoclib1"));

  • Display Name:

                            SPList myList = myWeb.Lists["Invoices"];

2 - Standard Lists

Assume  we need to instantiate a SPList object corresponding to a list that is not a document library with,
Root Folder Name: mycustomlist1
Display Name: Clients
the following code sample will illustrate that:

  • Root Folder Name:

                            SPWeb myWeb = SPContext.Current.Web;

                            //SPList myList = myWeb.GetList("sites/my-collaboration-portal/docs/Lists/ mycustomlist1 ");

                            SPList myList = myWeb.GetList(SPUrlUtility.CombineUrl(myWeb.ServerRelativeUrl, "/Lists/ mycustomlist1 ")); 
 

  • Display Name:

                            SPList myList = myWeb.Lists["Clients"];

3. Warnings:

3.1 Special characters

When you set your list display name, you will generally do it using the Web Site user language. If this language is not English, you will sometimes have to use special characters like:
É, è , ù, ê, Ø, ñ, ô, …

SharePoint generally use Unicode escape sequence for these characters. Assume your list display name in French is:
"ma première doclib",

you will have to use that string to retrieve it:

                            SPList myList = myWeb.Lists["ma premi\u00e8re doclib"];


If you are looking for any Unicode escape sequence, you can download a mapping table here.

If you have too many fields with special characters to manipulate, think to use Visual Studio Advanced Save Options and save your .aspx Page file in "UTF-8 with signature" or "Unicode" format, doing that will allow you to write your fields name using your language special characters. You can also modify your Web Application web.config to obtain the same result.

About this topic you can read this post:

Unicode in Visual Studio .Net

Tricks:

To avoid using special characters in your requests:
Use an English name for the list when you create it, and rename your list using Web Site user language.
Use the list Internal Name with SPWeb.GetList method to retrieve a list using server code (VB .net, C#...).

3.2 File Not Found exception

There is a lack in SharePoint when you are trying to find objects, because the methods you are using for that will throw an exception if the object does not exist instead of returning null. That forces you to manage certain parts of your code by handling exception that is not a good coding practice.

                            SPList listVariable;

                            try

                            {

                                listVariable = myWeb.Lists["ListIWant"];

                            }

                            catch (Exception e) { }

There is at least two ways of avoiding exception handling when trying to retrieve a list:

1 - Loop-through-the-lists

                            SPList listVariable;

                            foreach (SPList tempList in myWeb.Lists)

                            {

                                if (tempList.Title == "ListIWant")

                                {

                                    listVariable = tempList;

                                    break;

                                }

                            }

It is not so fool as it seems to be since someone found that loop was always faster than the previously described methods.

Fast access items in an SPListCollection

2 - Use-LINQ

There is a LINQ request posted by Adam Buenz that allows you to look for a list without throwing an exception if it does not exists.
By the way the Linq request actually is doing a loop.

        public static bool InspectForList(string listName)

        {

            var results = SPContext.Current.Web.Lists.Cast<SPList>().Where(item => Equals(string.Compare(item.Title, listName, true), 0));

            return results.Count() > 0;

        }

What Are The Biggest SharePoint API Mistakes?

For ending, a last advice,
You should always use the root folder name of a list to look for it, since this name will never change.

 

 

 

Thursday, June 12, 2008

Improve readibility of CAML in SPQuery using C# and Visual Studio

Introduction
If you want to break down line in C# while writing CAML to define an SPQuery query, you maybe try to look for C# continuation line character, the equivalent of _ in VB .net. Referring to C# Language Specification, C# doesn't need one. A line continues until a ; is reached.
However, If you try to break line in a string in Visual Studio you will have a "new line in constant " exception.
The solution is to use @ character before your string. Code sample
 SPSite mySite = new SPSite("http://frev1149:8080/");
 SPQuery myQuery = new SPQuery();
 myQuery.Query= @"
   <Where>
      <Eq>
        <FieldRef Name='StateMonthReport'/>
        <Value Type='Text'>Refusee</Value>
      </Eq>
   </Where>
   ";
 SPList myList = mySite.OpenWeb().Lists["Transmises"];
 SPListItemCollection myItems = myList.GetItems(myQuery);

Sunday, June 8, 2008

Create multiple Ajax-enabled Web Sites in Windows Sharepoint Services and MOSS 2007

Introduction
The goal of this post is to point out the key that will allow you to use Ajax for multiple sites in Windows SharePoint Services or MOSS 2007. Our team met the problem. We had several SharePoint Web Sites that had to exchange informations with an Ajax Web Service, and we couldn't use the SPContext object in the web service code because it was always instantiated the site collection top level site SPContext object.
We used a temporary solution passing the SharePoint Web Site GUID as a parameter to the Web Method.
Thanks to Daniel Larson that answered to a comment I posted on his blog, we found the solution. You may find it in a more complete version in the chapter 5 of his book written with Ted Pattison:

Inside Microsoft Windows SharePoint Services 3.0

Tutorial

To make a clear demonstration I will customize the WsAjaxEnabledWSSApplication I created in a previous post:

Integrate ASP.NET Web Service based AJAX with MOSS 2007 or Windows SharePoint Services 3.0

1 - Adding a new aspx page that will display the Title of the web site.

I add to the solution a new aspx page that will display the Title of the web site that is invoking the Ajax Web Service. This Title must be returned by the Ajax Web Service.



2 - Adding a new Web Method that will return the Title of the web site.

I add to the web service a new Web Method in order to get the Title of the Web Site that is invoking Web Service:
        [WebMethod]
        public string GetSPWebTitle()
        {
            return (SPContext.Current.Web.Title);
        }


3 - The AjaxRetrieveSPWebTitle.aspx page inline code

And now, the most interesting, the .aspx page inline code :
<%@ Assembly Name="Microsoft.SharePoint.ApplicationPages, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Page Language="C#" MasterPageFile="~/_layouts/application.master" %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Import Namespace="System.Globalization" %>

<asp:Content ContentPlaceHolderID="PlaceHolderMain" runat="server">

    <script runat="server">
    
        private const string WebInitScriptKey = @"WSAjaxEnebledWSSApplication.AjaxRetrieveSPWebGUID.aspx";
        private const string WebInitScriptFormat = @"window.spWebUrl = '{0}';";

        public void Page_Load(object sender, EventArgs e)
        {
            string webInitScript = string.Format(CultureInfo.InvariantCulture, WebInitScriptFormat, SPContext.Current.Web.Url);
            this.Page.ClientScript.RegisterClientScriptBlock(typeof(System.Web.UI.Page), WebInitScriptKey, webInitScript, true);
        }
    </script>

    <script type="text/javascript">
        function getMyWebTitle(){
            WsAjaxEnabledWSSApplication.HelloWorldService.set_path(window.spWebUrl + "/_vti_bin/AjaxWebService/HelloWorldService.asmx");
            WsAjaxEnabledWSSApplication.HelloWorldService.GetSPWebTitle(OnComplete, OnTimeOut, OnError);
        }
        
        function OnComplete(args){
            document.getElementById("divWebServiceReturn").innerText=args;
        }
        
        function OnTimeOut(args){
            alert("Time Out");
        }
        
        function OnError(args){
            alert("Error");
        }
    </script>

    <asp:ScriptManager ID="ScriptManager1" runat="server">
        <services>
                <asp:ServiceReference InlineScript="true" Path="~/_vti_bin/AjaxWebService/HelloWorldService.asmx" />
         </services>
    </asp:ScriptManager>
    <br />
    <br />
    <input type="button" value="Get myWeb Title" onclick="JavaScript:getMyWebTitle();" />
    <br />
    <br />
    <span>Ajax Web Service returned that web site Title: </span>
    <div style="display: inline; color: Black" id="divWebServiceReturn">
    </div>
</asp:Content>

4 - Summary.

So the Key point is :
to set the path correctly before calling the service
   WsAjaxEnabledWSSApplication.HelloWorldService.set_path(window.spWebUrl + "/_vti_bin/AjaxWebService/HelloWorldService.asmx");

And to set the path, I used the JavaScript property as used by Daniel Larson and Ted Pattison in SharePoint AJAX Toolkit:
   window.spWebUrl 


5 - Testing

I am now creating a new subsite, mySubsite1.
As my .aspx page is an application page, for any site in my Site Collection that will be using that page, I will get its Title :