Taking advantage of commands

The DataView control supports the concept of a command. In practice, you can think of a command as a “fancy event” which is generated by MS AJAX controls in response to a DOM click event. Commands have an advantage over traditional DOM event handling: for instance, you can easily pass additional information that will be processed by a command hander.

Lets start with a really simple example:

    <script type="text/javascript" 
script> <script type="text/javascript"> var data = [ { name: "luis", address: "fx" }, { name: "john", address: "lx" }, { name: "rita", address: "ams" } ]; Sys.require([Sys.components.dataView]); function handleCommand(sender, e) { alert(e.get_commandName()); } </script> </head> <body xmlns:sys="javascript:Sys" xmlns:dv="javascript:Sys.UI.DataView"> <ul class="sys-template" sys:attach="dv" dv:data="{{data}}" dv:oncommand="{{ handleCommand }}"> <li sys:command="sayHi">
{{ name }} - {{ address }}
</li> </ul> </body>

In the previous snippet, we’ve configure the use of commands by:

  • making each click in the inner LI items generate a command named sayHi. Commands can be defined declaratively through the use of the sys:command system attribute. The basic definition of a command relies only in giving it a name (the rest of the information will be picked up automatically);
  • we’ve set up the DataView so that all generated commands are “routed” to the handleCommand method. Since commands can be see as “events on steroids for MS AJAX controls”, then it should surprise you to know that the method will receive a reference to the object that generated the command and an EventArgs derived object which contains info about the command (we’ll return to this topic in the next paragraphs).

Functions that handle commands will always receive a reference to a Sys.CommandEventArgs instance. This “class” expands the Sys.CancelEventArgs class (this means  you’ll get a cancel property which allows you to cancel the bubbling of the command) and adds several new properties:

  • commandName: this property identifies the name of the current command. Notice that you can only have one function for handling commands. If a control generates several commands, then you’ll have to identify the “current” command;
  • commandArgument: references an object which has been previously set during the command configuration (you can do this by using the sys:commandargument attribute);
  • commandSource: identifies the HTML element that was “responsible” for generating the current command (don’t forget that commands are always generated in response to DOM click events).

Besides the sys:command attribute,there are still a couple of other system attributes we can use to influence the generated command:

  • sys:commandargument: you can use this attribute to set the command argument which will be passed when the “current command” is generated. A function that handles a command can get this info by accessing the commandArgument property of the Sys.CommandEventArgs object it receives;
  • sys:commandtarget: used for indicating the MS AJAX control which will be targeted by this command.

You’re probably a little confused with the sys:commandtarget attribute. To illustrate its use,we’ll update the previous example. Take a look at the code(I’m only showing the markup because that’s the only thing that changed):

<ul class="sys-template"
  <li  sys:command="sayHi"
    {{ name }}- {{ address }}
<ul id="customTarget"
    dv:oncommand="{{ handleCommand }}"

As you can see, we’ve added a new DataView control and we’ve configured it so that any command generated by it will be handled by the handleCommand function. Since we didn’t add any sys:command attribute to that second DataView, you might end up thinking that the previous code won’t do anything useful…

However, you might have noticed that we’ve changed the markup for that first DataView control. If you look carefully, you’ll see that the LI element has also been annotated with a *sys:commandtarget* attribute. That sys:commandtarget attribute ends up influencing the generation of the command: all click made over LI elements maintained by that first DataView control will still be transformed into commands, but now they’ll be dispatched to the #customTarget DataView (and that’s why you’ll still get the handleCommand function call!)

And that’s it for now. There’s still more to come on MS AJAX, so stay tuned.


~ by Luis Abreu on October 22, 2009.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: