Type of Submission: Article Title: IBM Case Manager Subtitle: Supporting Display of Long Date Format in ICM 5.2.1 using a Custom Plugin Keywords: scripts, customizing, widgets Author: Chad Lou Job Title: Senior Software Engineer, IBM Case Manager and Enterprise Content Management Email: [email protected] Bio: Senior Software Engineer of the IBM Case Manager Client. Company: IBM Contributor: Brent Taylor Job Title: Senior Software developer, IBM Case Manager Client Email: [email protected] Bio: Developer of the IBM Case Manager Client action framework. Company: IBM Contributor: Brett Morris Job Title: Architect, IBM Content Navigator Email: [email protected] Bio: Architect of IBM Content Navigator product Company: IBM Contributor: Lauren Mayers Job Title: Architect, IBM Case Manager Email: [email protected] Bio: Architect of the IBM Case Manager product Company: IBM Contributor: Yajie Yang Job Title: Development Manager, IBM Case Manager Email: [email protected] Bio: Development Manager of the IBM Case Manager product Company: IBM Abstract: This article describes a custom plugin to display long date format in IBM Case Manager client application. Supporting Display of Long Date Format in ICM 5.2.1 using a Custom Plugin Chad Lou, Brent Taylor, Brett Morris, Lauren Mayes, Yajie Yang Introduction IBM Case Manager (ICM) is a web-based solution that helps customers streamline the creation and management of case workflow. ICM 5.2.1 is built on the IBM Content Navigator (ICN) framework. Many customers have required the ability to display dates in long format. The ICN team designed and provided a plugin, which essentially redefines valueFormatter to use a long format as the default in ICN. This enhancement works for ICN widgets as well as ICM widgets based on or which extend from ICN widgets. These ICM widgets are: - In-basket - Case Doc - Case List However this plugin has no effect for dates in other places of ICM such as: - Case Information (Properties widget) - Case History - Case Comment - Case Toolbar - Case History Visualizer (CHV) One solution is to modify ICM code to display dates using ICN mechanism. However, the requirement came after ICM 5.2.1 is released. Aligning ICM with the ICN mechanism will be done in a future release. In the meantime, for ICM 5.2. 1, we still need to address this customer requirement. Also, dates are displayed in more than one way in ICM today, so enhancing ICM to be more consistent with ICN does not fully address all areas where dates are displayed. This article discusses an approach to provide the support by way of extending the custom plugin. Existing ICM Mechanism of Displaying Date/Time Let’s first look at how ICM displays Dates in ICM 5.2.1. ICM by default uses the short date format to display dates in our widgets. The Case History Visualizer (CHV) widget uses the medium date format, since the timeline field has limited width and must accommodate a varying amount of information. ICM has centralized the mechanism of displaying time format for ICM widgets in ICM 5.2. All time displaying routines go through icm.util.Util.js. There are 2 functions involved in displaying date/time in ICM. 1. formatLocaleDate 2. getLocaleDate These functions are defined in icm/util/Util.js. /** * get the date string based on format and plugin locale * primarily for CHV use * @private * @param date (object) or a UTC timestamp (string) * a javascript date object * @param format (object) * an object with date formatting settings * @return the text for displaying the date */ formatLocaleDate: function(date, format) { if (!date) { return ""; } if (typeof date == "string") { // assume date is a UTC stamp string date = dojo.date.stamp.fromISOString(date); } format.locale = ecm.model.desktop.valueFormatter.getLocale(); if (format.locale == "ar" && document.body.dir == "ltr") { var datePattern; if (format.formatLength == "full") { datePattern = "EEEE d MMMM y"; } else if (format.formatLength == "long") { datePattern = "d MMMM y"; } else if (format.formatLength == "medium") { datePattern = "dd/MM/yyyy"; } else { // short format or unspecified datePattern = "d/M/yyyy"; } format.datePattern = datePattern; } return locale.format(date, format); }, /** * get the date string based on date/time selector (default is both date and time) * convenience function for other widgets with fullYear to true and formatLength of short * @private * @param selector (string, optional) * can have value of either "date", "time" or "timestamp" (default) * @return the text for displaying the date */ getLocaleDate: function(date, selector) { var format = {selector: selector, fullYear: true, formatLength: "short"}; var formatLength = ecm.model.desktop.valueFormatter.formatLength; if(formatLength) { format.formatLength = formatLength; } return this.formatLocaleDate(date, format); }, ICN Plugin Mechanism of Displaying Date/Time in Long Format ICN is extensible using software modules created by third parties, called plug-ins. A plugin implements one or more of a group of extension interfaces defined for the application. These implementations then extend the system in some fashion according to the writer of the plug-in. ICN plug-ins are quite powerful in that they allow extension of the browser and services layers in a single plug-in. They also allow the configuration interface to be extended with plug-in specific configuration. An ICN Plugin can be developed using RAD, Rational Application Developer. Here are the component files of the plugin. The ICN plugin extends the browser layer and redefines the ValueFormatter javascript class. longDatePluginDojo/ValueFormatter.js formatValue: function(value, type, format) { ...... } else if (type == "xs:date") { if (!value || value == "") { formattedValue = ""; // explicit check for no date value } else { var date = stamp.fromISOString(value); if (date == null) { return ecm.messages.error; } if (this.locale == "ar" && document.body.dir == "ltr") { format = "d/M/yyyy"; } if (format) { formattedValue = locale.format(date, { locale: this.locale, selector: "date", datePattern: format }); } else { formattedValue = locale.format(date, { locale: this.locale, selector: "date", formatLength: "long", fullYear: true }); } } } else if (type == "xs:time") { if (!value || value == "") { formattedValue = ""; // explicit check for no time value } else { var date = stamp.fromISOString(value); if (format) { formattedValue = locale.format(date, { locale: this.locale, selector: "time", timePattern: format }); } else { formattedValue = locale.format(date, { locale: this.locale, selector: "time", formatLength: "long" }); } } } else if (type == "xs:timestamp") { if (!value || value == "") { formattedValue = ""; // explicit check for no datetime value } else { var date = stamp.fromISOString(value); if (this.locale == "ar" && document.body.dir == "ltr") { format = "d/M/yyyy h:mm a"; } if (format) { formattedValue = locale.format(date, { locale: this.locale, selector: "date", datePattern: format }); } else { formattedValue = locale.format(date, { locale: this.locale, formatLength: "long", fullYear: true }); } } After the new ValueFormatter is defined, it needs to be activated and taken into effect. The activation is done by the following code in the plugin.js: Desktop.valueFormatter = new ValueFormatter(); Extending the Custom Plugin to support long date format in ICM The ICN plugin works in ICM 5.2 for Inbaskets, Case List widget, but does not work in CHV, Case Info, Case History, where ICM uses its own date ValueFormatter, with short date format. It is possible to update ICM code to utilize ICN valueFormatter to display dates in ICM. This would also work for Case Tasks tab, and for Custom Task Search. However this would require changes to ICM code, and would result in requiring a new release of ICM. The solution we chose is to provide the feature by extending the ICN plugin. The ICN plugin modifies the ICN method of displaying date. We also need to adapt the plugin to handle the date display in ICM. Our approach is to augment the custom plugin, and update the ICM date function at runtime. So this will essentially overwrite the existing logic in ICM and replace it with a new modified function. The update of the logic needs to be performed after the corresponding ICM code loads. It can be executed at other times, but the best time is after the user logs in to ICM/ICN. The ICN Desktop model provides an “onLogin” event, which is triggered after the login process completes. By connecting to this event method, we can add our ICM event handler function at the appropriate time. In the handler function, we update the ICM logic for getLocaleDate, and set its formatLength explicitly to “long”, in order to display dates in long format in ICM widgets. require(["dojo/_base/declare", "dojo/_base/connect", "dojo/_base/lang", "ecm/model/Desktop", "icm/util/Util", "pvr/widget/editors/StaticTextEditor", "longDatePluginDojo/ValueFormatter"], function(declare, connect, lang, Desktop, Util, StaticTextEditor, ValueFormatter) { if (Desktop.id == "admin" || !(window.icm && icm.util)) { // plugin in effect only for non-admin desktops, and when icm.util is loaded return; } Desktop.valueFormatter = new ValueFormatter(); connect.connect(ecm.model.desktop, "onLogin", function() { console.log("updating ICM API onLogin"); Util.getLocaleDate = function(date, selector) { var format = {selector: selector, fullYear: true, formatLength: "long"}; return this.formatLocaleDate(date, format); } var originalFunc = StaticTextEditor.prototype.formatValue; lang.extend(StaticTextEditor, { formatValue: function() { var controller = this.controller || this.property.controller; var oldSetting = controller && controller.get("formatLength"); if (controller && !oldSetting) { controller.set("formatLength", "long"); } lang.hitch(this, originalFunc)(); if (!oldSetting) { controller.set("formatLength", oldSetting); } } }); }); }); We now have a clean separation of ICN logic and ICM logic in the plugin, and only the public ICM API is modified or extended. Supporting Long Date format in ICM Property Widget The Case Summary widget contains a property widget that displays date fields. The adaptation for Case Summary is made in LongDatePlugin.js for StaticTextEditor of pvr. The dojo extend function updates or changes the existing prototype function of a javascript object. Here we only update one function of the StaticTextEditor class, namely formatValue. This function is called by _setValueAttr function of the widget to return the formatted value of a field. For the date fields in property widget, the above code first saves the existing value of “formatLength” setting, format the datetime field using long format, then restores the original value of “formatLength”. This way it does not change the “formatLength” setting globally, and would not have an adverse effect on other property fields which could be on different widgets in the same page. The modification of the logic for property widget will take effect on the following fields in Case Summary widget in ICM. • Modified On • Added On • Other date fields, such as Due Date. The first two are system date fields. The third kind covers the user-defined date fields. Usage of the Plugin To use the plugin, install the plugin jar file from the ICN admin desktop or in the admin view. There are no configurations needed for the plugin. After installing the plugin, refresh the ICM page to see dates in long format. Discussions It is better to update the logic in onLogin event, than when the plugin code is loaded. The reason is the plugin code may be loaded at a different time from when the ICM logic is loaded. If we were to update the ICM logic when the plugin loads, then we would be assuming that ICM plugin will load first, then our custom plugin loads. This may introduce an issue related with timing, and can be unreliable. There is no guarantee that one plugin may finish loading before another plugin. However, there is guarantee that when user logs in, the ICM plugin has already been loaded and executed, and the corresponding ICM objects have been created. The ICM override is performed when user logs in to ICM/ICN. This is one of the proper ways to extend ICN/ICM. The override is added as a hook to the ICN onLogin event. All plugins will be loaded prior to user login. The “onLogin” event is triggered even if user just refreshes the URL. This mechanism was used in the Sametime plugin to read the Sametime configuration settings. The logic update in the plugin does not affect the CHV widget, because the CHV widget does not use the getLocaleDate function to display date and time. For CHV, we will continue to use the existing ICM mechanism for displaying dates in medium format. The long format also displays the time zone information fully spelled out, customers may just want to show the month spelled out, and may or may not want to display the time zone info. One proposed approach is to have mechanism in ICN admin desktop to specify which fields to display. Conclusion Extending or overwriting an existing API is a common practice in javascript-based web applications. It is a recommended approach for enhancement of a released ICN/ICM product. With the custom plugin, when ICN shows a date field, such as in a grid, ICN now use the extended API in the plugin to show dates in ICN widgets. When ICM shows a date field, it will call the updated/overridden ICM API. We discussed a custom plugin that shows long date format in ICM client. It works for ICN widgets as well as ICM widgets, with the exception of CHV widget, which requires its own specific format. The LongDate plugin is further adapted to accommodate for Case Summary widget. It also shows long date format for Modified-on and Added-on fields as well, along with fields in other widgets, such as Case History and Case Toolbar. And the plugin works on top of ICM 5.2.1, without code modification to ICM base code.
© Copyright 2024