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

[Dominik Csapak <d.csapak@proxmox.com>]

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@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
+ * 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',
 
-- 
2.30.2