![]() |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Version
WORK in PROGRESS
Table of Contents 1.2 What do you need to understand this book 7 3 Adapting the openCRX HTML GUI to Your Needs 9 3.1 Overview openCRX GUI Types 9 3.2 Customizing Options openCRX HTML GUI 10 3.3 Things to do before you start Customizing openCRX 11 3.4 Limitations of the generic HTML GUI 12 4.1.1 File Overloading at the Project Level 14 4.1.2 UI Configuration Overloading 14 4.1.3 Code Table Overloading 14 4.2 “Adding” Fields / Extending Objects 15 4.2.1 User-definable attributes of CrxObject 15 4.2.2 Property Data Bindings 16 5.1 Enabling/Disabling Packages at the Application Level 17 5.2 Enabling/Disabling Packages at the User Level 18 6.1 Enabling/Disabling Locales at the Application Level 19 6.2 Setting the Default Locale at the User Level 20 7 CSS, Headers, Footers, etc. 21 7.2 HTML Header and Footer Files 22 8.2 UI Configuration Overloading 23 8.5.1 Expanding/Collapsing Tabs 28 8.5.2 AdditionalElementDefinition 28 8.5.3 Base Filter for Grid Tabs 29 8.5.4 Selection of Filterable Attributes (maxMember) 31 8.5.5 Selection of Visible Attributes (showMaxMember) 31 8.5.6 Advanced Attribute Selection (showMemberRange) 31 8.6 Various XML Tags Explained 32 8.6.7 cssClassObjectContainer 33 8.6.21 orderObjectContainer 36 8.7.1.1 A comprehensive example with PropertyDataBindings 37 8.7.1.2 BooleanPropertyDataBinding 43 8.7.1.3 StringPropertyDataBinding 43 8.7.1.4 IntegerPropertyDataBinding 44 8.7.1.5 DecimalPropertyDataBinding 44 8.7.1.6 DatePropertyDataBinding 44 8.7.1.7 DateTimePropertyDataBinding 45 8.7.1.8 ReferencePropertyDataBinding 45 8.7.2 DataBinding ReferencedObjectDataBinding 45 8.7.3 DataBinding CompositeObjectDataBinding 46 8.7.4 DataBinding ProductConfigurationSet 46 8.7.5 DataBinding ProductConfigurationTypeSet 46 8.7.6 DataBinding LocalizedFieldDataBinding 47 8.7.7 DataBindings for Addresses 47 8.7.7.1 EmailAddressDataBinding 47 8.7.7.2 PhoneNumberDataBinding 48 8.7.7.3 WebAddressDataBinding 48 8.7.8 DataBinding AssignedActivityGroupsDataBinding 49 8.7.9 DataBinding DocumentFolderAssignmentsDataBinding 49 8.7.10 DataBinding FilteredActivitiesDataBinding 50 8.7.11 DataBinding FormattedFollowUpDataBinding 51 8.7.12 DataBinding FormattedNoteDataBinding 52 8.7.13 DataBinding JoiningListDataBinding 52 9.2.1 Adding Codes to Existing Code Tables 53 9.2.2 Disabling Existing Codes 53 9.2.3 Replacing Existing Code Tables 53 9.3 Segment-Specific Code Tables 53 10.1 MenuOps – openCRX Operations Menu 54 10.2 Navigation – openCRX Breadcrum 54 10.3 North – openCRX Header 54 10.4 RootMenu – openCRX Top Level Tabbed Menu 54 10.5 RootPanel – openCRX Top Level PopUp Menu 54 10.6 Search – openCRX Index-based Search 54 14 Advanced Customizing Options 58 14.5 Application Logic Extensions 58
List of Figures Figure 1: Types of openCRX GUIs 9 Figure 2: Non-Java GUIs for openCRX 9 Figure 3: openCRX Servlets enabling access with third-party clients 10 Figure 4: Customizing Options – openCRX Standard HTML GUI 10 Figure 5: openCRX Development and Customizing with Custom Project 13 Figure 6: UML Model - CrxObject 15 Figure 7: Add the string field Y!M nick to Contact objects 15 Figure 8: Wizard User Settings – enable/disable Root Menu Entries 18 Figure 9: Set Default Locale by Saving User Settings 20 Figure 10: Placement of attributes in the attribute pane (Tab, Group, Position) 25 Figure 11: Placement of grid tabs (Pane, -, Position) 26 Figure 12: Placement of attributes in grids (Level 0, Level 1, Level 2) 27 Figure 13: Sample Extension of class Product with PropertyDataBindings 41 Figure 14: Sample Extension of class Product with PropertyDataBindings 42 Figure 15: Property Set Extension 43
List of Listings Listing 1: UI Customizing File zorder_contact.xml 16 Listing 2: List of Packages in web.xml 17 Listing 3: Enabling/Disabling Packages in web.xml 17 Listing 4: Locales in web.xml 19 Listing 5: Activating/Deactivating Locales in web.xml 19 Listing 6: Active Locales in Login.jsp based on login-locales.jsp 20 Listing 7: UI Customizing File zorder_product.xml 38 Listing 8: Example AssignedActivityGroupsDataBinding 49 Listing 9: Example FilteredActivityGroupsDataBinding 50 Listing 10: Example FormattedFollowUpDataBinding 51 Listing 11: Example FormattedNoteDataBinding 52 Listing 12: Example JoiningListDataBinding 52 Listing 13: Example Adding a new code to an existing code table 53 Listing 14: Example Disabling of a code value 53 Listing 15: uiRefreshRate in web.xml 59 Listing 16: load-on-startup in web.xml 59 Listing 17: session-timeout in web.xml 60 Listing 18: transport-guarantee in web.xml 60
1 About this BookThis book describes various ways of customizing the openCRX AJAX HTML GUI to adapt the look and feel to your personal tastes and preferences or to your company's CI (corporate identity). openCRX is the leading enterprise-class open source CRM suite. openCRX is based on openMDX, an open source MDA framework based on the OMG's model driven architecture (MDA) standards. This guarantees total openness, standards compliance, a state-of-the-art component-based architecture, and virtually unlimited scalability. 1.1 Who this book is forThe intended audience are openCRX administrators and advanced users. 1.2 What do you need to understand this bookIt is helpful to have a good understanding of the openCRX architecture. We assume that you are able to read/understand the openCRX UML models and the openCRX Javadoc (Java API). It is also assumed that you are familiar with XML files and you should know how to program JSPs. 1.3 Tips, Warnings, etc.We make use the following pictograms:
2 PrerequisitesTo work through some of the examples and in particular to build your own customized openCRX, there are some prerequisites:
You can either follow the openCRX Server Installer documentation at http://www.opencrx.org/server.htm or you can do a manual installation of openCRX following the guide openCRX Manual Installation Tomcat 6.
Follow the openCRX SDK Installer documentation at http://www.opencrx.org/sdk.htm.
If you decide to
manipulate files directly in the apps folder, the same files are
contained in one of the subdirectories of the
directory 3 Adapting the openCRX HTML GUI to Your Needs3.1 Overview openCRX GUI TypesopenCRX is distributed with a generic but extremely powerful and feature-rich HTML-GUI (built with the Bootstrap framework) that works on any device. This AJAX-enabled HTML-GUI supports a wide range of modern browsers, including Chrome, Firefox, Opera, Safari, IE, etc. and it supports any device including mobile devices (iPhone, iPad, Android-based devices, etc.).
While this generic GUI has its strengths (entirely model-driven, light-weight, open and extensible), it also has its weaknesses (at times it can be hard to understand unless you are familiar with the openCRX UML model). While we are continuously enhancing the openCRX GUI, it is still a fact that it is nearly impossible to write a “one size fits all” GUI.
Another option you might consider is REST (Representational State Transfer); see also http://www.opencrx.org/opencrx/2.3/new.htm#REST and the openCRX Wiki (“How to use the REST servlet”). openCRX includes a set of servlets (caldav, ical, imap, vcard, rest, news, ...) allowing you to connect to openCRX with a wide range of specialized third-party clients like Mozilla Thunderbird, MS Outlook, SmartPhones, and others: Figure 3: openCRX Servlets enabling access with third-party clients 3.2 Customizing Options openCRX HTML GUIThe openCRX Standard HTML GUI can be customized in many ways to suit your needs: Figure 4: Customizing Options – openCRX Standard HTML GUI Basic customizing options are relatively straight-forward and require no (or only moderate) programming know how. Advanced customizing options, however, require a good understanding of the openCRX architecture. This guide covers basic customizing options. If you're interested in advanced customizing options, have a look at the source code or consider attending an openCRX Developer Workshop (see www.opencrx.org for more information). 3.3 Things to do before you start Customizing openCRXAdapting openCRX to your needs typically involves the following steps:
Obviously, if you're only interested in changing some of the colors, there is not much to do in step 2 above. However, if you plan to capture your companies business objects, business processes, forms, etc. with openCRX, it pays off to spend some time on collecting the requirements and then properly map them to openCRX before you get down to customizing...
3.4 Limitations of the generic HTML GUIEven though the openCRX HTML GUI is extremely flexible, we would like to point out a few limitations (not due to bad design, but rather we are looking at advanced features that have not been implemented yet). 3.4.1 Role-based UIopenCRX features UI perspectives, a mechanism that enables users to have different UI customizations based on the current role (e.g. one GUI for sales and another GUI for the back office). More information is available from http://www.opencrx.org/opencrx/2.3/new.htm#UIPerspectives. Obviously, the same goal can also be achieved with multiple web applications. Simply create a custom project for each role / customization and then deploy multiple web applications. 3.4.2 Model PermissionsModel permissions are not implemented yet. Hence you cannot control access to individual attributes of an object with simple customization (the openCRX security plugin controls access to complete objects, not to individual attributes of an object). You can, however, deploy multiple web applications or work with Layout JSPs to achieve the same goal. Alternatively, once the root admin (admin-Root) has defined a security policy, segment administrators can grant and/or revoke various GUI-level permissions . More information is available in the openCRX Admin Guide at http://www.opencrx.org/documents.htm. 4 Important HintsThe following information is so important that it deserves its own chapter! 4.1 OverloadingOverloading is a concept that allows you to selectively enhance (or even replace) features of the standard distribution of openCRX with your own changes and/or extensions.
Figure 5: openCRX Development and Customizing with Custom Project
4.1.1 File Overloading at the Project LevelTypically, files in your custom project will be added to the custom EARs. However, if a file in your custom project has the same name as a file of the standard distribution, your file will actually replace the respective file of the standard distribution when you build custom EARs.
4.1.2 UI Configuration OverloadingIt is likely that you want to change some of the default customizing. Quite possibly, however, (a) you want to make a few changes only and (b) you want to keep these changes if you upgrade to a new version of openCRX. This is where UI configuration overloading can add value. Instead of changing the original UI configuration files provided with the standard distribution you create a new configuration file (or multiple configuration files) containing all your changes. Make sure that you name your file(s) containing changed UI Element Definitions such that your changes are loaded AFTER the default configuration files, thereby overloading the original configuration. More information is available in chapter 8.2 UI Configuration Overloading. 4.1.3 Code Table OverloadingSimilar to UI configuration overloading, you can also overload code tables. Instead of changing original code tables you create new code table files that contain your changes/extensions. It is also possible to deactivate codes of the standard distribution. Make sure that you name your file(s) containing changed code tables such that your changes are loaded AFTER the default code tables, thereby overloading the code tables. More information is available in chapter 9.2 Code Table Overloading.
4.2 “Adding” Fields / Extending ObjectsEven though the openCRX UML Model covers a wide range of business objects, you may still want to “add” a field to a particular object. While the newbie's approach would be to add a field to the appropriate database table and then patch the code a bit here and there, take our advice and make use of the advanced extension mechanisms provided by openCRX. 4.2.1 User-definable attributes of CrxObject
To make an example, let's assume your Contacts absolutely need another String field to store the Yahoo! Messenger Nickname as shown below: Figure 7: Add the string field Y!M nick to Contact objects All you have to do to “add” the field Y!M nick to Contacts is to deploy the following UI customizing file zorder_contact.xml to the directory {TOMCAT_INSTALL_DIR}/apps/opencrx-core-CRX/opencrx-core-CRX/WEB-INF/config/ui/Root/en_US and then restart Tomcat. Listing 1: UI Customizing File zorder_contact.xml <?xml version="1.0" encoding="UTF-8"?> <org.openmdx.base.Authority
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
name="org:openmdx:ui1"
xsi:noNamespaceSchemaLocation="xri://+resource/org/openmdx/ui1/xmi1/ui1.xsd">
The above file is – strictly speaking – not adding a field to the class Contact, it is rather activating the attribute userString0 of the class Contact (which it inherits from the class CrxObject). The field userString0 is already available in the standard distribution of openCRX, it's just not visible by default.
4.2.2 Property Data BindingsWhat can you do if you need even more user-definable attributes, i.e. more than the ones provided by CrxObject? This is where the PropertyDataBinding concept comes in handy. With PropertyDataBindings you get access to a virtually unlimited pool of user-definable attributes. See chapter 8.7.1 PropertyDataBinding for a detailed introduction into this topic). 5 Managing Packages5.1 Enabling/Disabling Packages at the Application LevelWith the openCRX standard distribution all available packages are enabled. The openCRX administrator may wish to disable certain packages at the application level if they are not used. This chapter shows how you can achieve this. In the custom project sample, the package list is contained in the file: opencrx—custom\sample\src\data\org.opencrx.sample\WEB-INF\web.xml Once deployed on Tomcat, the package list is contained in the file apps\opencrx-core-CRX\opencrx-core-CRX\WEB-INF\web.xml Look for the section <!-- Admin --> to find a list of available packages: Listing 2: List of Packages in web.xml <!-- Admin
-->
You can disable packages by commenting them out (<!-- to open a comment and --> to close a comment). The following example shows how to deactivate the package depot1: Listing 3: Enabling/Disabling Packages in web.xml
...
5.2 Enabling/Disabling Packages at the User LevelThe most important personalization settings – including enabling/disabling of packages – are easily managed with the wizard User Settings. Navigate to your home page (click Home in the root menu) and then select Edit > User Settings from the main menu to start the User Settings Wizard.
6 Managing LocalesThe default installation of openCRX activates all locales that are included in the Open Source distribution. The openCRX administrator may wish to deactivate certain locales from the locale list. This chapter shows how you how to do this. 6.1 Enabling/Disabling Locales at the Application LevelThe locale list is contained in the file opencrx-core-CRX.ear\opencrx-core-CRX.war\WEB-INF\web.xml Look for the section <!-- locales --> to find a list of available locales: Listing 4: Locales in web.xml <!-- locales
-->
You can deactivate locales by simply commenting them out. The following example shows how to deactivate the locale de_CH. Listing 5: Activating/Deactivating Locales in web.xml <!-- locales
-->
As the Login page is displayed before the authentication of the user has taken place, Login.jsp cannot access the above information. That is why the list of available and active locales are maintained in the file login-locales.jsp as well. Changing the list of active locales is straightforward. Comment out any of the lines in the following code segment of localeSettings.jsp to disable the respective locale: Listing 6: Active Locales in Login.jsp based on login-locales.jsp ...
The above example shows how to disable the locales fa_IR and nl_NL in the Login page of openCRX.
6.2 Setting the Default Locale at the User Level
Figure 9: Set Default Locale by Saving User Settings If the login page supports a user's preferred locale xx_YY, you can request the login page in that locale xx_YY by appending the string "?locale=xx_YY" to the default login URL. Example: the following URL loads the German login page: http://demo.opencrx.org/opencrx-core-CRX/Login.jsp?locale=de_CH 7 CSS, Headers, Footers, etc.7.1 Cascading Style SheetsThe directory ...\opencrx-core-CRX\_style contains various CSS files:
Please note that various third-party modules (e.g. WYMeditor, wiky) may also load CSS files. Those files are typically located within the respective modules directory structure (e.g. .../javascript/wymeditor, .../javascript/wiky).
7.2 HTML Header and Footer FilesThe Layout JSPs and the login page (Login.jsp) by default include various HTML files. They are located in the directory ...\opencrx-core-CRX and you can adapt them to your liking:
See also chapter 13 Layout JSPs for additional information.
8 UI XML Files8.1 Overview8.2 UI Configuration Overloading8.3 InspectorThe inspector shows an object with its attributes:
8.4 Attribute Pane8.4.1 TabsThe ui file common.xml contains tab definitions that apply to all objects :
You can define your own tabs. The following example shows the definition of the tab [Accounts] of the attribute pane of accounts (ui file account.xml):
8.4.2 Field GroupsIn the ui file common.xml there are various default field groups defined that apply to all objects, e.g. Field Groups 0, 10, 20, and 30 in the the tabs [General] and [Details]. You can define your own field groups like shown in the following example:
8.4.3 Fields / AttributesWith order (or more specifically orderFieldGroup) you can define the positioning of an object's attribute in the attribute pane. You must provide three values in the form of <_item>xxx</item> where the first value corresponds to the id of the Tab, the second value to the FieldGroup and the third value to the position within the respective FieldGroup. The following example explains the placement of a contact's salutation: Figure 10: Placement of attributes in the attribute pane (Tab, Group, Position) With the tag <columnBreak>true</columnBreak> you can place the current attribute in a new column within the given Field Group.
8.5 Grid PanesShared and composite associations as well as multi-valued references are mapped to grids. Such grids can be positioned by providing three values in the form of <_item>xxx</item> where the first value corresponds to the id of the Grid Pane and the third value to the position within the respective Pane (the second value is not used). The following example explains the placement of an accounts composite association “member”: Figure 11: Placement of grid tabs (Pane, -, Position)
With order (or more specifically orderObjectContainer) you can define the positioning of an object's attribute within grids. You must provide three values in the form of <_item>xxx</item> where these values will used to define an (alphabetical) order. The following example explains the placement of a an address's usage: Figure 12: Placement of attributes in grids (Level 0, Level 1, Level 2)
|