AppSuite:Extending the UI (best practices): Difference between revisions

From Open-Xchange
No edit summary
No edit summary
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Stability-experimental}}
The content on this page has moved to https://documentation.open-xchange.com/latest/ui/extension-points/13-best-practices.html


<div class="title">Extension points:<br> Best practices</div>
Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition.
 
'''Abstract'''
 
''The extension points system allows different strategies to realize the desired behavior. This is a list of solutions for common scenarios pointing out also some disadvantages of different solutions.''
 
 
__TOC__
 
=== scenario: writing extension in general ===
 
''separate extension declaration and logic for reusability''
 
* example: io.ox/mail/common-extensions.js and io.ox/mail/detail/view.js
 
<code>
    var fnProcess = function (baton) { ... };
    // use function within some extension
    ext.point('io.ox/mail/detail/content').extend({
        id: 'links',
        index: 100,
        process: fnProcess
    });
    // use function within another extension
    ext.point('io.ox/mail/detail/content').extend({
        id: 'images',
        index: 100,
        process: fnProcess
    });
 
</code>
 
 
 
 
 
=== scenario: hide/show action ===
 
''simply register a fresh new extension with an index less than the original action extension.''
 
<code>
    // original extension
    new Action('io.ox/mail/actions/compose', {
        id: 'compose',
        index: 100,
        requires: function () {
            return true;
        },
        ...
    });
 
    // your extension to hide it
    ext.point('io.ox/mail/actions/compose').extend({
        // must be a different id than used in original extension
        id: 'compose_preprocess',
        // important: must be smaller than the one used in original extension that is usually 'default'
        index: 50,
        requires: function (e) {
            // is your condition meet?
            if (myCondition === true) {
                // stop propagation to suppress execution of
                // requires-handlers of extensions with a higher index
                e.stopPropagation();
                // force hide (or force show by using 'return true')
                return false;
            }
        }
    });
</code>
 
 
'''unfavorable variants'''
 
''using ext.point(...).replace''
 
* original requires function is replaced and can not be accessed anymore
* also copy and paste it contents does not help cause future changes are not carried over automatically
* see [[AppSuite:Extending_the_UI#replace_extension | documentation for .replace ]]
<code>
    // please do not use replace to overwrite 'requires'
    ext.point('io.ox/mail/actions/compose').replace({
        requires: function () {
            // my custom logic
        }
    })
</code>
 
=== scenario: stop propagation of action ===
 
''simply register a fresh new extension with an index less than the original action extension.''
 
<code>
    // original extension
    new Action('io.ox/mail/actions/compose', {
        index: 100,
        requires: function () {
            return true;
        },
        ...
    });
 
    // your extension to hide it
    ext.point('io.ox/mail/actions/compose').extend({
        // must be a different id than used in original extension that is usually 'default'
        id: 'compose_preprocess',
        // important: must be smaller than the one used in original extension
        index: 50,
        action: function (baton) {
            // be robust when clicked again and conditions may have changed
            baton.enable('default');
            if (myCondition === true) {
                baton.disable('default');
            }
        }
    });
</code>
'''hint'''
In case the condition for a single action target (f.e. a mail item) do not change you can use 'baton.preventDefault()' alternatively when you condition is met.
 
[[Category:AppSuite]]
[[Category:UI]]
[[Category:Extension points]]

Latest revision as of 09:48, 22 May 2017

The content on this page has moved to https://documentation.open-xchange.com/latest/ui/extension-points/13-best-practices.html

Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition.