|
|
| (39 intermediate revisions by 9 users not shown) |
| Line 1: |
Line 1: |
| <div class="title">Writing a portal plugin</div>
| | The content on this page has moved to https://documentation.open-xchange.com/latest/ui/customize/portal-widget.html |
|
| |
|
| '''Summary:''' This articles covers how to write a plugin that shows on the portal page. A portal plugin always gives a short overview on a piece of information (the so-called 'tile'). It can link a longer view that is opened when the tile is clicked, this we call the side pop-up. The side pop-up is optional.
| | 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. |
| | |
| == Where and how to start ==
| |
| Plugins are collected in the folder ui/apps/plugins. Start your new plugin there: Create a folder and in this folder, create two files: register.js (where everything happens) and manifest.json
| |
| | |
| == The simplest portal plugin: An advertisement ==
| |
| The simplest portal plugin comes without a side pop-up and shows static content on its tile. Two uses for this would be presenting an advertisement (or your daily creed, an often used check list....) or showing a link list (for example to other parts of an company's intranet that are not integrated into the AppSuite (yet)). We will now build an advertisement, which is just a slogan.
| |
| | |
| The beauty of this is that we do not have any dependencies (for example needing another module like the file store), so the content of our manifest.json is rather simple:
| |
| | |
| <pre class="language-javascript">
| |
| {
| |
| namespace: "portal"
| |
| }
| |
| </pre>
| |
| | |
| Nothing to see here. We say we belong in the portal namespace and that's it. We do not need to define any dependencies on other modules.
| |
| | |
| Our register.js is only slightly longer:
| |
| | |
| <pre class="language-javascript">
| |
| define("plugins/portal/myAd/register", ['io.ox/core/extensions'], function (ext) {
| |
| | |
| "use strict";
| |
| | |
| ext.point('io.ox/portal/widget/myAd').extend({
| |
| preview: function () {
| |
| var content = $('<div class="content">')
| |
| .text("Buy stuff. It's like solid happiness.");
| |
| this.append(content);
| |
| }
| |
| });
| |
| | |
| ext.point('io.ox/portal/widget/myAd/settings').extend({
| |
| title: 'My advertisement',
| |
| type: 'myAd'
| |
| });
| |
| });
| |
| </pre>
| |
| | |
| So what do we have here? We have two extension points:
| |
|
| |
| The first one is for the ad itself, ''io.ox/portal/widget/myAd''. This one contains a single method that we implement, ''preview''. ''Preview'' is responsible for the tile you see whenever you look at your portal. Technically, ''this'' contains the container to which you can attach your content. If you are brave, you can do changes on the container, too. But that is not needed for now.
| |
| | |
| The second is less obvious: It creates an option in the settings area for the portal (the one you reach by "customize this page"). There you will have to enable your setting (yes, this is a very polite advertisement). The ''title'' is what is shown as the name of your plugin (so chose a readable one), the type references the one you used in the definition.
| |
| | |
| == A more typical portal plugin ==
| |
| A typical portal plugin uses the tile to display a short summary or teaser of its contents and uses a side-popup to show the whole content.
| |
| | |
| The manifest.json can stay the same, but the register.js needs to do a little more now:
| |
| <pre class="language-javascript">
| |
| define("plugins/portal/myAd/register", ['io.ox/core/extensions'], function (ext) {
| |
| | |
| "use strict";
| |
| | |
| ext.point('io.ox/portal/widget/myAd').extend({
| |
| title: "My Advertisement",
| |
| | |
| load: function (baton) {
| |
| var def = $.Deferred();
| |
| def.resolve("It's like solid happiness.").done(function (data) {
| |
| baton.data = {teaser: 'Buy stuff', fullText: 'Buff stuff. It is like solid happiness.'};
| |
| });
| |
| return def;
| |
| },
| |
| | |
| preview: function (baton) {
| |
| var content = $('<div class="content pointer">')
| |
| .text(baton.data.teaser);
| |
| this.append(content);
| |
| },
| |
| | |
| draw: function (baton) {
| |
| var content = $('<div class="myAdd">')
| |
| .text(baton.data.fullText);
| |
| this.append(content);
| |
| }
| |
| });
| |
| | |
| ext.point('io.ox/portal/widget/myAd/settings').extend({
| |
| title: 'My advertisement',
| |
| type: 'myAd'
| |
| });
| |
| });
| |
| </pre>
| |
| | |
| What happened here? We have gained two new methods and all three methods seems to be passing something called ''baton'' around. The baton is actually just that - something to pass around. The baton carries data between different methods.
| |
| | |
| === Order of execution ===
| |
| How do the three functions interact? When a plugin is supposed to be rendered, the first method to be called is "load". Load usually does some (asynchronous) loading of data, be it from the file store or some external source. Meanwhile, the empty tile (well, if you give it a title, that is already rendered, so it is not completely naked) is rendered on the portal page.
| |
| | |
| When the loading is done, it is consensus that the loaded data is stored as baton.data. Then ''preview'' is called and usually does something with the data in the baton. It then renders its content, which is appended to the tile.
| |
| | |
| When the tile is clicked on, a side-popup is drawn (which, again, is nearly naked). Meanwhile, the function ''draw'' is called. As with ''preview'', 'draw'' usually uses the data from the baton.
| |
| | |
| Regarding the given example, this means that
| |
| | |
| | |
| | |
| == Advanced plugins ==
| |
| * unique
| |
| * unmovable
| |
| | |
| == Finishing touches ==
| |
| Now that you have learned all there is about portal plugins, it is time to clean up. Check whether your plugin only [[AppSuite:UI manifests explained | works when a certain module is active]]. Also, maybe we can interest you in [[AppSuite:i18n | preparing the text for readers from other countries]]? Splendid! Now you are good to go.
| |
| | |
| [[Category:AppSuite]]
| |
| [[Category:UI]]
| |