Adding a Rich Text Editor Component to Oracle PCS Web Form
September 30, 2017 | 7 minute readIntroduction
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.
Workspace Components
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.
Oracle JET
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
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.
Design
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.
- To minimize intrusion into PCS component HTML templates and Javascript modules, we will create our own richtext view template and view module.
- To know when to add the CKEditor to our web form, we will use an input field with a special name on the web form. At runtime, if this special input field for rich text exists in the web form, we will replace it with our CKEditor.
- Finally, we need a way to send the rich text values back to the web form. To do that, we will leverage the JQuery event feature to catch the submit action and set the value from the CKEditor instance to the rich text input field in the web form before the web form is submitted to the server.
Implementation
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.
js/main.js
This is the bootstrap file for RequireJS. We add the path to CKEditor to the configuration so that RequireJS can find and load it.
js/demo/v1.3/cookbook.html
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.
js/richtext.html
This is the view template of the Oracle JET design pattern called Model-View-ViewModel.
js/richtext.js
This is the view model for our rich text component. We will look at this file in detail below.
Setup event listener first
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.
- Events "startform:loaded" and "taskdetail:loaded": when the the start form and task detail components are loaded into the page, the view model replaces the rich text input field with our CKEditor.
- Event "mousedown": when a user clicks the submit button, the view model gets the value entered by user in CKEditor and sets it to the rich text input field so that it can be submitted back to the server as part of the form submission.
Add CKEditor to the web form
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.
Handle form submission event
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.
Simple PCS Process for Testing
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.
Test
After the test PCS process is deployed, we can start our testing.
Access the home page of the downloaded the PCS Component web app.
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".
Access the Cookbook demo
Click on the Cookbook button in the top right corner of the index page. It should look like this:
Access the start form
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.
Viewing form values
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.
Conclusion
This post demonstrates a way to leverage Oracle JET technology to add additional UI components to PCS Web Forms.
Siming Mu
Previous Post
BI Cloud Connector – Download Data Extraction Files from Oracle Fusion SaaS
Next Post