« Home

codeeffects.repository.js

Package

  • @codeeffects/repository - npm

    Files

    • codeeffects.repository.js
    • codeeffects.repository.common.css
    • codeeffects.repository.light.css
    • codeeffects.repository.dark.css

    Remarks

    This package is the client side of the Rule Repository (RR). You need it only if your application uses the Rule Repository .NET library and has its license. A stand-alone Rule Editor does not use it.

    RR is a self-contained web component. Given an empty element on your page, it draws everything inside it: the tabs, grids, filters, paging, sorting, dialogs, and the Rule Editor instances in which users create and change rules. RR keeps no data of its own. Whenever it needs something, such as a page of a grid, the options of a drop-down list, the details of a record, a save, or a delete, it builds a request, serializes it to a JSON string, and hands the string to a callback function that you provide. Your callback posts the string to your own Repository endpoint, which passes it to the Repository library on the server, and returns the JSON string that the library produces. RR never contacts a server by itself.

    The script is an ES module. It declares the CodeEffects.Rule.Repository namespace and exports it as $repo. Unlike the editor's $rule and $ce, $repo is not a global variable; the script adds nothing to the global object except the CodeEffects namespace itself. Reference it as a module script and read the namespace, or import $repo from the module:

      <script type="module" src="codeeffects.editor.js"></script>
  <script type="module" src="codeeffects.repository.js"></script>
  <script type="module" src="your-page.js"></script>

      // In your-page.js, which loads after both modules
  const $repo = CodeEffects.Rule.Repository;

  // Or, in a module that bundles the script
  import { $repo } from "./codeeffects.repository.js";

    Module scripts run in the order written once the page is parsed, so a script listed after the other two finds both in place.

    RR needs the Rule Editor script (codeeffects.editor.js) on the same page: every rule RR shows is a Rule Editor, and the date range filter draws the editor's calendar. The two scripts can be referenced in any order. Load the stylesheets of both packages: the common stylesheet and one of the light or dark themes for each.

    RR assumes the user is signed in to your application. It has no sign-in of its own, so the endpoint your callback posts to must require your application's sign-in. The Rule Storage in Rule Repository article describes what RR stores and how your application gets the live rules back.

Global Objects

  • $repo

    Type: (Object) - The CodeEffects.Rule.Repository namespace

    The module's shortcut for the CodeEffects.Rule.Repository namespace. Its public members are init(..), render(..), and notificationTypes.

  • $repo.notificationTypes

    Type: (Object) - Frozen

    The values that RR passes as the second argument of your notifyCallback.

      $repo.notificationTypes = Object.freeze(
  {
  	confirmation: "confirmation",
  	warning: "warning",
  	error: "error"
  });

