The Client

The Rule Repository's user interface runs in the browser. Your page gives it one empty element and one function that forwards its requests to your endpoint; RR draws everything else inside that element: the tabs, grids, filters, dialogs and Rule Editors. This page explains what the page needs, how to start RR on it, and what you can adjust.

You need a page because RR is a web component, not a separate site. It can be a dedicated page in a new application, a page in an existing administration area, a Razor view, a WebForms page, or a route in a React, Angular or Vue application.

The Files

RR needs the files of both browser packages, because every rule RR shows is a Rule Editor:

Package	Files
`@codeeffects/editor`	`codeeffects.editor.js`, `codeeffects.editor.common.css`, `codeeffects.editor.light.css`, `codeeffects.editor.dark.css`
`@codeeffects/repository`	`codeeffects.repository.js`, `codeeffects.repository.common.css`, `codeeffects.repository.light.css`, `codeeffects.repository.dark.css`

Install them from npm, or copy them into your static files folder (wwwroot in ASP.NET Core). Serve them from your own site; RR loads nothing from anywhere else.

A Complete Page

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Business Rules</title>

	<link rel="stylesheet" href="/lib/codeeffects/codeeffects.editor.common.css">
	<link rel="stylesheet" href="/lib/codeeffects/codeeffects.editor.light.css">
	<link rel="stylesheet" href="/lib/codeeffects/codeeffects.repository.common.css">
	<link rel="stylesheet" href="/lib/codeeffects/codeeffects.repository.light.css">
	<link rel="stylesheet" href="/css/site.css">
</head>
<body>
	<div id="rules"></div>

	<script type="module" src="/lib/codeeffects/codeeffects.editor.js"></script>
	<script type="module" src="/lib/codeeffects/codeeffects.repository.js"></script>
	<script type="module" src="/js/rules-page.js"></script>
</body>
</html>

// /js/rules-page.js: runs after both Code Effects modules, because module scripts run in the order written
const $repo = CodeEffects.Rule.Repository;

const repository = $repo.init({
	// The element RR takes over
	id: "rules",

	// Every request RR makes goes through here: post it to your endpoint and return the answer
	requestCallback: async (requestJson) => {
		const response = await fetch("/api/rules", {
			method: "POST",
			headers: { "Content-Type": "application/json" },
			credentials: "same-origin",
			body: requestJson
		});
		if (!response.ok) throw new Error("The rules endpoint returned HTTP " + response.status + ".");
		return await response.text();
	},

	// Optional settings
	defaultView: "rules",
	editor: { showLineDots: true }
});

// The handle comes back at once; RR is ready one round trip later
repository.ready.then(() => console.log("Rule Repository is ready"));

That is the whole client-side integration. requestCallback receives the request as a string and must return the response string (or a promise of it). It may add headers your application needs, such as an antiforgery header of your own framework, or a bearer token if your site uses one.

In a bundled application, import instead of reading the namespace:

import "./codeeffects.editor.js";
import { $repo } from "./codeeffects.repository.js";

The Options

Option	Default	What it decides
`id`	(required)	The element RR fills.
`requestCallback`	(required)	The function that forwards requests to your endpoint.
`notifyCallback`	`null`	Shows RR's on-screen messages in your own notification component instead of RR's. Receives `(message, type)`; show `message` as text, never as HTML, because it can contain names users typed.
`defaultView`	`"rules"`	The grid shown first: `sources`, `sourceVersions`, `rules`, `ruleVersions`, `drafts`, `tests`, `evaluations` or `userActivity`. A grid the user may not see falls back to the first one they may.
`pageSizes`, `defaultPageSize`	`[5, 10, 25]`, `10`	Grid page sizes.
`mobileBreakpoint`	`640`	The width, in pixels, up to which RR uses its phone layout.
`filterDelay`	`250`	Milliseconds RR waits after typing in a filter before it asks the server.
`animations`	`true`	Animations of tabs, dialogs and the full view.
`locale`	the browser's	The language tag used for the dates RR prints. All other text comes from the server's user interface text.
`help`	`true`	Links to the Code Effects documentation inside RR. Set `false` to hide them all.
`editor`		Settings for every Rule Editor in RR: `showHelpString`, `showLineDots`, `showDescriptionsOnMouseHover`, `showMenuOnElementClicked`, `showMenuOnRightArrowKey`.
`useTrustedTypes`, `trustedTypesPolicy`	`false`, `"codeeffects-repository"`	For pages that enforce Trusted Types. See Security.
`data`		The answer to RR's first request, if your page already has it; saves one round trip.

The full reference is codeeffects.repository.js.

What is not an option: which grids and buttons a user sees. That comes from the user's permissions on the server, never from the page, so a user cannot widen it by changing the page.

The Handle

$repo.init returns a handle:

Member	Use
`ready`	A promise that resolves when RR has loaded its first data.
`render(view)`	Switches to a grid, such as `render("tests")`.
`refresh(view)`	Draws a grid again from the server, keeping its filters, page and sort; with no argument, the grid showing.
`dispose()`	Removes RR and its document-level handlers. Call it in a single-page application before you remove RR's element (for example, when the route changes).

Size and Layout

RR fills the width of its element; place the element where it has room, usually the main content area of your layout.
RR takes its font family and size from the element you mount it into, so it matches your page. Set font-size on that element to make all of RR larger or smaller.
Below 1,400, 1,100 and 760 pixels of width RR moves its tabs and filters into menus and hides less important columns; up to mobileBreakpoint it uses a phone layout.
Dialogs open over the whole window. Keep transform, filter and a z-index of your own off the elements that contain RR, or the dialogs can be confined or hidden.

Themes, fonts and every style you can change are covered in CSS Styles.

In Different Front Ends

Razor Pages, MVC views, WebForms pages: put the element, the links and the three script tags in the page or its layout section, exactly as in the example.
React: render an empty div with a fixed id, call $repo.init in an effect after it mounts, and call dispose() in the effect's cleanup.
Angular and Vue: the same, in ngAfterViewInit / ngOnDestroy or mounted / unmounted.

One RR is on a page at a time: calling $repo.init again removes the previous one first.

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

p102

l107

l097 --