CAML در شِیرپوینت برای کوئری گرفتن (پرسوجو کردن) از لیستها و کمک در ایجاد و سفارشی کردن سایت استفاده میشود. برنامهنویسی اغلب یک مهارت لازم برای بهدست آوردن دادهها از شِیرپوینت است. در اینجا میخواهیم نشان دهیم چگونه میتوان پرسوجوهای کمل برای استخراج داده از لیستها ایجاد کرد.
زبان CAML
زبان کمل از نخستین نسخه SharePoint 2001 و SharePoint Team Services همراه شِیرپوینت بوده است. XML تعریف شدهای است که کمک میکند تا وظایف کار با داده (data manipulation) در شِیرپوینت را انجام دهید. میتوان ارتباط لیست و کمل را مشابه جدول پایگاه داده و پرسوجو(query) دانست. هنگامی که از db پرسوجو میکنیم هم میتوانید تمام رکوردها را از جدول بگیرید و رکوردی که میخواهید را پیدا کنید و یا اینکه از یک پرسوجوی SQL استفاده کنید تا با محدود کردن نتیجه فقط رکورد مدنظر شما را برگرداند. کمل در این کار شما را یاری میکند.
کمل باید یک سند well-formed XML باشد که از المنت های زیر تشکیل شده:
<Query>
<Where>
<!--Comparison Operators here-->
<Eq>
<FieldRef Name="insertFieldNameHere" />
<Value Type="insertDataTypeHere">insertValueHere</Value>
</Eq>
</Where>
<OrderBy>
<FieldRef Name="insertFieldNameHere" />
<FieldRef Name="insertFieldNameHere" />
</OrderBy>
</Query> |
این پرسوجوی کمل ساده یک فیلتر تعریف میکند به این مضمون: هرگاه فیلدی برابر مقداری (مشخصشده با استفاده از عنصر Eq) باشد. بهعلاوه میتوان یک یا چندین عنصر FieldRef داخل عنصر OrderBy مشخص کرد که نتایج برحسب یک یا چند ستون مرتب شوند.
در نمونه پیشین یک پرسوجوی کمل میتواند از یک یا چندین عملگر مقایسهای جدول زیر استفاده کند که برای بیشتر فیلتر کردن نتایج پرسوجو استفاده میشود.
جدول عملگرهای مقایسهای |
Begins with a Given Text Value | Begins With |
Contains a given text value | Contains |
Equal to | Eq |
Greater than or equal to | Geq |
Greater than | Gt |
Less than or equal to | Leq |
Less than | Lt |
Not equal to | Neq |
Compares dates in recurring events to determine if they overlap | DateRangesOverlap |
Is not null | IsNotNull
|
Is null | IsNull
|
شما بایست تمام این عناصر را با یک عنصر فرزند FieldRef همراه کنید.عنصر FieldRef نام مختص به شِیرپوینت ستونی که بایست ارزیابی شود را مشخص می کند.بهعلاوه اغلب عناصر پرسوجو (بجز IsNotNull و IsNull) نیازمند مشخص شدن یک عنصر فرزند Value هستند.جایی که شما مشخص میکنید کدام مقدار با عنصر FieldRef ارزیابی میشود.
متاسفانه شِیرپوینت همیشه FieldRefs هایی که میخواهید ارجاع دهید را مستقیماً در اختیار نمیگذارد. کد زیر نمونهای است که با استفاده از آن میتوانید نام FieldRef های یک لیست را با استفاده از یک برنامه کنسول و API های MOSS 2007 استخراج کنید:
using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;
namespace SharePointUtils
{
class Program
{
static void Main(string[] args)
{
string siteUrl = args[0];
string listName = args[1];
string viewName = args[2];
SPSite site = new SPSite(siteUrl);
SPWeb web = site.OpenWeb();
SPList employeesList = web.Lists[listName];
SPQuery query = new SPQuery(employeesList.Views[viewName]);
System.Diagnostics.Debug.WriteLine(query.ViewXml);
Console.WriteLine(query.ViewXml);
Console.ReadLine();
}
}
} |
کد بسیار ساده است و خروجی آن برای هنگام نوشتن پرسوجوی کمل بسیار مفید است.سه آرگومان نیاز است به ترتیب URL سایت، نام لیست و نام نما (View). اشیاء سایت، وب و لیست ایجاد میشوند همچنین نمونه ای از SPQuery هم ایجاد میشود. SPQuery برای بهدست آوردن نام فیلدهای مختص شِیرپوینت (یا همان FieldRefs) از نما استفاده میشود. شکل زیر نمایAll Items مربوط به یک لیست سفارشی بنام Employees را نشان میدهد. برای اجرای صحیح کدهایی که در ادامه میآید بر روی سایتتان نیازمند ایجاد این لیست سفارشی بر روی سایت خود هستید.
هنگامی که کد پیشین را برای نمای All Items لیست سفارشی Employees اجرا کنید نتایج مطابق شکل زیر خواهد بود.
فیلدهای لیست داخل عنصر FieldRef تعریف میشوند برای مثال سه فیلدی که در شکل بالا آمدهاند Employee Name و Salary و Start Date در حقیقت به ترتیب بعنوان "LinkTitle" و "Salary و "Start_x0020_Date" ارائه شدهاند.
بخش بعدی ایجاد یک پرسوجوی کمل با استفاده از FieldRefs برروی لیست Employees است.
پرسوجو بر روی لیست
بعد شناسایی FieldRefs ای که میخواهید با آن پرسوجوی خود را فیلتر کنید دیگر پرسوجو بسیار ساده است. به عنوان نمونه در لیست Employees پرسوجویی خواهیم داشت که لیست تمام کارمندانی که پیش از January 1, 2003 آغاز بهکار نمودهاند را برگرداند، کافی است کارمندانی با تاریخ شروع پیش از January 1, 2003 را بهدست آوریم:
<Query>
<OrderBy>
<FieldRef Name="Title" />
</OrderBy>
<Where>
<Lt>
<FieldRef Name="Start_x0020_Date" />
<Value Type="DateTime">2003-01-01T00:00:00Z</Value>
</Lt>
</Where>
</Query> |
این پرسوجو دو کار انجام میدهد نخست، با کمک عنصر OrderByمشخص میکند دادهها چگونه مرتب شوند که اینجا فیلد Title است که معادل نام کارمند است.بعد، یک عنصر Where که تعریف شده تا فیلتر را مشخص کند و مشابه بخش WHERE در SQL است. عنصر Where یک Lt (کوچکتر از) تعریف می کند که دارای دو عنصر FieldRef و Value میباشد. FieldRef نام ستون در لیست و Value نوع داده و مقداری که باید مقایسه شود را مشخص میکند.
در زیر قطعه کدی است که پرسوجوی بالا را اجرا میکند:
using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;
namespace SharePointUtils
{
class CAMLQuery
{
static void Main(string[] args)
{
string siteName = args[0];
string listName = args[1];
string viewName = args[1];
SPSite site = new SPSite(siteName);
SPWeb web = site.OpenWeb();
SPList employeesList = web.Lists[listName];
SPQuery query = new SPQuery(employeesList.Views[viewName]);
query.Query = "<Query><OrderBy><FieldRef Name=\"Title\"
➥/></OrderBy><Where><Lt><FieldRef Name=\"Start_x0020_Date\" /><Value
➥Type=\"DateTime\">2003-01-01T00:00:00Z</Value></Lt></Where></Query>";
SPListItemCollection filteredEmployees = employeesList.GetItems(query);
foreach (SPListItem i in filteredEmployees)
{
System.Diagnostics.Debug.WriteLine(i["Title"].ToString() + " " +
➥i["Salary"].ToString() + " " + i["Start_x0020_Date"].ToString());
}
Console.ReadLine();
}
}
}
|
کد انجام پرسوجو مانند نخستین مثال است بجز تنظیم مشخصه (property) Query شی SPQuery که query نام.دارد اینجاست که پرسوجوی کمل - که برای فیلتر کردن داده استفاده میشود - را نسبت میدهید. نتایج با بکارگیری متد GetItems از شی SPList و نمونه ای از کلاس SPListItemCollection بازگردانده میشود.این collection مقادیر را برروی خروجی نمایش میدهد. در ادامه نمونهای از خروجی برگردانده شده از پرسوجوی کمل را خواهیم دید:
Brandon Bobb 62000 12/1/2001 12:00:00 AM
Rob Foster 110000 1/1/1999 12:00:00 AM
Stephen Baron 79000 1/25/2002 12:00:00 AM
|
تعداد رکوردهای لیست محدود بوده، نتایج به 3 رکورد محدود شده است.حال چگونه میتوان فیلتر بیشتری بر لیست اعمال کرد؟ کمل دارای عناصر And و Or است که می تواند همراه با عنصر Where بهکاررود. در زیر نمونهای از پرسوجوی کمل که با تاریخ آغاز قبل از January 1, 2003 و درآمد کمتر از $80,000 فیلتر میشود میآید:
<Query>
<OrderBy>
<FieldRef Name="Title" />
</OrderBy>
<Where>
<And>
<Lt>
<FieldRef Name="Start_x0020_Date" />
<Value Type="DateTime">2003-01-01T00:00:00Z</Value>
</Lt>
<Lt>
<FieldRef Name="Salary" />
<Value Type="Currency">80000</Value>
</Lt>
</And>
</Where>
</Query> |
طبیعتاً این فیلتر دو رکورد زیر از لیست مثال برمیگرداند:
Brandon Bobb 62000 12/1/2001 12:00:00 AM
Stephen Baron 79000 1/25/2002 12:00:00 AM
|
همان گونه که میبینید، پرسوجوی کمل بهسادگی ایجاد و اجرا میشود. در بخش بعدی به یک ابزار رایگان میپردازیم که بهسادگی میتوانید پرسوجوهای خود را ایجاد و آزمایش نمایید.
بهکارگیری U2U CAML Query Builder
این ابزار یک دانلود رایگان از U2U است که میتوانید برای ایجاد و آزمایش پرسوجوی کمل استفاده کنید. ابزاری مفید که در زمان و اقدامهای شما در هنگام نوشتن پرسوجوهای کمل صرفهجویی میکند. می توانید از این آدرس آن را دانلود نمایید.
شکل ابزار را به همراه لیست Employees که بحث شد نشان میدهد:
ملاحظه مینمایید که پس از این که لیست را انتخاب کنید ستونهای لیست در کنترل ListBox جای میگیرند. سپس میتوانید هر ستون را انتخاب کرده و برخی اطلاعات درمورد این که پرسوجو چگونه باید فیلتر شود فراهم کنید.در شکل پرسوجوی کمل رکوردهای دارای درآمد بالاتر از $30,000 را فیلتر میکند.
همچنین بسادگی میتوانید پرسوجوی کمل را پیش آزمون کنید قبل از این که هرگونه کدی بنویسید. می توانید با کلیک دکمه Test این کار را بکنید. شکل زیر نتایجی که باپرسوجوی کمل بالا بازگردانده شده را نشان میدهد.
خلاصه
کمل زبان قدرتمندی است که نیازمند افزودن آن به مجموعه مهارتهای شِیرپوینتی خود هستید.در این مباحث جزییاتی درمورد این که چگونه از کمل برای پرسوجو کردن لیستها و فیلتر کردن دادهها براساس معیارهای مشخص ارایه کردیم که به شما کمک میکند تا کارایی وبپارت های خود و سایر کدهایی که در تعامل با هر نوع از لیستهای بر اساس داده است را بهبود بخشید.
ترجمهای از فصل اول کتاب Microsoft® SharePoint® 2007 Development Unleashed
