OX6:Gui Plugin Development
Introduction
With Open-Xchange you will be able to add your own JavaScript code for existing events. The following examples show how you can add your own About page, your own Window Title, and your own message for not activated/bought components of OX (Upsell Message).
Setup and file description
Two things have to be done to register your own JavaScript code within the server:
1. You have to create the property file in /opt/open-xchange/etc/groupware/settings/, for example myjscode.properties. The file should have the following value:
modules/$NAME/enabled=true
$NAME is equal to the file name of the property file, in our case it would be:
modules/myjscode/enabled=true
This will enable the JS code located in $WEBSRV/ox6/plugins/$NAME (for example /var/www/ox6/plugins/myjscode/).
2. Next we have to create the folder that we configured, in our example we would have to create:
mkdir /var/www/ox6/plugins/myjscode/
The server now will have a look at this directory and searches for the register.js file in this directory. All your JS enhancements should be written to that file.
3. Afterwards you have to restart the groupware server with:
/etc/init.d/open-xchange-groupware restart
Examples
Customized About page
/opt/open-xchange/etc/groupware/settings/productinfo.properties:
# This program is free software; you can redistribute it and/or modify it # under the terms of the GNU General Public License, Version 2 as published # by the Free Software Foundation. # # Copyright (C) 2004-2007 Open-Xchange, Inc. # Mail: info@open-xchange.com # # @author: Stefan Preuss <stefan.preuss@open-xchange.com> modules/productinfo/enabled=true
/var/www/ox6/plugins/productinfo/register.js:
/** * * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License, Version 2 as published * by the Free Software Foundation. * * Copyright (C) 2004-2007 Open-Xchange, Inc. * Mail: info@open-xchange.com * * @author: Stefan Preuss <stefan.preuss@open-xchange.com> * */ oxProductInfo.vendor_address = "Open-Xchange GmbH\nMartinstrasse 41\n57462 Olpe\nE-Mail: info@open-xchange.com\n<a href=\"http://www.open-xchange.com\" target=\"_blank\">www.open-xchange.com</a>"
Customized Window Title
/opt/open-xchange/etc/groupware/settings/windowtitle.properties:
# This program is free software; you can redistribute it and/or modify it # under the terms of the GNU General Public License, Version 2 as published # by the Free Software Foundation. # # Copyright (C) 2004-2007 Open-Xchange, Inc. # Mail: info@open-xchange.com # # @author: Stefan Preuss <stefan.preuss@open-xchange.com> modules/windowtitle/enabled=true
/var/www/ox6/plugins/windowtitle/register.js:
/**
*
* This program is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License, Version 2 as published
* by the Free Software Foundation.
*
* Copyright (C) 2004-2007 Open-Xchange, Inc.
* Mail: info@open-xchange.com
*
* @author: Stefan Preuss <stefan.preuss@open-xchange.com>
*
*/
oxProductInfo.product_name = "This is the fabulous Open-Xchange Server";
try {
window.document.title = oxProductInfo.product_name;
} catch (e) { }
Customized Upsell Message
/opt/open-xchange/etc/groupware/settings/upsell.properties:
# This program is free software; you can redistribute it and/or modify it # under the terms of the GNU General Public License, Version 2 as published # by the Free Software Foundation. # # Copyright (C) 2004-2007 Open-Xchange, Inc. # Mail: info@open-xchange.com # # Author: Stefan Preuss <stefan.preuss@open-xchange.com> # The following property enables the Upsell-Layer Plugin for the OX6 AJAX GUI modules/upsell/enabled=true
/var/www/ox6/plugins/upsell/register.js:
/**
*
* This program is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License, Version 2 as published
* by the Free Software Foundation.
*
* Copyright (C) 2004-2007 Open-Xchange, Inc.
* Mail: info@open-xchange.com
*
* @author: Stefan Preuss <stefan.preuss@open-xchange.com>
*
*/
/*
* Example for an Upsell-Layer
* The OX GUI triggers a special event if a user clicks on disabled features.
*/
/*
* Register to Upsell-Event
*/
register("Feature_Not_Available", showUpsellLayer);
/**
* Function to display an Upsell-Alert dialog
* @param feature String (optional) - Module description
* @param win Window (optional) - Only needed/given if we trigger the event from the new object windows
*/
function showUpsellLayer(feature, win) {
// setting corewindow to default if win is not defined
win = win || corewindow;
/*
* Build up the dialog content
* Note: You can also use myDiv.innerHTML!
*/
var myDiv = newnode("div",{ textAlign: "center", padding: "10px" }, 0, [
newnode("div", 0, { background: "url(http://www.example.com/img/header/logo.gif)" }, 0,
win.document),
newnode("span", 0, 0, [
document.createTextNode("Diese Funktion ist nur in Open-Xchange Premium verfügbar!") ],
win.document),
newnode("input", { marginTop: "10px"},
{ type: "button", onclick: function() { window.open("http://www.open-xchange.com") },
value: "Weitere Information zu Open-Xchange Premium!" }, 0,
win.document),
newnode("input", { marginTop: "10px"},
{ type: "button", onclick: function() { window.open("http://www.open-xchange.com") },
value: "Paket-Upgrade auf Open-Xchange Premium!" }, 0,
win.document)
], win.document);
// calling the newAlert function to open the dialog at the given window
win.newAlert("Hinweis " + feature, null, AlertPopup.close, myDiv);
}
/*
* Comment this out to change the grayed out module images in the upper left corner!
*/
/*
if (!document.getElementById("sp_c_portal").src.match(/mod_portal_sel.gif$/)) {
document.getElementById("sp_c_portal").src = getFullImgSrc("img/portal/mod_portal.gif");
}
document.getElementById("sp_c_calendar").src = getFullImgSrc("img/calendar/mod_calendar.gif");
document.getElementById("sp_c_tasks").src = getFullImgSrc("img/tasks/mod_tasks.gif");
document.getElementById("sp_c_infostore").src = getFullImgSrc("img/infostore/mod_infostore.gif");
*/
Currently, the parameter feature can have following values:
- configuration/mail/accounts/new
- modules/calendar
- modules/calendar/freebusy
- modules/calendar/mini_calender
- modules/calendar/new/add_attachment
- modules/calendar/new/add_participants
- modules/calendar/new/delete_attachment
- modules/calendar/new/remove_participants
- modules/calendar/save_to_infostore
- modules/calendar/team
- modules/contacts
- modules/contacts/save_to_infostore
- modules/contacts/new/add_attachment
- modules/contacts/new/delete_attachment
- modules/folders/users
- modules/infostore
- modules/infostore/send_as_attachment
- modules/infostore/send_as_link
- modules/infostore/mail/save_to_infostore
- modules/mail
- modules/mail/save_to_infostore
- modules/mail/new/add_infostore_attachment
- modules/portal
- modules/tasks
- modules/tasks/save_to_infostore
- modules/tasks/new/add_participants
- modules/tasks/new/remove_participants
- modules/tasks/new/add_attachment
- modules/tasks/new/delete_attachment
The following events may triggered by plugins (if enabled):
- modules/usm/eas
Customized / Extended configuration tree
In order to extend your configuration frontend you will have to make more changes than overwriting existing JS methods. You have to implement your own configuration site. Below, you will find the JS API Doc that will show you how to build external contents into the configuration frontend:
JavaScript API for extending the configuration frontend and Gui Plugin API Documentation
/opt/open-xchange/etc/groupware/settings/extendconfiguration.properties:
modules/extendconfiguration/enabled=true
/var/www/ox6/plugins/extendconfiguration/register.js:
// Extending the configuration tree.
// Add a new folder-like node called "Example", and inside it another node
// called "Page". The position of a node is specified by a path string.
// Each tree level is separated by slashes. There should be only two levels
// below the standard "configuration" root element: configuration/x for inner
// nodes and configuration/x/y for leaf nodes.
new ox.Configuration.InnerNode("configuration/example", "Example");
var node = new ox.Configuration.LeafNode("configuration/example/page", "Page");
// Connect the node to a new page.
var page = new ox.Configuration.Page(node, "Example Configuration Page");
// All data on the page is collected in a single data object. This object is
// transmitted to and from the server in the methods load() and save() using
// static methods of ox.JSON.
// For save(), the parameter cont is a continuation function which must be
// called after the data was saved successfully.
page.save = function(data, cont) {
ox.JSON.put(AjaxRoot + "/serverplugin?action=set&session=" + session,
data, cont);
}
// The continuation function of load() expects the data object as parameter.
// To extract the data object from the server reply, a new continuation function
// is used.
page.load = function(cont) {
ox.JSON.get(AjaxRoot + "/serverplugin?action=get&session=" + session,
function(reply) { cont(reply.data); });
};
// Content is added to the page with the method addWidget().
// Here, a static text is added at the top of the page.
page.addWidget(new ox.UI.Text("Long explanation text"));
// Individual input widgets can be connected to fields in the data object by
// specifying the field name as the second parameter to addWidget().
page.addWidget(new ox.UI.CheckBox("CheckBox Label"), "fieldname");
// Layout can be controlled by using container widgets.
// Configuration pages currently support only the Group container, which adds
// a header over its children.
// Every group has its own data object, which becomes nested in the page's
// data object.
var group = new ox.Configuration.Group("Group title");
page.addWidget(group, "subobject");
// Adding widgets to a goup happens exactly like for a page, since both are
// descendants of ox.UI.Container.
var input = new ox.UI.Input("Detail field");
group.addWidget(input, "input");
// All input widgets have a default value which is used when the data object
// does not contain the widget's field (e. g. on first login).
input.default_value = "default";
// ox.UI.Selection has many descendants which implement the same thing:
// A field which must contain one of several possible values.
// The possible values are set with the method setEntries().
var choice = new ox.UI.ComboBox("Choice");
group.addWidget(choice, "choice");
choice.setEntries([0, 1, Infinity], ["Zero", "One", "Infinity"]);
Customized new buttons in the panel
This example adds a new area to the contacts panel called "SMS". The area then has two buttons, "Display" and "Send". The "Display" button is active if one ore multiple contacts are selected and fires a js alert for each of them when being clicked. The "SMS" button is only active when one single contact is active and has a business telephone number stored in it. On click a js alert is executed and the telephone number is displayed.
/**
*
* This program is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License, Version 2 as published
* by the Free Software Foundation.
*
* Copyright (C) 2004-2007 Open-Xchange, Inc.
* Mail: info@open-xchange.com
*
* @author: Viktor
*
*/
//create a new menu Object for the panel and define the unique id (id1 here)
var contextmenu = MenuNodes.createSmallButtonContext("id1", "SMS");
/**
* Add menu Entries to the new generated panel object and define the icons
* as well as the to be called functions. The identifiers must be unique
* all over the complete js code (button1 and button2) in this example
*/
MenuNodes.createSmallButton(contextmenu,"button1", "Display",
"themes/default/img/menu/edit.gif",
"themes/default/img/menu/edit_d.gif",
click1);
MenuNodes.createSmallButton(contextmenu,"button2", "Send",
"themes/default/img/menu/edit.gif",
"themes/default/img/menu/edit_d.gif",
click2);
/* The pannel object gets the id 20 and gets displayed in the fixed area
* possible areas are FIXED and DYNAMIC the id controls the order in the areas
*/
addMenuNode(contextmenu.node, MenuNodes.FIXED, 20);
//Following makes the new pannel options dynamic active/inactive
changeDisplay("contacts", "id1");
menuarrows["contacts"] = {};
function changeplugin() {
menuglobalzaehler = 0;
menuarrows["contacts"]["id1"] = new Array();
//menucountselected here holds the amount of select items
menu_display_contents("contacts","id1", menucountselected >= 1,
"button1");
// following an example how to get data out of the GUI internal cache. button2
// is only active when a contact which as a business tel number is selected.
if (activemodule == "contacts") {
OXCache.newRequest(null, "contacts", {
objects: menuselectedobjects,
columns: ["telephone_business1"]
}, null, function(data) {
menu_display_contents("contacts","id1",
menucountselected == 1 &&
data.objects[0].telephone_business1,
"button2");
});
}
}
register("OX_SELECTED_ITEMS_CHANGED", changeplugin);
//now the called functions for the buttons follow
function click1() {
OXCache.newRequest(null, "contacts", {
objects: menuselectedobjects,
columns: ["id", "folder_id", "last_name"]
}, null, display);
}
function click2() {
OXCache.newRequest(null, "contacts", {
objects: menuselectedobjects,
columns: ["telephone_business1"]
}, null, call);
}
function display(data) {
for (var i = 0; i < menucountselected; i++)
alert(data.objects[i].last_name);
}
function call(data) {
alert("Now, a SMS to " + data.objects[0].telephone_business1 +
" could have been sent");
}
Embedding external webapps which require authentication (works with OX 6.16 and higher)
In other examples on this page/wiki, you learned how to extend the settings tree with your own links to external web sites or similar. But often it is required to login into such external web applications with some credentials. In many situations, the OX credentials and the credentials for the external web app are the same. So it would be an improvement for the OX user to be automatically logged in to this webapp when clicking some link within OX settings tree.
To achieve this functionality, we introduced a new servlet in OX version 6.16 and higher with some kind of "Single Sign On" functionality, which is reachable at path "/ajax/sso" only via HTTPS (INFO: HTTP connections will NOT work). This servlet can be used to retrieve the following data from the user which uses the OX GUI:
"login" -> The string which was entered at OX login screen. "imap_login" -> The string which was provisioned into the OX account as "imaplogin. This is used to authenticate against the primary IMAP/Mail Account. "username" -> OX internal username which was choosen by the administrator of the OX context/setup. "password" -> The password of the user. "context_id" -> OX internal number which references the context where the user resides in. Specified by the administrator at OX context creation. "context_name" -> OX internal string which references the context. Specified by the administrator at OX context creation.
Basically, you have to extend the settings/configuration tree in OX to contain a custom link/button where the user can click on. If this link is clicked, you have to call the SSO servlet with the session-id of the current user. Once you called the servlet, it will send some response with a json object which contains the needed data explained above. You can then use this data to "POST" to your external Webapplication Login URL, once your Webapplication has authenticated the POST request, it should redirect the request to its main application. In this case, the OX user is now successfully logged in to your external web application with just a click instead of entering his credentials again.
Here is an example, how to call the SSO servlet:
//this will fetch needed infos for redirecting
function callExtAPP(){
ox.JSON.get("/ajax/sso?action=get&session="+session, function(reply) {
username = reply.data.username;
password = reply.data.password;
login = reply.data.login;
});
}
You can call this function for example on a "onClick" event, which was triggered by an OX user who clicks some link in the configuration/settings tree.
Customizing the Help, Logout, examples UWA link, Session Expired and Direct Link locations / URLs
If you need to change or customize the Help, Logout, Session Expired or Direct Link locations / URLs you can use the following variables and parameters. You can set them anywhere within your plugin. If not set, the system defaults will be used. Don't use the expression 'var' as this is publicly available.
// the base path for the help pages
help_location = "[protocol]://[hostname][path]/help/[language{1}]/";
// the redirect url after logout logout_location = "[protocol]://[hostname][path]";
// the redirect url if the session expires sessionExpired_location = "[protocol]://[hostname][path]";
// the direct link url, used in the infostore detail views and the new e-mail window // note: do not remove or modify the part "#m=[module]&f=[folder]&i=[object_id]", otherwise direct links won't work anymore directLink_location = "[protocol]://[hostname][path]#m=[module]&f=[folder]&i=[object_id]";
// example for the UWA link from the UWA-Module settings page // The text between %s%s gets shown as href for the given link uwaLink.text = "Please have a look at the %sInteresting UWA modules%s page. It shows a list of widgets and their associated data." uwaLink.link = "http://www.open-xchange.com/index.php?id=361&L=[language{0}]"
As you can see you can use place holders, similar to other programming languages. These place holders will get parsed and replaced by the OX application. Here comes a short description of some of them:
[protocol] = the current used protocol - e.g. http or https
[hostname] = the hostname - e.g www.myox.de
[path] = the path (if any) behind the hostname - e.g. /ox6/ - or empty if not used
[file] = the file parameter (if any) - e.g. ox.html
[language{0|1}] = the users language - e.g. de_DE, where {0} is the language iso code and {1} the country iso code
[context_id] = the users context id
[timezone] = the users timezone - e.g. Europe/Berlin
A full set of available parameters will follow soon. Note: The parameters [module], [folder] and [object_id] are only available at the directLink and can't be used anywhere else.
Help Menu
It is possible to add entries to the pop-up menu of the help button in the top right corner. The following is a simple example which opens a language-specific help page:
var label = { de_DE: "Hilfe", en_US: "Help", fr_FR: "Aide" };
HelpMenu.addText(label[config.language || "en_US"], displayLink);
function displayLink() {
open("/help/" + config.language);
}
The manual handling of the label is required until proper support for the internationalization plug-in is implemented.
Custom widget for the sidebar ( works with OX 6.18.2 and higher )
The sidebar has the possibility to add own content for example, advertising, upsell or help. This available aera is equal to the per default shown mini calendar. The custom widget can be added to the contend below, above and as replacement for the mini calendar::
// create the widget
var swidget = new ox.gui.Custom(function() {
this.dom.node.innerHTML = "Hey, I'm an custom widget!";
}, "custom-widget").
css({ backgroundColor: "lightyellow", border: "1px solid #fc0",
padding: "5px", lineHeight: "11pt", height: "100%" }). setLayoutParam({ position: "bottom", height: "50px" });
// insert widget into the sidepanel on the given position
// 3 = above mini-cal, 1 or 2 = below mini-cal
ox.widgets.sidepanel.insert(swidget, 3);
//trigger validate to force repaint
ox.widgets.sidepanel.validate();
// optional: remove comment to permanently disable the mini-calendar
// ox.widgets.miniCalendar.disable();
// ox.widgets.miniCalendar.hide();
Events
It is possible to hook in some Events of the Frontend, here an autogenerated list of a small for...if:
LanguageChanged LanguageChangedInternal OX_Configuration_Changed OX_Configuration_Loaded OX_Refresh OX_Configuration_Loaded_Complete OX_Login Loaded Loading OX_Show_Help_Panel OX_Show_Help OX_Show_About LoginPageLoaded OX_Folder_Cleared OX_SELECTED_ITEMS_CHANGED OX_menu_Change_Height OX_Switched OX_Mail_Move OX_Calendar_Move OX_Contact_Move OX_InfoStore_Move OX_Task_Move OX_Object_Move OX_Mail_Copy OX_Contact_Copy OX_Object_Copy OX_Configuration_Switch_Folder_View OX_Direct_Linking OX_GLOBAL_CLICK OX_menu_After_Change_Height OX_menu_RESIZE OX_New_Error OX_New_Info OX_Configuration_Set_Empty OX_Switch_Module OX_Switch_View OX_Selected_Nested OX_Selected_Draft Selected Confirmation_Changed SubSelected SubSelectedTeamMember OX_Selected_Member OX_Lockable OX_Change_InfoStore_Detail_View OX_Change_Language OX_Execute_Function OX_Calendar_Change_Confirm OX_Calendar_Team_Add_Team OX_Task_Change_Confirm OX_Task_Standard_Search Preload OX_Configuration_Load_Foldertree OX_Portal_Click_Item OX_NEW_MAIL OX_Mail_Reply OX_Mail_ReplyAll OX_Mail_Forward OX_Mail_Edit_Draft OX_Mail_Change_Structure updateAllNewMailNumbers_Created OX_Mail_Delete OX_Mail_SaveMail OX_Attachment_Open OX_Attachment_Open_Nested OX_Attachment_Save OX_New_OXObject OX_Calendar_Edit OX_Calendar_Delete _IE_resize_complete OX_Calendar_Switch_Detail OX_Contact_Edit OX_Contact_Duplicate OX_Contact_Delete OX_Contact_SendVCard OX_Contact_Switch_Detail cb_abstact_email1 sendMailToContact OX_Changed_DefaultIMAP_Unread OX_Tasks_Switch_Split_Detail OX_Task_Delete OX_Task_Edit OX_Task_Duplicate OX_Object_Add_Attachment OX_Create_Object OX_Configuration_GUI_Changed OX_Save_Configuration OX_Configuration_Settings_Changed_Language OX_Configuration_Settings_Changed_Timezone OX_Configuration_Settings_Changed_GUI OX_Configuration_Settings_Changed_Mail OX_Configuration_Settings_Changed_Modules OX_Configuration_Settings_Changed_Calendar_Notification OX_Configuration_Settings_Changed_Task_Notification OX_Configuration_Settings_Changed_Region_Date OX_Configuration_Settings_Changed_Tree OX_SELECTION_CHANGED_CONFIRM OX_Show_Mail_Panel OX_Show_MiniCalendar OX_SELECTED_SUBSELECTION_CHANGED OX_Task_Search OX_Search_InfoStore OX_Configuration_Change_Right OX_Configuration_Move_Folder OX_Config_Folder_Changed OX_Show_Rights OX_Before_Create_Calendar OX_Before_Create_Contact OX_Before_Create_Distributionlist OX_Before_Create_Task OX_Before_Create_InfoStore OX_Teammember_Changed OX_Switch_InfoStore_Detail OX_SELECTION_CHANGED OX_Refresh_Mini_Calendar OX_Select_MiniMonth OX_Select_MiniYear OX_Dummy OX_Quota_Update Logout OX_Add_Flag OX_Mail_Flag OX_Mail_Spam OX_Mail_Ham OX_Mail_Show_Source OX_New_Search OX_Delete_Search OX_Print OX_Attachment_SaveInfoStore
Would be nice if some body could add some description to particular Events :-)