Introduce Param.JS

Author: kjeske

docs/content/features/actions.md

@@ -54,9 +54,9 @@ Examples:
 <input type="text" hydro-on:keyup.shift.enter="@(() => Model.Save())">
 ```
 
-## Arguments
+## Parameters
 
-If your action contains arguments, you can pass them in a regular way.
+If your action contains parameters, you can pass them in a regular way.
 
 Example:
 
@@ -86,6 +86,50 @@ public class Counter : HydroComponent
 </div>
 ```
 
+## JavaScript expression as a parameter
+
+In some cases, like integrating with JavaScript libraries like maps, rich-text editors, etc. it might be useful to
+call a Hydro action with parameters evaluated on client side via JavaScript expression. You can use then `Param.JS<T>(string value)` method, where:
+- `T`: type of the parameter
+- `value`: JavaScript expression to evaluate
+
+If your parameter type is a `string`, you can use a shorter version:
+
+`Param.JS(string value)`
+
+Example:
+
+```c#
+// RichContent.cshtml.cs
+
+public class Content : HydroComponent
+{
+    public void Update(string value)
+    {
+        // ...
+    }
+}
+```
+
+```razor
+<!-- Content.cshtml -->
+
+@model Content
+<div>
+  <input type="text" id="myInput">
+  <button hydro-on:click="@(() => Model.Update(Param.JS("window.myInput.value")))">
+    Update content
+  </button>
+</div>
+```
+
+After clicking the button from the code above, Hydro will execute the expression
+`window.myInput.value` on the client side, and pass it as a `value` parameter to the `Update` action.
+
+> NOTE: In case of using widely this feature in your component, you can add:
+>
+> ```@using static Hydro.Param``` and call `JS` without `Param.` prefix.
+
 ## Asynchronous actions
 
 If you want to use asynchronous operations in your actions, just change the signature of the method as in this example:

src/ExpressionExtensions.cs

@@ -4,13 +4,16 @@ namespace Hydro;
 
 internal static class ExpressionExtensions
 {
+    private const string JsIndicationStart = "HYDRO_JS(";
+    private const string JsIndicationEnd = ")HYDRO_JS";
+
     public static (string Name, IDictionary<string, object> Parameters)? GetNameAndParameters(this Expression<Action> expression)
     {
         if (expression is not { Body: MethodCallExpression methodCall })
         {
             return null;
         }
-        
+
         var name = methodCall.Method.Name;
         var paramInfos = methodCall.Method.GetParameters();
         var arguments = methodCall.Arguments;
@@ -37,15 +40,30 @@ private static object EvaluateExpressionValue(Expression expression)
         {
             case ConstantExpression constantExpression:
                 return constantExpression.Value;
-            
+
             case MemberExpression memberExpression:
                 var objectMember = Expression.Convert(memberExpression, typeof(object));
                 var getterLambda = Expression.Lambda<Func<object>>(objectMember);
                 var getter = getterLambda.Compile();
                 return getter();
-            
+
+            case MethodCallExpression callExpression
+                when callExpression.Method.DeclaringType == typeof(Param)
+                     && callExpression.Method.Name == nameof(Param.JS)
+                     && callExpression.Arguments.Any()
+                     && callExpression.Arguments[0] is ConstantExpression constantExpression:
+
+                return EncodeJsExpression(constantExpression.Value);
+
             default:
                 throw new NotSupportedException("Unsupported expression type: " + expression.GetType().Name);
         }
     }
+
+    private static string EncodeJsExpression(object expression) =>
+        $"{JsIndicationStart}{expression}{JsIndicationEnd}";
+
+    internal static string DecodeJsExpressionsInJson(string json) =>
+        json.Replace("\"" + JsIndicationStart, "")
+            .Replace(JsIndicationEnd + "\"", "");
 }

src/Param.cs

@@ -0,0 +1,19 @@
+namespace Hydro;
+
+/// <summary>
+/// Used in Hydro action calls for passing JavaScript expressions as parameters
+/// </summary>
+public static class Param
+{
+    /// <summary>
+    /// Pass JavaScript expression as a parameter to Hydro action
+    /// </summary>
+    /// <param name="value">JavaScript expression</param>
+    public static T JS<T>(string value) => default;
+    
+    /// <summary>
+    /// Pass JavaScript expression as a parameter to Hydro action
+    /// </summary>
+    /// <param name="value">JavaScript expression</param>
+    public static string JS(string value) => default;
+}

src/TagHelpers/HydroOnTagHelper.cs

@@ -24,7 +24,7 @@ public IDictionary<string, Expression<Action>> Handlers
         get => _handlers ??= new Dictionary<string, Expression<Action>>(StringComparer.OrdinalIgnoreCase);
         set => _handlers = value;
     }
-    
+
     /// <summary>
     /// Disable during execution
     /// </summary>
@@ -48,7 +48,7 @@ public override void Process(TagHelperContext context, TagHelperOutput output)
         {
             return;
         }
-        
+
         foreach (var eventItem in _handlers)
         {
             var eventData = eventItem.Value.GetNameAndParameters();
@@ -57,22 +57,31 @@ public override void Process(TagHelperContext context, TagHelperOutput output)
             {
                 continue;
             }
-            
+
             var eventDefinition = eventItem.Key;
 
-            var invokeData = JsonConvert.SerializeObject(new
-            {
-                eventData.Value.Name,
-                eventData.Value.Parameters
-            }, JsonSettings.SerializerSettings);
+            var jsInvokeExpression = GetJsInvokeExpression(eventData.Value.Name, eventData.Value.Parameters);
 
             output.Attributes.RemoveAll(HandlersPrefix + eventDefinition);
-            output.Attributes.Add(new TagHelperAttribute($"x-on:{eventDefinition}", new HtmlString($"invoke($event, {invokeData})"), HtmlAttributeValueStyle.SingleQuotes));
+            output.Attributes.Add(new TagHelperAttribute($"x-on:{eventDefinition}", new HtmlString(jsInvokeExpression), HtmlAttributeValueStyle.SingleQuotes));
 
             if (Disable || new[] { "click", "submit" }.Any(e => e.StartsWith(e)))
             {
                 output.Attributes.Add(new("data-loading-disable"));
             }
         }
     }
+
+    private static string GetJsInvokeExpression(string name, IDictionary<string, object> parameters)
+    {
+        var invokeJson = JsonConvert.SerializeObject(new
+        {
+            Name = name,
+            Parameters = parameters
+        }, JsonSettings.SerializerSettings);
+
+        var invokeJsObject = ExpressionExtensions.DecodeJsExpressionsInJson(invokeJson);
+
+        return $"invoke($event, {invokeJsObject})";
+    }
 }