IMPORTANT! This class is used with the latest ASP.NET web platforms. Use the Asp.RuleEditor class with classic ASP.NET WebForms and ASP.NET platform (.NET 4.5) and RuleEditor with classic ASP.NET MVC platform (.NET 4.5).

Provides core functionality for authoring and validating complex business rules in ASP.NET web applications.

Syntax

public partial class RuleEditor : CodeEffects.Rule.Models.IControl

Properties

• 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 the Rule Editor. Only rules of evaluation type should be added to this collection, which will 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 automatically includes 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 settings. This saves bandwidth. But sometimes developers need to explicitly exclude certain operators for existing data types. The following code sample demonstrates how to exclude the string operators startsWith, doesntStartWith, endsWith, and doesntEndWith:

  private RuleEditor GetRuleEditor()
  {
  	List<Operator> excludedOperators = new List<Operator>();
  
  	excludedOperators.Add(
  		new Operator
  		{
  			Type = OperatorType.String,
  			ExcludedOperator =
  				ExcludedOperator.StartsWith |
  				ExcludedOperator.DoesNotStartWith |
  				ExcludedOperator.EndsWith |
  				ExcludedOperator.DoesNotEndWith
  		});
  
  	// Use client ID of the DIV container
  	Code.Rule.Web.RuleEditor editor = new RuleEditor("divRuleEditor")
  	{
  		Mode = Common.RuleType.Execution,
  		SourceType = typeof(Patient),
  		Rule = Rule.Models.RuleModel.Create(typeof(Patient)),
  		ExcludedOperators = excludedOperators
  	};
  
  	return editor;
  }
  

• 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 the custom help, warning 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 default English Help XML document can be found here.

• HelpXmlFile Type: System.String

  Gets or sets the full path to the XML file that contains the custom Help XML. A copy of the default English Help XML document can be found here. You can use your own custom Help XML by replacing the built-in document if you'd like to change the default English messages, or if Rule Editor is used in a multilingual project.

• ID Type: System.String

  Gets or sets the ID of Rule Editor. This value must match the value of ID of the HTML DIV tag that hosts the editor on the client.

• IsEmpty Type: System.Boolean

  Gets the value indicating whether the Rule Area 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 the default). The RuleType.Evaluation value restricts rule authors to evaluation type rules only. The RuleEditor.Filter value sets Rule Editor up for data filtering. Other modes are available as well. See the Understanding Modes topic for details. The default value is RuleType.Evaluation.

• Rule Type: CodeEffects.Rule.Models.RuleModel

  Gets or sets an instance of the RuleModel, created on the server and passed down to the client. See demo projects for details of the use of this class.

• 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. Value of 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 Area. Element descriptions are optional. Developers can set them using the Description property of ActionAttribute, FieldAttribute, MethodAttribute, or ParameterAttribute respectively. The default value is True. Value of this property has no effect on rule evaluation.

• ShowHelpString Type: System.Boolean

  Gets or sets the value indicating whether Rule Editor should display the Help String located between the Toolbar and the Rule Area. The default value is True. Value of this property has no effect on rule evaluation.

• ShowLineDots Type: System.Boolean

  Gets or sets the value indicating whether Rule Editor should display a period char before each new line in the Rule Area. The default value is False. Value of this property has no effect on rule evaluation.

• ShowMenuOnElementClicked Type: System.Boolean

  Gets or sets the value indicating whether 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 elements, 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. Vaue of this property has no effect on rule evaluation.

• ShowMenuOnRightArrowKey Type: System.Boolean

  Gets or sets the value indicating whether 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. Value of this property has no effect on rule evaluation.

• ShowToolBar Type: System.Boolean

  Gets or sets the value indicating whether Rule Editor should display its Toolbar. The default value is True. Value of this property has no effect on rule evaluation.

• SourceType 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, SourceType, or SourceXmlFile properties. You can obtain the full name of the source object's assembly by executing Assembly.GetAssembly( SourceObjectType ).FullName.

• SourceTypeName 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, SourceType, 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.

• ToolBarRules Type: System.Collections.Generic.ICollection<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.

  

• UseHihestZindex Type: System.Boolean

  Gets or sets the value indicating whether the Rule Editor should calculate and use the highest zIndex for its pop-up elements such as menus, date pickers, and so on. Set this value to True only if your script dynamically adds other DOM elements that could potentially hide editor's menus. The default value is False.

Methods

• GetClientInvalidData() Returns: System.String
  Parameters: None

  Returns a JSON string containing an array of rule elements that failed rule validation. Certain client methods in the Client-Side API consume data supplied by this method. See demo projects for details on implementation of this methid.

• GetClientRuleData() Returns: System.String
  Parameters: None

  Returns a JSON string containing elements of the rule. Certain client methods in the Client-Side API consume data supplied by this method. See demo projects for details on implementation of this methid.

• GetClientSettings() Returns: System.String
  Parameters: None

  Returns a JSON string containing the source object members info that the Rule Editor needs in order to complete its initialization on page load. Pass the returned string to the loadSettings() method of the Client-Side API. See demo projects for implementation details of this methid.

• 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. You also use this string to load the rule into the Rule Editor for editing and deletion.

• GetInitialSettings() Returns: System.String
  Parameters: None

  Returns a JSON string containing the current environment info, UI messages and labels, mode info, and some other data that the Rule Editor needs in order to initialize itself after the page is loaded. Pass the returned string to the $rule.init() global method of the Client-Side API before initializing the Rule Editor. See demo projects for implementation details of this methid.

• GetSourceXml() Returns: System.String
  Parameters: None

  Returns a Source XML document. This method can 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 Rule Editor for further processing on the server. This method is used by the server-side code to deserialize the client data into the rule source. Download any of the demo projects to see Code Effects implemented in an Ajax 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 Rule XML document into the instance of the Rule Editor. After successfully loading, the rule can be viewed and modified.

• LoadRuleFile(System.String,CodeEffects.Rule.Core.GetRuleDelegate) 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.
  • ruleDelegate, CodeEffects.Rule.Common.GetRuleDelegate - A delegate that takes a rule ID and returns XML of that rule.

  Loads the XML file that contains 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 Rule XML document into the instance of the Rule Editor. After successfully loading, the rule can be viewed and modified.

• LoadRuleXml(System.String,CodeEffects.Rule.Core.GetRuleDelegate) 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.
  • ruleDelegate, CodeEffects.Rule.Common.GetRuleDelegate - A delegate that takes a rule ID and returns XML of that rule.

  Loads the XML string that contains 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.

• ToString(Dictionary<String, GetDataSourceDelegate>) Returns: System.String
  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.

• ToString(CodeEffects.Rule.Core.GetRuleDelegate) Returns: System.String
  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.

• ToString(CodeEffects.Rule.Core.GetRuleDelegate, Dictionary<String,GetDataSourceDelegate>) Returns: System.String
  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 and/or could contain fields from menu 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.