⚡︎ BoxLang Module: Boxlang UI Forms Module

Components

This module contributes the following Components to the language:

• form - the wrapping HTML <form...></form> component otherHTML form tag components. Produces an HTML form.
• input - the <input.../> HTML form component
• select - the <select ... ></select> HTML form component
• slider - generates an HTML 5 input range slider
• textarea - the <textarea>...</textarea> HTML form component

The majority of attributes to these components serve as pass-through attributes to the generated HTML tag. Exceptions to these, by tag, include:

form

• format - this attribute will throw an error if present and is anything other than HTML. XML and Flash forms will not be supported.
• passthrough - this is a list of passthrough attributes which will be added to the form tag.
• scriptsrc - this defines an external location for the custom forms javascript file, which is sourced into the HTML output
• preservedata - When the form action posts back to the page that contains the form, this attribute determines whether to override the control values with the submitted values.
• id - defaults to name when omitted. action, method, and onsubmit pass through; supplying action defaults method to post.

AJAX Binds

AJAX binds require bx-ui-compat to be installed by the application; it is not a runtime dependency of this module. Forms containing bound inputs or selects automatically import ajax-core.js, ajaxproxy.js, and ajax-core.css before the form markup when the compatibility module is available. Ordinary forms do not import this runtime, and the import is safely skipped when the compatibility module is unavailable.

<cfform name="catalogForm" action="catalog.cfm">
	<cfinput name="category" />
	<cfselect name="products" bind="cfc:CatalogService.getProducts({category})" bindonload="true"
		value="id" display="name"></cfselect>
</cfform>

input and select preserve bind, bindattribute, bindonload, onbinderror, and onbindsuccess as lowercase HTML attributes. The client scanner wires CFC, URL, JavaScript, and local binds, registers source listeners and ColdFusion.bindHandlerCache, and evaluates bindonload binds on window load. Run BXUICompat.Bind.scan(root) after AJAX content swaps. Standalone controls require an explicit <bx:ajaximport tags="form" /> before their markup.

Select id defaults to name. Bound selects with value/display or a server-side query emit BXUICompat.initSelect column and selection metadata; otherwise query results use the first column as value and the second as display. No server-generated bind registration is needed.

Unsupported form Component Attributes

The following attributes are unsupported and generate a warning log message if used.

• enablecab
• skin
• preloader
• timeout
• wmode
• accessible
• archive
• codebase

input

• label - if provided, will generate an HTML label tag before the generated input tag
• message - can be provided as a custom message if validation fails
• passthrough - this is a list of passthrough attributes which will be added to the form tag.

Planned input Component Attributes supported

The following have not yet been implemented in the input component but are planned for development in the near-term.

• autosuggest - Valid only for type="text". Specifies entry completion suggestions to display as the user types into a text input. The user can select a suggestion to complete the text entry. The valid value can be either of the following:
  • A string consisting of the suggestion values separated by the delimiter specified by the delimiter attribute.
  • A bind expression that gets the suggestion values based on the current input text.
• autosuggestbinddelay - Valid only for type="text". The minimum time between autosuggest bind expression invocations, in seconds. Use this attribute to limit the number of requests that are sent to the server when a user types.
• autosuggestminlength - Valid only for type="text". The minimum number of characters required in the text box before invoking a bind expression to return items for suggestion.
• delimiter - Optional delimiter which informs the autosuggest attribute
• maxresultsdisplayed - Optional numeric value which informs the max result displayed by the autosuggest
• showautosuggestloadingicon - A Boolean value that specifies whether to display an animated icon when loading an autosuggest value for a text input.
• typeahead - A Boolean value that specifies whether the autosuggest feature should automatically complete a user's entry with the first result in the suggestion list.
• validate - Supported validation types include: date, time, float, integer, telephone, zipcode, creditcard, social_security_number, and regular_expression.

JavaScript Tests

This module uses Vitest with a JSDOM environment for automated JavaScript validation tests.

Run locally

• npm ci
• npm test
• npm run test:watch
• npm run test:coverage

Coverage output is written to build/reports/js-coverage.

The Java tests verify the forms module's own output - form/select defaults, bind attribute pass-through and BXUICompat.initSelect metadata - plus that an AjaxImport component is invoked before the form markup when a form is bound. They register a stub AjaxImport for that check and do not depend on bx-ui-compat. The compatibility module's AJAX runtime (<bx:ajaximport> asset output and the client-side bind scanner) is owned and tested by bx-ui-compat.

Unsupported input Component Attributes

• validateAt - Since the validate attribute passes through to an HTML5 type attribute on the tag, this attribute is not supported

slider

The slider component creates a type="range" input component but access the following additional attributes:

• increment - specifies the step value of the slider
• bgColor - specifies the background color of the slider body
• color - specifes the color of the slider control
• vertical - Optional boolean attribute. When true, the slider will have a vertical orientation

textarea

• passthrough - this is a list of passthrough attributes which will be added to the form tag.
• message - can be provided as a custom message if validation fails
• passthrough - this is a list of passthrough attributes which will be added to the form tag.

Unsupported textarea Component Attributes

The following attributes are not supported and will be ignored if provided:

• stylesXML
• templatesXML
• richtext
• toolbar
• toolbarOnFocus

|:------------------------------------------------------: |
| ⚡︎ B o x L a n g ⚡︎
| Dynamic : Modular : Productive
|:------------------------------------------------------: |

Copyright Since 2023 by Ortus Solutions, Corp
www.boxlang.io | www.ortussolutions.com

Ortus Sponsors

BoxLang is a professional open-source project and it is completely funded by the community and Ortus Solutions, Corp. Ortus Patreons get many benefits like a cfcasts account, a FORGEBOX Pro account and so much more. If you are interested in becoming a sponsor, please visit our patronage page: https://patreon.com/ortussolutions