|
|
| Line 1: |
Line 1: |
| − | <!-- !!! -->
| + | The content on this page has moved to https://documentation.open-xchange.com/latest/ui/extension-points/13-best-practices.html |
| − | <!-- PLEASE APPLY CHANGES ONLY TO THE NEW TECHNICAL DOCUMENTATION: wd/frontend/web/documentation -->
| |
| − | <!-- !!! -->
| |
| | | | |
| − | {{Stability-experimental}}
| + | 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. |
| − | | |
| − | <div class="title">Extension points:<br> Best practices</div>
| |
| − | | |
| − | '''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 [https://documentation.open-xchange.com/latest/ui/extension-points/02-points.html 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]]
| |