Home›Docs›Utilities›FieldTools Utility

FieldTools Utility

Last updated: 1 month ago

The fieldTools utility functions can be used to get form field values, set form field values, and reset form field values. Supports both native form fields and custom form fields.

Field Component: Feature and Functionality Demo Examples1 month ago Field Component1 month ago Fields Component1 month ago FieldTools Utility1 month ago

Preface

Getting and setting values for form fields is a common operation in frontend development. However, there are various types of form fields with different approaches for value handling. Additionally, some custom form fields and regular div elements also require value operations. This field tools collection was designed to enable getting and setting values with just one line of code within this framework.

getType(selector)

This function retrieves the type of a form field, accepting one parameter - a node selector, written the same way as the first parameter of the getEl function.

For native input elements (including types like file/range/radio/checkbox), textarea, and select elements, it will output the string native
For custom form fields like oc-input, oc-textarea, etc., it will output the string comp
For div and other nodes, it will output the string other

Output
HTML
JS

```
                
                
            
```

                
                    demo0004.onclick=()=>{
                        console.log(orca.fieldTools.getType('#demo0001'));
                        console.log(orca.fieldTools.getType('#demo0002'));
                        console.log(orca.fieldTools.getType('#demo0002'));
                    }
                    demo0104.onclick=()=>{
                        console.log(orca.fieldTools.getType('#demo0101'));
                        console.log(orca.fieldTools.getType('#demo0102'));
                        console.log(orca.fieldTools.getType('#demo0102'));
                    }
                    demo0204.onclick=()=>{
                        console.log(orca.fieldTools.getType('#demo0201'));
                        console.log(orca.fieldTools.getType('#demo0202'));
                        console.log(orca.fieldTools.getType('#demo0202'));
                    }

getVals(param)

This method retrieves values from form fields, accepting one parameter - an object with the following properties:

target: Form field node selector, written the same way as the first parameter of getEl
format: Output value type, options include string, array or empty (defaults to empty for default output)
parent: Parent node selector - when the target node is a radio or checkbox, you need to get values from fields with the same name, requiring parent specification (if not specified, searches from document)
separator: Multi-value separator, defaults to comma ,
child: When the target node is a regular div etc., you can specify a child node selector to get the textContent from the child node as output value

Default Output

When no format is specified, values are output in default format.

Native form fields with multiple checkboxes, file with multiple attribute, and select types output as array data by default; single checkbox, file and select without multiple attribute output single values
Custom form fields all output as strings by default
Other nodes also output as strings by default

For native select controls, values are first taken from the value attribute of option nodes, and if empty, from the label attribute.

Among custom form fields, only oc-file outputs a file array by default - others output strings.

Output
HTML
JS

Native Form Fields

Get

Get

Get

Get

Get

Get

Get

Get

Get

Get

Custom Form Fields

Get

Get

Get

Get

Get

Get

Get

Get

Get

Get

Get

Get

Get

Get

Regular Nodes

value01
Get
```
                
                
            
```

                
                    for(let k of [...document.querySelectorAll('.get-dft')]){
                        let btn = k.querySelector(':scope>span'),
                            input = k.firstElementChild;
                        btn.onclick = ()=>{
                            console.log(orca.fieldTools.getVals({target:input}))
                        }
                    }

Output from Child Node

When the target node is a regular HTML node like div, span, etc., even if specified to get values from that node, its internal structure might be complex. In this case, the child parameter can specify a child node to get values from.

Output
HTML
JS

Country: Japan
```
                
                
            
```

                
                    demo0902btn01.onclick=()=>{
                        //Get value from i tag
                        console.log(orca.fieldTools.getVals({target:'#demo0902',child:'i'}));
                    }

Output from Attribute

If the target node is not a form field and the value exists in the node's attribute rather than its innerHTML (or textContent), then use key to specify the attribute to get.

Output
HTML
JS

Country: Japan
```
                
                
            
```

                
                    demo3902btn01.onclick=()=>{
                        //Get value from i tag
                        console.log(orca.fieldTools.getVals({target:'#demo3902',child:'i',key:'data-name'}));
                    }

Output as String

If the retrieved value is for data processing, you can set format:'array' to output in array format; in most cases you can set format:'string' for string output.

Currently all custom components' value properties are in string format, while native form fields (except checkbox, file, select which default to array output) also output as strings.

Note: Native file components are only suitable for array output - string output would just be filenames with no real meaning.

Output
HTML
JS

Get

Get

Get
```
                
                
            
```

                
                    for(let k of [...document.querySelectorAll('.get-str')]){
                        let btn = k.querySelector(':scope>span'),
                            input = k.firstElementChild;
                        btn.onclick = ()=>{
                            console.log(orca.fieldTools.getVals({target:input,format:'string'}))
                        }
                    }

setVals(param)

This method sets values for form fields, accepting one parameter - an object with the following properties:

target: Form field node selector, written the same way as the first parameter of getEl
value: The value to set, can be string, number, string[] or number[]
parent: Parent node selector - when the target node is a radio or checkbox, you need to set values for fields with the same name, requiring parent specification (if not specified, searches from document)
separator: Multi-value separator, defaults to comma ,
child: When the target node is a regular div etc., you can specify a child node selector to set the textContent of the child node
keyVal: Key-value pair for setting values - when the target or child node is not a custom or native form field, if this property is set it will take precedence, e.g. keyVal=['label','abc']

Setting Native Form Fields

