|
|
Registering custom macro methods |
|
|
|
|
|
Registering custom macro methods |
|
|
|
|
|
|
Registering custom macro methods |
|
|
|
|
|
Registering custom macro methods |
|
|
|
|
|
|
||
Besides the default methods that can be used in data macros, it is also possible to define custom methods that could be used in macro expressions. An example of such a custom method is located in the ~\App_Code\Samples\Classes\CustomMacroMethods.cs class. The following points summarize what has to be done to implement such a custom method and demonstrates it on the code used in the above mentioned class.
1. Implement all overloads of the custom method.
public static string MyMethod(string param1) { return MyMethod(param1, "default"); }
public static string MyMethod(string param1, string param2) { return param1 + " " + param2; } |
2. Create a wrapper for the method that is suitable for MacroResolver. When creating a wrapper for any custom method, its signature and return type must be exactly the same as shown below.
public static object MyMethod(params object[] parameters) { switch (parameters.Length) { case 1: return EcommerceFunctions.MyMethod(ValidationHelper.GetString(parameters[0], ""));
case 2: return EcommerceFunctions.MyMethod(ValidationHelper.GetString(parameters[0], ""), ValidationHelper.GetString(parameters[1], ""));
default: throw new NotSupportedException(); } } |
3. Add a method for registration of the new method using MacroMethods.RegisterMethod. Its parameters are the following:
•1. parameter: Method name.
•2. parameter: Method delegate (wrapper method).
•3. parameter: Return type of the method.
•4. parameter: Comment for the method used in macro autocompletion.
•5. parameter: Formatting string for "human readable" translation of the method call (optional, you do not have to specify).
•6. parameter: Minimal number of parameters needed to call the method (mimimal overload).
•7. parameter: Parameter definition in format {{name, type, comment}, {name, type, comment}, ...}.
•8. parameter: A list of special parameters needed to be supplied by resolver (these parameters are automatically passed by MacroResolver as the first parameters to the wrapper method).
•9. parameter: List of types for which the method is applicable (set to null for all types to be allowed). When not specified, the method will be applicable to the type of its first parameter.
•10. parameter: Code snippet which is used in macro autocompletion when TAB is pressed (to determine cursor position, use the pipe character |).
As you can see in the code below, the method is registered twice. At first, it is registered as a standard method with a comment and parameter descriptions for use in macro autocompletion. The second registration registers the method with the MyMethod(ToLower(CurrentDocument.DocumentName), |); code snippet. The | character indicates that the cursor will be at the position of the second parameter when the code snippet is inserted.
public static void RegisterMethods() { MacroMethods.RegisterMethod("MyMethod", MyMethod, typeof(string), "Returns concatenation of two strings.", null, 1, new object[,] { { "param1", typeof(string), "First string to concatenate." }, { "param2", typeof(string), "Second string to concatenate." } }, null);
MacroMethods.RegisterMethod("MyMethodSnippet", MyMethod, typeof(string), "Calls MyMethod on lower case current user name.", null, 0, null, null, new List<Type>() { typeof(string) }, "MyMethod(ToLower(CurrentDocument.DocumentName), |);", false); } |
4. Finally, ensure execution of the RegisterMethods method implemented in the previous step in the Init() method in the CMSModuleLoader partial class. In case of the mentioned example, there is a commented line ensuring this in the Init() method in ~\App_Code\Samples\Modules\SampleMacroModule.cs.
public override void Init() { // -- Custom macro methods CustomMacroMethods.RegisterMethods(); } |
5. The method is now registered and ready to be used. To verify this, try e.g. creating a new transformation and using a macro in its text. The new method should be offered in the autocompletion box if you try to apply it to a string parameter. As you can see in the screenshot below, the second parameter in the method signature — String param2 — is displayed in italic letters. This means that the method is overloaded and this parameter is optional and only present in the overload. You should also see the MyMethodSnippet method below the one mentioned above. Selecting this one inserts the defined code snippet.
