The purpose of the Toolbar is to give rule authors an easy-to-use UI for basic rule management: creating, editing, and deleting rules. It can also be used to select (load) an existing rule, and to name and describe new or existing rules.
The Toolbar does not store your rules anywhere, nor does it delete or update them in their physical location. Instead, it gives you, the developer, the rule's data every time a rule author wants to work with that rule. Upon receiving that data, you must decide where to store the rule, where to load it from, and whether the current rule author has the right to perform any action on that rule.
The Toolbar is shown by default in every mode of the Rule Editor except Filter, where it is hidden by default and a rule needs no name. To remove it, set the Control.ShowToolBar property to false; to show it in Filter mode, set the property to true. If you hide the Toolbar but still need to manage rules, you must implement your own controls, such as Save and Load buttons, and connect them with your server-side code. Hiding the Toolbar also makes the rule name optional: rules no longer need a name to be valid, and the editor ignores Control.ToolBarRules and Control.RuleNameIsRequired.
If shown, the Toolbar always appears on top of the Rule Area. It consists of five UI elements, described below. The Toolbar's labels, hints, and messages come from Help XML, so you can change or translate any of them.
The Rules menu provides options to create new rules and to load existing ones. The number of options to create new rules, and their labels, depend on the Control.EvaluationMode property:
Evaluation (the default): one option, New rule.... The new rule is of evaluation type.Filter, when you show the Toolbar there: one option, New filter.... The new rule is of evaluation type. In this mode the editor uses the filter wording of Help XML, such as "Get records where..." instead of "Check if...".Execution: two options, New execution type rule... and New evaluation type rule.... The new rule is of execution or evaluation type, as selected.Loop or Ruleset: one option, New rule.... The new rule is of execution type.
Selecting a new rule option clears the Rule Area, the Name and Description boxes, and the Delete button, and starts a new rule of the corresponding type. It is important to understand the Rule Editor's modes and how they operate.
You can also add existing rules to this menu so that rule authors can load them for editing. It is entirely up to you to decide which rules to include, as long as they correlate with the current value of Control.EvaluationMode. You can include any type of rule when the mode is Execution. However, the Rule Editor refuses to load an execution type rule while the mode is Evaluation (the default): it shows the notification "This rule cannot be loaded using the current Mode" instead. Most of our demo projects demonstrate how to fill the Rules menu.
Control.ToolBarRules is the property that must be populated for existing rules to appear in the Rules menu. It is an ICollection<MenuItem>. Each MenuItem needs an ID and a DisplayName, and the menu shows the display name. The item's Description property is not used by this menu.
using System.Collections.Generic;
using CodeEffects.Rule.Common.Models;
using CodeEffects.Rule.Editor;
using CodeEffects.Rule.Editor.Models;
var editor = new Control
{
ID = "divEditor",
SourceType = typeof(Patient),
EvaluationMode = EvaluationMode.Evaluation,
ToolBarRules = new List<MenuItem>
{
new MenuItem("6f9619ff-8b86-d011-b42d-00c04fc964ff", "Allergies check"),
new MenuItem("a7b3e8d4-52c1-4c1f-9a3e-0e5f6d1c2b77", "Senior discount")
}
};
When a rule author selects one of these rules, the Rule Editor calls your client-side load callback with the rule's ID. Your code gets the rule from its storage and passes it to the editor.
Name Box
Rule authors can name rules by typing the name into the Name box. The box holds up to 50 characters. The name is stored in Rule XML and it is also what the Rules menu shows for the rule.
By default, the name is required in every mode except Filter. A rule submitted without a name is reported as invalid, and the Name box shows Required field. Set Control.RuleNameIsRequired to false to make the name optional. The hint shown in the empty box is the ruleDefaultName label of Help XML.
Description Box
Rule authors can also give a rule a short description in the Description box. This field is optional and holds up to 80 characters. The description is stored in Rule XML with the name. The hint shown in the empty box is the ruleDefaultDescription label of Help XML.
The Rule Editor does not show the Toolbar's rule descriptions in the Rules menu. It shows the descriptions of reusable rules in a rule when the author hovers over the reusable rule in the Rule Area, if Control.ShowDescriptionsOnMouseHover is true, which is the default.
The Save button notifies your code that the current rule needs to be saved. The Rule Editor does not save the rule, because it has no knowledge of the infrastructure or systems that process your rules. Instead, it calls your client-side save callback. Your code retrieves the rule with the editor's extract() function, which returns it as a JSON string in the editor's own format, and sends it to your server. There, the server-side editor reads it with Control.LoadRuleData(..), checks that it is valid, and turns it into Rule XML for storage. It is up to you how to handle that data.
An empty rule cannot be saved. If the Rule Area holds no rule, the editor shows the notification "You cannot submit an empty rule." and does not call your code.
After your code has stored the rule, call the editor's saved(id, name) function. It adds a new rule to the Rules menu, or updates the name of an existing one, keeps the menu sorted by name, adds the Delete button to the Toolbar, and, for an evaluation type rule, adds it to the editor's list of reusable rules. See the client-side API for details.
The Delete button notifies your code that the rule author wants to delete the currently loaded rule. As with every other part of the Toolbar, the Rule Editor does not and cannot delete your rules. It tells your code which rule the user wants to delete.
This button appears only when a rule that has an ID is in the Rule Area: a rule loaded from your storage, or a new rule after you have called saved(id, name). Starting a new rule, or calling clear(), removes the button. When the author clicks it, the browser first shows a confirmation dialog with the warning that other rules that reference the rule may be affected and that the action cannot be undone. The text comes from Help XML. Only after the author confirms does the editor call your client-side delete callback with the rule's ID.
After your code has deleted the rule, call the editor's deleted(id) function to remove the rule from the Rules menu and from the list of reusable rules.
The three callbacks are passed to $rule.init() when the editor is created. They can also be set later with the editor's setCallbacks() function.
const editor = $rule.init({
id: "divEditor",
globalData: settings.globalData,
editorData: settings.editorData,
// Save: the callback has no parameters; read the rule with extract()
saveRuleCallback: async function ()
{
const rule = editor.extract();
const saved = await postRule(rule); // your code; returns the rule's ID and name
editor.saved(saved.id, saved.name);
},
// Load: called with the ID of the rule picked in the Rules menu
loadRuleCallback: async function (id)
{
editor.loadRule(await getRule(id)); // your code
},
// Delete: called with the ID of the loaded rule, after the author confirms
deleteRuleCallback: async function (id)
{
await removeRule(id); // your code
editor.deleted(id).clear();
}
});
The three functions are required when the Toolbar is shown. If you hide it, they are optional. See client-side initialization for all options, including notifyCallback, which receives the editor's own notifications.
Please refer to our demo projects for details on implementing particular features described in this article.