Oracle PCS Web Forms allow PCS developers to construct a web-based interface for users to interact with process instances. The Web Form comes out of the box with some basic UI components such as input fields, text areas, buttons, tables, etc. One frequently used web-based text editing tool: Rich Text Editor, however, is missing. We ran into this requirement in a recent customer engagement.
This post demonstrates one way to add a popular rich text editor to your Web Forms in a customized Workspace application. The implementation leverages popular Javascript frameworks such JQuery and Knockout. So this post might also serve as a general example for customizing PCS Workspace applications using these common web UI frameworks.
The Oracle PCS Workspace web application allows users to start process instances and work with user tasks. While the out of the box Workspace application is not customizable, PCS does provide a set of Workspace components for embedding and customization. These components include common Workspace functions such as application list, task list and task details. You can download the entire set of Workspace components from your PCS instance, install them as a single web application on your own web server and run it as your own Workspace web application. More information on the Workspace components can be obtained at
The downloaded Workspace components are organized into a demo called Cookbook. We will customize this Cookbook demo to add our rich text editor.
PCS Workspace components are implemented using Oracle Javascript Extension Tools (JET). JET is based on popular Javascript frameworks RequireJS, JQuery and Knockout. Knowledge in these frameworks is a prerequisite for working with Workspace components. More information on Oracle JET:
http://www.oracle.com/webfolder/technetwork/jet/globalExamples.html
CKEditor is a Rich Text Editor that has both open source and commercial versions. It supports JQuery via its JQuery Adapter, which makes our implementation much easier.
To begin with, we know we cannot add the CKEditor component at Web Form design time in the PCS Composer because the CKEditor is simply not included in PCS. We have to add the editor to the web form at runtime. As a first step, we need to download the Workspace Components and deploy it on our own web server. The web server can be on-premise or in the cloud such as Oracle JCS. Now we have our own Workspace application and we are free to add the CKEditor to it.
This sample web application is built on top of the PCS Component application downloaded from PCS instance. After you expand the war file, the folder structure of the web app looks like this:
CKEditor is added to the js folder.
This is the bootstrap file for RequireJS. We add the path to CKEditor to the configuration so that RequireJS can find and load it.
This is the main container for PCS Components. We add a new <div> tag for our rich text editor and bind it to richtext module.
This is the view template of the Oracle JET design pattern called Model-View-ViewModel.
This is the view model for our rich text component. We will look at this file in detail below.
this.handleBindingsApplied = function(info) {
console.log('---> in RichTextEditorViewModel.handleBindingsApplied');
var richTextDiv = $('#richtext-div');
var mainContentObject = richTextDiv.parent().find('#mainContent');
mainContentObject.on("startform:loaded", showRichTextEditor);
mainContentObject.on("taskdetail:loaded", showRichTextEditor);
mainContentObject.on('mousedown', richEditorEventHandler);
}
After the Knockout binding is applied, the rich text view model finds the <div> tag with an id of "#richtext-div". This div tag is added to the cookbook.html. Then it finds its sibling <div> with an id of "#mainContent", which will be the container for PCS Components such as start form, task list and task detail.
Once the #mainContent is found, the view model sets up three event listeners.
function showRichTextEditor() {
var hiddenControl = $('[name=RichTextHidden]');
if (hiddenControl) {
var richTextValue = hiddenControl.val();
if (hiddenControl.length > 0) {
console.log('---> hiddenControl.id = ' + hiddenControl.get(0).id);
self.richEditor2 = CKEDITOR.replace( hiddenControl.get(0).id );
self.richEditor2.setData(richTextValue);
}
}
}
When the start form component and task detail component are loaded, this function is invoked. It searches for an object named "RichTextHidden" in the web form; gets its value; replaces it with the CKEditor and sets the CKEditor's value to the value of the original RichTextHidden field.
var setRichTextData = function() {
var richText = self.richEditor2.getData();
var hiddenControl = $('[name=RichTextHidden]');
hiddenControl.val(richText);
};
function richEditorEventHandler(event) {
if (event.target.innerText == "Submit") {
console.log('---> rich editor mousedown.');
setRichTextData();
}
}
When a user presses the Submit button, the rich text view model processes this event by saving the value of the CKEditor to the original RichTextHidden input field, so that the value is submitted back to the server as part of the form submission.
For testing purposes, we can construct a basic PCS process like the following:
We create two simple web forms. One as a start form, the other for displaying the rich text value enterred in the start form.
After the test PCS process is deployed, we can start our testing.
http://host:port/richtextweb/index.html
where host and port point to the server where your richtextweb application is deployed. You should see a page like the following:
Specify the PCS instance host and port along with user credentials and click "Apply".
Click on the Cookbook button in the top right corner of the index page. It should look like this:
Click on the "Rich Text Input" icon and it takes to the start form that we designed. However, notice the RichTextHidden input field on the form is now replaced with the CKEditor.
Enter something in the form and click submit.
After the start form is submitted and an instance of our test process is created, the process instance moves to the next human task. If you execute the second human task, you can view the values entered in the start form.
This post demonstrates a way to leverage Oracle JET technology to add additional UI components to PCS Web Forms.
Previous Post
Next Post