<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>MagicAjax.NET Usage</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<style type="text/css"> <!-- .MainHeader { font-weight: bold; color: white; background-color: #0066cc; font-size: 10pt}
body { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 10pt; color: black; background-color: white}
.BorderHeader { background-color: #999900; font-size: 8pt; font-weight: bold; color: #333300; text-align: center}
.MainContent { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 10pt; color: black }
.BorderContent { font-size: 8pt; color: black; border-color: black #666600 #666600; padding-top: 2px; padding-right: 2px; padding-bottom: 10px; padding-left: 2px; margin-bottom: 2px; border-style: solid; border-top-width: 0px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px}
a:link { color: #000099; text-decoration: underline}
a:hover { color: #000099; text-decoration: underline}
a:visited { color: #000099; text-decoration: underline}
li { color: black; list-style-type: circle; position: relative; left: -15px; clip: rect( )}
.NewsDate { color: black; font-weight: bold; font-size: 11pt}
td { font-size: 10pt}
th { font-size: 10pt}
.Annotation { font-size: 10px}
H1 { text-align: center; }
A.qindex {}
A.qindexRef {}
A.el { text-decoration: none; font-weight: bold }
A.elRef { font-weight: bold }
A.code { text-decoration: none; font-weight: normal; color: #4444ee }
A.codeRef { font-weight: normal; color: #4444ee }
DL.el { margin-left: -1cm }
DIV.fragment { width: 100%; border: none; background-color: #003300 }
DIV.ah { background-color: black; margin-bottom: 3; margin-top: 3 }
TD.md { background-color: #006600 }
DIV.groupHeader { margin-left: 16; margin-top: 12; margin-bottom: 6; font-weight: bold }
DIV.groupText { margin-left: 16; font-style: italic; font-size: smaller }
FONT.keyword { color: #008000 }
FONT.keywordtype { color: #999920 }
FONT.keywordflow { color: #e0FF00 }
FONT.comment { color: #009900 }
FONT.preprocessor { color: #809020 }
FONT.stringliteral { color: #002080 }
FONT.charliteral { color: #008080 }
H3 { FONT-FAMILY: trebuchet ms,helvetica,arial }
.ex { FONT-SIZE: 8pt; FONT-FAMILY: tahoma }
CODE.keywordtype { COLOR: #00ccff }
CODE.keyword { FONT-WEIGHT: bold; COLOR: #00ccff }
CODE.fn { COLOR: white; FONT-WEIGHT: bold; }
CODE.var { COLOR: #dcdcdc; }
CODE.macro { COLOR: #809020; FONT-WEIGHT: bold; }
CODE.comm { COLOR: lime }
CODE.num { COLOR: purple }
CODE.str { COLOR: #ffcc33; font-style: italic }
.SectionHeader { font-size: 14px; color: #FFFFCC; font-weight: bold}
.header { font-size: 16px; font-weight: bold; color: #663399}
--></style>
</head>
<body text="#000000" bgColor="#ffffff">
<p class="header" align="center">MagicAjax.NET Framework</p>
<P class="header" align="center">Usage</P>
<p class="MainHeader" align="left">Table of Contents</p>
<UL>
<LI>
Programming
<ul>
<li>
<A href="#ajaxcall">Handling an AjaxCall</A>
<li>
<A href="#timer">Setting an Ajax refresh timer</A>
</li>
</ul>
<li>
Controls
<ul>
<LI>
<A href="#ajaxpanel">AjaxPanel</A>
<LI>
<A href="#AjaxZone">AjaxZone</A>
<LI>
<A href="#ClientEventTrigger">ClientEventTrigger</A>
<LI>
<A href="#KeyClientEventWrapper">KeyClientEventWrapper</A>
<LI>
<A href="#AjaxPage">AjaxPage and AjaxUserControl</A>
<LI>
<A href="#AjaxHtml">AjaxHtmlAnchor and AjaxHtmlImage</A>
<LI>
<A href="#attributes">MagicAjax attributes for ASP.NET controls</A>
</LI>
</ul>
</li>
</UL>
<p class="MainHeader" align="left">Programming</p>
<p class="NewsDate"><a name="ajaxcall"></a>Handling an AjaxCall</p>
<p class="MainContent">Depending on the PageStore Mode configuration option, the
page's execution cycle will differ significantly (see <A href="Configuration.html#Mode">
Configuration Options</A>). For the default 'NoStore' mode, the page's
execution cycle will be the same as a PostBack. You can distinguish if a
PostBack or an AjaxCall occured, by checking the return value of the <b>MagicAjaxContext.Current.IsAjaxCallForPage</b>
method.
</p>
<P class="MainContent"><b>Note:</b> There is a <b>MagicAjaxContext.Current.IsAjaxCall</b>
property that is true if the http request was originated by an AjaxCall, but
the recommended method of checking whether an AjaxCall was invoked is by using <b>IsAjaxCallForPage</b>.
If the page is created because of a <i>Server.Transfer</i> call that occured
during an AjaxCall, IsAjaxCallForPage will return false so that your page can
execute as a normal page request. The <b>AjaxPage.IsAjaxCall</b> property,
that makes a call to IsAjaxCallForPage, is provided for convenience (see <A href="#AjaxPage">
AjaxPage</A>).</P>
<P class="MainContent">MagicAjax sends javascript code to the client as a response
to an AjaxCall. If you want to send your custom javascript along with
MagicAjax's, you can use the static functions of <b>AjaxCallHelper</b>.
For example:
<pre> private void Button1_Click(object sender, System.EventArgs e)
{
AjaxCallHelper.WriteAlert ("Button1 was clicked.");
}</pre>
<hr>
<p class="NewsDate"><a name="timer"></a>Setting an Ajax refresh timer</p>
<p class="MainContent">You can use the <STRONG>AjaxCallHelper.SetAjaxCallTimerInterval</STRONG>
method to set a page wide timer that will invoke AjaxCalls at the intervals
that you define. You can call it either at the initial page request or during
an AjaxCall to initiate it or change the interval value. If you call it with an
interval value of zero, the timer will deactivate.
</p>
<P class="MainContent">Example:
<pre> private void Page_Load(object sender, System.EventArgs e)
{
if (!IsPostBack)
{
// Ajax refresh every 10 seconds
MagicAjax.AjaxCallHelper.SetAjaxCallTimerInterval(10000);
}
}
</pre>
</P>
<p class="MainHeader" align="left">Controls</p>
<p class="NewsDate"><a name="ajaxpanel"></a>AjaxPanel</p>
<p class="MainContent">This is the core control of the MagicAjax framework. The
PostBack functionality of all the controls that are inside an AjaxPanel will be
replaced by an AJAX callback (AjaxCall), unless defined otherwise. AjaxPanel
works like the ASP.NET Panel, its contents are visible on the designer, you
can set all the WebControl attributes to it, change its Visible property
etc.
</p>
<P class="MainContent">Its <b>AjaxCallConnection </b>property can be set to:
<ul>
<li>
Asynchronous (Default)
<ul>
The AjaxCall will be invoked in the background
</ul>
<li>
Synchronous
<ul>
The client's browser will wait for the AjaxCall to finish
</ul>
<li>
None
<ul>
Controls inside the AjaxPanel will invoke a normal PostBack
</ul>
</li>
</ul>
<P></P>
<P class="MainContent">Its <b>ExcludeFlags</b> property determines which form
elements should be excluded from posting to the server during an AjaxCall, thus
reducing the AjaxCall traffic. It sets the <A href="#attributes">ExcludeFlags</A>
MagicAjax ASP.NET control attribute. A child AjaxPanel automatically "inherits"
the ExcludeFlags of its parent AjaxPanel. The child can mark more form elements
to exclude through its ExcludeFlags property but it cannot send to the
server form elements that have been marked for exclusion by its parent
AjaxPanel.</P>
<P class="MainContent">In order to reduce the amount of html needed to send to
client, AjaxPanel defines individual 'html holders'. If the html
of a holder changes during an AjaxCall, MagicAjax sends the whole
html of the holder so that it can be reflected to the client's browser.
Every immediate WebControl child of an AjaxPanel is considered a separate
holder, and one extra holder is defined for the literal and HtmlControls
content of the AjaxPanel. Thus, if the html of a WebControl, that is
enclosed inside an AjaxPanel, changes, only the html of the particular
WebControl will be sent to the client.</P>
<P class="MainContent">An AjaxPanel (child AjaxPanel) that is inside
another AjaxPanel (parent AjaxPanel), define its html holders separately from
its parent. The parent AjaxPanel will ignore the html of the child AjaxPanel;
only the child AjaxPanel will be responsible for reflecting its holders on the
client. Thus, you can reduce the traffic of AjaxCalls, by adding many
AjaxPanels that define more and smaller html holders. For example, if you put a
table inside an AjaxPanel and change one of its cells during an AjaxCall, the
complete html of the table is going to be sent to the client. On the other
hand, if you add an AjaxPanel for each cell, only the html of the contents of
the changed cell will be sent to the client.</P>
<P class="MainContent">In order to monitor the traffic of AjaxCalls that your page
is producing, you can enable the <A href="Configuration.html#tracing">tracing</A> configuration
option.</P>
<P class="MainContent">
<hr>
<p class="NewsDate"><a name="AjaxZone"></a>AjaxZone</p>
<P>It's an AjaxPanel that has the MagicAjax attribute <a href="#attributes">AjaxLocalScope</a>
set to true. It is provided for convenience and readability. When an AjaxCall
is invoked from a control inside an AjaxZone, only the values of the form
elements that are contained inside this AjaxZone will be sent to the server and
the server will check for changes and "reflect" only the AjaxPanels that are
inside the AjaxZone. This helps reduce the Ajax traffic and speed up a bit
the server's response. It's intented for isolated and independent portions
of a page, like UserControls.
</P>
<P>An AjaxZone can contain other AjaxZones. A control belongs to the AjaxZone that
is its immediate parent.
<hr>
<P></P>
<P></P>
<p class="NewsDate"><a name="ClientEventTrigger"></a>ClientEventTrigger</p>
<p class="MainContent">Captures a client event of a control. The EventName property
must be set to the client event (i.e. "focus", "change", etc.) and the
ControlID property must be set to the ID of the control whose event you
want to capture. The AjaxCall that will be invoked is dependent at the
ClientEventTrigger's placement, not the placement of ControlID's control. For
example, if the ClientEventTrigger is inside an AjaxPanel an AjaxCall will
be invoked even if the ControlID's control is not inside an AjaxPanel. The
ClientEventTrigger must be inside the same NamingContainer (i.e. UserControl)
as the ControlID's control.
<hr>
<P></P>
<p class="NewsDate"><a name="KeyClientEventWrapper"></a>KeyClientEventWrapper</p>
<p class="MainContent">Captures the KeyPress, KeyDown, and KeyUp client events of
its inner controls. The KeyPress event has the IE behaviour across all browsers
(invoked when a character is typed or Enter is pressed).
<hr>
<P></P>
<p class="NewsDate"><a name="AjaxPage"></a>AjaxPage and AjaxUserControl</p>
<p class="MainContent">Making your pages and usercontrols inherit from AjaxPage and
AjaxUserControl is not required; they're provided only for convenience. They
expose the MagicAjax's stored page events (see <A href="Configuration.html#Mode">Session/Cache
PageStore modes</A>) and provide the <b>IsAjaxCall</b> property that makes
a call to MagicAjaxContext.Current.IsAjaxCallForPage.
<hr>
<P></P>
<p class="NewsDate"><a name="AjaxHtml"></a>AjaxHtmlAnchor and AjaxHtmlImage</p>
<p class="MainContent">These controls are intented to be used only for the <A href="Configuration.html#Mode">
Session/Cache PageStore modes</A>. When these modes are selected, ASP.NET's
HtmlAnchor and HtmlImage loose their <i>href</i> and <i>src</i> attributes
during an AjaxCall. AjaxHtmlAnchor and AjaxHtmlImage can be used in their
place.
<hr>
<P></P>
<p class="NewsDate"><a name="attributes"></a>MagicAjax attributes for ASP.NET
controls</p>
<p class="MainContent">You can add special attributes to ASP.NET controls that
define how they will be handled by MagicAjax:
<ul>
<li>
<b>AjaxCall</b> ("Async" or "Sync" or "None")
<p>If you add the <i>AjaxCall</i> attribute with "Async"/"Sync" value to a control
that has PostBack functionality (i.e. Button, LinkButton, CheckBox, etc.) the
PostBack functionality of the control will be replaced by AJAX functionality,
even if it is not contained inside an AjaxPanel. If you add the <i>AjaxCall</i>
attribute with "None" value to a control that is inside an AjaxPanel, the
control will perform a PostBack instead of an AjaxCall. By adding the <i>AjaxCall</i>
attribute, you override the AjaxCallConnection property of its parent AjaxPanel
(if the AjaxPanel is set to Asynchronous, you can add <i>AjaxCall</i> with
"sync" value to a control to make it perform a synchronous AjaxCall). The
effect of the <i>AjaxCall</i> attribute is applied to all the children of the
control, so if you add it to a plain ASP.NET Panel, all the controls that are
contained inside this Panel will get the effect of the <i>AjaxCall</i> attribute.
</p>
<li>
<b>ExcludeFromPost</b> ("true" or "false")
<p>When an AjaxCall is invoked, the client sends the values of the form elements to
the server as POST data. If there is a control that is used only to display
information and not to get input from the user, you can add the <i>ExcludeFromPost</i>
attribute with "true" value and the value of this control will not be sent
to the server. For example, if your page contains a readonly TextBox that is
used to display chat messages, sending its contents for every AjaxCall is
unnecessary traffic; you can avoid it by using the <i>ExcludeFromPost</i> attribute.</p>
<li>
<b>AjaxLocalScope</b> ("true" or "false")
<p>Makes the control behave like an <A href="#AjaxZone">AjaxZone</A>.</p>
<li>
<b>ExcludeFlags</b> (expression)
<p>Determines which form elements will be excluded from posting to server during an
AjaxCall. These form elements will be excluded when an AjaxCall is invoked from
the control or one of its children. It should be set to an arithmetic
expression that has an integer as a result. The javascript constants <STRONG>excfViewState</STRONG>,
<STRONG>excfFingerprints</STRONG>, <STRONG>excfUserHidden</STRONG>, <STRONG>excfAllHidden</STRONG>,
<STRONG>excfFormElements</STRONG>, <STRONG>excfAllElements </STRONG>can be used
for convenience.</p>
<p>Example:
<pre> <asp:button excludeflags="excfFormElements | excfViewState" ...></pre>
<P></P>
</li>
</ul>
<P></P>
<p>All the attributes can be added inside the control's tag statement or by
code. Their values, and consequently their function, can be changed during an
AjaxCall.
</p>
<p>Example:
<pre> Button1.Attributes["ajaxcall"] = "async";</pre>
<hr>
<P></P>
<P class="MainHeader" align="left"> </P>
<P>Copyright � 2005-2006 by The MagicAjax.NET Team</P>
</body>
</html>
Submit an article or tip