1. Universal event handling for components in Kentico CMS
Boris Pocatko
Solution Architect
Kentico Software

2. Agenda
Problem
Solution
API
How does it work

3. Problem
A quite common need is to implement components which influence each other.
Examples
Hiding a control or web part when the user selects a specific value in a dropdown box.
Dependent form fields
Recalculating price according to selected currency in separate web parts

4. Problem I. schema
Component 1 ?
Component 2

5. Problem I. solution schema
Component 1
Component 2
RegisterToE... E E
HandleE(…) { … }
Solution:
Usage of events, where Component 2 registers to an Event implemented in the Component 1. Component 1 then raises the Event on some action and the Component 2 handles it with a handler registered to the Event of Component 1.

6. Problem I. solution Component 1 Component 2
public event EventHandler E;
private void FunctionThatRaisesEventE() {
// Raise event
this.StatusUpdated(new object(), new EventArgs()); }
Component 2
public void SetupControl() {
// Register event handling method
component1.E += new EventHandler(HandleE); }
public void HandleE(object sender, EventArgs e)
// Handle event

7. Problem I. summary The good Acceptable difficulty
Not much coding involved
Simplest solution
Two components, which can be used independently in the portal engine, thus resulting in bigger flexibility when designing a page
The bad
Control reference needed
Component are depending on each other
Explicit event declaration

8. Problem II. schema Component 3 Component 1 Component 2 Component 64
Component 5

9. Problem II. solution schema 1
Component 3
RegisterToE...
HandleE(…) { … }
Component 1
Component 2 E E
RegisterToE...
HandleE(…) { … } E2 E2
RegisterToE3...
Component 6
Component 4
Component 5
RegisterToE2...
RegisterToE3...
HandleE3(…) { … }
HandleE2(…) { … }
HandleE3(…) { … } E3 E3

10. Problem II. solution I summary
The good
Flexibility
The bad
Control reference needed
Component are depending on each other
Explicit event declaration
Increased difficulty
Poor maintainability

11. Problem II. solution schema 2
Component 1
Method 3
Method 1
Method 2
Method 6
Method 4
Method 5

12. Problem II. solution II summary
The good
Medium implementation difficulty
The bad
Difficult maintainability
Flexibility loss
Components re-use is difficult

13. Problem I. solution with Kentico component events
private void FunctionThatRaisesEventE(object sender, EventArgs e) {
// Raise Event
ComponentEvents.RequestEvents.RaiseEvent(sender, e, "E"); }
Component 2
public void SetupControl() {
// Register for Event
ComponentEvents.RequestEvents.RegisterForEvent("E", HandleE); }
public void HandleE(object sender, EventArgs e)
// Handle event

14. Problem II. solution schema 1 compared
Component 3
RegisterToE...
Getting rid of component dependencies (references aren’t necessary) and of event declarations
HandleE(…) { … }
Component 1
Component 2 E E
RegisterToE...
HandleE(…) { … } E2 E2
Component 6
Component 4
Component 5
RegisterToE3...
RegisterToE2...
RegisterToE3...
HandleE3(…) { … }
HandleE2(…) { … }
HandleE3(…) { … } E3 E3

15. Problem II. solution with Kentico component events
RegisterToE...
HandleE(…) { … }
Component 1
Component 2 E
RegisterToE...
HandleE(…) { … } E2
RegisterToE3...
Component 6
Component 4
Component 5
RegisterToE2...
RegisterToE3...
HandleE3(…) { … }
HandleE2(…) { … }
HandleE3(…) { … } E3

16. Problem II. solution with Kentico component events summary
Increased flexibility
Easier development
Re-use of components
No control references necessary
No controls dependencies
Easier maintainability
No explicit event declaration necessary

17. Component Events API I. Namespaces/classes Registering of events
CMS.SettingsProvider.ComponentEvents.RequestEvents
Events that are fired and survive within current request
CMS.SettingsProvider.ComponentEvents.GlobalEvents
- Global events that are fired and survive across requests during the whole application lifetime
Registering of events
RegisterForEvent(string eventName, EventHandler<EventArgs> handler)
RegisterForEvent(string eventName, string actionName, EventHandler<EventArgs> handler)
RegisterForEvent<ArgsType>(string eventName, string actionName, EventHandler<ArgsType> handler) where ArgsType : EventArgs
eventName: name of the event (e.g. Update)
actionName: action name, adds granularity, (e.g. Before, After)
handler: handler method for the event

18. Component Events API II.
Registering of events
RegisterForComponentEvent(string componentName, string eventName, EventHandler<EventArgs> handler)
RegisterForComponentEvent(string componentName, string eventName, string actionName, EventHandler<EventArgs> handler)
componentName: name of the component, another level of granularity (e.g. web part id)
actionName: action name, adds granularity (e.g. Before, After)
eventName: name of the event (e.g. Update)
handler: handler method for the event

19. Component Events API III.
Raising of events
RaiseComponentEvent(object sender, EventArgs e, string componentName, string eventName)
RaiseComponentEvent(object sender, EventArgs e, string componentName, string eventName, string actionName)
RaiseEvent(object sender, EventArgs e, string eventName)
sender: object raising the event (e.g. web part)
e: event arguments
componentName: name of the component raising the event
actionName: action name, adds granularity (e.g. Before, After)
eventName: name of the event (e.g. Update)
Registration & raise parameters need to match

20. How does it work
Events and handlers stored in a hashtable - case insensitive
During event registration a new entry is created in the hashtable
When an event is raised, the system calls all event handler methods registered (saved) for a given key combination of component name, event and action
The hashtable looks the following way:
componentName:eventName | sub-hashtable
eventName | sub-hashtable
sub-hashtable:
key: actionName or ##global##
value: handler

21. How does it work
Simple debug screenshot of an event with a sub-hashtable with only one value:

22. How does it work Calling:
ComponentEvents.RequestEvents.RegisterForComponentEvent("testComponent", "testEvent", "testAction", SomeMethod)
ComponentEvents.RequestEvents.RegisterForComponentEvent("testComponent", "testEvent", "testAction2", SomeMethod)
Creates a hashtable within the events hashtable, with the event key “testComponent:testEvent”. The sub-hashtable contains two values, with keys “testAction” and “testAction2”:

23. Example of use: Wizard layout web part
Components developed for the Wizard layout web part can subscribe to a number of Events:
LOAD_STEP
VALIDATE_STEP
FINISH_STEP
CANCEL_STEP
FINISH
These Events are registered as component events

24. Kentico component events
DEMO – Component events

25. Additional resources Wizard layout web part
Link / Button web part
(supports events)
Kentico CMS API reference

26. Questions & Answers ?

27. Thank you!