Creating Custom Events

Custom events can be created in the framework. This should be done if default event handlers are not sufficient for your application, and you need to create your own components.

A custom event must have:

A unique name.
An event class that must be an instance of the BaseEvent class. The BaseEvent class is an abstract class which requires all of its sub-classes to implement the fireEvent() method. In this method, event triggering must be implemented (the custom event handler’s interface method must be called).
An event handler interface which must extend the BrowserEventHandler interface. The event handler interface can only have a single method. This method’s parameter must be the event class.

A custom event must be registered to the framework. The custom event must be sent to the server-side from the client side. This is done by using JavaScript, by calling the jbstrap.fireEvent() method.

Registering a custom event to the framework

Every custom event must be registered to the framework individually. If an event is not registered, it will not work. It is recommended that the events are registered in the Startup class, in the init() method, because then it will be usable when the framework is started, and the code will remain more readable.

  Registering the „exampleEvent” custom event to the framework:  
        
EventType.addCustomEvent("exampleEvent",ExampleEvent.class,ExampleEventHandler.class);

Firing a custom event

Custom events are not triggered automatically on the interface. They must be implemented by the developer. If you want to trigger a custom event, a custom JavaScript must be executed, either on the server or the client-side.

To fire the event, use the fireEvent() JavaScript method which can be accessed through the jbstrap object. The method has four parameters that must be specified:

The first parameter must be the ID of the component firing the event. The component ID is the component’s HTML tag ID attribute value.
The second parameter is the name of the event stored as a String. This is the name that was specified during registration.
The third parameter is the event type. With all custom events, this must be null.
The fourth parameter is a JavaScript object. The contents of this object will be copied by the framework into the event object. This means that every attribute must be specified here, that you wish to use on the server-side via the event object.

  Firing the exampleEvent on the interface. The event class will have values of value1 and value2 passed. (JavaScript code):  
        
jbstrap.fireEvent($(component).attr("id"), "exampleEvent", null, {value1: "example value", value2: false});

Creating a custom event

The use of custom events in the framework is the same as the use of the default events. The event handler method must be implemented by using the custom event handler interface. Then this handler is assigned to the component which uses the custom event.

Storing custom event handler implementations must be done by the custom component, just like the method that is required for registering the event.

  Example for storing a custom event, and implementing the register method:  
        
public class ExampleComponent extends Component<ExampleComponent> {

	private ExampleEventHandler exampleEventHandler;

	public ExampleComponent(final String language) {
		super(language);
	}

	public void setExampleEventHandler(final ExampleEventHandler handler) {
		this.exampleEventHandler = handler;
	}

	public ExampleEventHandler getExampleEventHandler() {
		return this.exampleEventHandler;
	}

	@Override
	public void writeHTML(final StringWriter writer) {
		writer.write(openTag("div"));
		drawSubComponents(writer);
		writer.write(closeTag("div"));
	}
}


//Sample for the exampleEventHandler class:
public interface ExampleEventHandler extends BrowserEventHandler {

	void onExampleEvent(ExampleEvent event);

}


//Sample for the exampleEvent class:
public class ExampleEvent extends BaseEvent {
	private String value1;
	private Boolean value2;

	public String getValue1() {
		return this.value1;
	}

	public Boolean getValue2() {
		return this.value2;
	}

	@Override
	public void fireEvent() {
		final Component<?> component = getComponent();
		if (component instanceof ExampleComponent) {
			final ExampleEventHandler handler = ((ExampleComponent)component).getExampleEventHandler();
			if (handler != null) {
				handler.onExampleEvent(this);
			}
		}
	}
}