# 08. __Data Binding__ [![+Professional Support](https://www.totaljs.com/img/badge-support.svg)](https://www.totaljs.com/support/) [![+Chat with contributors](https://www.totaljs.com/img/badge-chat.svg)](https://messenger.totaljs.com) Data-Binding is a special feature in jComponent. It can affect DOM element dynamically. __Topics:__ - [Commands](#) - [Types of command expressions](#) - [Advanced usage](#) --- __Declaration__: ```html
``` ### Commands - [command: `attr`](#) - [command: `changes`](#) - [command: `checked`](#) - [command: `class`](#) - [command: `click`](#) - [command: `config`](#) - [command: `currency`](#) - [command: `def`](#) - [command: `delay`](#) - [command: `disabled`](#) - [command: `empty`](#) - [command: `enabled`](#) - [command: `exec`](#) - [command: `focus`](#) - [command: `format`](#) - [command: `hide`](#) - [command: `href`](#) - [command: `html`](#) - [command: `init`](#) - [command: `import`](#) - [command: `invisible`](#) - [command: `refresh`](#) - [command: `resize`](#) - [command: `required`](#) - [command: `set`](#) - [command: `setter`](#) - [command: `show`](#) - [command: `src`](#) - [command: `strict`](#) - [command: `template`](#) - [command: `text`](#) - [command: `title`](#) - [command: `track`](#) - [command: `tracktype`](#) - [command: `val`](#) - [command: `vbindarray`](#) - [command: `visible`](#) - [command: `.class_name`](#) #### command: `attr` `+v18` command sets a value into the custom attribute: ```html
``` #### command: `changes` `+v18` command performs all other commands only if the value will be changed. It works with `object` types too. ```html
``` #### command: `checked` Sets the `checked` attribute. Targeted for HTML controls only `input`. Expression must return `Boolean`. ```html ``` #### command: `class` Toggles specified `class` when the `data-bind` is processed. Epression must be `String` only. Supports multiple classes seperated by empty space. ```html ``` #### command: `click` `+v17` Executes method when the user clicks on the element. ```html
``` #### command: `config` Performs `reconfiguration` for the current jComponent. Expression must return `String` with jComponent configuration or can return `Object`. ```html
My textbox
etc..
``` #### command: `currency` `+v18` Renders formatted currency. A value in `currency` command is a currency, it's not evaluated and can be used `[value_from_ENV]`. ```html
Additional example with a dynamic currency:
``` #### command: `def` Sets the `def` attribute. It's targeted for HTML controls only `input`, `textarea`, `select` and `button`. ```html String:
Number:
Boolean:
Object:
Array:
``` #### command: `delay` Delays a binding for 2 seconds. Must be a number which represents `milliseconds`. ```html ``` #### command: `disabled` Sets the `disabled` attribute. It's targeted for HTML controls only `input`, `textarea`, `select` and `button`. Expression must return `Boolean`. `+v17` extends `disabled` command for components. Now the library can perform reconfigure with `disabled:true/false` command. ```html ``` #### command: `empty` `+v17` Sets an `empty` HTML to the current element when is the value `null` or `undefined` or __empty string__. ```html
``` #### command: `enabled` `+v16` Sets the `enabled` attribute. It's targeted for HTML controls only `input`, `textarea`, `select` and `button`. Expression must return `Boolean`. `+v17` extends `enabled` command for components. Now the library can perform reconfigure with `disabled:true/false` command. ```html ``` #### command: `exec` Expression must be a link to a function. This function will be executed if the `data-bind` __path__ will be changed. ```html
``` #### command: `focus` `+v18` supports `focus` command which can contain a __jQuery selector__ which will perform `.focus()`. Example: ```html
``` #### command: `format` `+v17` enables a specific format for `Date` or `Number` types. ```html
// Or link to environment variable
// +v17 supports path to value in the form of environment variables
``` #### command: `hide` Toggles `hidden` class. Expression must return `Boolean`. ```html
``` #### command: `href` Sets `href` attribute. It's targeted for links `` only. Expression must return `String`. ```html
``` #### command: `html` Sets the value as the HTML content. Expression must return `String`. ```html
``` #### command: `init` `+v17` Executes method when the binder is initialized. This command is performed only one time. ```html
``` #### command: `import` Performs `IMPORT()`. Expression must be __URL address__ `String` or (`+v16`) `value` must return a valid URL adress. This command imports each resource only one time. ```html
``` `+v18` adds a support for ` ``` `+v18` supports __ENV__ ```html
``` #### command: `invisible` `+v16` sets `invisible` class to this element if the condition is valid. `invisible` class is a part of `spa.min.css` and it's declaration is `.invisible { visibility: hidden; }`. __Usage__: ```html
``` #### command: `refresh` `+v18` Expression must be a link to a function. This function will be executed if __the element is visible__ and the `data-bind` __path__ will be changed. ```html
``` #### command: `resize` `+v18` executes `resize` method in all nested components. IMPORTANT: __the element must visible__. #### command: `required` `+v18` performs `required` reconfiguration for the current element component. It expects boolean value type. ```html
Company name
``` #### command: `set` `+v18` can set a value to a component. It will works with `vbindarray` too, but only in readonly mode. - `.` dot in component's path allows to bind a value from `data-bind` - `set` command is very important for binding ```html
OR
``` #### command: `setter` `+v16` performs `element.SETTER()` for nested components. ```html
``` #### command: `show` Toggles `hidden` class. Expression must return `Boolean`. ```html
``` #### command: `src` Sets `src` attribute, targeted for ` ``` #### command: `strict` This command performs a strict comparing of path. Must be __without expression__. ```html
``` - allowed paths `myobj` or `myobj.address` - another paths like `myobj.customer` or something else doesn't affect this binder #### command: `template` Compiles HTML content as a Tangular template. Can be defined __without expression__. `+v17` expression can contain a jQuery `selector` which enables Virtual DOM comparing for content. ```html
``` - `value` represents Tangular model __Virtual DOM__: Template is compiled to Virtual DOM and then it's compared with current DOM. This feature can improve rendering (blinking) when the content is re-rendering. #### command: `text` Sets a value as the TEXT content (HTML markup will be escaped). Expression must return `String`. ```html
``` #### command: `title` Sets `title` attribute. ```html
``` #### command: `track` Enables a strict path comparison for defined paths separated by comma (use a `field` name without parent path). Binder will render the content below if the main path `object` will be changed or specific field (`name` or `price`) will be changed. ```html
``` #### command: `tracktype` Tracks only changes according to defined `SET()` types. A value can contain multiple values separated by comma. ```html
``` Internal types: - `0` init value - `1` manually via e.g. `SET()` - `2` by input - `3` default value #### command: `val` Sets `value` for the input/textarea/select. Expression must return `String`. ```html ``` #### command: `vbindarray` `+v17` This is very special command. It has same functionality like `template` but the ` ``` #### command: `visible` `+v16` sets `invisible` class to this element if the condition is __not valid__. `invisible` class is a part of `spa.min.css` and it's declaration is `.invisible { visibility: hidden; }`. __Usage__: ```html
``` #### command: `.class_name` Toggles `.class_name` if the expression returns `true`. You can use multiple `.class_name` commands. ```html
Multiple:
``` ## Types of command expressions You can use multiple types of command expressions. You need to choose what suits is for you. In most cases `value` argument contains the real value from a model according to the `data-bind` path. :warning: __IMPORTANT:__ `click` command uses other order of arguments. __Arrow function in the form__: ```html COMMAND:(value,path,jQueryElement)=>value.toUpperCase() COMMAND:n=>n.toUpperCase() ``` __Direct value__: ```html COMMAND:value.toUpperCase() COMMAND:value COMMAND:value > 10 ``` __Link to method__: ```html COMMAND:upper_value ``` - but `function upper_value(value, path, element)` must be defined in the window scope ## Advanced usage - [Good to know](#) - [Linking commands to same expression](#) - [Extending command by adding a selector](#) - [Nullable values](#) - [Multiple watchers](#) - [jComponent scopes](#) - [Inline helpers](#) - [Using data-bind in jComponents](#) - [Disable Data Binding](#) - [Refreshing Data Binding](#) - [Less code in Data Binding](#) - [Virtual binder: VBIND](#) - [Virtual binder: VBINDARRAY](#) ### Good to know `+v16` Most of commands are performend when the __element is visible__ --> in other words: the __command__ `show` must return `true` or `hide` must return `false`. If you want to evaluate a command for hidden element then you can extend command by adding `~` before the name of command, for example: ```html
...
``` ### Linking commands to same expression You can link commands to same expression with help of `+` char with spaces on both sides. ```html
``` ### Extending command by adding a selector You can extend most of commands by adding a custom __jQuery selector__. ```html Declaration:
Usage:

