|
|
| (15 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| <div class="title">Extending the UI: Hands-on introduction</div>
| | The content on this page has moved to https://documentation.open-xchange.com/latest/ui/extension-points/01-introduction.html |
|
| |
|
| '''Abstract'''
| | 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. |
| | |
| ''Abstractly speaking extension points are an architecture for letting plugins contribute functionality to other parts of the program. They form the core of the OX App Suite plugin architecture. This is a hands-on introduction based on simple code examples. For more details take a look at [[ AppSuite:Extending_the_UI| Extending the UI]].''
| |
| | |
| | |
| __TOC__
| |
| ==Hands-on extending the UI==
| |
| In case you want try code by your own please follow these steps:
| |
| * get a appropriate browser to execute custom javascript during runtime (for example chrome with it's [https://developers.google.com/chrome-developer-tools/docs/console developer tools])
| |
| * login on OX App Suite
| |
| * copy code from beyond to you console and execute
| |
| * perhaps it could be necessary to switch app or reload the page
| |
| | |
| === Your first extension ===
| |
| Let's start with some example code.
| |
| <pre class="language-javascript"> // The extension point system lives in the
| |
| // 'io.ox/core/extensions' module
| |
| require(["io.ox/core/extensions"], function (ext) {
| |
|
| |
| // An extension point represents the system that can be extended
| |
| // It has an id (in this case 'io.ox/mail/detail')
| |
| var point = ext.point("io.ox/mail/detail");
| |
| | |
| // Now, let's extend that extension point. Every extension point
| |
| // has some kind of contract about what it expects its extensions to provide.
| |
| // In this case, the extension is supposed to provide a draw method
| |
| // and is passed the node to draw into as the 'this' variable
| |
| point.extend({
| |
| id: 'example1', // Every extension is supposed to have an id
| |
| index: 1, // Extensions are ordered based on their indexes
| |
| draw: function () {
| |
| // This function is called by the part of the code that
| |
| // offers this extension point
| |
| this.append($("<h3>").text("Hello, Traveller!"));
| |
| }
| |
| });
| |
| });
| |
| </pre>
| |
| | |
| Please have a look at the detail view of a mail now. Perhaps you have to select another mail to see the difference. | |
| <gallery>
| |
| File:Ui_ext_handson_1_1.png|step 1: default mail detail
| |
| File:Ui_ext_handson_1_2.png|step 2: execute code in chrome dev tools console
| |
| File:Ui_ext_handson_1_3.png|step 3: extended mail detail
| |
| </gallery>
| |
| | |
| <!--
| |
| === Mail app get's a new action ===
| |
| Like this point in mail, many parts of the UI offer extension points. Let's extend the OX App Suite UI in a few other places. First, let us add a button to the mail app toolbar.
| |
| | |
| '''Attention''' This example will only work if you haven't visited the mail app yet. If you have, just reload this page, then run the example and then visit the mail app.
| |
| | |
| <pre class="language-javascript">
| |
| require(['io.ox/core/extensions', 'io.ox/core/extPatterns/links'], function (ext, links) {
| |
| | |
| // Firstly we'll add a new button to the toolbar
| |
| | |
| // This addas a new button to the toolbar and offers itself an extension point 'io.ox/mail/actions/exampleAction', which
| |
| // can be extended to contain the functionality for this button
| |
| // This way, more than one button or link can reference the same
| |
| // action
| |
| ext.point('io.ox/mail/links/toolbar').extend(new links.Link({
| |
| index: 200,
| |
| id: 'example',
| |
| label: 'Do something',
| |
| ref: 'io.ox/mail/actions/exampleAction'
| |
| }));
| |
| | |
| // This defines the extension for the above newly created extension point
| |
| // and contains the code to run, once the button is clicked
| |
| new links.Action('io.ox/mail/actions/exampleAction', {
| |
| id: 'exampleAction',
| |
| action: function () {
| |
| alert("Hello, traveller!");
| |
| }
| |
| });
| |
| | |
| });
| |
| </pre>
| |
| -->
| |
| === A qualified mail footer ===
| |
| Let's try and add a section to the mails detail view and use some data of the currently viewed mail. For information about the baton object please take a look at the [[ AppSuite:Extending_the_UI| more detailed]] article how to extend the UI.
| |
| | |
| <pre class="language-javascript">
| |
| require(['io.ox/core/extensions'], function (ext) {
| |
| | |
| ext.point("io.ox/mail/detail").extend({
| |
| id: "lessonExample",
| |
| index: 300,
| |
| draw: function (baton) {
| |
| var data = baton.data;
| |
| this.append("<br>");
| |
| this.append($("<em>").append(
| |
| $.txt("The eMail '"),
| |
| $("<b>").text(data.subject),
| |
| $.txt("' was brought to you by: "),
| |
| $("<b>").text("Your Name Inc.")
| |
| ));
| |
| }
| |
| });
| |
| | |
| });
| |
| </pre>
| |
| | |
| <gallery>
| |
| File:Ui_ext_handson_3_1.png|step 1: default mail detail
| |
| File:Ui_ext_handson_3_2.png|step 2: execute code in chrome dev tools console
| |
| File:Ui_ext_handson_3_3.png|step 3: extended mail detail
| |
| </gallery>
| |
| | |
| After switching to the mail app again, you might have to select another mail to once again run through the rendering process that calls on the extensions. As you can see in the example above, the code calling the extension passes along the eMail in the ''data'' attribute of the [[AppSuite:Extending_the_UI#Baton | baton]] parameter. The ''index'' of the extension means that it is rendered after the mail body, who's extensions index is '''300'''. Currently (until we have more comprehensive documentation) you can only find the indexes (and the way an extension is supposed to behave) by reading our code. Reload the page (to clear out the registered extensions) and try switching the index to '''190''' and see where the added sentence shows up now.
| |
| | |
| ==Customizing extensions==
| |
| Since extensions are a property of the runtime system, you can also modify them. The extension system offers a couple of things you can do with existing extensions like '''changing their order, disabling them or replacing them.''' Let's look at how to accomplish all of these, again by modifying the mail detail view.
| |
| | |
| ===switch off the inline links===
| |
| <pre class="language-javascript">
| |
| require(["io.ox/core/extensions"], function (ext) {
| |
| // Here the id of the extension comes into play again.
| |
| // If you look at the code of the mail detail view (in io.ox/mail/view-detail)
| |
| // You can see the extension registers itself with the id 'inline-links'
| |
| // So that is the argument we pass to disable
| |
| ext.point("io.ox/mail/detail").disable('inline-links');
| |
| });
| |
| </pre>
| |
| | |
| <gallery>
| |
| File:Ui_ext_handson_4_1.png|step 1: default mail detail
| |
| File:Ui_ext_handson_4_2.png|step 2: execute code in chrome dev tools console
| |
| File:Ui_ext_handson_4_3.png|step 3: mail detail with disabled inline links
| |
| </gallery>
| |
| | |
| ''Again: When navigating back to the email view you might have to select another mail to make this change visible.''
| |
| | |
| ===replace the way the time is rendered===
| |
| | |
| <pre class="language-javascript">
| |
| require(["io.ox/core/extensions", "io.ox/mail/util", "io.ox/core/date"], function (ext, util, date) {
| |
| debugger;
| |
| ext.point("io.ox/mail/detail/header").replace({
| |
| //current extension will extended not fully replaced
| |
| // so we do not have to specify the index to keep time on it's place
| |
| id: 'receiveddate', // The extension we want to replace has this id as well
| |
| draw: function (baton) {
| |
| var data = baton.data;
| |
| //show unix timestamp (plus trailing '000' for milliseconds )
| |
| var timeToRender = (data.received_date || data.sent_date || 0);
| |
| this.append(
| |
| $('<div>').addClass('date list').text(timeToRender)
| |
| );
| |
| }
| |
| });
| |
| });
| |
| </pre>
| |
| | |
| <gallery>
| |
| File:Ui_ext_handson_5_1.png|step 1: default mail detail
| |
| File:Ui_ext_handson_5_2.png|step 2: execute code in chrome dev tools console
| |
| File:Ui_ext_handson_5_3.png|step 3: extended mail detail with unix timestamp
| |
| </gallery>
| |
| | |
| === switch order ===
| |
| And now let's switch the order around:
| |
| | |
| <pre class="language-javascript">
| |
| require(["io.ox/core/extensions"], function (ext) {
| |
| // From the extension point 'io.ox/mail/detail' get the extension with
| |
| // the id 'subject' (which is passed to the callback)
| |
| debugger;
| |
| ext.point("io.ox/mail/detail/header").get("subject", function (extension) {
| |
| // Put it last
| |
| extension.index = 300;
| |
| });
| |
| | |
| });
| |
| </pre>
| |
| | |
| <gallery>
| |
| File:Ui_ext_handson_6_1.png|step 1: default mail detail
| |
| File:Ui_ext_handson_6_2.png|step 2: execute code in chrome dev tools console
| |
| File:Ui_ext_handson_6_3.png|step 3: pushed subject to header bottom
| |
| </gallery>
| |
| | |
| [[Category:AppSuite]]
| |
| [[Category:UI]]
| |