RuleEditor class

Namespace: CodeEffects.Rule.Asp
Assembly: CodeEffects.Rule.dll

Provides core functionality for authoring and validating complex business rules in a web client such as a web browser. Implemented as an ASP.NET server control.

Syntax

[DefaultProperty("SourceType")]
[AspNetHostingPermission(SecurityAction.Demand,
	Level = AspNetHostingPermissionLevel.Minimal)]
[AspNetHostingPermission(SecurityAction.InheritanceDemand,
	Level = AspNetHostingPermissionLevel.Minimal)]
[ToolboxData("<{0}:RuleEditor runat=\"server\"></{0}:RuleEditor>")]
[Designer(typeof(RuleEditorDesigner))]
[DesignTimeVisible(true)]
public class RuleEditor : System.Web.UI.WebControls.Panel,
	CodeEffects.Rule.Models.IControl

Events

  • 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 ASP.NET 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 ASP.NET 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 ASP.NET demo project.)

Properties

  • 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. See the client-side implementation and client-side API topics for details.

  • 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. Code Effects component 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, Code Effects 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.ruleControl.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 default English Help XML document used in version 4.x can be found here. You can replace the default Help XML with your own document:

    XmlDocument help = new XmlDocument();
    
    // Load your custom help form file...
    help.LoadFile("C:\Help\Custom.config");
    
    // ... or load it from XML string
    help.Load(customHelpXml);
    
    // Assign loaded Help XML to HelpXml property of the rule editor
    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 default English Help XML document used in version 4.x 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 Code Effects 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" 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. Code Effects component performs automatic validation every time a rule is submitted. If validation fails, the Rule Editor 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 Code Effects component 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 Code Effects component 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, Code Effects component 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 Code Effects component to render its UI in the browser.

  • SourceXmlFile Type: System.String

    Gets or sets the full path to the custom XML file that describes the source object. In Code Effects, this document is called Source XML. It's used by Code Effects component 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 files used by Code Effects 4.0 to render themes:

    • 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

    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.

Methods

  • 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 Code Effects. Certain client methods in the client-side API consume data supplied by this method. Download any of the demo projects to see Code Effects component 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 Code Effects. Certain client methods in client-side API consume data supplied by this method. Download any of the demo projects to see Code Effects 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 Code Effects. Certain client methods in the client-side API consume data supplied by this method. Download any of the demo projects to see Code Effects implemented in an 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, massages 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 default Help XML document used in version 4.x 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.

  • GetSaveArguments() Returns: CodeEffects.Rule.Asp.SaveEventArgs
    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. The client-side Implementation topic uses this method in one of its code samples.

  • 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:

    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 Code Effects component is used in a client-side application. Download any of the demo projects to see Code Effects 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.

  • 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<stringGetDataSourceDelegate> d =
    	new Dictionary<stringGetDataSourceDelegate>();
    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.

Post your support requests on Stackoverflow.com. You can also post your comments and product feedback using the form at the bottom of this page.
Comments: 0
Name (optional):
Comment (URLs are allowed and must start with http:// or https://; all tags will be encoded):
Remaining character count: