Welcome! This guide will help you better understand how to maximize your use of the Mediachase AJAX Calendar.NET.

Before writing code, you should integrate Mediachase Ajax Calendar to your web project.

Please do the following:

• Add reference to Microsoft ASP.NET Ajax library (System.Web.Extensions.dll) or create new ASP.NET Ajax-Enabled web-site in Visual Studio.
• Add reference to calendar control library (Mediachase.AjaxCalendar.dll)
• Also you can add controls from calendar control library to Microsoft Visual Studio toolbox.

Then you can place Mediachase Ajax Calendar control into your web-page.

Let’s assume you have placed MediachaseAjaxCalendar composite control into your web-page. The tag inside the page should be like this:

  <cc1:MediachaseAjaxCalendar ID="CalendarCtrl" runat="server">
  </cc1:MediachaseAjaxCalendar>

First, you have to make a web-service which must be inherited from IItemsWebServiceInterface. You have to apply “ScriptService” attribute to your web-service class:

[ScriptService]
[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
public class Default : System.Web.Services.WebService, IItemsWebServiceInterface
{...}

You do not need to generate the web-service methods calls on client side. They will be generated automatically. The web-service will contain four methods:

  CalendarItem[] LoadItems(string startDate, string endDate, object calendarExtension);
  void DeleteItem(string uid, object calendarExtension);
  void CreateItem(string title, string startDate, string endDate, string description, bool isAllDay, object extentions, object calendarExtension);
  void UpdateItem(string uid, string title, string startDate, string endDate, string description, bool isAllDay, object extentions, object calendarExtension);

Note 1: Parameter “calendarExtension” was added to web-service methods in version 3.2. If you want to upgrade your Ajax Calendar.NET to version 3.2 from 3.0 or 3.1 you must replace the control dll and add this parameter to your web-service methods.

Method “LoadItems” should return array of Calendar items for the time period between “startDate” and “endDate”. You can fill return array like in the following code:

[WebMethod]
public CalendarItem[] LoadItems(string startDate, string endDate, object calendarExtension)
	{
	List<CalendarItem> al = new List<CalendarItem>();
	DateTime viewStartDate = DateTime.Now;
	DateTime viewEndDate = DateTime.Now;  string[] date = startDate.Split(new char[] { '.' });
	viewStartDate = new DateTime(int.Parse(date[0]), int.Parse(date[1]), int.Parse(date[2]), int.Parse(date[3]), int.Parse(date[4]), int.Parse(date[5]));
	date = endDate.Split(new char[] { '.' });
	viewEndDate = new DateTime(int.Parse(date[0]), int.Parse(date[1]), int.Parse(date[2]), int.Parse(date[3]), int.Parse(date[4]), int.Parse(date[5]));
	CalendarItem it = new CalendarItem(...);
	...
	al.Add(it);
	...
	return al.ToArray();
}

Note 2: parameters “startDate” and “endDate” of the web-service methods contain information about date in the following format “yyyy.M.d.H.m.s” (four digit year, month number from 1 to 12, day number from 1 to 31, hour from 0 to 23, minute from 0 to 59, and second from 0 to 59). So you should parse them to get objects of DateTime class.

Method “DeleteItem” should delete calendar item from items storage by its Uid. Each calendar item has string public property “Uid”. The Uid of each must be unique in items storage.

Method “CreateItem” should create CalendarItem object and add it items storage.

Method “UpdateItem” should update calendar item by its Uid.

Second you have to set created web-service as calendar control data source. Class CalendarItemsDataSource is defined in Mediachase.AjaxCalendar namespace. You can set it in markup:

<cc1:MediachaseAjaxCalendar ID="CalendarCtrl" runat="server">
	<DataSource ItemsWebServiceFullName="Test.Default"
ItemsWebServicePath="~/Default.asmx" />
</cc1:MediachaseAjaxCalendar>

or background code:

CalendarCtrl.DataSource = new Mediachase.AjaxCalendar.CalendarItemsDataSource("~/Default.asmx", "Test.Default");

Each object of type “CalendarItemsDataSource” has two required values: “ItemsWebServicePath” – a path to created web-service which works with calendar items, and “ItemsWebServiceFullName” – name of the web-service class with its namespace.

Each view type can have only one data source, but when you have placed composite calendar control into web page, you can set for each view of composite control its own data source:

<cc1:MediachaseAjaxCalendar ID="CalendarCtrl" runat="server">
<MultiDayView>
	<DataSource ItemsWebServiceFullName="Test1.Default" ItemsWebServicePath="~/Default2.asmx" />
</MultiDayView>
<MonthView>
	<DataSource ItemsWebServiceFullName="Test2.Default3" ItemsWebServicePath="~/Default3.asmx" />
</MonthView>
<YearView>
	<DataSource ItemsWebServiceFullName="Test3.Default7" ItemsWebServicePath="/Default7.asmx" />
</YearView>
</cc1:MediachaseAjaxCalendar>

Note: when you specify data source of the composite calendar control and if some views do not have specified data source, they will use data source of composite control.

Third your page with calendar control must contain “ScriptManager” element. It even can be empty:

<asp:ScriptManager runat="server">
</asp:ScriptManager>

After these three steps (web-service, data source and script manager) your calendar control is ready to display items.

Calendar control provides wide range of its appearance tuning. All views have several parameters with the same names and other parameters are specific for each view.

You can get access to every view of composite control using its properties “MultiDayView”, “MonthView” ,“YearView”, and “TaskView” (CalendarCtrl.MonthView.SelectedDate = …).
Note: when you use composite calendar control you should call its’ method “Refresh” after changing its properties (such as “SelectedDate” or “ViewType”) on server side.

Note: you have to set height in “GridStyle” in pixels, otherwise calendar control will not work correctly.

MultiDay view contains also event bar – an area above main calendar grid which shows items those can not be shown in main grid. Event bar have some specific settings (with prefix “EventBar”).

If DisplayMode = LeadToFisrtMonthDay month tries to be displayed from the first date. If it is set to FromSelectedDate month is displayed from week with “SelectedDate”.

Task view contains column for displaying item titles at the left of main grid area. Also TitleItemTemplate and TitleItemMapping properties were added to Task view. So developer can manage information displaying in title column as well as in main grid. If you want to hide title column just set its width (in TitleColumnStyle) to “0px”.
Task view has two displaying modes: expandable and scrollable. In expandable mode calendar height depends on number of items in it and grid is displayed without right scroll bar. In scrollable mode calendar height is fixed and right scroll bar is shown. To set expandable mode set grid height (in GridStyle) to “0px”, to set scrollable mode set positive grid height in pixels.

Note: when ScaleType = Hour, DayStartHour!=0, DayEndHour!=23 some items could not be displayed in Task view. For instance SelectedDate= “08/08/2008”, DayStartHour=9, DayEndHour = 17 and we have calendar item with StartDate=”08/08/2008 18:10” and EndDate = “08/09/2008 08:30”. This item will not be displayed because Task view grid does not display hours from 00:00 to 09:00 and from 18:00 to 23:59 with such day start and end hour settings.

Every view type of calendar control provide possibility to customize view of displaying items. For this purpose two string public properties exist in every view type of calendar control: “ItemTemplate” and “ItemMapping”.
ItemTemplate should contain valid html-code which is being inserted in every item displayed on calendar grid. For instance item template for MultiDay view similar to Google calendar item can look like this (this template is used in MultiDay view if you do not specify other one):

”<div style=“background-color: #2952a3; height:1px; font-size:1px; line-height:1px; margin:0px 2px;”></div><div style=“background-color: #2952a3; height:1px; font-size:1px; line-height:1px; margin:0px 1px; ”></div><div style=“background-color:#668CD9; border-left: solid 1px #2952a3; border-right: solid 1px #2952a3; height:100%;”><table border=“0” cellpadding=“2” width=“100%” cellspacing=“0” style=“background-color:rgb(41, 82, 163); width:100%; font-weight:bold; font-size:11px; color:#ffffff; table-layout:fixed; overflow:hidden; font-family:Verdana,Sans-serif;”><tr mcc_action=“move”><td style=“cursor:move; overflow:hidden;” unselectable=“on”><span id=“sHour”></span>:<span id=“sMinute”></span></td></tr></table><div id=“title” style=“cursor:default; color:#ffffff; font-family:Verdana,Sans-serif; font-size:11px;” unselectable=“on”></div><div id=“resizer” mcc_action=“resize” style=“font-size:5px; line-height:5px; position:absolute; bottom: 5px; height:5px; width:100%; z-index:11; cursor:s-resize;”><table width=“100%” height=“100%”><tr><td align=“center” style=“color:#ffffff”>————–</td></tr></table></div></div><div style=“position:absolute; bottom:0px; width:100%;”><div style=“background-color: #2952a3; height:1px; font-size:1px; line-height:1px; border-left: 1px solid #2952a3; border-right: 1px solid #2952a3;”></div></div>”

Note 1: try not to make complicated item template with multiple nesting levels. On client machine recursive function is used for item template filling with data, so in some browsers highly complicated templates could not be processed correctly.

Pay your attention to “mcc_action” attribute. By means of this attribute you inform client machine browser that when user clicks on the area with such attribute he can perform some actions on selected calendar item.

In MultiDay view the attribute has three possible values (case sensitive): “move,” “resize” and “delete.” When it is set to “move” user can move calendar item over calendar grid (and drop it at new position), when it is set to “resize” user can change calendar item (event) duration. Usually html area with mcc_action=“resize” is placed at the bottom of calendar item.

In MultiDay view also exist parameters names “EventBarItemTemplate” and “EventBarItemMapping”. They have the same meanings as “ItemsTemplate” and “ItemMapping” but they are applied to event bar only. For event bar attribute “mcc_action” has only two values: “move” and “delete” (you can not change item duration in event bar).

In Month view and Year view parameters “ItemTemplate” and “ItemMapping” also exist. For Month view attribute “mcc_action” also has two values: “move” and “delete”. In Year view this attribute has only one value “delete” (in Year view user is not able to drag and drop items).

Note 2: If you do not mark some html area in your item template with “mcc_action” attribute with value “move”, user will not be able to drag and drop calendar items on client machine. The same is for value “resize” in MultiDay view.
Note 3: Try not to mark all area of item template with mcc_action=“move”. In this case there will be no way to make out request for item editing. Usually area with mcc_action=“move” is placed at the top of the item.

In figure 1 you can see areas marked with attribute “mcc_action” in default item template in MultiDay view.

Fig.1

Now pay your attention to “id” attribute in previous html item template. The calendar data-binding is performed on client machine. So it is necessary to create mapping between content of calendar item and html item template. That is why we need another one parameter “ItemMapping”. It is also string parameter in each view type of the calendar control. Filling html item template with the values from calendar item is performed using html item template ids (“id” attributes). “ItemMapping” contains string that describe rules of filling html item template with values in JSON notation. Every “object” (between ”{” and ”}”) in the string has three required fileds (case sensitive): “id” – id of html tag in html item template; “property” – a java-script property of html document node; “value” – expression which will be assigned to the mentioned “property”. If you do not specify “ItemMapping” parameter the following one will be used (for MultiDay view):

”[{“id”:“title”,”property”:“innerHTML”,”value”:“Title”},{“id”:“sHour”,”property”:“innerHTML”,”value”:“StartDate.getHours()<10?’0’+item.StartDate.getHours():item.StartDate.getHours()”},{“id”:“sMinute”,”property”:“innerHTML”,”value”:“StartDate.getMinutes()<10?’0’+item.StartDate.getMinutes():item.StartDate.getMinutes()”}]”.

The “property” value must be a valid java-script property of html document node, such as “innerHTML”, “value”, “style”, “style.left”, “style.bgColor”, etc. The “value” value should contain valid java-script expression that uses calendar item properties. It have to start with one of calendar item field name (case sensitive): “Uid”, “Title”, “StartDate” “EndDate”, “Description”, “IsAllDay” and “Extentions” (“Title”, “IsAllDay = = false?’10’:’20’”, “Extentions.CanEdit = = true”, “Extentions.BgColor”, etc). Usually it just contains only the name of field, but you can also write complicated expression like in previous item mapping.

Note 4: From version 3.1 you can set many properties of one html node with help of item mapping. For instance: [{“id”:“title”,”property”:“innerHTML”,”value”:“Title”},{“id”:“title”,”property”:“style.backgroundColor”,”value”:“Extensions.BgColor”},{“id”:“title”,”property”:“style.border”,”value”:“Extensions.BorderStyle”}]”. It is evident, that your calendar item must contain “BgColor” and “BorderStyle” properties in its “Extensions” object.

If you use composite calendar control and its public property “DrillDownEnabled” is set to true, the control raises SelectedViewChange server event when user clicks day of month link in the control. You can create your handler than will also handle the event (but you cannot remove the default handler, that will switch view type of calendar anyway).

CalendarCtrl.SelectedViewChange+=new
EventHandler<Mediachase.AjaxCalendar.CalendarViewSelectEventArgs>(CalendarCtrl_SelectedViewChange);

void CalendarCtrl_SelectedViewChange(object sender,
Mediachase.AjaxCalendar.CalendarViewSelectEventArgs e)
{ switch (e.NewViewType) { … } }

When user clicks on calendar grid in browser calendar control raises client java-script events.

There are six different events:

• OnItemCreating (raised when user presses mouse button over the empty grid space);
  
• OnItemCreated (raised when user releases previously pressed mouse button);
  
• OnItemUpdating (raised when user presses mouse button over calendar item);
  
• OnItemUpdated (raised when user releases previously pressed mouse button over calendar item area with mcc_action == “move” or mcc_action == “resize”);
  
• OnItemDeleting (raised when user press mouse button over calendar item area marked with attribute mcc_action=“delete”);
  
• OnItemDeleted (raised when user releases previously pressed mouse button over calendar item area marked with attribute mcc_action=“delete”).

By default calendar control has its own client handlers for these events. You can disable them by setting calendar control public server properties UseDefaultCreateHandler, UseDefaultUpdateHandler, UseDefaultDeleteHandler to “false”

Developer can register his own client event handlers using java-script. Fist you should find a java-script object corresponding to current calendar view. You can do it using “$find” function from Microsoft ASP.NET Ajax client library:

var view = $find(’<%=CalendarCtrl.ClientViewId%>’);

Each calendar view (including composite calendar control) has public string property named “ClientViewId” for this purpose. To find event bar java-script object (for MultiDay view ) you can use property “ClientEventBarId”:

<%if(CalendarCtrl.ViewType == Mediachase.AjaxCalendar.CalendarViewType.MultiDay){%>
var eventbar = $find(’<%=this.CalendarCtrl.ClientEventBarId%>’);
...
<%}%>

Second you should use the following functions of found java-script object to register your own event handlers (names of functions are case sensitive):

add_itemCreating(yourCreatingHandlerFunction);
add_itemCreated(yourCreatedHandlerFunction);
add_itemUpdating(yourUpdatingHandlerFunction);
add_itemUpdated(yourUpdatedHandlerFunction);
add_itemDeleting(yourDeletingHandlerFunction);
add_itemDeleted(yourDeletedHandlerFunction).

If you want to remove your handlers you can use the following functions (names of functions are case sensitive):

remove_itemCreating(yourCreatingHandlerFunction);
remove_itemCreated(yourCreatedHandlerFunction);
remove_itemUpdating(yourUpdatingHandlerFunction);
remove_itemUpdated(yourUpdatedHandlerFunction);
remove_itemDeleting(yourDeletingHandlerFunction);
remove_itemDeleted(yourDeletedHandlerFunction).

For example:

if(view)
{
	view.add_itemUpdating(Function.createDelegate(this, this.OnItemUpdating));
}
if(eventbar)
{
	eventbar.add_itemUpdating(Function.createDelegate(this, this.OnItemUpdating));
}

It is obvious that “your*HandlerFunction” functions must be defined in your java-script code.

All your java-script event handler functions must have two parameters: first is “sender,” second is “args.”

function MyItemUpdatingHandler(sender, args)
{
...
}

First parameter “sender” is java script object that raised the client event. You have only one useful function in it for you (name is case sensitive): “get_ActionName”. This function has empty list of input parameters. You can use it in “OnItemUpdating” or “OnItemUpdated” event handler for distinguishing item update type. If this function returns empty string it means that user clicked in calendar item area which was not marked with any of “mcc_action” attribute.

if(sender.get_ActionName()=="")
{
	//handle the event
}

If the function return value equals to “move” it means that user want to move item (“resize” – he wants to change item duration, “delete” – to delete item).

Second parameter “args” has much more useful fields for developer. Fields names are case sensitive.

1. “MouseEvent” property of object “args” contains native java-script mouse event. You can get from it type of event (if(args.MouseEvent.type==’mouseup’)), mouse coordinates in browser window (args.MouseEvent.clientX, args.MouseEvent.clientY), etc.
2. When “*ing” event (OnItemUpdating, OnItemCreating, OnItemDeleting) is raised “args” object has “Canceled” field with default value “false”. If you want to cancel item creating, updating or deleting you can set it “true” and the action will be canceled (args.Canceled = true).
3. “Uid” property contains string uid of existing calendar item. When “OnItemCreating” and “OnItemCreated” events are raised “args” object does not contain “Uid” field because item is not created yet.
4. “Title” holds title of existing item or ”&nbsp;” string when “OnItemCreating” and “OnItemCreated” events are raised.
5. “StartDate” contains start date (instance of java-script Date class). “OnItemCreating” and “OnItemCreated” events are raised this field contains start date for new item. If “OnItemUpdating” is raised it contains start date of existing item. If “OnItemUpdated” is raised and sender.get_ActionName()==“move” it contains new start date of existing item. If “OnItemDeleting” event is raised it contains existing item start date.
6. “EndDate” holds end date (instance of java-script Date class). If “OnItemCreating” and “OnItemCreated” events are raised this field contains end date for new item. If “OnItemUpdating” is raised it contains end date of existing item. If “OnItemUpdated” is raised and sender.get_ActionName()==“move” or sender.get_ActionName()==“resize” it contains new end date of existing item. If “OnItemDeleting” event is raised it contains existing item end date.
7. “Description” contains description of existing item or ”&nbsp;” string when “OnItemCreating” and “OnItemCreated” events are raised.
8. “IsAllDay” contains boolean value that show if item is all day.
9. “Extensions” contains existing item extensions or “null” if “OnItemCreating” and “OnItemCreated” events are raised.
10. “ItemsManager” contains java-script object that allows developer manage items on client machine.
11. “CalendarExtension” (from version 3.2) contains calendar extension from server-side “CalendarExtension” property of currently displaying view.

“ItemsManager” object has three useful functions for developer. You can call them from your java-script code inside your client event handlers. Parameter “calendarExtension” was added in version 3.2. If you upgraded you control from version 3.0 or 3.1 you must add this parameter in calling these methods from your java-script code.

CreateItem(title, startDate, endDate, description, isAllDay, extensions, calendarExtension);
UpdateItem(uid, title, startDate, endDate, description, isAllDay, extensions, calendarExtension);
DeleteItem(uid, calendarExtension);

For example:

function MyItemUpdatedHandler(sender, args)
{
	args.ItemsManager.UpdateItem(args.Uid, args.Title, args.StartDate,
 			args.EndDate, args.Description, args.IsAllDay, args.Extensions, args.CalendarExtension);
}

Note 1: on client side, parameters “startDate” and “endDate” of ItemsManager methods accept instances of java-script Date class only.

Note 2: in Year view of calendar control “OnItemCreating”, “OnItemCreated” and “OnItemUpdated” events are not raised. Also in Year view server parameters “UseDefaultCreateHandle” and “UseDefaultUpdateHandler” are not used. If you want to handle “OnItemUpdating” event you must make your own handler and register it using “add_itemUpdating” function. But events “OnItemDeleting” and “OnItemDeleted” are still raised.

Note 3: When “OnItemDeleted” event is raised its “args” contains reduced set of fields: “ItemsManager”, “MouseEvent”, “Uid”, and “CalendarExtension” only.

From version 3.2.2 you can add custom client-side handlers which will be executed before items loading, after successful items loading and after failed items loading. For this purpose server side properties “ItemsStartLoadingHandler”, “ItemsLoadedHandler”, and “ItemsLoadFailedHandler” exist in each calendar view. This property must contain java-script function name that is defined in your code. By default this property contains empty string. Your items loading handler functions must contain two parameters: “senderId” and “args”. SenderId is client side id of calendar items manager. You can use $find method from Microsoft ASP.NET Ajax client side library to get items manager by its id:

function Loaded(senderId, args)
{
	var im = $find(senderId);
	if(im!=null)
	{
		//.....
	}
}

Parameter “args” contains three properties (names are case sensitive): “StartDate”, “EndDate”, and “CalendarExtension”.