edit.html for Custom Content Forms
The edit.html
file is where the custom content form
implementation begins. It is a mandatory file. This file is called to load the custom
content form within the iframe when creating or editing a content item. In general it
deals with HTML markup, styles, and code implementation needed for rendering the content
item fields and metadata. This file loads the content-form-sdk-1.0.js
JavaScript library to communicate with the content item page in the user interface. This
file also handles notifying field value changes to the user interface and listening to
the updates from the interface. The default implementation of this file in starter form
renders system metadata field editors of the item. This can be edited to include
type-specific field editors or to alter system field editors as needed.
Import the SDK Library
Oracle provides a JavaScript API for the custom form residing in an
iframe element to communicate with the content item edit page in the user interface.
So this library should be included in edit.html
. Load the
content-form-sdk-1.0.js library using either the
<script>
tag or requireJS
. This SDK has
a global object called contentFormSDK.
Using the <script> Tag
<!-- load the content form SDK -->
<script src="/documents/static/gemini/api/content-form-sdk-1.0.js"></script>
Using requireJS
<!-- using requireJS -->
<script>
requirejs.config({
paths: {
contentFormSDK: '/documents/static/gemini/api/content-form-sdk-1.0'
}
});
require(['contentFormSDK'],
function (contentFormSDK) {
});
</script>
Initialize the Form
Invoke contentFormSDK.init()
and pass a callback
function to initialize the form and start communicating with the interface. This
callback function will be called with an instance of the SDK when the user interface
is ready to render the form. With the SDK instance, the item being created or edited
can be accessed, and the custom form code can communicate with the interface.
Below is the sample callback function initForm
.
<script>
/* globals contentFormSDK */
(function() {
function initForm(sdk) {
// type
var type = sdk.getType();
// item being rendered in the form
var item = sdk.getItem();
// current locale of the UI
var locale = sdk.getLocale();
// fields of the item
var fields = item.getFields();
// item properties
var itemProps = item.get();
}
// this is the entry point to initialize the form sdk.
contentFormSDK.init(initForm);
})();
</script>
Get and Set Item Name and Description
The item name and description can be obtained from the
item.get()
method . When they are set in their respective
editors, the change event listeners of the editors can set their updated value in
the item by calling item.setName()
and
item.setDescription()
as shown in the following sample.
// item properties
var itemProps = item.get();
// name field
var nameField = itemProps.name ? itemProps.name :'';
nameField.addEventListener('change', function(e) {
item.setName(nameField.value);
});
//description field
var descField = document.getElementById('description-input');
descField.value = itemProps.description ? itemProps.description : '';
descField.addEventListener('change', function(e) {
item.setDescription(descField.value);
});
Get and Set Field Values
Custom fields can be obtained from the item.getFields()
method. It returns an array of field objects. These field objects help access field
values and modify them.
// fields of the item
var fields = item.getFields();
fields.forEach(function(field){
var fieldDefn = field.getDefinition(),
fieldName = fieldDefn.name,
dataType = fieldDefn.datatype;
// handle updating a field of datatype 'text'
if(dataType === sdk.dataTypes.TEXT){
var titleInput = document.getElementById('title');
titleInput.value = field.getValue() ? field.getValue() : '';
titleInput.addEventListener('change', function(e) {
field.setValue(titleInput.value);
});
}
});
Validating System and Custom Field Values
Validating field values is optional. If you would like to validate values before setting values in the item or field, you can invoke their respective validate methods to check if the value is valid. These validate methods work similar to the validation in out-of-the box content forms.
// validating name of the item
var nameField = document.getElementById('name-input');
nameField.value = itemProps.name ? itemProps.name : '';
nameField.addEventListener('change', function (e) {
item.validateName(nameField.value).then(function (validation) {
if(validation && validation.isValid) {
// set name of the item
item.setName(nameField.value);
} else {
// display name validation error
}
}).catch(function (error) {
// handle error
});
});
// validating a field value
var titleInput = document.getElementById('title');
titleInput.value = field.getValue() ? field.getValue() : '';
titleInput.addEventListener('change', function (e) {
field.validate(titleInput.value).then(function (validation) {
if(validation && validation.isValid) {
field.setValue(titleInput.value);
} else{
//display field validation error
}
}).catch(function (error) {
// handle error
});
});
For multi-valued fields, when you want to validate values for a specific
index, you can pass an additional parameter {index:
<index>}
.
field.validate(value, {index:2}).then(function (validation) {
// handle validation result
});
Validating Form
Content form SDK provides a mechanism to implement custom validation of the
form by registering a validation callback function. This can be done via
sdk.registerFormValidation(callback)
. If such registration and
callback function is present, then the callback function will be invoked from the
interface when the form is saved. This callback function should handle form validation
and return whether or not the form is valid.
var item;
function initForm(sdk) {
item = sdk.getItem();
// validation callback registration
sdk.registerFormValidation(validateForm);
// ... rest of the form init code
}
function validateForm() {
var isValid = true,
message = '';
if (!item.get().name) {
isValid = false;
message = 'Name is required'
}
return {
isValid: isValid,
message: message
}
}
Previewing Assets from the Form
Content form SDK provides an option to preview other assets that the item
references. This can be done by invoking sdk.previewAsset({id:
<assetId>})
and passing an id of the asset you want to preview.
This opens up the asset in preview drawer.
sdk.previewAsset({id: <asset_id>});