What is the CAML Builder?
CAML itself is the abbreviation of Collaborative Application Markup Language. It is an XML-based query language that helps you querying, building and customizing Web sites based on Windows SharePoint Services. The XML elements define various aspects of a WSS site. In the first version of our CAML Builder tool, only the query aspect of CAML is worked out. The tool will help you build, test and execute your CAML queries.
We provide you with two things:
- A Windows application you can use to connect to your portal or team site and build your CAML query string in a WYSIWYG manner. (U2UCamlCreator.exe)
- A small assembly you can reference helping you with the execution of your CAML query string within your code. (U2U.SharePoint.CAML.Server.dll)
CAML builder is downloadable from our SharePoint site. <-- download here!!! You just unzip the file and start working with it. We will work out an official article with more guidance info on the stuff you can do with CAML and the tool. But for the moment, if you want to start, here is a small walkthrough demonstrating the possible use of the tool.
A Small Example
To illustrate the CAML Builder, I will guide you through a small example. Suppose, you have within a WSS team site the following list of products.
You now have to build a small Web part to be displayed on the home page of the team site that displays the results of the following query: 'Get me all products that have a Red color, and a price higher that $500 but less than $1000 and contain the word mountain in the product name and all of this ordered by size'. You can build a nice UI to make the parameters dynamic, but the query itself is not an easy one to construct in CAML without some help. With the CAML Query Builder, it takes only a couple of seconds to build this query string.
Here are the steps
- Open the CAML Query Builder tool - U2UCamlCreator.exe
- Enter the URL to your site and either use the credentials of the logged on user or provide ones yourself. Note that the CAML builder internally works completely with the SharePoint Web services and thus can be used on non-SharePoint machines.
- A treeview with the available lists and libraries is displayed.
- Clicking on the list you want to work with displays the fields in another panel.
- The panel above lets you build up your CAML string very easily. For our query, we first select the size field and then check the Order By.
- Next is the part of the color. Clicking the color and the Where checkbox allows us to define the nex part of the query. Just click the small > button to add the new part to the Query string visualized in the treeview at the right.
- Finishing off with the price and the contains in the same manner
- In the lower panel of the window, you will find the CAML query string written out in full. As you notice, it is quite a challenge to construct this string without the help of the builder.
- Of course, we can test our work by clicking the Test button.
- I can copy and paste the query string now to be used within my application. But I do not want to have this string in my code. So what I will do is save the query configuration I just have created in a small XML file that in our application has a .caml extension.
- And then we can close the tool. Note that when you start it again, you can simply open the saved .caml file and continue with the query.
- I am going to build now a small ASP.NET user control to execute this query and show it in a datagrid wrapped up in a Web part to my users.
I will of course use the SmartPart to host the user control in SharePoint.
The user control UI is very simple. It just contains a datagrid.
- Executing a CAML query string can be done via the SPQuery class of the WSS object model. Together with the CAML Query Builder tool, we also provide you with a small assembly that encapsulates all of that code. The only thing you need to do is
- set a reference to U2U.SharePoint.CAML.Server.dll
- declare a namespace
using U2U.SharePoint.CAML.Server;
- In the load event-handler, create an object of the CAMLHelper class. You have the option in the constructor to provide it with the site, list and CAML query string in the form of an XML document or just point to the file we have saved using the Query Builder tool itself.
CAMLHelper hlp = new CAMLHelper(Server.MapPath("~/UserControls/products.caml"));
- You have two methods on the CAMLHelper. The ExecuteQuery returns you a DataTable, and the ExecuteXMLQuery returns you an XML string.
DataGrid1.DataSource = hlp.ExecuteQuery();
DataGrid1.DataBind();
- Deploying our user control and code behind 'the SmartPart way', we end up on our home page with the following result. I also use the property builder of the datagrid to display only a number of the columns returned by the helper.
Voilà. In a couple of minutes I have created here a Web part that internally does some fairly complex stuff. Using the CAML Query Builder and the assembly hiding the execution details for me, I can concentrate on the business part of the Web part and not on the plumbing to get it all executed.
I really want to thank Karine Bosch (our CAML girl) who I think has done a great job with the implementation of the CAML Builder. If you have any specific questions regarding the tool, you can contact either her (karine@u2u.be) or myself (patrick@u2u.be). We have a small discussion forum available on the SharePoint site in addition.
What's the future bringing? Well, Karine has started on a small update of the CAML builder to be able to internally switch from the Web Services approach to the Object Model approach. And then she will start concentrating on how we can define which fields we want to have returned instead of returning all of them.
From the U2U side, we are working on a number of other SharePoint and IBF-related tools we will bring to the community. We just need the time to finish them :-)