Wagtail client-side components
    Preparing search index...

    Class RulesController

    Adds the ability for a controlled form element to conditionally enable or show targeted elements based on the data from the controlled form along with a set of rules to match against that data.

    <form data-controller="w-rules" data-action="change->w-rules#resolve">
      <select name="fav-drink" required>
        <option value="">Select a drink</option>
        <option value="coffee">Coffee</option>
        <option value="other">Other</option>
      </select>
      <button type="button" data-w-rules-target="enable" data-w-rules='{"fav-drink": ["coffee"]}'>
        Continue
      </button>
    </form>

    <form data-controller="w-rules" data-action="change->w-rules#resolve">
      <select name="fav-drink" required>
        <option value="">Select a drink</option>
        <option value="coffee">Coffee</option>
        <option value="other">Other</option>
      </select>
      <input type="text" name="other-drink" data-w-rules-target="show" data-w-rules='{"fav-drink": ["other"]}'>
    </form>

    - Use match to apply different sets of rules
    <form data-controller="w-rules" data-action="change->w-rules#resolve">
      <input type="file" id="avatar" name="avatar" accept="image/png, image/jpeg">
      <input type="email" id="email" name="email" required>
      <output name="summary" for="file email">
        <span data-w-rules='{"avatar": [""], "email": [""]}' data-w-rules-match="not" data-w-rules-target="show">Your profile details are ready.</span>
        <span data-w-rules='{"avatar": [""], "email": [""]}' data-w-rules-match="any" data-w-rules-target="show">Your profile details are missing.</span>
      </output>
    </form>

    Hierarchy

    Index

    Constructors

    constructor

    Properties

    context enableTargets formCache hasEnableTarget hasShowTarget matchValue rulesCache showTargets blessings outlets targets values

    Accessors

    application classes data effectHandlers effectTargets element form identifier matchers outlets scope targets shouldLoad

    Methods

    connect disconnect dispatch enableTargetConnected enableTargetDisconnected getMatchType initialize parseRules resolve showTargetConnected showTargetDisconnected afterLoad

    Constructors

    • Parameters

      • context: Context

      Returns RulesController

    Properties

    context: Context
    enableTargets: FormControlElement[]

    Targets will be enabled if the target's rule matches the scoped form data, otherwise will be disabled.

    formCache: HTMLFormElement | null
    hasEnableTarget: boolean

    True if there is at least one enable target, used to ensure rules do not run if not needed.

    hasShowTarget: boolean

    True if there is at least one show target, used to ensure rules do not run if not needed.

    matchValue: Match

    The matching strategy to use for the rules, defaults to all and used as the fallback if not provided.

    rulesCache: Record<string, RuleEntry[]>
    showTargets: HTMLElement[]

    Targets will be shown if the target's rule matches the scoped form data, otherwise will be hidden with the hidden attribute.

    blessings: (<T>(constructor: Constructor<T>) => any)[]
    outlets: string[]
    targets: string[] = ...
    values: { match: { default: Match; type: StringConstructor } } = ...

    Accessors

    • get application(): Application

      Returns Application

    • get classes(): ClassMap

      Returns ClassMap

    • get data(): DataMap

      Returns DataMap

    • get effectHandlers(): Record<Effect, EffectHandler>

      Effect handlers to first determine if the effect needs to be applied, if it does, it will return a function to apply the effect.

      Returns Record<Effect, EffectHandler>

    • get element(): ElementType

      Returns ElementType

    • get identifier(): string

      Returns string

    • get matchers(): Record<Match, (rules: RuleEntry[]) => boolean>

      Returns an object of match functions that will be used to match against the current state of the form data.

      Returns Record<Match, (rules: RuleEntry[]) => boolean>

    • get outlets(): OutletSet

      Returns OutletSet

    • get scope(): Scope

      Returns Scope

    • get targets(): TargetSet

      Returns TargetSet

    • get shouldLoad(): boolean

      Returns boolean

    Methods

    • Returns void

    • Returns void

    • Parameters

      • eventName: string
      • Optional__namedParameters: Partial<
            {
                bubbles: boolean;
                cancelable: boolean;
                detail: Object;
                prefix: string;
                target: Element
                | Window
                | Document;
            },
        >

      Returns CustomEvent<Object>

    • Get the match type for the specified target, effect or event so that the most specific match value can be used for this rules resolving.

      First check the event for provided params, then the target element for attributes, finally the controller's match value with default and error handling for edge cases.

      Parameters

      • target: Element
      • effect: Effect = Effect.Enable
      • __namedParameters: { params?: { match?: Match } } = {}

      Returns Match

    • Finds & parses the rules for the provided target by the rules attribute, which is determined via the identifier and the provided effect name, (e.g. data-w-rules-enable). Falling back to the generic attribute if not found (e.g. data-w-rules).

      With the found rules, check the rules cache first, then parse the rules for caching if not found.

      When parsing the rule, assume an Object.entries format or convert an object to this format. Then ensure each value is an array of strings for consistent comparison to FormData values.

      Parameters

      • target: Element
      • effect: Effect = Effect.Enable

      Returns RuleEntry[]

    • Resolve the conditional targets based on the form data and the target(s) rule attributes and the controlled element's form data.

      For each effect target, determine the match type to use, parse the rules, run the matchers and apply the effect if needed.

      An effect event is dispatched before applying the effect, which can be cancelled to prevent the effect from being applied.

      Finally, a resolved event is dispatched after all effects have been processed.

      Parameters

      • Optionalevent: Event & { params?: { match?: Match } }

      Returns void

    • Parameters

      • _identifier: string
      • _application: Application

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods