Introduction
Oracle Documents Cloud Service provides a powerful REST API and embed tools allowing integrate with almost anything today. This section will cover a web text editor reading and sending html/text content to the Documents Cloud using basic javascript and JQuery. The first example covers the basic action to load a text area and send as a text file to the server. For the second example, the web editor will be the CKEditor and we can see the following steps covered in the example:
- Basic Authentication
- Download (GET) an existing file to the editor from the Documents Cloud
- Change the text and save (POST) to the Documents Cloud as a new revision
This post is the first of a series of different uses of the API for document creation and manipulation. Other features such as Document Picker will be covered in the future.
Main Article
Simplifying this example, I’ve removed complex scripts and functions and using basic authentication. The web editor component, CKEditor also has the minimal plugins and only basic features are covered, which you can change later in a more complex solution.
What you need?
- Access to a Oracle Documents Cloud instance (https://cloud.oracle.com/documents)
- A Web Server to host your custom HTML file
- Optionally download the 3rd party editor CKEditor (Any edition) from http://ckeditor.com
(The examples are using the CDN version) - Follow the steps and have fun
Preparing the environment
Each example is a single html file that you can use a web server to host.
For this example, we will create three HTML files, the hellodocs.html to test the environment, the simpletexteditor.html with just a textarea and the texteditor.html with the 3rd party CKEditor create Rich Text and send to the Documents Cloud.
Testing the environment
Test the access to the Documents Cloud UI by entering you username, password and identify domain. The address will looks like this: https://<DoCS_server>/documents. Optionally you can also enter in the address https://<DoCS_server>/documents/api to see the response from the server.
To make sure that your environment is ready, use this code to see if you can run JQuery and you have connectivity to your Oracle Documents Cloud instance:
$(document).ready(function(){
$("#hellodocs").click(function(){
var docsUrl = DoCSinstance.value + '/documents/api/1.1';
$("#test1").text('Loading!');
$.ajax ( {
type: 'GET',
url: docsUrl,
dataType: 'text',
beforeSend: function (xhr) {
xhr.setRequestHeader ('Authorization',
'Basic ' + btoa(DoCSuser.value + ':' + DoCSpassword.value));
},
success: function(data) {
$("#test1").text(data);
$("#editor1").val(data);
$("#status").text('Success');
},
error: function(jqXHR, textStatus, errorThrown) {
$("#status").text('ErrorMessage: '+ jqXHR.responseText);
$("#test1").text('Error: '+ textStatus, errorThrown);
}
} );
});
});
For the JQuery REST calls you need to have the correct setup to avoid CORS issues, or else you will experience 401 error messages.
Now include the following code to test the CKEditor:
<script src="//cdn.ckeditor.com/4.4.7/full/ckeditor.js"></script>
<script src="//cdn.ckeditor.com/4.4.7/full/adapters/jquery.js"></script>
<script>
$( document ).ready( function() {
$("#editor1").ckeditor();
} );
</script>
Full Hello World code here:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Hello DoCS</title>
<meta name="description" content="Hello Documents Cloud - by A-Team">
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
<script src="//cdn.ckeditor.com/4.4.7/full/ckeditor.js"></script>
<script src="//cdn.ckeditor.com/4.4.7/full/adapters/jquery.js"></script>
<script>
$( document ).ready( function() {
$("#editor1").ckeditor();
} );
</script>
</head>
<body>
<script>
$(document).ready(function(){
$("#hellodocs").click(function(){
var docsUrl = DoCSinstance.value + '/documents/api/1.1';
$("#test1").text('Loading!');
$.ajax ( {
type: 'GET',
url: docsUrl,
dataType: 'text',
beforeSend: function (xhr) {
xhr.setRequestHeader ('Authorization',
'Basic ' + btoa(DoCSuser.value + ':' + DoCSpassword.value));
},
success: function(data) {
$("#test1").text(data);
$("#editor1").val(data);
$("#status").text('Success');
},
error: function(jqXHR, textStatus, errorThrown) {
$("#status").text('ErrorMessage: '+ jqXHR.responseText);
$("#test1").text('Error: '+ textStatus, errorThrown);
}
} );
});
});
</script>
<h2>Hello Documents Cloud</h2>
<p>
Username: <input id="DoCSuser" type="text" value="tenant.user">
Password: <input id="DoCSpassword" type="password" value="userpassword">
</p>
DoCS Instance: <input id="DoCSinstance" type="text" size="36" value="https://tenant.documents.us2.oraclecloud.com">
<button id="hellodocs">DoCS Test</button>
<p id="test1">.</p>
<p id="status">Enter your username/password and Documents Cloud Instance to test</p>
<textarea cols="80" id="editor1" name="editor1" rows="10">
Some Text
</textarea>
</body>
</html>
With this simple code, your page will looks like this:
Cloud Text Editor
Only two REST calls will be used in the example, the Download File(/documents/api/1.1/files/{{file id}}/data)[GET] and the Upload File Version(/documents/api/1.1/files/{{file id}}/data)[POST].
Here you can find the code example of the text editor in the cloud integrated to the Documents Cloud:
[Example 1: simpletexteditor.html]
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Simple Documents Cloud Text Editor Example(Not really editor)</title>
<meta name="description" content="Simple Documents Cloud Text Editor (Not really editor)">
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
</head>
<body>
<script>
$(document).ready(function(){
$("#btnLoadDoc").click(function(){
var docsUrl = DoCSinstance.value + '/documents/api/1.1';
var strFileId = metadataFileId.value;
$("#status").text('Loading!');
$.ajax ( {
type: 'GET',
url: docsUrl + '/files/' + strFileId + '/data',
crossDomain: true,
xhrFields: { withCredentials: true },
beforeSend: function (xhr) {
xhr.setRequestHeader ('Authorization',
'Basic ' + btoa(DoCSuser.value + ':' + DoCSpassword.value));
},
success: function(data) {
$("#editor1").text(data);
$("#status").text('Document loaded');
$("#metadataInfo").text('');
},
error: function(jqXHR, textStatus, errorThrown) {
$("#status").text('ErrorMessage: '+ jqXHR.responseText);
$("#metadataInfo").text('Error: '+ textStatus, errorThrown);
}
} );
});
$("#btnSaveDoc").click(function(){
var docsUrl = DoCSinstance.value + '/documents/api/1.1';
var strFileId = (metadataFileId.value == '' ? '' : '/' + metadataFileId.value);
var strFileName = metadataFilename.value;
$("#status").text("Saving!");
var fileContent = new Blob([editor1.value], { type: 'text/plain'});;
var filePackage = new FormData()
filePackage.append('jsonInputParameters','{"parentID": "self"}');
filePackage.append('primaryFile',fileContent, strFileName);
$.ajax ( {
type: 'POST',
url: docsUrl + '/files' + strFileId + '/data',
enctype: 'multipart/form-data',
data: filePackage,
cache: false,
processData: false,
contentType: false,
crossDomain: true,
xhrFields: { withCredentials: true },
beforeSend: function (xhr) {
xhr.setRequestHeader ('Authorization',
'Basic ' + btoa(DoCSuser.value + ':' + DoCSpassword.value));
},
success: function(data) {
$("#status").text('Document Saved');
$.each(data, function(key, value) {
if(key == "version"){
$("#metadataVersion").text('Version: ' + value);
}
if(key == "id"){
$("#metadataFileId").val(value);
}
$("#metadataInfo").append(key + ': ' + value + '<br>');
});
},
error: function(jqXHR, textStatus, errorThrown) {
$("#status").text('ErrorMessage: '+ jqXHR.responseText);
$("#metadataInfo").text('Error: '+ textStatus, errorThrown);
}
} );
});
});
</script>
<h2>Simple Oracle Documents Cloud Text Editor sample</h2>
<p>
Username: <input id="DoCSuser" type="text" value="tenant.user">
Password: <input id="DoCSpassword" type="password" value="userpassword">
</p>
Documents Cloud Address: <input id="DoCSinstance" type="text" size="50" value="https://tenant.documents.us2.oraclecloud.com">
<p>
File Name: <input id="metadataFilename" type="text" size="10" value="">
File Id: <input id="metadataFileId" type="text" size="53" value="">
<span id="metadataVersion" style="color:blue">--</span>
</p>
<p></p>
<button id="btnLoadDoc">Load Text</button>
<button id="btnSaveDoc">Save Text</button>
<br>
<textarea cols="80" id="editor1" name="editor1" rows="10">
My First Documents Cloud text document
</textarea>
<p id="status">Enter your username/password and Documents Cloud Instance to test</p>
<p id="metadataInfo"></p>
<script>
$("#metadataFilename").val('mytext' + (Math.floor((Math.random() * 1000) + 1)) + '.txt');
$("#btnLoadDoc").prop('disabled', true);
$('#metadataFileId').on('input', function() {
$("#btnLoadDoc").prop('disabled', false);
});
</script>
</body>
</html>
/ / ]] >
// ]]>
Now including the 3rd party CKEditor:
[Example 2: texteditor.html]
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Custom Documents Cloud Text Editor Sample - by A-Team</title>
<meta name="description" content="Custom Documents Cloud Text Editor - by A-Team">
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
<script src="//cdn.ckeditor.com/4.4.7/full/ckeditor.js"></script>
<script src="//cdn.ckeditor.com/4.4.7/full/adapters/jquery.js"></script>
<script>
$( document ).ready( function() {
$("#editor1").ckeditor();
} );
</script>
</head>
<body>
<script>
$(document).ready(function(){
$("#btnLoadDoc").click(function(){
var docsUrl = DoCSinstance.value + '/documents/api/1.1';
var strFileId = metadataFileId.value;
$("#status").text('Loading!');
$.ajax ( {
type: 'GET',
url: docsUrl + '/files/' + strFileId + '/data',
crossDomain: true,
xhrFields: { withCredentials: true },
beforeSend: function (xhr) {
xhr.setRequestHeader ('Authorization',
'Basic ' + btoa(DoCSuser.value + ':' + DoCSpassword.value));
},
success: function(data) {
$("#editor1").val(data);
$("#status").text('Document loaded');
$("#metadataInfo").text('');
},
error: function(jqXHR, textStatus, errorThrown) {
$("#status").text('ErrorMessage: '+ jqXHR.responseText);
$("#metadataInfo").text('Error: '+ textStatus, errorThrown);
}
} );
});
$("#btnSaveDoc").click(function(){
var docsUrl = DoCSinstance.value + '/documents/api/1.1';
var strFileId = (metadataFileId.value == '' ? '' : '/' + metadataFileId.value);
var strFileName = metadataFilename.value;
$("#status").text("Saving!");
var fileContent = new Blob([$("#editor1").val()], { type: 'text/plain'});;
var filePackage = new FormData()
filePackage.append('jsonInputParameters','{"parentID": "self"}');
filePackage.append('primaryFile',fileContent, strFileName);
$.ajax ( {
type: 'POST',
url: docsUrl + '/files' + strFileId + '/data',
enctype: 'multipart/form-data',
data: filePackage,
cache: false,
processData: false,
contentType: false,
crossDomain: true,
xhrFields: { withCredentials: true },
beforeSend: function (xhr) {
xhr.setRequestHeader ('Authorization',
'Basic ' + btoa(DoCSuser.value + ':' + DoCSpassword.value));
},
success: function(data) {
$("#status").text('Document Saved');
$.each(data, function(key, value) {
if(key == "version"){
$("#metadataVersion").text('Version: ' + value);
}
if(key == "id"){
$("#metadataFileId").val(value);
}
$("#metadataInfo").append(key + ': ' + value + '<br>');
});
$("#btnLoadDoc").prop('disabled', false);
},
error: function(jqXHR, textStatus, errorThrown) {
$("#status").text('ErrorMessage: '+ jqXHR.responseText);
$("#status").text('Login Error: '+ textStatus, errorThrown);
}
} );
});
});
</script>
<h2>Oracle Documents Cloud Text Editor Sample</h2>
<p>
Username: <input id="DoCSuser" type="text" value="tenant.user">
Password: <input id="DoCSpassword" type="password" value="userpassword">
</p>
Documents Cloud Address: <input id="DoCSinstance" type="text" size="50" value="https://tenant.us2.oraclecloud.com">
<p>
File Name: <input id="metadataFilename" type="text" size="10" value="">
File Id: <input id="metadataFileId" type="text" size="53" value="">
<span id="metadataVersion" style="color:blue">--</span>
</p>
<p></p>
<button id="btnLoadDoc">Load Text</button>
<button id="btnSaveDoc">Save Text</button>
<br>
<textarea cols="80" id="editor1" name="editor1" rows="10">
My First <b>Documents Cloud</b> text document
</textarea>
<p id="status">Enter your username/password and Documents Cloud Instance to test</p>
<p id="metadataInfo"></p>
<script>
$("#metadataFilename").val('mytext' + (Math.floor((Math.random() * 1000) + 1)) + '.html');
$("#btnLoadDoc").prop('disabled', true);
$('#metadataFileId').on('input', function() {
$("#btnLoadDoc").prop('disabled', false);
});
</script>
</body>
</html>
Your page will looks like this:
Simple and powerful.
View of the Documents Cloud UI and the articles stored with the example:
You can also use with Inline editing with multiples editable regions:
And other more complex coding can use multiple instances of the editor with various documents cloud documents in the same page.
Conclusion
This article covers the basis of using the REST API of Documents Cloud, with a simple example of what you can do with Oracle Documents Cloud Service. With this you can expand to use more features for a complete solution fitting your needs, like browse an image in the repository and include in the text, create new files, share your documents with others and much more.
Reference
Oracle Documents Cloud Service info: http://cloud.oracle.com/documents
DoCS REST API: http://docs.oracle.com/cloud/latest/documentcs_welcome/WCCCD/odcs-restapi.htm
(3rd Party) CKEditor Documentation: http://docs.ckeditor.com
All content listed on this page is the property of Oracle Corp. Redistribution not allowed without written permission