``` ### Nullable values Nullable / Undefined values can be handled easily. Just use `!COMMAND` and evaluating will be performed if the value won't be `null` or `undefined`. ```html
``` ### Multiple watchers You can define multiple data-bind paths in the same HTML element. Paths must be divided by this `__|__` phrase. For example: ```html
``` ### jComponent scopes You can use `data-bind` in jComponent scopes, but you need to defined `?` (question mark) on the start of `data-bind` path. Question mark `?` will be replaced for a scope path. ```html
``` `+v17` supports scope in command values: ```html
``` __Good to know__: - it will work only if the jComponent scope will contain some jComponents ### Inline helpers Data-Binding supports inline helpers: ```html 1. Direct assignment
2. With arrow function
3. Plugins
``` ### Using data-bind in jComponents The example below will work in component's scope only. ```html Binds a value according to the data-jc-path attribute. It works in the component scope only.
Binds a component config. It works in component scope only.
Binds a value defined via component.data('property', value). It works in the component scope only.
``` `+v17` supports private binding methods: ```html
``` ### Less code in Data Binding `+v17` supports shorter commands: ```html
``` ### Disable Data Binding `+v17` supports disabling of data binding: ```html
``` ### Refreshing Data Binding `+v17` supports refreshing of data-bind. It can be helpful for specific components and behaviours. ```html
``` ### Virtual binder: VBIND `+v16` supports this method. Virtual binder `VBIND` is a special thing and it can bind data from a custom model which doesn't need to be defined in the window scop. Compiled element doesn't need to be a part of DOM. - paths __must start__ with (dot) `.path` - it expects a custom object ```javascript // VBIND(template); var obj = VBIND('
'); // Sets a model obj.set({ name: 'Peter' }); // Sets a specific value with path obj.set('name', 'Peter'); // +v18 Updates a specific path obj.upd(path); // +v18 Updates entire object obj.upd(); // Removes the binder obj.remove(); // jQuery element obj.element.html(); //
PETER
// Attachs element into the DOM $(document.body).append(obj.element); ``` `+v17` supports private binding methods: ```javascript var obj = VBIND('
'); obj.mymethod = function(value, path, el) { // this === jQuery element return 'VALUE_FOR_COMMAND'; }; // Sets a model obj.set({ name: 'Peter' }); ``` #### Obtaining `VBIND` instance from element ```javascript var vbind = element.vbind(); vbind.set(YOUR_OBJECT); ``` ### Virtual binder: VBINDARRAY `+v16` supports this method. `VBINDARRAY` prepares a `template` as `VBIND` object and it renders items/templates very effective according to the array. It's someting similiar like Virtual DOM. - paths __must start__ with (dot) `.path` in the template - each `VBIND` element will contain `data-index` attribute with the item array index ```javascript // VBINDARRAY(template, target_element); var obj = VBINDARRAY('
', document.body); obj.set([{ name: 'Peter' }, { name: 'Anna' }, { name: 'Lucia' }]); ``` `+v17` supports private binding methods: ```javascript var obj = VBINDARRAY('
', document.body); obj.mymethod = function(value, path, el) { // this === jQuery element return 'VALUE_FOR_COMMAND'; }; // Possibilities: // obj.set(index, item); // obj.set(array); // Sets a model obj.set([{ name: 'Peter' }, { name: 'Anna' }, { name: 'Lucia' }]); // v18 additional methods: // obj.upd(index); // obj.upd(); ``` #### Obtaining `VBINDARRAY` instance from element ```javascript var vbindarray = element.vbindarray(); vbindarray.set([YOUR_ARRAY]); ```