Provides core functionality for authoring and validating complex business rules in a web client such as a web browser. Implemented as an ASP.NET WebForms server control.
-
DeleteRule Delegate: CodeEffects.Rule.Asp.RuleEventHandler
Raised when the rule author clicks the Delete button on the Toolbar. Passes the instance of the RuleEventArgs class to its event handler. Commonly used to notify the calling code that the currently displayed rule needs to be deleted. This event is ignored if Rule Editor doesn't use the Toolbar (RuleEditor.ShowToolBar = False).
protected override void OnInit(EventArgs e)
{
base.OnInit(e);
if (this.ruleControl.ShowToolBar)
this.ruleControl.DeleteRule +=
new RuleEventHandler(this.DeleteRule);
}
private void DeleteRule(object sender, RuleEventArgs e)
{
try
{
// Delete the file of this rule
Storage.DeleteRule(e);
// Remove this rule from the ToolBarRules collection
Storage.RemoveRuleFromCollection(
this.ruleControl.ToolBarRules, e.RuleID);
// Also, remove this rule from the context menu
if ((bool)e.IsEvaluationTypeRule)
Storage.RemoveRuleFromCollection(
this.ruleControl.ContextMenuRules, e.RuleID);
// Clear the Rule Area
this.ruleControl.Clear();
// Notify the user
this.lblInfo.Text = "The rule was deleted successfully";
}
catch (RuleException ex)
{
this.lblInfo.Text = ex.Message;
}
}
(This is a code sample taken from the Classic ASP.NET WebForms demo project.)
-
LoadRule Delegate: CodeEffects.Rule.Asp.RuleEventHandler
Raised when the rule author selects one of the existing rules from the Rules menu on the Toolbar. Passes the instance of the RuleEventArgs class to its event handler. Commonly used to notify the calling code that the rule author requested that a certain rule be loaded into the Rule Area. This event is ignored if Rule Editor doesn't use the Toolbar (RuleEditor.ShowToolBar = False).
protected override void OnInit(EventArgs e)
{
base.OnInit(e);
if (this.ruleControl.ShowToolBar)
this.ruleControl.LoadRule +=
new RuleEventHandler(this.LoadRule);
}
private void LoadRule(object sender, RuleEventArgs e)
{
try
{
// Load Rule XML from storage as string XML
string ruleXml = Storage.LoadRuleXml(e);
// Load that string XML into the rule control
this.ruleControl.LoadRuleXml(ruleXml);
}
catch (RuleException ex)
{
this.lblInfo.Text = "Error loading the rule: " + ex.Message;
}
}
(This is a code sample taken from the Classic ASP.NET WebForms demo project.)
-
SaveRule Delegate: CodeEffects.Rule.Asp.SaveEventHandler
Raised when the rule author clicks the Save button on the Toolbar. Passes the instance of the SaveEventArgs class to its event handler. Commonly used to notify the code that the rule author needs to save the currently displayed rule and pass the rule's data to the handler. This event is ignored if Rule Editor doesn't use the Toolbar (RuleEditor.ShowToolBar = False). Note that validation of the rule is performed automatically; you only need to check the value of the RuleEditor.IsValid property:
protected override void OnInit(EventArgs e)
{
base.OnInit(e);
if (this.ruleControl.ShowToolBar)
this.ruleControl.SaveRule +=
new SaveEventHandler(this.SaveRule);
}
private void SaveRule(object sender, SaveEventArgs e)
{
// First check if the rule is empty or invalid
if(this.ruleControl.IsEmpty || !this.ruleControl.IsValid)
{
this.lblInfo.Text = "The rule is either empty or invalid.";
return;
}
// Save this rule as an XML file
Storage.SaveRule(e);
// Add this rule to the Rules menu in the Toolbar in order
// for the rule author to be able to load it for editing
Storage.AddRuleToCollection(
this.ruleControl.ToolBarRules,
e.RuleID,
e.RuleName,
e.RuleDescription);
Storage.SortRules(this.ruleControl.ToolBarRules);
// If it's an evaluation type rule, add it to the context menu
// in order for the rule author to be able to use it as a reusable rule
if (e.IsEvaluationTypeRule)
Storage.AddRuleToCollection(
this.ruleControl.ContextMenuRules,
e.RuleID,
e.RuleName,
e.RuleDescription);
// Notify the user
this.lblInfo.Text = "Rule was saved successfully";
}
(This is a code sample taken from the Classic ASP.NET WebForms demo project.)
-
CacheHelp Type: System.Boolean
Gets or sets the value indicating whether the Help XML document should be cached for faster retrieval. The default value is False.
-
CacheSource Type: System.Boolean
Gets or sets the value indicating whether the Source XML document should be cached for faster retrieval. The default value is False.
-
ClientOnly Type: System.Boolean
Gets or sets the value indicating whether the Rule Editor should instantiate itself as a pure JavaScript object to be used in client-side web application. The default value is False.
-
ContextMenuRules Type: System.Collections.Generic.ICollection<MenuItem>
Gets or sets the collection of reusable rules that will be added to the field context menu in Rule Editor. Only rules of evaluation type should be added to this collection, and such rules appear in the menu as if they were regular fields. It's up to the developer to decide which existing evaluation type rules (if any) should be added to the context menu. See the reusable rules topic for details.
-
DataSources Type: System.Collections.Generic.ICollection<DataSourceHolder>
Gets or sets the collection of named GetDataSourceDelegate delegates. Each delegate is represented in the collection by an instance of the DataSourceHolder class. See the customizable dynamic sources topic for details.
-
ExcludedOperators Type: System.Collections.Generic.ICollection<Operator>
Gets or sets a collection of operators that should be excluded from the Rule Editor. Rule Editor is smart enough to include all necessary operators based on data types used by the source object. For example, if your source object doesn't use the System.DateTime type, Rule Editor will exclude all date operators from the client-side data that it normally adds to the markup on page load, which saves bandwidth. But sometimes, developers need to explicitly exclude certain operators for existing data types. The following code sample demonstrates how to exclude string operators startsWith, doesntStartWith, endsWith, and doesntEndWith:
this.ruleEditorInstance.ExcludedOperators.Add(
new Operator
{
Type = OperatorType.String,
ExcludedOperator =
ExcludedOperator.StartsWith |
ExcludedOperator.DoesNotStartWith |
ExcludedOperator.EndsWith |
ExcludedOperator.DoesNotEndWith
});
-
GetRuleDelegate Type: CodeEffects.Rule.Core.GetRuleDelegate
Gets or sets a reference to a method that returns Rule XML by rule ID. This is a very important topic related to reusable rules, rule evaluation, and automatic rule validation. Make sure to read the GetRuleDelegate topic. IMPORTANT! If the value of this property is not set, Rule Editor does not perform the circular references check.
-
HelpXml Type: System.Xml.XmlDocument
Gets or sets the XmlDocument object that contains custom help and validation messages shown in the Help String, as well as all UI labels and values used by the Rule Editor on the client. In Code Effects, this document is called Help XML. A copy of the current default English Help XML document can be found here. You can replace the default Help XML with your own document:
XmlDocument help = new XmlDocument();
help.LoadFile("C:\Help\Custom.config");
help.Load(customHelpXml);
RuleEditor1.HelpXml = help;
-
HelpXmlFile Type: System.String
Gets or sets the full path to the XML file that contains the custom Help XML. A copy of the current default English Help XML document can be found here. You can use your own custom Help XML by replacing the built-in document in cases where you'd like to change the default English messages or where the Rule Editor is used in a multilingual project. To do that, first obtain the default XML document by calling RuleEditor.GetHelpXml(), then open the resulting string in any XML editor, edit any messages (but not node names or document structure), save the file, and load it with the rule editor:
RuleEditor1.HemlXmlFile = Server.MapPath("/Help/Custom.config");
IMPORTANT! You must use the OnInit or OnLoad event handlers of your Page in order to set the path to the custom Help XML file if you use Rule Editor as a client-only component (the ClientOnly property is set to True) and want to set the path programmatically. For example, the following code snippets, taken from our ASP.NET demo project, declare the "client-only" rule editor in HTML and set its custom Help XML in page's OnLoad event handler:
<%@ Page Title="" Language="C#" MasterPageFile="~/Common/Controls/Site.Master"
AutoEventWireup="true" EnableViewState="false" CodeBehind="Ajax.aspx.cs"
Inherits="CodeEffects.Rule.Demo.Bre.Asp.Ajax" %>
<%@ Register assembly="CodeEffects.Rule.Editor.Asp" namespace="CodeEffects.Rule.Asp"
tagprefix="rule" %>
<asp:Content ID="Content1" ContentPlaceHolderID="ContentPlaceHolder1"
runat="server">
... the rest of the page is omitted ...
<div style="margin-top:10px;">
<rule:RuleEditor ID="ruleControl" runat="server" ClientOnly="true"
Theme="White" />
</div>
... the rest of the page is omitted ...
</asp:Content>
using System;
using System.Web.UI;
using System.Web.Services;
namespace CodeEffects.Rule.Demo.Bre.Asp
{
public partial class Ajax : Page
{
protected override void OnLoad(EventArgs e)
{
base.OnLoad(e);
this.ruleControl.HelpXmlFile = @"C:\CustomHelp.xml";
}
[WebMethod(false)]
public static string LoadSettings()
{
// The method is omitted
}
// The rest of the class is omitted
}
}
-
IsEmpty Type: System.Boolean
Gets the value indicating whether the Rule Editor is empty (contains no rule elements).
-
IsValid Type: System.Boolean
Gets the value indicating whether the submitted rule passed automatic rule validation. Rule Editor performs automatic validation every time a rule is submitted. If validation fails, Rule Area highlights all invalid elements, and rule authors can hover the mouse over each invalid element to see the description of each problem. Those default English descriptions can be changed by altering the Help XML document.
-
KeepDeclaredOrder Type: System.Boolean
Gets or sets the value indicating whether the Rule Editor should alphabetically order fields and actions in menus or keep the order in which they are declared in the source object. The default value is False.
-
Mode Type: CodeEffects.Rule.Common.RuleType
Gets or sets the current mode of the Rule Editor. The RuleType.Execution value allows rule authors to create both evaluation and execution type rules (in this mode the evaluation type is default). The RuleType.Evaluation value restricts rule authors to evaluation type rules only. The RuleEditor.Filter value sets Rule Editor up for data filtering. The RuleEditor.Loop value evaluates a single execution type rule in a loop. The default value is RuleType.Evaluation.
-
RuleNameIsRequired Type: System.Boolean
Gets or sets the value indicating whether Rule Editor should require each rule to have a name when the rule author uses Toolbar to save or update a rule. The default value is True. This property is ignored if the RuleEditor.ShowToolBar is set to False. Setting this property has no effect on rule evaluation.
-
ShowDescriptionsOnMouseHover Type: System.Boolean
Gets or sets the value indicating whether the Rule Editor should display descriptions of actions, fields, in-rule methods, parameters of actions, or in-rule methods and reusable rules when the rule author hovers the mouse over those elements in the Rule Editor. Element descriptions are optional, and developers can set them using the Description property of the ActionAttribute, FieldAttribute, MethodAttribute, or ParameterAttribute respectively. The default value is True. Setting this property has no effect on rule evaluation.
-
ShowHelpString Type: System.Boolean
Gets or sets the value indicating whether the rule editor should display the Help String located between the Toolbar and the Rule Area. The default value is True. Setting this property has no effect on rule evaluation.
-
ShowLineDots Type: System.Boolean
Gets or sets the value indicating whether the Rule Editor should display a period before each new line in the rule. The default value is False. Setting this property has no effect on rule evaluation.
-
ShowMenuOnElementClicked Type: System.Boolean
Gets or sets the value indicating whether the rule editor should display the related context menu when the rule author clicks most rule elements. If True, this property allows rule authors to edit rule values, change fields, actions, operators, and so on "on the fly", simply by clicking an element and selecting a replacement value from the menu. If there are no suitable items, Rule Editor displays the menu for the next element (if any). The default value is True. Setting this property has no effect on rule evaluation.
-
ShowMenuOnRightArrowKey Type: System.Boolean
Gets or sets the value indicating whether the Rule Editor should show a context menu that lists the next possible elements of the rule every time the rule author presses the Right Arrow key while browsing the current rule using the keyboard. Setting this value to True eliminates the need to hit the Space Bar to bring up the menu every time the author needs to insert a new rule element. The default value is True. Setting this property has no effect on rule evaluation.
-
ShowToolBar Type: System.Boolean
Gets or sets the value indicating whether the Rule Editor should display its Toolbar. The default value is True. Setting this property has no effect on rule evaluation.
-
Source Type: System.Type
Gets or sets the type of the source object. This property is required if no value has been set for any of the SourceXml, SourceType, or SourceXmlFile properties.
-
SourceAssembly Type: System.String
Gets or sets the full name of the assembly that contains the source object declaration. This property is required if no value has been set for any of the SourceXml, Source, or SourceXmlFile properties. You can obtain the full name of the source object's assembly by executing Assembly.GetAssembly( SourceObjectType ).FullName.
-
SourceType Type: System.String
Gets or sets the full name of the source object type. This property is required if no value has been set for any of the SourceXml, Source, or SourceXmlFile properties. You can obtain the source object's full name by executing sourceObjectInstance.GetType().FullName.
-
SourceXml Type: System.Xml.XmlDocument
Gets or sets the XmlDocument that defines the structure of the source object. In Code Effects, this document is called Source XML. This document is used internally by Rule Editor to render its UI in the browser.
-
SourceXmlFile Type: System.String
Gets or sets the full path to the custom XML file that defines the source object. In Code Effects, this document is called Source XML. It's used by Rule Editor to render its UI in the browser.
-
Theme Type: CodeEffects.Rule.Common.ThemeType
Gets or sets the CSS theme of the Rule Editor. The default value is ThemeType.Gray. Setting the value of this property to ThemeType.None adds no theme to the page. Below is the list of all CSS themes that can be used with Rule Editor (if used, each theme requires the CodeEffects.Common.css file to be referenced on the page as well):
- Black - CodeEffects.Rule.Common.ThemeType.Black
- Blue - CodeEffects.Rule.Common.ThemeType.Blue
- Gray - CodeEffects.Rule.Common.ThemeType.Gray
- Green - CodeEffects.Rule.Common.ThemeType.Green
- Navy - CodeEffects.Rule.Common.ThemeType.Navy
- Red - CodeEffects.Rule.Common.ThemeType.Red
- White - CodeEffects.Rule.Common.ThemeType.White
- Common - CodeEffects.Rule.Common.ThemeType.Common
The appearance topic provides details on this subject.
-
ToolBarRules Type: System.Collections.Generic.ICollection<CodeEffects.Rule.Common.MenuItem>
Gets or sets the collection of existing rules that will be added to the Rules menu of the Toolbar. Adding rules to the Rules menu allows rule authors to select each rule in order to load it into the Rule Editor for editing or deletion. It's up to the developer which rules (if any) to add to this collection. This property is ignored if the ShowToolBar property is set to False.
-
Clear()
Returns: System.Void
Parameters: None
Removes all rule elements from the Rule Editor.
-
ClearCache()
Returns: System.Void
Parameters: None
Removes all Source XML and Help XML entries from the server's cache. Also see documentation on the related HelpXml, HelpXmlFile, SourceXml, and SourceXmlFile properties.
-
GetClientInvalidData()
Returns: System.String
Parameters: None
Returns a JSON string containing an array of rule elements that failed rule validation, and is used in client-side implementations of Rule Editor. Certain client methods in the client-side API consume data supplied by this method. Download any of the demo projects to see the Rule Editor implemented in client-side application.
-
GetClientRuleData()
Returns: System.String
Parameters:
None
Returns a JSON string containing elements of the rule, and is used in client-side implementations of Rule Editor. Certain client methods in client-side API consume data supplied by this method. Download any of the demo projects to see the Rule Editor implemented in client-side application.
-
GetClientSettings() Returns: System.String
Parameters: None
Returns a JSON string containing all client settings that the Rule Editor needs in order to instantiate itself on the page after the page is loaded in the client, and is used in client-side implementations of Rule Editor. Certain client methods in the client-side API consume data supplied by this method. Download any of the demo projects to see the Rule Editor implemented in a client-side application.
-
GetHelpXml() Returns: System.String
Parameters: None
Returns the current Help XML document as an XML string. Use this method if you'd like to obtain the default English Help XML used by your copy of Code Effects. You might want to do this if you'd like to use your own UI labels, messages and values in a multilingual project. See descriptions of the related HelpXml and HelpXmlFile properties for details on how to load modified Help XML documents. A copy of the current default English Help XML document can be found here.
-
GetRuleXml() Returns: System.String
Parameters: None
Returns a string that contains the XML document of the rule currently shown in the Rule Editor. Check the IsValid property to verify that the current rule is valid before calling this method, otherwise an InvalidRuleException will be thrown. Use the returned string to store the rule in a database as an XML type or in a file system as an XML file. This is the string that you pass to all evaluation classes to evaluate your rule, and you also use this string to load the rule into the Rule Editor for editing and deletion.
-
Parameters: None
Returns an instance of the SaveEventArgs type that contains details about the rule that is being saved. Calling this method outside the context of saving a rule (i.e., not in the SaveRule event handler) does not make sense because in that case it returns empty arguments.
-
GetSourceXml() Returns: System.String
Parameters: None
Returns the Source XML document. This method might be used to obtain the Source XML in order to edit it manually.
-
LoadClientData(System.String) Returns: System.Void
Parameters:
- ruleClientData, System.String - JSON string that contains the current rule.
Loads the rule into the server instance of Code Effects for further processing on the server. This method is used by the server-side code to deserialize the client data into the rule source when Rule Editor is used in a client-side application. Download any of the demo projects to see Rule Editor implemented in client-side application.
-
LoadRuleFile(System.String) Returns: System.Void
Parameters:
- ruleXmlFileFullPath, System.String - Full path to the file that contains the XML rule document. See the GetRuleXml() method for details on obtaining the Rule XML document.
Loads the XML file that contains the Rule XML document into the instance of the Rule Editor. After successfully loading, the rule can be viewed and modified.
-
LoadRuleXml(System.String) Returns: System.Void
Parameters:
- ruleXml, System.String - Rule XML document as a string. See the GetRuleXml() method for details on obtaining the Rule XML document.
Loads the XML string that contains the Rule XML document into the instance of the Rule Editor. After successfully loading, the rule can be viewed and modified.
-
ToString() Returns: System.String
Parameters: None
Returns a string representation of the current rule.
-
Parameters:
- dataSources,
System.Collections.Generic.Dictionary<System.String, CodeEffects.Rule.Common.GetDataSourceDelegate> - A dictionary of Dynamic Menu Data Sources.
Returns a string representation of the current rule. Takes a dictionary of data sources in order to retrieve the proper display names if the current rule uses items of those sources as field values or action parameters. See the description of the last ToString() overload for details.
-
Parameters:
- ruleDelegate, CodeEffects.Rule.Common.GetRuleDelegate - A delegate that takes a rule ID and returns the XML of that rule.
Returns a string representation of the current rule. Takes the delegate that returns Rule XML by rule ID in order to get the proper display names of all reusable rules that the current rule might reference. See the description of the last ToString() overload for details.
-
Parameters:
- ruleDelegate, CodeEffects.Rule.Common.GetRuleDelegate - A delegate that takes a rule ID and returns the XML of that rule.
- dataSources,
System.Collections.Generic.Dictionary<System.String, CodeEffects.Rule.Common.GetDataSourceDelegate> - A dictionary of Dynamic Menu Data Sources.
Returns a string representation of the current rule. This overload "combines" the previous two.
Imagine that we have a source object that declares a couple of dynamic data sources:
[Data("Education", typeof(Utility), "GetEducationTypes")]
[Data("Physicians", typeof(Physician), "ListPhysicians")]
public class Patient
{
// The rest of the class declaration is omitted
}
Next, imagine that we also have a method that has a signature of GetRuleDelegate:
private string GetRuleXml(string ruleID)
{
return MyStorage.GetRuleById(ruleID);
}
To have the Rule Editor display a rule that implements our source object, we could write the following statement in order to get the string representation of that rule:
Dictionary<string, GetDataSourceDelegate> d =
new Dictionary<string, GetDataSourceDelegate>();
d.Add("Education", new Utility().GetEducationTypes);
d.Add("Physicians", Physician.ListPhysicians);
string ruleString = this.ruleControl.ToString(GetRuleXml, d);
The GetEducationTypes is an instance method of some Utility class. We have to get an instance of that class in order to use the method. The ListPhysicians is a static method of a Physician class.
The reason why we had to go through all that hassle in order to get a string is because our imaginary rule could reference any number of reusable rules or could contain field values that were selected by the rule author from those data sources used by our source object. If you're sure that your rule doesn't use dynamic data sources and does not reference any other rules (or all your rules are stored in the same ruleset file), then simply use the plain ToString overload to get the rule's string.