[pve-devel] [PATCH widget-toolkit] cbind: document cbind by adding a small summary and example

[Aaron Lauterer]

Sounds good and sums it up nicely :)

I did find two grammatical issues, but that is nit picking on the highest level ;) It is okay and very understandable the way it is.

Reviewed-By: Aaron Lauterer <a.lauterer at proxmox.com>

On 10/25/21 09:26, Dominik Csapak wrote:
> Explain the use-case, the difference to normal binds, and give an
> example that contains all features that can be used with explanations.
> 
> Signed-off-by: Dominik Csapak <d.csapak at proxmox.com>
> ---
>   src/mixin/CBind.js | 78 ++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 78 insertions(+)
> 
> diff --git a/src/mixin/CBind.js b/src/mixin/CBind.js
> index 8b4153c..71c0b56 100644
> --- a/src/mixin/CBind.js
> +++ b/src/mixin/CBind.js
> @@ -1,3 +1,81 @@
> +/*
> + * The Proxmox CBind mixin is intended to supplement the 'bind' mechanism
> + * of ExtJS. In contrast to the 'bind', 'cbind' only act during creation
s/act/acts/
s/during/during the/

> + * of the component, not during its lifetime.
> + *
> + * It is used to dynamically set properties of components during their
> + * creation (like a 'nodename' for example), but not later. It is also no
> + * 'double-bind', meaning that a field which has its value 'cbind' will
> + * not change the value of the 'cbind' when the value of the field changes.
> + *
> + * We use it to get a 'declarative' approach to component declaration, even
> + * when we need to set some properties of sub-components dynamically.
> + * This reduces the code in the 'initComponent' and instead we can statically
> + * declare items,buttons,tbars, etc. with the dynamic parts in the 'cbind'.
> + *
> + * It is used like in the following example:
> + *
> + * Ext.define('Some.Component', {
> + *     extend: 'Some.other.Component',
> + *
> + *     // first it has to be enabled
> + *     mixins: ['Proxmox.Mixin.CBind'],
> + *
> + *     // then a base config has to be defined. this can be a function,
> + *     // which has access to the initial config and can store persistent
> + *     // properties, as well as return temporary ones (which only exist during
> + *     // the cbind process)
> + *     // this function will be called before 'initComponent'
> + *     cbindData: function(initialconfig) {
> + *         // 'this' here is the same as in 'initComponent'
> + *         let me = this;
> + *         me.persistentProperty = false;
> + *         return {
> + *             temporaryProperty: true,
> + *         };
> + *     },
> + *
> + *     // if there is no need for persistent properties,
> + *     // it can also simply be an object
> + *     cbindData: {
> + *         temporaryProperty: true,
> + *         // properties itself can also be functions that will be evaluated
> + *         // before replacing the values
> + *         dynamicProperty: (cfg) => !cfg.temporaryProperty,
> + *         // they can be any value
> + *         numericProp: 0,
> + *         // even objects
> + *         objectProp: {
> + *             foo: 'bar',
> + *             bar: 'baz',
> + *         }
> + *     },
> + *
> + *     // you can 'cbind' the component itself, here the 'target' property
> + *     // will be replaced with the content of 'temporaryProperty' (true)
> + *     // before the component is initialized
> + *     cbind: {
> + *          target: '{temporaryProperty}',
> + *     },
> + *
> + *     // you can also 'cbind' values of nested items/etc. like this
> + *     items: [
> + *         {
> + *             xtype: 'checkbox',
> + *             cbind: {
> + *                 // you can negate a property with prefixing '!'
> + *                 value: '{!persistentProperty}',
> + *                 // access to properties of objects can be done like this
> + *                 object: '{objectProp.foo}'
> + *                 // and it can be a function too, when you need more
> + *                 // complicated logic ('dynamic' will get set to 1 here)
> + *                 dynamic: (get) => get('numericProp') + 1,
> + *             },
> + *         },
> + *     ],
> + * });
> + */
> +
>   Ext.define('Proxmox.Mixin.CBind', {
>       extend: 'Ext.Mixin',
>   
>