Native file controls cannot have values set via JS - files can only be selected manually through the Windows dialog. For radio groups and checkbox groups, the setVals method will find all radio or checkbox controls with the same name in the entire document and set the corresponding value controls to checked state. To improve search efficiency, you can set the parent property to narrow the search scope.

Output
HTML
JS

Set

Set

Set

Set

Set

Set

Set

Set

Set

Set
```
                
                
            
```

                
                    for(let k of [...document.querySelectorAll('.set-dft')]){
                        let btn = k.querySelector(':scope>span'),
                            input = k.firstElementChild,
                            value = btn.getAttribute('value');
                        btn.onclick = ()=>{
                            orca.fieldTools.setVals({target:input,value})
                        }
                    }

Setting Custom Form Fields

Custom form field components can all have their values set via setAttribute('value', value). Therefore, for custom form field components, the core of the fieldTools.setVals method is:

Since custom file form fields are based on native file form fields, values cannot be set directly - even if you try to set a value, it will be treated as a reset operation. Other custom form fields can have their values set normally.

Output
HTML
JS

Set

Set

Set

Set

Set

Set

Set

Set

Set

Set

Set

Set

Set
```
                
                
            
```

                
                    for(let k of [...document.querySelectorAll('.set-comp')]){
                        let btn = k.querySelector(':scope>span'),
                            input = k.firstElementChild,
                            value = btn.getAttribute('value');
                        btn.onclick = ()=>{
                            orca.fieldTools.setVals({target:input,value})
                        }
                    }

Setting Regular Nodes

Setting values for regular nodes essentially replaces their innerHTML. If the target node is complex, you can set the child property to specify which child node should receive the value.

Output
HTML
JS

value01
Set

Country: Japan
Set
```
                
                
            
```

                
                    for(let k of [...document.querySelectorAll('.set-html')]){
                        let btn = k.querySelector(':scope>span'),
                            input = k.firstElementChild,
                            value = btn.getAttribute('value');
                        btn.onclick = ()=>{
                            // If an 'i' child node is found, fill the value into this node
                            orca.fieldTools.setVals({target:input,value,child:'i'})
                        }
                    }

Setting Values via Attributes

For regular nodes, the value isn't necessarily in their innerHTML - it might exist in their attribute. In such cases, you need to use key to specify which attribute to set.

Output
HTML
JS

India
Set

Country: Japan
Set
```
                
                
            
```

                
                    for(let k of [...document.querySelectorAll('.set-key')]){
                        let btn = k.querySelector(':scope>span'),
                            input = k.firstElementChild,
                            child = k.querySelector('[data-name]'),
                            value = btn.getAttribute('value');
                        btn.onclick = ()=>{
                            // If an 'i' child node is found, fill the value into this node
                            orca.fieldTools.setVals({target:input,value,key:'data-name',child:'i'});
                            input.innerHTML += child.getAttribute('data-name');
                        }
                    }

reset(param)

This method can reset form fields, accepting one parameter - an object with the following properties:

target: Form field node selector, written the same way as the first parameter of getEl
parent: Parent node selector - when the target node is a radio or checkbox, you need to get values from fields with the same name, requiring parent specification (if not specified, searches from document)
zero: Whether to force the value to be cleared to zero

The reset method essentially resets the form field to its initial attributes. Using the zero parameter means clearing the value (equivalent to a clear operation).

Resetting Native Form Fields

Native file controls cannot have values set via JS - files can only be selected manually through the Windows dialog. For radio groups and checkbox groups, the reset method will find all radio or checkbox controls with the same name in the entire document and reset them. To improve search efficiency, you can set the parent property to narrow the search scope.

Output
HTML
JS

Reset Clear

value01 Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear
```
                
                
            
```

                
                    for(let k of [...document.querySelectorAll('.reset-dft')]){
                        let btn1 = k.querySelector(':scope>span'),
                            btn2 = k.querySelector(':scope>i'),
                            input = k.firstElementChild;
                        btn1.onclick = ()=>{
                            orca.fieldTools.reset({target:input})
                        }
                        btn2.onclick = ()=>{
                            orca.fieldTools.reset({target:input,zero:true})
                        }
                    }

Resetting Custom Form Fields

Custom form fields all have reset() and clear() methods, which correspond to the reset and clear operations in the fieldTools.reset() method.

Output
HTML
JS

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear

Reset Clear
```
                
                
            
```

                
                    for(let k of [...document.querySelectorAll('.reset-comp')]){
                        let btn1 = k.querySelector(':scope>span'),
                            btn2 = k.querySelector(':scope>i'),
                            input = k.firstElementChild;
                        btn1.onclick = ()=>{
                            orca.fieldTools.reset({target:input})
                        }
                        btn2.onclick = ()=>{
                            orca.fieldTools.reset({target:input,zero:true})
                        }
                    }

Resetting Regular Nodes

Regular nodes don't have reset methods by default, but if you add reset() and clear() methods to a node, you can then use the fieldTools.reset() method to reset it.

Output
HTML
JS

value01
Reset Clear
```
                
                
            
```

                
                    for(let k of [...document.querySelectorAll('.reset-html')]){
                        let btn1 = k.querySelector(':scope>span'),
                            btn2 = k.querySelector(':scope>i'),
                            input = k.firstElementChild,
                            html=input.innerHTML;
                        //reset & clear
                        input.reset = ()=>input.innerHTML = html;
                        input.clear = ()=>input.innerHTML = '';
                        btn1.onclick = ()=>{
                            orca.fieldTools.reset({target:input})
                        }
                        btn2.onclick = ()=>{
                            orca.fieldTools.reset({target:input,zero:true})
                        }
                    }