Initialization of the Rule Editor

The Rule Editor can be initialized on a web page in one of two ways:

  • Server-centric initialization
  • Client-centric initialization

Both are for a stand-alone Rule Editor: an editor that your page hosts and whose rules your application loads, saves and deletes itself. The Rule Repository (RR) initializes its editors on its own, so a page that shows RR uses neither of them; see Rule Editors in the Rule Repository at the end of this article for what you can set there instead.

The first approach is intended for applications that frequently change editor settings, such as source objects, UI options, current UI culture, or other server-generated configuration. Since those settings are already produced on the server, it often makes sense to perform the entire editor initialization there. This initialization method has been available since the first release of the Code Effects platform in 2009 and remains supported for backward compatibility.

The second approach is handled primarily by the client-side editor script. It requires only two pieces of data from the server, while all remaining settings can be configured directly by your client-side code.

Both approaches provide identical functionality. Ultimately, they both initialize the editor by calling the same $rule.init() method, differing only in the data passed to it. If the argument contains the globalData property, the editor uses the client-centric initialization. Otherwise, it expects the JSON string produced by the GetGlobalData() method (or an object whose d property holds that string, as the old ASP.NET web methods return it).

Server-Centric Initialization

First, initialize the server-side Control instance and obtain the two pieces of data required by the client. The following example comes from one of our demo projects and uses the Reflection source model:

using CodeEffects.Rule.Common.Models;
using CodeEffects.Rule.Editor;

public class Settings
{
	public string? GlobalData { get; set; }
	public string? EditorData { get; set; }
	public EvaluationMode Mode { get; set; } = EvaluationMode.Execution;
	
	// The editor supports many more settings.
	// This example uses only the most common ones.
	
	public bool Toolbar { get; set; } = true;
	public bool HelpString { get; set; } = true;
	public bool Dots { get; set; } = false;
}

public static class Api
{
	public static void MapEndpoints(this WebApplication app)
	{
		// Returns client settings for the editor
		app.MapGet("/api/settings", () =>
		{
			var settings = new Settings();
			var editor = GetControl(settings);
			
			// Set UI settings for the editor
			settings.GlobalData = editor.GetGlobalData();
			
			// Set source-related settings
			settings.EditorData = editor.GetEditorData();
			
			return Results.Ok(settings);
		});
	}
	
	private static Control GetControl(Settings settings)
	{
		// Pass the ID of the div element
		// that hosts the editor
		var editor = new Control("divEditor");
		
		// Use Reflection source model
		editor.SourceType = typeof(Patient);
		editor.EvaluationMode = settings.Mode;
		
		editor.ShowHelpString = settings.HelpString;
		editor.ShowToolBar = settings.Toolbar;
		editor.ShowLineDots = settings.Dots;
		
		return editor;
	}
}

The client-side implementation is intentionally simple:

// Declare editor as a global variable
var editor = null;

// Load settings
const res = await fetch(
	'/api/settings',
	{headers: {'Accept': 'application/json'}});
	
const settings = await res.json();

// Initialize the editor
editor = $rule.init(settings.globalData);

// Attach rule management callbacks
// (load, delete, save, and optionally notify).
// See the demo projects for their implementation.
editor.setCallbacks(load, remove, save);

// Load source-related settings
editor.loadSettings(settings.editorData);

// Only if the server's Control uses an Adaptive Source:
// give the editor the callback that requests its menus
editor.setAdaptiveSource(
	{
		menuCallback: menu,
		behavior: $rule.behavior.replace
	});

// Optional: a value that the editor sends to your server
// with every Adaptive Source menu request
editor.setRefData("Anything");

Adaptive Source in the Server-Centric Initialization

If the server's Control uses the Adaptive Source model (its SourceProvider property is set), the editor data tells the client so, but it cannot carry the client-side callback that requests the menus. Call the editor's setAdaptiveSource(..) function after loadSettings(..) and pass it the same object that the client-centric initialization passes as adaptiveSource: the menuCallback that sends the menu request to your server, and optionally behavior, min and max. Without it the editor cannot load its menus. The Adaptive Source article shows a menu() callback and the server endpoint that answers it.

For an editor that uses a Reflection source or Source XML, do not call setAdaptiveSource(..).

Reference Data in the Server-Centric Initialization

The editor can carry a value of your own, its reference data, and hand it back to you whenever it requests an Adaptive Source menu. Set it with the editor's setRefData(..) function after loadSettings(..). It is useful when your server needs to know something about this particular editor to build its menus, such as the customer, the project or the record the rule is for, without keeping that in a server session.

