@cntwg/html-helper 0.0.21 → 0.0.23

package/doc/html-ctrls-fields.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.0.5|
+>|***rev.*:**|0.0.7|
 >|:---|---:|
->|date:|2023-10-05|
+>|date:|2024-11-20|
 
 ## Introduction
 
@@ -8,6 +8,7 @@ This paper describes a classes provided by `html-ctrls-fields.js` module.
 
 ## Module classes
 
+<a name="THtmlInputField"></a>
 ### **THtmlInputField**
 
 This class provide a container useful when dealing with an elements such an input fields or a checkboxes placed on an HTML-form.
@@ -20,129 +21,175 @@ The class constructor creates a new instance of the class.
 
 The class constructor receives a parameters listed below:
 
-|parameter name|value type|default value|description|
+| parameter name | value type | default value | description |
 |:---|---|---:|:---|
-|`name`|`string`|---|\<*reserved*>|
-|`eholds`|`object`|---|contains ref-list for container elements|
-|`options`|`object`|---|contains a container settings|
+| `name` | `string` | --- | \<*reserved*> |
+| `eholds` | `object`| --- | contains ref-list for container elements |
+| `options` | `object` | --- | contains a container settings |
 
 ##### `eholds` parameter
 
 The `eholds` structure has listed below:
 
-|parameter name|value type|default value|description|
+| parameter name | value type | default value | description |
 |:---|---|---:|:---|
-|`host`|`HTMLElement`|---|points to a host element which holds all other items|
-|`label`|`HTMLElement`|---|points to a label item|
-|`field`|`HTMLElement`|---|points to a field item|
+| `host` | `HTMLElement` | --- | points to a host element which holds all other items |
+| `label` | `HTMLElement` | --- | points to a label item |
+| `field` | `HTMLElement` | --- | points to a field item |
 
 ##### `options` parameter
 
 The `options` structure has listed below:
 
-|option name|value type|default value|description|
+| option name | value type | default value | description |
 |:---|---|---:|:---|
-|`idPref`|---|---|\<*reserved*>|
-|`baseClassID`|---|---|\<*reserved*>|
-|`hint`|---|---|\<*reserved*>|
-|`fldType`|---|---|\<*reserved*>|
-|`isReadOnly`|---|---|\<*reserved*>|
+| `idPref` | 'string' | --- | \<*reserved*> |
+| `baseClassID` | --- | --- | \<*reserved*> |
+| `hint` | `string` | --- | \<*reserved*> |
+| `fldType` | `string` | `default` | defines an input field type |
+| `isReadOnly` | `boolean` | `true` | defines whether an element value can be modified |
+
+The `fldType` option value can be: `text`, `field`, `checkbox`, `switch` or `default` (*the latter is the same as `field`*).
 
 #### class properties
 
-The table below describes a properties of a `THtmlInputField` class:
+##### **isModified**
+
+| property type | read only | description |
+|---|---|:---|
+| `boolean` | yes | shows whether or not the field content was modified |
+
+<a name="THtmlInputField+type"></a>
+##### **type**
+
+> since: `v0.0.23`
 
-|property name|property type|read only|description|
-|:---|---|---|:---|
-|`value`|`string` or `boolean`|no|contains a container value|
-|`isModified`|`boolean`|yes|show whether or not the field content was modified|
+| property type | read only | description |
+|---|---|:---|
+| `string` | yes | contains a container type |
+
+<a name="THtmlInputField+value"></a>
+##### **value**
+
+| property type | read only | description |
+|---|---|:---|
+| `string`, *`boolean`* | no | contains a container value |
 
 #### class methods
 
-##### **clear()**
+<a name="THtmlInputField+clear"></a>
+##### **clear()** => `void`
 
 > Note: \<*reserved*>
 
-##### **isEmpty()**
+<a name="THtmlInputField+isEmpty"></a>
+##### **isEmpty()** => `boolean`
 
 This method returns `true` if the container field element contains an empty string.
 
-##### **isNotEmpty()**
+<a name="THtmlInputField+isNotEmpty"></a>
+##### **isNotEmpty()** => `boolean`
 
 This method returns `true` if the container field element contains a non-empty string.
 
-##### **hideItem()**
+<a name="THtmlInputField+hide"></a>
+##### **hideItem()** => `void`
 
 This method hides a container on the Web-form.
 
-##### **showItem()**
+<a name="THtmlInputField+show"></a>
+##### **showItem()** => `void`
 
 This method shows a container on the Web-form.
 
-##### **attachTo(target)**
+<a name="THtmlInputField+attachTo"></a>
+##### **attachTo(target)** => `boolean`
 
 This method attaches a container to a parent HTML-element given by a `target` parameter. If succeed `true` returned.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `target` | `HTMLElement` | --- | a target element |
+
 #### class methods (*static*)
 
-##### **create(name\[, options])**
+<a name="THtmlInputField.create"></a>
+##### **create(name\[, options])** => `?THtmlInputField`
 
 This method creates an instance of the class. If failed `null` returned.
 
