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.csa...@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
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
