createApplyEffect() function

Creates an apply effect function with the ability of deferred execution that can perform side effects depending on a target element and validation results validity state.

Syntax

createApplyEffect(effectFunction, defaultStateValues)

Parameters

effectFunction
An effect function that will be called with the following arguments:
- htmlElement
  An object that implements the HTMLElement interface.
- stateValues
  An object that specifies values for validity states. The available properties are:
  - true
    An object with properties for the validity state equal to true. The available properties are:
    - delay
      A number in milliseconds for the effect to be deferred for this validity state.
    - value
      Any value to be used for applying the effect for this validity state.
  - false
    An object with properties for the validity state equal to false. The available properties are:
    - delay
      A number in milliseconds for the effect to be deferred for this validity state.
    - value
      Any value to be used for applying the effect for this validity state.
  - ...
    Any additional properties can be supplied for using in effectFunciton.
- validationResult
  A ValidationResult object.
- effectID
  A string identifier of the effect.
defaultStateValues ^optional
An object that specifies values for validity states. The available properties are:
- true ^optional
  An object with properties for the validity state equal to true. The available properties are:
  - delay ^optional
    A number in milliseconds for the effect to be deferred for this validity state.
    Default: 0.
  - value ^optional
    Any value to be used for applying the effect for this validity state.
    Default: null.
- false ^optional
  An object with properties for the validity state equal to false. The available properties are:
  - delay ^optional
    A number in milliseconds for the effect to be deferred for this validity state.
    Default: 0.
  - value ^optional
    Any value to be used for applying the effect for this validity state.
    Default: null.
- ... ^optional
  Default values for any additional properties can be specified here if planned to be supplied in stateValues for using in effectFunciton.

Return value

A new apply effect function that accepts htmlElement, effectID, stateValues as arguments and returns an Array with two functions: for cancellation and setting the effect.

When invoked on the server side, gives a warning and for crash-safety returns a function which in turn will return an Array with two empty functions.

Exceptions

If anything other than a function was passed in as effectFunciton the corresponding error will be thrown.
For the returned apply effect function: if anything other than HTMLElement, string and Object or more arguments of a particular type were passed in, throws the corresponding error.

Description

The createApplyEffect() function allows to perform deferred side effects with different delays and effect data for “valid” and “invalid” states. Side effects can be changing CSS properties, attributes, showing, hiding, enabling, disabling, creating, deleting other HTML elements etc.

You can write the logic inside effectFunction that can be performed depending on passed in arguments: htmlElement, its parent, sibling or child elements, current validity state and an effect identifier.

The effect control functions cancelEffect() and setEffect() returned by the applyEffect() function are intended to be used as state callbacks and accept a ValidationResult as an argument. The cancelEffect() function cancels a deferred execution of effectFunction and setEffect() enqueues a new execution of effectFunction.

const effectFunction = (
    htmlElement, stateValues, validationResult, effectID
) => {
    const { isValid } = validationResult;
    const { value } = stateValues[isValid]; // using data depending on validity

    // effect logic
    // ....
};

const defaultStateValues = {
  true: { delay: 0, value: 'default effect data for the valid state' },
  false: { delay: 0, value: 'default effect data for the invalid state' },
};

const applyEffect = createApplyEffect(effectFunction, defaultStateValues);

const [cancelEffect, setEffect] = applyEffect();

The parameters of the applyEffect() function can be passed in any order for convenience. When passed, they override their default counterparts such that:

htmlElement overrides the element set as the target property of ValidationResult passed in the cancelEffect() and setEffect() functions;
properties of the stateValues object override the properties of the defaultStateValues;
if effectID is specified it overrides the default effect identifier which is unique for every applyEffect() function call.

const stateValues = {
  true: { delay: 0, value: 'effect data for the valid state' },
  false: { delay: 2000, value: 'effect data for the invalid state' },
};

const effectID = 'someEID';

// parameters can be passed in any order
applyEffect();
applyEffect(stateValues);
applyEffect(effectID, stateValues);
applyEffect(htmlElement, effectID, stateValues);
applyEffect(effectID, htmlElement, stateValues);
applyEffect(effectID, stateValues, htmlElement);
applyEffect(htmlElement, stateValues, effectID);
applyEffect(stateValues, htmlElement, effectID);
applyEffect(stateValues, effectID, htmlElement);

When pairs of effect control functions are created by different calls of the applyEffect() function with the same effectID passed in, cancelEffect() cancels effectFunction enqueued by setEffect() from another call, if the same htmlElement was passed as the target property in ValidationResult. In other words, separate calls of the applyEffect() function with the same effectID constitute a compound effect applied to the htmlElement.

// the same htmlElement and effectID
// cancelEffect1 and cancelEffect2 both
// will be cancelling the effect set by either setEffect1 or setEffect2

const [cancelEffect1, setEffect1] = applyEffect(
    htmlElement, stateValues1, effectID
);

const [cancelEffect2, setEffect2] = applyEffect(
    htmlElement, stateValues2, effectID
);

// the same effectID
// cancelEffect1 and cancelEffect2 both
// will be cancelling the effect set by either setEffect1 or setEffect2
// only if the same html element will be passed as the 'target' property
// of validation results

const [cancelEffect1, setEffect1] = applyEffect(stateValues1, effectID);
const [cancelEffect2, setEffect2] = applyEffect(stateValues2, effectID);

Implementation: create-apply-effect.js.

Examples

The following functions were created with using createApplyEffect():

For examples, see their implementations.