How the value travels:

  • The editor puts it in the context it passes to your menuCallback, as args.context.refData. Your callback sends that context to your server with the menu request, as the Adaptive Source example does.
  • On the server, the context arrives as a Context object, so the value is Context.RefData (a string). Control.GetAdaptiveData(..) passes the same object to the GetFieldsAndMethods(..) and GetSettersAndActions(..) methods of your ISourceProvider. Use a string, or serialize anything larger to one, such as a small JSON document.
  • It goes one way, from the editor to your server, and only with Adaptive Source menu requests. The editor does not add it to the rule it gives your save callback, and nothing your server returns changes it. To change it, call setRefData(..) again.

Call both functions again after every loadSettings(..). loadSettings(..) replaces all of the editor's settings, so it clears the Adaptive Source callback and the reference data that were set before it. This applies to an editor started by the client-centric initialization too, if your code calls loadSettings(..) on it later.

Client-Centric Initialization

The client-centric approach gives your client-side code complete control over editor initialization. The following example uses the Adaptive Source model from one of our demo project repos.

In this case, the Settings class is smaller because UI settings are configured on the client instead of the server. Likewise, the GetControl() method only needs to assign the source provider that implements the ISourceProvider interface and supplies dynamic menus while the user creates or updates rules.

The endpoint itself remains unchanged:

public class Settings
{
	public string? GlobalData { get; set; }
	public string? EditorData { get; set; }

	public EvaluationMode Mode { get; set; } =
		EvaluationMode.Execution;
}

private static Control GetControl(Settings settings)
{
	var editor = new Control();
	editor.SourceProvider = new PatientSourceProvider();
	editor.EvaluationMode = settings.Mode;
	
	return editor;
}

The client-side initialization is more flexible:

var editor = null;

const res = await fetch(
	'/api/settings',
	{headers: {'Accept': 'application/json'}});

const settings = await res.json();

// Initialize the editor
editor = $rule.init(
	{
		id: "divEditor",
		
		// Optional: a value that the editor sends to your
		// server with every Adaptive Source menu request
		refData: "Anything",
		showHelpString: true,
		showToolBar: true,
		globalData: settings.globalData,
		editorData: settings.editorData,
		saveRuleCallback: save,
		loadRuleCallback: load,
		deleteRuleCallback: remove,
		notifyCallback: info,
		
		// Passing the adaptiveSource object
		// instructs the editor to use the
		// Adaptive Source model.
		adaptiveSource:
			{
				menuCallback: menu,
				behavior: $rule.behavior.replace
			}
	});

In this example, the $rule.init() method receives a single settings object that controls the editor initialization. Every property of that object is documented in the Client-Side API Reference.

The client-centric initialization takes the Adaptive Source settings and the reference data directly: the adaptiveSource object replaces the setAdaptiveSource(..) call, and the refData property replaces the setRefData(..) call of the server-centric initialization. The reference data travels exactly as described in Reference Data in the Server-Centric Initialization: in args.context.refData of every menuCallback call, to Context.RefData on your server. Call setRefData(..) later to change it; with a Reflection source or Source XML the editor never requests menus, so it never sends the value.

Properties

The settings object that the client-centric initialization passes to $rule.init() has its own reference: see the properties of the settings parameter in $rule.init(..) on the codeeffects.editor.js page of the Client-Side API Reference.

Rule Editors in the Rule Repository

Every rule that RR shows is a Rule Editor, but RR creates and initializes these editors itself. Your page calls $repo.init(..) once, and RR does the rest. Compared with a stand-alone editor:

Stand-alone editor Editor inside RR
Who calls $rule.init(..) Your page, in one of the two ways above RR. Your code never calls it for RR's editors
GetGlobalData() and GetEditorData() Your server creates a Control and returns both Not used. RR's server library builds the editor's data from the stored source version the rule belongs to
Display settings Any property of $rule.init(..)'s settings object, or the Control's properties Only the five in the editor property of $repo.init(..): showHelpString, showLineDots, showDescriptionsOnMouseHover, showMenuOnElementClicked and showMenuOnRightArrowKey
Toolbar and the save, load and delete callbacks Yours to turn on and implement Never used. RR has no Toolbar in its editors and saves, loads and deletes rules itself
Adaptive Source adaptiveSource or setAdaptiveSource(..), with your menuCallback Not used. An Adaptive Source reaches RR only through source synchronization, and RR's editors always run on a stored version of the source object
Reference data refData or setRefData(..) Not used, since RR's editors request no Adaptive Source menus
Pop-up layering useHighestZindex, false by default Always on, because RR's editors live in its dialogs

The stylesheets are the same for both: see CSS Styles.

Ask on Stack Overflow - Yes, it's still active
Ask in GitHub Discussions

p102

l097 --

l102

p101

×