Global Functions

  • $repo.init(..)

    Returns: (Object) - The handle of the mounted repository

    Mounts RR into the element you name and returns a handle to it. If RR is already mounted, the method disposes the current instance first.

    The method returns synchronously, but RR is not on the screen yet: it has to ask the server what to draw, and that takes a round trip. The ready property of the returned handle is a promise that resolves with the handle when RR is up and rejects if it could not start. RR also reports a failure to your notifyCallback.

    The method throws an error if no element with the given ID exists, if neither a requestCallback nor the legacy global callback is available when the first request is sent, or if the Trusted Types settings do not match the page's Content Security Policy (see useTrustedTypes).

    Parameters

    • options (Object) - The settings object described below. Optional in the sense that the method does not require every property, but requestCallback is needed for RR to work. For backward compatibility, a string is accepted and is taken as the value of id.

    Properties of the options object

    • id (String) - The ID of the element that RR takes over. RR looks for an element with divEditor if the property is missing. The method throws an error if the page has no such element.

    • requestCallback (Function) - Receives every request that RR makes and returns the answer. Required, unless the page declares the legacy global function ceRepositoryRequest. The callback may be synchronous or return a Promise.

      Parameters

      • json (String) - The request, as a JSON string. Do not change it. Post it as it is to your Repository endpoint.

      Returns

      The JSON string that your endpoint returned, or a Promise that resolves with it. An object that has already been parsed is accepted too.

      Example

        async function request(json)
  {
  	const res = await fetch(
  		'/api/repository',
  		{
  			method: 'POST',
  			headers: {'Content-Type': 'application/json'},
  			body: json
  		});

  	return await res.text();
  }

  const repository = $repo.init({
  	id: "divRepository",
  	requestCallback: request
  });

    • data (Object) - The answer to RR's first (Init) request, if your page has already fetched it together with its other data. RR then skips that round trip. Either the whole response or only its Record is accepted. Optional.

    • notifyCallback (Function) - Lets your page show RR's own on-screen messages in its own notification interface. Without it, RR shows them itself. Optional. The callback is not related to the Notify event of the server.

      Parameters

      • message (String) - Plain text. It can contain names and descriptions that users typed, so show it with textContent or the text binding of your UI library, never with innerHTML.
      • type (String) - One of the $repo.notificationTypes values.

      Remarks

      If your page shows a dialog over a rule editor that RR hosts, the dialog should stop the propagation of its clicks. Otherwise, the editor clears its highlighted invalid elements when the user answers the dialog.

    • defaultView (String) - The grid that RR shows first. One of sources, sourceVersions, rules, ruleVersions, drafts, tests, evaluations, and userActivity. Optional. Default value is rules. If the user's permissions do not include the view, RR shows the first grid the user can see.

    • pageSizes (Array) - The page sizes a user can choose in the grids. Optional. Default value is [5, 10, 25].

    • defaultPageSize (Integer) - The page size that RR starts with. It must be one of pageSizes, or RR uses the first one. Optional. Default value is 10.

    • mobileBreakpoint (Integer) - The width of the screen, in pixels, up to which RR switches to its phone layout. Optional. Default value is 640.

    • filterDelay (Integer) - The time, in milliseconds, that RR waits after the user stops typing in a filter before it requests the filtered rows. Optional. Default value is 250.

    • animations (Boolean) - Indicates whether RR animates its tabs, dialogs, and full view. The wait spinner is not affected. Optional. Default value is true.

    • locale (String) - A BCP 47 language tag. It changes only the dates that RR prints. Every other piece of text comes from the user interface XML, which the server translates. Optional. The default is the language of the browser.

    • help (Boolean) - Indicates whether RR shows links to the Code Effects documentation. Set it to false to hide all of them. Optional. Default value is true.

    • editor (Object) - Settings for every Rule Editor that RR opens. Optional. All properties are optional:

      • showHelpString (Boolean) - Default value is true.
      • showLineDots (Boolean) - Default value is false.
      • showDescriptionsOnMouseHover (Boolean) - Default value is true.
      • showMenuOnElementClicked (Boolean) - Default value is true.
      • showMenuOnRightArrowKey (Boolean) - Default value is true.

      See the properties of the same names in $rule.init(..). RR always runs its editors on a stored version of a source object, so it takes no Adaptive Source settings.

    • useTrustedTypes (Boolean) - Indicates whether RR passes its markup through a Trusted Types policy. Optional. Default value is false, and then RR never touches window.trustedTypes and writes plain strings. If your page enforces Trusted Types and this property is not true, $repo.init(..) throws an error that says so. RR never enforces Trusted Types itself; only the Content Security Policy of your page does.

    • trustedTypesPolicy (String) - The name of the Trusted Types policy that all of RR's markup goes through. RR reads it only when useTrustedTypes is true. Optional. Default value is codeeffects-repository. When the page enforces Trusted Types, its Content Security Policy must list the name in the trusted-types directive, otherwise $repo.init(..) throws an error that names it:

        require-trusted-types-for 'script'; trusted-types codeeffects-repository

      Use one name per page. The rule editor needs no policy of its own.

    Remarks

    The grids that a user sees, and what the user can do in them, are decided by the user's permission set alone. It arrives from the server in the answer to the first request, so no property of the options object widens or narrows it. The views and permissions properties of earlier builds are ignored.

    Example

      const repository = $repo.init({
  	id: "divRepository",
  	requestCallback: request,
  	notifyCallback: (message, type) => showToast(message, type),
  	defaultView: "rules",
  	editor: { showLineDots: true }
  });

  await repository.ready;

  • $repo.render(..)

    Returns: Nothing

    Draws the given view again from the server. Use the render(..) function of the handle returned by $repo.init(..) instead. This function remains for pages written against an earlier build, which have no handle.

    Parameters

    • viewType (String) - One of the view names listed under the defaultView property of $repo.init(..). The method throws an error for an unknown name.

Public Instance Functions

The $repo.init(..) method returns the following object.

  • ready

    Type: (Promise)

    A promise that resolves with the handle when RR is on the screen and rejects with the error if it could not start. Await it when your code needs to know that RR is up or why it is not.

  • dispose()

    Returns: Nothing

    Takes RR back off the page. It closes every dialog, disposes every Rule Editor that RR created, empties the hosting element, and removes the handlers that RR put on the document and on the window.

    A page that never removes the RR container never needs this function. A single-page application that swaps routes does, because RR keeps handlers on the document, and each rule editor keeps more.

  • refresh(..)

    Returns: (Object) - The handle

    Requests the view from the server again and draws it, keeping its filters, page, and sort order.

    Parameters

    • viewType (String) - A view name. Optional. If omitted, RR redraws the view on the screen.

  • render(..)

    Returns: (Object) - The handle

    Switches to the given view.

    Parameters

    • viewType (String) - A view name. Required. If the user's permissions do not include the view, RR shows the first grid the user can see.

Legacy Globals

An earlier build of RR mounted itself when the page loaded and read its settings from two global names. They are still read, so a page written against that build keeps working, but new code should use the properties of $repo.init(..) instead. Anything passed to $repo.init(..) wins over the globals.

  • ceRepositorySettings - A global object whose properties are the same as the options of $repo.init(..).
  • ceRepositoryRequest(json) - A global function used as the requestCallback when the options have none.

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

p102

l097 --

l102

p101

×