Rewrite and expand input trigger functionality

[bennothommo]

Workshop theme PR: wintercms/wn-workshop-theme#3
Original docs: https://wintercms.com/docs/v1.2/ui/script/input-trigger

This PR rewrites and expands upon the Input trigger functionality present in Winter CMS, and makes it available as an optional extra to themes in the front-end.

Whilst still remaining fully backwards-compatible with the current Trigger functionality included in the Storm UI library, this expands on the trigger functionality significantly.

Multiple triggers supported

An element may now have multiple triggers, by adding a specific name in the middle of the data-trigger attributes. For example, a button could have an enable or disable trigger depending on certain exclusive conditions:

<button
    id="save"
    data-trigger-enable=".terms-and-conditions"
    data-trigger-enable-condition="checked"
    data-trigger-enable-action="enable"
    data-trigger-disable=".privacy-policy"
    data-trigger-disable-condition="unchecked"
    data-trigger-disable-action="disable"
>Save</button>

In the example above, the name enable and disable have been used to differentiate the triggers, but you may use any name you wish, as long as it has a trigger element, a condition and a target.

Naming changes and new trigger parameters

A new trigger parameter - trigger-priority - is available to order triggers if you use more than one trigger on the same element. Priorities are ordered ascendingly, with higher priority triggers being fired after lower priority triggers.

The following trigger parameters have been renamed to be shorter, but the original names will still be compatible.

• The trigger-closest-parent parameter has been renamed to trigger-parent
• The trigger-condition parameter has been renamed to trigger-when
• The trigger-action parameter has been renamed to trigger-do

New conditions and parameters

In addition to the checked, unchecked and value conditions, additional conditions have been made available. Conditions also take into account multiple inputs.

• empty - triggered when the selected input(s) are empty/unchecked.
• oneOf:value, value... - triggered when the selected input(s) values match one of the given values.
• allOf:value, value... - triggered when the selected input(s) values match all of the given values.
• focus - triggered when the selected input(s) are focused on.
• blur - triggered when the selected input(s) lose focus.
• attr:attributeName, attributeValue - triggered when the selected input(s) have a specific attribue name and value.
• class:className - triggered when the selected input(s) have a specific class name.

Parameters can be provided in the format condition:param1, param2 similar to Laravel's validation rules. If a comma needs to be used within a parameter, the parameter can be quoted to prevent that comma from being used to split the parameters.

The checked condition has an optional parameter which can be a number, indicating that at least that number of checkboxes must be checked.

New actions

In addition to the show, hide, enable, disable and empty actions, additional actions have been made available, similar in format to the conditions, to run on the trigger element.

• value:newValue - sets the value of the trigger element to the new value.
• valueOf:selector, newValue - sets the value of a child element(s) of a trigger element that matches the selector.
• check - checks a checkbox/radio trigger element.
• unchceck - unchecks a checkbox/radio trigger element.
• class:className, unmetClassName - defines a class to add to the trigger element when the condition is met. Optionally, can also provide a class when the condition is unmet.
• classOf:selector, className, unmetClassName - defines a class to add to a child element of the trigger element when the condition is met. Optionally, can also provide a class when the condition is unmet.
• attr:attributeName, attributeValue, unmetAttributeValue - sets the given attribute name with the given value on the trigger element when the condition is met. Optionally, can also provide an unmet value.
• attrOf:selector, attributeName, attributeValue, unmetAttributeValue - sets the given attribute name with the given value on a child element of the trigger element when the condition is met. Optionally, can also provide an unmet value.
• style:styleName, styleValue, unmetStyleValue - sets the given styling attribute with the given value on the trigger element when the condition is met. Optionally, can also provide an unmet value.
• styleOf:selector, styleName, styleValue, unmetStyleValue - sets the given styling attribute with the given value on a child element of the trigger element when the condition is met. Optionally, can also provide an unmet value.

For the value, class, attr and style actions, the value of the target element can be inserted into the parameters. In order to prevent this from being abused, the value will be HTML encoded.

For the value action, if this is targeted on a non-input type element, it will change the inner text of that element.

Multiple conditions and actions

Both conditions and actions support multiple commands, by using a pipe (|) symbol between commands, again similar to Laravel. Conditions will always been treated as AND-type conditions - all conditions need to pass for the trigger to occur.

<input type="checkbox" value="red">
<input type="checkbox" value="orange">
<input type="checkbox" value="yellow">
<input type="checkbox" value="green">
<input type="checkbox" value="blue">
<input type="checkbox" value="indigo">
<input type="checkbox" value="violet">

<div
    class="message"
    data-trigger="input[type=checkbox]"
    data-trigger-when="checked:3|value:green"
    data-trigger-do="hide"
>
    You must select 3 colours, and one of them must be green.
</div>

[mjauvin]

Niiice!

[mjauvin]

Suggested change

	case 'notWithin':
	case 'notwithin':

[mjauvin]

Did you miss this one @bennothommo ?

[bennothommo]

Yes, yes I did. :)