RegorConfig

Overview

The RegorConfig class is used to configure and customize the behavior of the Regor library. It provides options for setting directives, global context, and other configuration parameters.

Try it live

import { html, ref, RegorConfig, type PropValidationMode } from 'regor'

export function createConfiguration(interactive = false) {
  const config = new RegorConfig()
  const policy = ref<PropValidationMode>('throw')
  const applied = ref(config.propValidationMode)
  const apply = () => {
    config.propValidationMode = policy()
    applied(config.propValidationMode)
  }
  return { interactive, config, policy, applied, apply }
}

export const configurationTemplate = html` <div
  class="guide-demo guide-demo--split"
>
  <div class="guide-controls">
    <label for="config-policy">Prop validation policy</label
    ><select id="config-policy" r-model="policy" :disabled="!interactive">
      <option value="throw">throw</option>
      <option value="warn">warn</option>
      <option value="off">off</option></select
    ><button type="button" @click="apply" :disabled="!interactive">
      Apply to this instance
    </button>
  </div>
  <div class="guide-readout">
    <span class="guide-kicker">LOCAL REGORCONFIG</span
    ><output class="directive-output" role="status">{{ applied }}</output>
    <p>
      The browser mount passes this instance to createApp. The page's other apps
      keep their own configuration.
    </p>
  </div>
</div>`

import { createApp, RegorConfig, useScope } from 'regor'
import { apiExamples } from './examples'

const element = document.getElementById('api-demo')
const name = element?.dataset.example
if (element && name && Object.hasOwn(apiExamples, name)) {
  const example = apiExamples[name as keyof typeof apiExamples]
  const scope = useScope<object>(() => example.create(true))
  const config =
    'config' in scope.context && scope.context.config instanceof RegorConfig
      ? scope.context.config
      : undefined
  createApp(scope, { element, template: example.template }, config)
}

Usage

The RegorConfig class is typically used to create a configuration object that can be passed to Regor during initialization. You can customize various aspects of Regor's behavior using this configuration.

Example

import { RegorConfig } from 'regor'

// Create a new RegorConfig with custom global context
const config = new RegorConfig({
  customGlobalFunction: () => {
    // Your custom global function logic here
  },
  // ...other global variables
})

// Use the custom configuration when creating a Regor app
const app = createApp(context, template, config)

Constructor

The RegorConfig constructor allows you to create an instance of the RegorConfig class with optional initial configuration options.

Parameters

• globalContext (optional): A custom global context object that can be used to define global variables and functions accessible within Regor templates.

Properties

globalContext (Record<string, any>)

This property holds the global context object, which can be used to define global variables and functions accessible within Regor templates. You can customize this context during configuration.

useInterpolation (boolean)

• Default: true

This property controls whether Regor should enable interpolation for data binding. When set to true, Regor will automatically perform data binding using the {{ }} syntax in templates. Interpolation also supports the [[ ]] syntax.

propValidationMode ('throw' | 'warn' | 'off')

• Default: 'throw'

Controls how head.validateProps(...) behaves when a validator fails.

• 'throw': throw immediately on invalid prop
• 'warn': forward the validation failure to warningHandler.warning(...) and continue
• 'off': disable runtime prop validation

Example:

import { RegorConfig, createApp } from 'regor'

const config = new RegorConfig()
config.propValidationMode = 'warn'

createApp(appContext, template, config)

Methods

addComponent(...)

This method allows you to register components with Regor. Components are reusable elements that can be used in your templates. You can pass one or more components to this method for registration.

Parameters

• components (Array) - One or more component objects to register.

Example

import { RegorConfig } from 'regor'
import { MyComponent1, MyComponent2 } from './components'

const config = new RegorConfig()

// Register custom components
config.addComponent(MyComponent1, MyComponent2)

setDirectives(prefix: string)

This method allows you to set the prefix for directives used in Regor templates. Directives are special attributes or bindings that control how elements behave in the template.

Parameters

• prefix (string) - The prefix string to use for directives. For example, setting it to 'r-' would make directives look like r-for, r-bind, etc.

Example

import { RegorConfig } from 'regor'

const config = new RegorConfig()

// Set custom directive prefix
config.setDirectives('r-')

updateDirectives(updater: (directiveMap: Record<string, Directive>, builtInNames: Record<string, string>) => void)

This method allows you to update the directives used in Regor templates by providing a custom updater function. The updater function receives two arguments: directiveMap and builtInNames, which represent the current directive mapping and built-in directive names.

Parameters

• updater (Function) - A function that takes two arguments: directiveMap and builtInNames. You can use this function to modify the directive mapping and built-in names.

Example

import { RegorConfig } from 'regor'

const config = new RegorConfig()

// Update directives with a custom updater function
config.updateDirectives((directiveMap, builtInNames) => {
  // Customize the directive map or built-in names here
})

Default Configuration

The RegorConfig class provides default configuration values for various properties and options. These defaults are used if no custom configuration is provided.

Notes

• The RegorConfig class allows you to fine-tune Regor's behavior to match your specific application requirements.

• You can customize global context variables and functions to make them available in Regor templates.

• The useInterpolation property enables or disables the use of {{}} syntax for data binding in templates.

• Interpolation supports both {{ }} and [[ ]] syntaxes.

• The propValidationMode property controls whether component prop validation throws, warns, or is disabled.

• Registering custom components using addComponent makes those components available for use in your Regor templates.

• The setDirectives method allows you to set a custom prefix for directives used in your templates.

• The updateDirectives method provides a way to modify the directive mapping and built-in names used by Regor, allowing for advanced customization.

See Also

Back to the API list