Class CalcValueHost

CalcValueHost is a specialized ValueHost whose value is calculated when its getValue method is called. You supply a function callback in its CalcValueHostConfig to set it up.

Calculations allow you to expand what is available to Conditions without having to create new rules. This class was inspired by this use case:

The user wants to compare two dates to determine if the number of days between them is greater to (or equal or less than) another value. With CalcValueHost, the user can use the GreaterThanCondition to compare two integers, one being the value returned by a CalcValueHost and the other is the number of days to compare.

CalcValueHost has nifty conversion functions built in, that can be used to prepare the values it needs, the same way the comparison conditions do. let totalDays = vh.convert(value, 'TotalDays'); // 'TotalDays' is a lookup key Internally CalcValueHost uses Jivs' DataTypeConverters and DataTypeIdentifiers to convert the original value into the value demanded by its own dataType property.

Here is pseudo code for configuring the CalcValueHost used in this example.

function differenceBetweenDates(callingValueHost: ICalcValueHost, findValueHosts: IValueHostsManager)
: SimpleValueType
{
     let totalDays1 = callingValueHost.convert(findValueHosts.getValueHost('StartDate')?.getValue(), LookupKey.TotalDays);
     let totalDays2 = callingValueHost.convert(findValueHosts.getValueHost('EndDate')?.getValue(), LookupKey.TotalDays);
     if (typeof totalDays1 !== 'number' || typeof totalDays2 !== 'number')
         return undefined;   // can log with findValueHosts.services.logger.log();
     return Math.abs(totalDays2 - totalDays1);
}

// create the CalcValueHostConfig to supply to the ValidationManager
let builder = build(services);
builder.calc('DiffDays', LookupKey.Integer, differenceBetweenDates);

// create the 'StartDate' input with a LessThanCondition
builder.input('StartDate', 'Date', { label: 'Start date' })
 .lessThan(10, { valueHostName: 'DiffDays' });

Your function can also save stateful information with the valueHost.saveIntoInstanceState.

Hierarchy (view full)

Implements

Constructors

constructor

Accessors

valueHostsManager services config logger isChanged instanceState

Methods

convert convertToPrimitive getValue setValue dispose getName getLabel canChangeValueCheck setValueToUndefined additionalInstanceStateUpdatesOnSetValue useOnValueChanged getDataType getDataTypeLabel isEnabled getEnablerCondition setEnabled updateInstanceState saveIntoInstanceState getFromInstanceState

Constructors

constructor

Accessors

valueHostsManager

Protected services

Protected config

Protected logger

isChanged

  • get isChanged(): boolean

  • Determines how the validation system sees the Value in terms of editing. When true, it was changed. When false, it was not. The setValue()/setInputValue()/setValues() functions are the only ones to change this flag. They all set it to true automatically except set it to false when the option.Reset is true. The ValueHost.validate() function may skip validation of an InputValueHost when IsChanged is false, depending on the options for validate. For example, calling validate immediately after loading up the form, you want to avoid showing Category=Require validators. Those should appear only if the user edits, or when the user attempts to submit.

    Returns boolean

Protected instanceState

Methods

convert

  • convert(value, sourceLookupKey, resultLookupKey): SimpleValueType

  • Provides conversion support against the original value using the DataTypeConverters and DataTypeIdentifiers through services.dataTypeConverterService.convert()

    Parameters

    • value: any

      The value to be converted. Check its type and possibly its content.

    • sourceLookupKey: null | string

      The value can represent several other values, such as a Date represents date, time, etc. Use this when you need to distinguish between them. If null or '', evaluate the value itself, such as checking its class (using 'instanceof') or for properties of an interface that you are using. This is often the dataType property of the ValueHost.

    • resultLookupKey: string

    Returns SimpleValueType

    The converted value. If the value is not convertable, return undefined.

    Result Lookup Key

    • The lookup key that the result should be.

convertToPrimitive

  • convertToPrimitive(value, sourceLookupKey, resultLookupKey): SimpleValueType

  • Provides conversion support against the original value using the DataTypeConverters and DataTypeIdentifiers through services.dataTypeConverterService.convert(). Attempts to convert it all the way down to a number, string or boolean. Return null if the value represents null. Return undefined if the value was unconvertable.

    Parameters

    • value: any

      The value to be converted. Check its type and possibly its content.

    • sourceLookupKey: null | string

      The value can represent several other values, such as a Date represents date, time, etc. Use this when you need to distinguish between them. If null or '', evaluate the value itself, such as checking its class (using 'instanceof') or for properties of an interface that you are using. This is often the dataType property of the ValueHost.

    • resultLookupKey: String | Number | Boolean

    Returns SimpleValueType

    The converted value. If the value is not convertable, return undefined.

    Result Lookup Key

    • The lookup key that the result should be. When handling conditions, this is usually from conditionConfig.conversionLookupKey or secondConversionLookupKey.

getValue

setValue

dispose

getName

getLabel

Protected canChangeValueCheck

setValueToUndefined

  • setValueToUndefined(options?): void

  • Consuming system calls this when it attempts to resolve the input field/element value but cannot. It identifies that the native value is undefined. Note this does not reset IsChanged to false without explicitly specifying options.Reset = true;

    Parameters

    • Optional options: SetValueOptions

      validate - Invoke validation after setting the value. Reset - Clears validation (except when validate=true) and sets IsChanged to false. ConversionErrorTokenValue - When setting the value to undefined, it means there was an error converting. Provide a string here that is a UI friendly error message. It will appear in the Category=Require validator within the {ConversionError} token.

    Returns void

Protected additionalInstanceStateUpdatesOnSetValue

Protected useOnValueChanged

getDataType

getDataTypeLabel

isEnabled

  • isEnabled(): boolean

  • Determines if the ValueHost is enabled for user interaction. It is enabled unless you explicilty set it to false using ValueHostConfig.initialEnabled : false, setup the EnablerCondition which determines when it is enabled, or the ValueHost's own setEnabled() function.

    When disabled, the data values of the ValueHost do not get changed by setValue() and related functions. However, those functions offer the overrideDisabled option to force the change.

    When disabled and the ValueHost have validators, all validation is disabled and its ValidationStatus reports ValidationState.Disabled.

    Returns boolean

Protected getEnablerCondition

setEnabled

  • setEnabled(enabled): void

  • Sets the enabled state of the ValueHost. When false, the ValueHost is disabled and setValue() and related functions will not change the value. However, they offer the overrideDisabled option to force the change. When disabled and the ValueHost has validators, all validation is disabled and its ValidationStatus reports ValidationState.Disabled.

    This value is part of the ValueHost's InstanceState, not the Config, although the ValueHostConfig.initialEnabled is used when it is not set in the state.

    Parameters

    • enabled: boolean

    Returns void

updateInstanceState

saveIntoInstanceState

getFromInstanceState

Settings

Member Visibility

Theme

On This Page

constructorvalueHostsManagerservicesconfigloggerisChangedinstanceStateconvertconvertToPrimitivegetValuesetValuedisposegetNamegetLabelcanChangeValueChecksetValueToUndefinedadditionalInstanceStateUpdatesOnSetValueuseOnValueChangedgetDataTypegetDataTypeLabelisEnabledgetEnablerConditionsetEnabledupdateInstanceStatesaveIntoInstanceStategetFromInstanceState

Generated using TypeDoc v0.25.12