Thursday, April 09, 2009

SharePoint Data Zoom: What the heck is NVelocity and why should you care?


A few weeks back I announced that we'll be releasing a free web part called the SharePoint Data Zoom Web Part. I'm happy to say that the web part was made publicly available yesterday. In my original post, I made mention of the NVelocity template engine, explaining that NVelocity provided the basis for creating scripts in Data Zoom. In this post, I'd like to give a little more background on NVelocity and begin to show you how the SharePoint Data Zoom Web Part is going to help you get your job done.
You may be asking yourself , "why would I want to use NVelocity for creating SharePoint web applications?". Well, NVelocity is a port to the .NET framework of the Java Apache Software Foundation Velocity project . If you are migrating an existing Java-based application to .NET, and the existing application was written with the Velocity template engine, then using NVelocity could make the migration process much smoother.
Not coming from Java? No problem. Like me, you may just prefer the template syntax of NVelocity over the syntax used in a normal ASP.NET Web Forms page. The Velocity Template Language was designed specifically for building HTML pages. Velocity provides you with a very clean syntax for performing common operations such as iterating over a set of database records and displaying each record in an HTML page. One could say that Velocity and NVelocity are Domain Specific Languages for HTML.
A while back, the folks at the Castle Project took NVelocity and branched it for the purpose of fixing bugs and making a few improvements. The Castle Project maintains the MonoRail code base, a popular Model-View-Control framework (MVC). As you may have already guessed, the "view" in MonoRail's MVC is provided by none other than NVelocity.
OK, let's move on to helping you get your job done with Data Zoom. What does an NVelocity script look like? Is NVelocity really that easy to use? Well, I'll let you be the judge. In the context of our SharePoint Data Zoom Web Part, here's a simple NVelocity example:
1 <div style="padding:10px">
2
3 #if( $user )
4   Hello $user.Name, welcome back to the '$web.Title' site.
5 #else
6   Welcome to the '$web.Title' site.
7 #end
8
9 </div>

The above example looks amazingly just like HTML, no? Of course, with the exception of some dollar signs ($) and an 'if..else..end' block. The dollar signs indicate variables, which are really .NET objects in disguise. In the SharePoint Data Zoom Web Part, we provide you with some SharePoint "context" objects to make your life easier. In this case, $user is the current web user, and $web is the current SharePoint web object (see line 4 and line 6). Thus, $user.Name is the name property for the current user, and $web.Title is the title property for the current web site. Piece of cake! It gets even better though. We’ve included a source editor with the Data Zoom web part that will let you create scripts from right there in your SharePoint pages. And just so you don’t have to remember all the names, properties and complicated syntax for intimidating SharePoint objects like “$web.Title” and “$user.Name”, we’ve created a menu system in the source editor which inserts snippets for you in just one click.
Here's a slightly more advanced example. In this case, we'll get the "Tasks" list from the current web site and display its Title, Created and Modified fields for each item in the list:
 1 ## Get the tasks list
 2 #set( $tasksList = $web.lists.get_item("Tasks") )
 3
 4 ## Get edit url information
 5 #set( $sourceUrlEncoded = $HttpUtility.UrlEncode($request.RawUrl) )
 6 #set( $editForm = $tasksList.Forms.get_item($PAGETYPE_PAGE_EDITFORM) )
 7
 8 #foreach($item in $tasksList.Items)
 9  #beforeall
10    <table class="ms-listviewtable" cellpadding="3" cellspacing="0" border="0" width="100%">
11      <tr class="ms-viewheadertr">
12        <th class="ms-vh2-nofilter">Title</th>
13        <th class="ms-vh2-nofilter">Created</th>
14        <th class="ms-vh2-nofilter">Modified</th>
15      </tr>
16  #odd
17      <tr class="">
18  #even
19      <tr class="ms-alternating">
20  #each
21        <td class="ms-vb2"><a href="$web.Url/$editForm.Url?ID=$item.ID&Source=$sourceUrlEncoded">$item.Title</a></td>
22        <td class="ms-vb2">$item.get_item("Created").ToString("d")</td>
23        <td class="ms-vb2">$item.get_item("Modified").ToString("d")</td>
24  #after
25      </tr>
26  #afterall
27    </table>
28  #nodata
29    No tasks found
30
31 #end



Lines such as 2 and 4 which begin with "##" double pounds signs are just comments. Read them or ignore them. On lines 2,5 and 6 we're calling the "#set" directive to assign values in our own user variables. Specifically, line 2 is where we get the Tasks list. On line 8, we begin a "for..each..end" loop that does the work of running through the Tasks list and printing each item's Title, Created and Modified field values. Slightly more involved than the first example, but still pretty darn simple! By the time you were able to get logged into SharePoint Designer and started doing the work, you could have already had this script done with the Data Zoom web part. ;)
Well, I've tried to provide you with a bit of history on NVelocity, and I've shown you a few simple examples of how our SharePoint Data Zoom Web Part can make it really easy for you to create applications in SharePoint. These examples have been extremely simple. There are more in depth examples available on the community site (link below). I'll wrap up with a few more notes and links you may find useful as next steps.
  • SharePoint Data Zoom Web Part home page

    - Get more info and download the bits.
  • Help documentation

    - Online documentation.
  • Community site

    - Shared scripts library.
  • Support forums

    - Ask questions, get answers.
Even further reading...

No comments: