|
|
| (33 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 |
| __TOC__
| |
|
| |
|
| ==Preface==
| | 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. |
| In case you want try the provided code examples byr your own please follow these steps:
| |
| * get a browser with some possibilty to execute custom javascript during runtime (for example chrome with it's developer tools)
| |
| * successful login on OX App Suite
| |
| * enter one of the code blocks from beyond
| |
| | |
| ==Extension Points==
| |
| | |
| 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.
| |
| | |
| | |
| ==Extending the UI==
| |
| | |
| === 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/detai'')
| |
| 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, perhaps you have to select another mail to get effect.
| |
| <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 new mail footer using ===
| |
| Let's try and add a section to the mails detail view and use some 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, 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. First, let's 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>
| |
| | |
| | |
| Again: When navigating back to the email view you might have to select another mail to make this change visible.
| |
| Next, let's 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) {
| |
| ext.point("io.ox/mail/detail").replace({
| |
| id: 'receiveddate', // The extension we want to replace has this id as well
| |
| draw: function (data) {
| |
| var timeToRender = (data.received_date || data.sent_date || 0);
| |
| | |
| this.append(
| |
| $('<div>').addClass('date list').text(timeToRender)
| |
| );
| |
| }
| |
| });
| |
| | |
| });
| |
| </pre>
| |
| | |
| | |
| 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)
| |
| | |
| ext.point("io.ox/mail/detail").get("subject", function (extension) {
| |
| // Put it last
| |
| extension.index = 300;
| |
| });
| |
| | |
| });
| |
| </pre>
| |
| | |
| | |
| As you can see, unlike adding functionality, customizing and modifying existing extensions is always more of a grey box operation and might incur some risks when updating the software. For example when replacing a certain functionality parts of the original functionality will have to be reimplemented, and all that extra code will have to be maintained in the future. In essence extension points are better suited to integrating new functionality into the product rather than customizing existing functionality, but, when in a pinch or really wanting to change a certain part of the software, this is certainly a way to consider. At its most extreme use you could even disable all extensions for the mail detail view to register a set of your own extensions to completely change the way mails are displayed, at the cost of having to maintain your own detail view.
| |
| | |
| This wraps up our little tour of the OX App Suite extension point system. It is used to integrate new functionality into the OX App Suite and provides a system for 3rd party applications to become extensible themselves. It can be used to customize the existing UI at the cost of havint to know a bit more about the internals of our application. For now until more comprehensive documentation becomes available, look at the existing OX App Suite code to see concrete extensions and extension points in action.
| |
| | |
| [[Category:AppSuite]]
| |
| [[Category:UI]]
| |