-The `name` parameter represents an ID of the created container.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an ID of the created container |
+| `options` | `object` | --- | an options |
 
 For details of `options` parameter see a `createElement` method description.
 
-##### **createElement(name\[, options\[, bRetChild]])**
+<a name="THtmlInputField.createElement"></a>
+##### **createElement(name\[, options\[, bRetChild]])** => `null|object|HTMLElement`
 
 This method creates a container with all elements needed for input field component to function.
 
-The `name` parameter represents an ID of the created container.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an ID of the created container |
+| `options` | `object` | --- | an options |
+| `bRetChild` | `boolean` | `false` | a flag to change a result value type |
 
 The `options` structure has listed below:
 
-|option name|value type|default value|description|
+| option name | value type | default value | description |
 |:---|---|---:|:---|
-|`host`|`HTMLElement`|---|an HTML-element which is a host for all container elements|
-|`idPref`|`string`|---|a prefix which modified a container ID, if given|
-|`label`|`string`|---|a text for the field label|
-|`labelPosition`|`string`|---|defines a position to place a label|
-|`useDelim`|`boolean`|`true`|defines whether a delimeter is used within a text of a label|
-|`baseClassID`|`object`|---|containes a list of class name attributes for container elements|
-|`hint`|`string`|---|defines a helper string which is shown when a field content is empty|
-|`fldType`|`string`|---|defines a field type|
-|`isReadOnly`|`boolean`|`true`|defines whether a field content can be modified|
+| `host` | `HTMLElement`| --- | an HTML-element which is a host for all container elements |
+| `idPref` | `string` | --- | a prefix which modified a container ID, if given |
+| `label` | `string` | --- | a text for the field label |
+| `labelPosition` | `string` | --- | defines a position to place a label |
+| `useDelim` | `boolean` | `true` | defines whether a delimiter is used within a text of a label |
+| `baseClassID` | `object` | --- | contains a list of class name attributes for container elements |
+| `hint` | `string` | --- | defines a helper string which is shown when a field content is empty |
+| `fldType` | `string` | `default` | defines a field type |
+| `isReadOnly` | `boolean` | `true` | defines whether a field content can be modified |
+
+The `labelPosition` option value can be: `before`, `after` or `default` (*the latter is the same as `before`*).
 
 The `baseClassID` structure has listed below:
 
-|option name|value type|default value|description|
+| option name | value type | default value | description |
 |:---|---|---:|:---|
-|`main`|---|---|containes a list of class name attributes for all elements|
-|`host`|---|---|containes a list of class name attributes for container host|
-|`label`|---|---|containes a list of class name attributes for label element|
-|`field`|---|---|containes a list of class name attributes for field element|
+| `main` | `string`, `string[]` | --- | contains a list of class name attributes for all elements |
+| `host` | `string`, `string[]` | --- | contains a list of class name attributes for container host |
+| `label` | `string`, `string[]` | --- | contains a list of class name attributes for label element |
+| `field` | `string`, `string[]` | --- | contains a list of class name attributes for field element |
 
-The `bRetChild` parameter, if given, changes the result value of the method. It must be of a `boolean` type. If value is `false` the only host element is returned as a result (a default behavoir). If `true`, an `object` of the following structure is returned:
+The `fldType` option value can be: `text`, `field`, `checkbox`, `switch` or `default` (*the latter is the same as `field`*).
 
-|property name|value type|description|
+The `bRetChild` parameter, if given, changes the result value of the method. It must be of a `boolean` type. If value is `false` the only host element is returned as a result (a default behavior). If `true`, an `object` of the following structure is returned:
+
+| property name | value type | description |
 |:---|---|:---|
-|`host`|`HTMLElement`|a container host element|
-|`label`|`HTMLElement`|a container label element|
-|`field`|`HTMLElement`|a container field element|
+| `host` | `HTMLElement` | a container host element |
+| `label` | `HTMLElement` | a container label element |
+| `field` | `HTMLElement` | a container field element |
 
 #### class methods (*special*)
 
-##### **on(name, event)**
+<a name="THtmlInputField+on"></a>
+##### **on(name, event)** => `void`
+
+This method sets event handler for the list event addressed by a `name` parameter.
 
-This method sets event handler addressed by `name` parameter for the class instance.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an event name |
+| `event` | `function` | --- | a callback function |
 
-> Note: for current implementation you can't reset or set new event handler (*especially another one*) if a handler with the same name exists already.
+> Note: for current implementation you can't reset or set new event handler (especially another one) if a handler with the same name exists already.
 
 #### class events
 
 The class generates the events listed in the table bellow:
 
-|event name|description|
+| event name | description |
 |:---|:---|
-|`value-changed`|fired when value is changed|
-|`value-empty`|fired due editing of the field when its value become an empty string|
+| `value-changed` | fired when value is changed |
+| `value-empty` | fired due editing of the field when its value become an empty string |