Click or drag to resize

Events

Event routing is a cornerstone of the Wisej architecture. Wisej client side JavaScript widgets can fire events on the server and server side components can fire and handle events synchronously or asynchronously (out-of-bound) using .NET standard events.

Event Handling

Handling events is as simple as attaching a listener to the event of overriding the event method. There is really nothing else to it.

Event Handler
this.button1.Click += this.Button1_Click;
...

void Button1_Click(object sender, EventArgs e) {

  this.button1.Text = "Clicked!";

}

Another way to handle events in derived classes is to simply override the event methods and process the event before or after it's fired.

Event Override
class MyButton : Wisej.Web.Button {

protected override void OnMouseDown(MouseEventArgs e) {

  this.Text = "The mouse is at " + e.Location;

}
Note Note

Note that Wisej is able to inform the server of the mouse location (relative to the browser and relative to the control) as well as the keyboard state, mouse buttons and wheel delta.

Touch events from mobile devices are all translated to the appropriate mouse events.

Lazy Events

There is a group of "critical" events that are not fired back to the server unless the application has specifically attached to the handler. These are events that would typically fire multiple times:

  • MouseMove

  • MouseEnter

  • MouseHover

  • MouseLeave

  • MouseWheel

  • KeyDown

  • KeyPress

  • KeyUp

  • QueryContinueDrag

  • DragDrop

  • DragEnter

  • DragOver

  • DragLeave

  • Swipe

  • Pinch

  • Rotate

  • Track

  • TouchStart

  • TouchEnd

  • TouchCancel

Once an handler is attached, you may also override the event method in a derived class.

Out of Bound Events

Out-of-bound events are events fired outside of a browser request (user action). For example, an event fired by a thread monitoring the stock market is an out-of-bound event since the thread is running in the background and is unaware of any browser activity.

The client may also fire unattended events back to the server. However, these are in-bound events since the server is processing a request from the browser and has a valid session to work with.

When processing out-of-bound events you are processing a background task, which is a thread that has absolutely no knowledge of the session, or sessions, that is handling the event. Handling out-of-bound events - something close to impossible with other systems - is easy with Wisej, all you need to do is wrap the handling code in Application.RunInContext(component, ()=>{ code }) or Application.Update(component, ()=>{ code }).

The only difference between RunInContext and Update is that the Update call pushes any changes to the visual components back to the client.

Handling Out-of-Bound Events
public class Window1 : Wisej.Web.Form {


  // When this window is loaded, we connect to a background task (thread) monitoring the stock market.
  // The thread was started independently and the static reference saved in MyApp.Program.

  protected override void OnLoad(EventArgs e) {

    Program.StockMarketMonitor.PriceDrop += this.StockMarketMonitor_PriceDrop;

    base.OnLoad(e);
  }

  // When we receive a PriceDrop event, display an alert.

  void StockMarketMonitor_PriceDrop(object sender, StockMarketMonitorEventArgs e) {

      // Restore the context using this component and run in context using Update since
      // we want to show the alert box immediately on the user's browser.

      Application.Update(this, ()=>{

          AlertBox.Show($"The price of {e.Symbol} dropped below {e.Limit}", MessageBoxIcon.Warning);

          // Note: We can also update the user's browser several times using: Application.Update(component) at any time.

      });
  }

}

Once you are back in context, you can handle any component in the user session: update text, hide, show, move. There are no limits to what you can do using Wisej Real Time features.

JavaScript Events

When creating new Wisej components and widgets, or integrating existing jQuery or other third party JavaScript widgets, you will most likely need to fire an event from JavaScript running in the browser back to the server and handle it as any other .NET event.

This is how you fire the event from a Wisej widget:

JavaScrip Event Firing Example
/**
 * Assuming that this code is being processed as part of a Wisej widget, fire a simple event
 * notifying the server side of this widget (the corresponding control) that the label was clicked.
 */
 this.fireEvent("labelClicked");

 /**
  * We can also send data back to the server together with an event.
  * For example, say we want to notify the server component that a specific label was clicked.
  */
 this.fireDataEvent("labelClicked", label.getName());

 /**
  * And we can send complex data structures when we need to send back multiple values.
  */
 this.fireDataEvent("labelClicked", {name: label.getName(), x:e.getDocumentX(), y:e.getDocumentY()});

 /**
  * We can even send back the reference to a widget. Wisej will convert it to an actual control on
  * the server side!
  *
  * Assuming that label is a Wisej widget:
  */
 this.fireDataEvent("labelClicked", {label: label, name: label.getName(), x:e.getDocumentX(), y:e.getDocumentY()});

The example above shows how to fire JavaScript events back to the server. The example below shows how to register an Wisej control to receive custom events and how to handle the data transported with the event.

Registering and Handling Custom Client Events
// Override OnWebRender() to register the additional custom events:
protected override voide OnWebRender(dynamic config) {

  base.OnWebRender((object)config);

  // add the new events to the list of wired events.
  config.wiredEvents.Add("labelClicked");

  // if the event "labelClicked" carried data with it, we need to declare the name of the data member like this:
  config.wiredEvents.Add("labelClicked(Name)");


  // the name in parethesis cna be anything. the example above used Name since the event was simply firing back the name.
  // the example below uses "Data" as a more appropriate name when the event carries complex data structures:
  config.wiredEvents.Add("labelClicked(Data)");

}

// To handle the event, override OnWebEvent():
protected override void OnWebEvent(WisejEventArgs e) {

  switch (e.Type) {

    case "labelClicked":
      // the data caming in from the client is accessible using e.Parameters.{Name}.

      // in the case of the event sending back simply the name: this.fireDataEvent("labelClick", label.getName());
      AlertBox.Show(e.Parameters.Name);

      // in the case of the event sending back a data strucure:
      AlertBox.Show("Label Clicked at X:" + e.Parameters.Data.x + " Y: " + e.Parameters.Data.y);

      break;

    default:
      base.OnWebEvent(e);
      break;
  }

}

When integrating third party widgets, you can handle and process their events in JavaScript and send back to Wisej a custom event of any type.

See Also