Merge pull request #25 from hydrostack/16-support-subjects-in-the-events

Support event subjects

Author: kjeske

docs/content/features/events.md

@@ -145,7 +145,7 @@ public void Add()
 `Add` triggers the event asynchronously, so the button that triggers this action will be disabled until the action is done. The event execution won't be connected with the action's pipeline and will be run on its own.
 
 
-## Events scope
+## Event scope
 
 By default, the events are dispatched only to their parent component. To publish a global event use the following
 method:
@@ -154,6 +154,12 @@ method:
 Dispatch(new ShowMessage(Content), Scope.Global);
 ```
 
+or
+
+```c#
+DispatchGlobal(new ShowMessage(Content));
+```
+
 Any component that subscribes for `ShowMessage` will be notified, no matter the component's location.
 
 ## Inlined subscription
@@ -193,4 +199,63 @@ public class ProductList : HydroComponent
         // When ProductAddedEvent occurs, component will be rerendered
     }
 }
-```
+```
+
+## Event subject
+
+There might be a situation where you want to filter the events you receive in your subscription handler. It means that
+your component subscribes to an event, but handles it only when it contains a certain flag. That flag can be any string
+and is called a `subject`.
+
+You can imagine a page with multiple lists of todos. Each list is a Hydro component that listens to events like `TodoAdded`,
+`TodoRemoved` or `TodoEdited`. When a todo is removed on one list, you don't want all the other lists to receive and react to that event, but only
+the list that contained that todo item. This is solved in Hydro by using `subject` parameter, which in this case will be the list's id.
+When `TodoAdded`, `TodoRemoved` or `TodoEdited` are dispatched, `subject` is set to their list's id. The list component subscribes to those
+events with `subject` set to the their list's id.
+
+Example:
+
+```c#
+// Todo.cshtml.cs
+
+public class Todo : HydroComponent
+{
+    public string TodoId { get; set; }
+    public string ListId { get; set; }
+    public string Text { get; set; }
+    public bool IsDone { get; set; }
+    
+    public void Remove(string id)
+    {
+        DispatchGlobal(new TodoRemoved { TodoId }, subject: ListId);
+    }
+}
+```
+
+```c#
+// TodoList.cshtml.cs
+
+public class TodoList : HydroComponent
+{
+    public string ListId { get; set; }
+    public List<Todo> Todos { get; set; }
+    
+    public TodoList()
+    {
+        Subscribe<TodoRemoved>(subject: () => ListId, Handle);
+    }
+    
+    public void Handle(TodoRemoved data)
+    {
+        // will be called only when subject is ListId
+        Todos.RemoveAll(todo => todo.TodoId == data.TodoId);
+    }
+}
+```
+
+In `Subscribe` method call `subject` parameter is a `Func<string>` instead of `string`, 
+because its value could be taken from component's properties that are not set yet, since it's
+a constructor.
+
+> NOTE: If you subscribe for an event without specifying the subject, it will catch all the events
+of that type, no matter if they were dispatched with subject or not.

src/HydroComponent.cs

@@ -143,10 +143,11 @@ public async Task<IHtmlContent> InvokeAsync(object parameters = null, string key
     /// Subscribes to a Hydro event
     /// </summary>
     /// <typeparam name="TEvent">Event type</typeparam>
-    public void Subscribe<TEvent>() =>
+    public void Subscribe<TEvent>(Func<string> subject = null) =>
         _subscriptions.Add(new HydroEventSubscription
         {
             EventName = GetFullTypeName(typeof(TEvent)),
+            SubjectRetriever = subject,
             Action = (TEvent _) => { }
         });
 
@@ -162,6 +163,20 @@ public void Subscribe<TEvent>(Action<TEvent> action) =>
             Action = action
         });
 
+    /// <summary>
+    /// Subscribes to a Hydro event
+    /// </summary>
+    /// <param name="subject">Subject</param>
+    /// <param name="action">Action to execute when event occurs</param>
+    /// <typeparam name="TEvent">Event type</typeparam>
+    public void Subscribe<TEvent>(Func<string> subject, Action<TEvent> action) =>
+        _subscriptions.Add(new HydroEventSubscription
+        {
+            EventName = GetFullTypeName(typeof(TEvent)),
+            SubjectRetriever = subject,
+            Action = action
+        });
+
     private static string GetFullTypeName(Type type) =>
         type.DeclaringType != null
             ? type.DeclaringType.Name + "+" + type.Name
@@ -179,6 +194,20 @@ public void Subscribe<TEvent>(Func<TEvent, Task> action) =>
             Action = action
         });
 
+    /// <summary>
+    /// Subscribes to a Hydro event
+    /// </summary>
+    /// <param name="subject">Subject</param>
+    /// <param name="action">Action to execute when event occurs</param>
+    /// <typeparam name="TEvent">Event type</typeparam>
+    public void Subscribe<TEvent>(Func<string> subject, Func<TEvent, Task> action) =>
+        _subscriptions.Add(new HydroEventSubscription
+        {
+            EventName = GetFullTypeName(typeof(TEvent)),
+            Action = action,
+            SubjectRetriever = subject
+        });
+
     /// <summary>
     /// Triggers a Hydro event
     /// </summary>
@@ -195,9 +224,10 @@ public void Dispatch<TEvent>(TEvent data, Scope scope = Scope.Parent, bool async
     /// <param name="name">Name of the event</param>
     /// <param name="data">Data to pass</param>
     /// <param name="scope">Scope of the event</param>
+    /// <param name="subject">Subject</param>
     /// <param name="asynchronous">Do not chain the execution of handlers and run them separately</param>
     /// <typeparam name="TEvent">Event type</typeparam>
-    public void Dispatch<TEvent>(string name, TEvent data, Scope scope = Scope.Parent, bool asynchronous = false)
+    public void Dispatch<TEvent>(string name, TEvent data, Scope scope = Scope.Parent, bool asynchronous = false, string subject = null)
     {
         var operationId = !asynchronous && HttpContext.Request.Headers.TryGetValue(HydroConsts.RequestHeaders.OperationId, out var incomingOperationId)
             ? incomingOperationId.First()
@@ -208,10 +238,21 @@ public void Dispatch<TEvent>(string name, TEvent data, Scope scope = Scope.Paren
             Name = name,
             Data = data,
             Scope = scope.ToString().ToLower(),
+            Subject = subject,
             OperationId = operationId
         });
     }
 
+    /// <summary>
+    /// Triggers a Hydro event in a global scope
+    /// </summary>
+    /// <param name="data">Data to pass</param>
+    /// <param name="subject">Subject</param>
+    /// <param name="asynchronous">Do not chain the execution of handlers and run them separately</param>
+    /// <typeparam name="TEvent">Event type</typeparam>
+    public void DispatchGlobal<TEvent>(TEvent data, string subject = null, bool asynchronous = false) =>
+        Dispatch(GetFullTypeName(typeof(TEvent)), data, Scope.Global, asynchronous, subject);
+
     /// <summary>
     /// Provides actions that can be executed on client side
     /// </summary>
@@ -232,7 +273,7 @@ public virtual Task MountAsync()
     public virtual void Mount()
     {
     }
-
+    
     /// <summary>
     /// Triggered before each render
     /// </summary>
@@ -538,6 +579,7 @@ private HtmlNode GetEventSubscriptionScript(HtmlDocument document, HydroEventSub
         var eventData = new
         {
             name = subscription.EventName,
+            subject = subscription.SubjectRetriever?.Invoke(),
             path = $"/hydro/{GetType().Name}/event".ToLower()
         };
 
@@ -566,7 +608,14 @@ private void PopulateDispatchers()
         }
 
         var data = _dispatchEvents
-            .Select(e => new { name = e.Name, data = Base64.Serialize(e.Data), scope = e.Scope, operationId = e.OperationId })
+            .Select(e => new
+            {
+                name = e.Name,
+                data = Base64.Serialize(e.Data),
+                scope = e.Scope,
+                subject = e.Subject,
+                operationId = e.OperationId
+            })
             .ToList();
 
         HttpContext.Response.Headers.TryAdd(HydroConsts.ResponseHeaders.Trigger, JsonConvert.SerializeObject(data));
@@ -676,35 +725,36 @@ private async Task TriggerEvent()
             return;
         }
 
-        var subscription = _subscriptions.FirstOrDefault(s => s.EventName == eventNameValue);
+        var eventSubject = (string)HttpContext.Items[HydroConsts.ContextItems.EventSubject];
+        var subscriptions = _subscriptions
+            .Where(s => s.EventName == eventNameValue && (s.SubjectRetriever == null || s.SubjectRetriever() == eventSubject))
+            .ToList();
 
-        if (subscription == null)
+        foreach (var subscription in subscriptions)
         {
-            return;
-        }
+            var methodInfo = subscription.Action.Method;
+            var parameters = methodInfo.GetParameters();
+            var parameterType = parameters.First().ParameterType;
+            var model = Base64.Deserialize((string)HttpContext.Items[HydroConsts.ContextItems.EventData], parameterType);
 
-        var methodInfo = subscription.Action.Method;
-        var parameters = methodInfo.GetParameters();
-        var parameterType = parameters.First().ParameterType;
-        var model = Base64.Deserialize((string)HttpContext.Items[HydroConsts.ContextItems.EventData], parameterType);
+            var operationId = HttpContext.Request.Headers.TryGetValue(HydroConsts.RequestHeaders.OperationId, out var incomingOperationId)
+                ? incomingOperationId.First()
+                : Guid.NewGuid().ToString("N");
 
-        var operationId = HttpContext.Request.Headers.TryGetValue(HydroConsts.RequestHeaders.OperationId, out var incomingOperationId)
-            ? incomingOperationId.First()
-            : Guid.NewGuid().ToString("N");
+            HttpContext.Response.Headers.TryAdd(HydroConsts.ResponseHeaders.OperationId, operationId);
 
-        HttpContext.Response.Headers.TryAdd(HydroConsts.ResponseHeaders.OperationId, operationId);
-
-        var isAsync = typeof(Task).IsAssignableFrom(methodInfo.ReturnType);
+            var isAsync = typeof(Task).IsAssignableFrom(methodInfo.ReturnType);
 
-        if (isAsync)
-        {
-            var method = InvokeActionAsyncMethod.MakeGenericMethod(parameterType);
-            await (Task)method.Invoke(null, new[] { subscription.Action, model })!;
-        }
-        else
-        {
-            var method = InvokeActionMethod.MakeGenericMethod(parameterType);
-            method.Invoke(null, new[] { subscription.Action, model });
+            if (isAsync)
+            {
+                var method = InvokeActionAsyncMethod.MakeGenericMethod(parameterType);
+                await (Task)method.Invoke(null, new[] { subscription.Action, model })!;
+            }
+            else
+            {
+                var method = InvokeActionMethod.MakeGenericMethod(parameterType);
+                method.Invoke(null, new[] { subscription.Action, model });
+            }
         }
     }
 

src/HydroComponentEvent.cs

@@ -3,6 +3,7 @@
 internal class HydroComponentEvent
 {
     public string Name { get; init; }
+    public string Subject { get; init; }
     public object Data { get; init; }
     public string Scope { get; set; }
     public string OperationId { get; set; }

src/HydroComponentsExtensions.cs

@@ -98,6 +98,7 @@ private static async Task ExecuteRequestOperations(HttpContext context, string m
         {
             context.Items.Add(HydroConsts.ContextItems.EventName, eventData.Name);
             context.Items.Add(HydroConsts.ContextItems.EventData, eventData.Data);
+            context.Items.Add(HydroConsts.ContextItems.EventSubject, eventData.Subject);
         }
 
         if (!string.IsNullOrWhiteSpace(method) && type != "event")

src/HydroConsts.cs

@@ -27,6 +27,7 @@ public static class ContextItems
         public const string RequestForm = "hydro-request-form";
         public const string Parameters = "hydro-parameters";
         public const string EventData = "hydro-event-model";
+        public const string EventSubject = "hydro-event-subject";
         public const string IsRootRendered = "hydro-root-rendered";
     }
 

src/HydroEventPayload.cs

@@ -3,6 +3,7 @@ namespace Hydro;
 internal class HydroEventPayload
 {
     public string Name { get; set; }
+    public string Subject { get; set; }
     public object Data { get; set; }
     public Scope Scope { get; set; }
     public string OperationId { get; set; }

src/HydroEventSubscription.cs

@@ -3,5 +3,6 @@
 internal class HydroEventSubscription
 {
     public string EventName { get; set; }
+    public Func<string> SubjectRetriever { get; set; }
     public Delegate Action { get; set; }
 }

src/Scripts/hydro.js

@@ -110,7 +110,7 @@
     const operationId = eventData.operationId;
     const hydroEvent = el.getAttribute("x-on-hydro-event");
     const wireEventData = JSON.parse(hydroEvent);
-    await hydroRequest(el, url, { eventData: { name: wireEventData.name, data: eventData.data } }, 'event', wireEventData, operationId);
+    await hydroRequest(el, url, { eventData: { name: wireEventData.name, data: eventData.data, subject: eventData.subject } }, 'event', wireEventData, operationId);
   }
 
   async function hydroBind(el) {
@@ -393,11 +393,17 @@
                 const eventData = {
                   detail: {
                     data: trigger.data,
+                    subject: trigger.subject,
                     operationId: trigger.operationId
                   }
                 };
 
                 document.dispatchEvent(new CustomEvent(eventName, eventData));
+
+                if (trigger.subject) {
+                  const subjectEventName = `${eventScope}:${trigger.name}:${trigger.subject}`;
+                  document.dispatchEvent(new CustomEvent(subjectEventName, eventData));
+                }
               });
             }
           });
@@ -598,8 +604,8 @@ document.addEventListener('alpine:init', () => {
       }
 
       const data = JSON.parse(expression);
-      const globalEventName = `global:${data.name}`;
-      const localEventName = `${component.id}:${data.name}`;
+      const globalEventName = data.subject ? `global:${data.name}:${data.subject}` : `global:${data.name}`;
+      const localEventName = data.subject ? `${component.id}:${data.name}:${data.subject}` : `${component.id}:${data.name}`;
       const eventPath = data.path;
 
       const eventHandler = async (event) => {