Custom Panels Reference

TruEdit provides support for custom panels for two purposes:

  • To present a custom user interface for Custom Metadata Data entry purposes.
  • To present a custom user interface for the invocation of a Custom Automation.

A Custom Panel is a web form that is displayed in an iFrame within the TruEdit application. In the case of a Custom Metadata Data entry panel, this form typically would be used to communicate with a third-party system to support selection of values for a TruEdit custom metadata field. In the case of a Custom Automation panel, the form typically would be used to facilitate the export of a job’s output file to a third-party system.

Configuring a Custom Data Entry Panel

A Custom Data entry panel can be hosted either on a third-party server or directly by TruEdit. When creating a Custom Metadata Field in the TruEdit Admin, if you set the Type to “Text”, one of the options in the Control drop-down menu will be “Data-entry Panel”:

You can then either enter a URL that points to where your panel is hosted:

Or, you can upload a zip file of your custom panel files (packaged as a standalone website whose default page is index.html):

Viewing a Custom Data Entry Panel Field

Once a Custom Metadata Field has been configured to present a Custom Data entry panel and that field has been associated with a TruEdit Profile, a user can access the custom panel either via the TruAuthor Check-in Dialog or via the Custom Metadata section of the Job Details Pane within the Web Client.

Fields that offer a Custom Data entry panel will display an associated icon that a user can click to invoke the iframe and load the Custom Panel. (We are working on adding support for presenting these custom metadata panels in the check-in dialog of the web client as well as in the other client applications where Custom Metadata can be edited.)

Custom Data Entry Panel Field in the TruEdit Web Client

Once a user enters edit mode:

The user can click the  icon to launch the iframe, and load the custom panel.

Custom Data Entry Panel Field in the TruAuthor Checkin Dialog

As in the Web Client, the user can click the icon to launch the iframe, and load the custom panel.

Configuring a Custom Automation Panel

A Custom Automation Panel can currently only be hosted on a third-party server, but we plan to support the ability for TruEdit to host these as well. To create an automation, you must use the TruEdit Rest API. We offer some example code for how this can be accomplished via our TruEdit WordPress Plugin that presents a custom panel within the TruEdit Web Client for sending a TruAuthor post to a WordPress server.

Viewing a Custom Automation Panel

Once a Custom Automation has been configured and that automation has been associated with a TruEdit Profile, a user can access the Custom Automation Panel via the context-sensitive menu on a job. If there are no Automations associated with the job’s profile, then this menu item will no be presented in the menu. Simply select the automation in the sub-menu to launch the iframe and load the custom panel.


TruEdit Custom Panel Communication via Events

Communication between a Custom Panel and the TruEdit application is performed via window.postMessage(). Using this technique, an event listener in TruEdit listens for messages emitted by the custom panel, and the custom panel can likewise register a listener for events emitted by the TruEdit application. Soon after a Custom Panel is invoked through the TruEdit user interface, your code can emit an event to the TruEdit Application to provide the custom panel with context-specific job details. Here’s how you would set up a listener for that in your custom panel’s javascript:

var formValues = null;
parent.postMessage("fetch_job_meta_data", document.referrer);
window.addEventListener("message", function el(e) {
    if (e.data && typeof e.data !== "string" && e.data.eventType === 'init') {
        formValues = JSON.parse(JSON.stringify(e.data));
        window.removeEventListener("message", el, false);
    }
});

When a user hits Submit or Cancel on a Custom Data entry panel, the form should send feedback to the TruEdit Application to either set or maintain the value for the corresponding field. Here’s an example that shows how to do that:

/**
 * A handler function to prevent default submission and run our custom script.
 * @param  {Event} event  the submit event triggered by the user
 * @return {void}
 */
var handleFormSubmit = function handleFormSubmit(event) {
    // Stop the form from submitting since we’re handling that with AJAX.
    event.preventDefault();
    
    // Call our function to get the form data. getFormValues() is not shown in this example.
    var data = getFormValues();
    
    // Send the data to the parent
    if (document.referrer) {
        parent.postMessage(data, document.referrer);
    }
};
var handleCancel = function handleCancel(event) {
    // Call our function to get the original data. getOldValue() is not shown in this example.
    var data = getOldValue();
    if (document.referrer) {
        parent.postMessage(data, document.referrer);
    }
};
/*
 * This is where things actually get started. We find the form element using
 * its class name, then attach the `handleFormSubmit()` function to the 
 * `submit` event and attach the `handleCancel()` function to the `cancel` event.
 */
var form = document.getElementById("theForm");
form.addEventListener("submit", handleFormSubmit);
form.addEventListener("cancel", handleCancel);

When a user hits Submit or Cancel on a Custom Automation panel, the form should send feedback to the TruEdit Application to log the results of the automation attempt. Here’s an example that shows how to do that:

/**
 * A handler function to prevent default submission and run our custom script.
 * @param  {Event} event  the submit event triggered by the user
 * @return {void}
 */
var handleFormSubmit = function handleFormSubmit(event) {
    // Stop the form from submitting since we’re handling that with AJAX.
    event.preventDefault();
    
    // Initialize the response.
    var data = {};
    data.action = "send";
    // Set data.success to true if the automation was successful or false if it was not.
    data.success = true;
    // Send the data to the parent
    if (document.referrer) {
        parent.postMessage(data, document.referrer);
    }
};
var handleCancel = function handleCancel(event) {
    // Initialize the response.
    var data = {};
    if (document.referrer) {
        parent.postMessage(data, document.referrer);
    }
};
/*
 * This is where things actually get started. We find the form element using
 * its class name, then attach the `handleFormSubmit()` function to the 
 * `submit` event and attach the `handleCancel()` function to the `cancel` event.
 */
var form = document.getElementById("theForm");
form.addEventListener("submit", handleFormSubmit);
form.addEventListener("cancel", handleCancel);

Confirming that the call to an Automation Form is coming from TruEdit

Since TruEdit is calling a Custom Automation Panel that is not necessarily hosted by TruEdit, developers of a Custom Automation Panel need to make sure that a call is legitimately coming from TruEdit. To support this verification process, the request for a remote form will include a URL parameter with a one-time token (x-Source-Verification-Token) supplied by the TruEdit Server. The recipient remote form can then securely call a method in the TruEdit API with the one-time token to verify the Web Client request (see /api/1/info/verifytoken (POST)).

If verification is successful, the form can proceed with it’s expected functionality; conversely, a verification failure indicates that it should not proceed. In either case, upon the verification attempt, TruEdit will discard the one-time token.

Examples

An example Custom Metadata Data-Entry Panel can be found at https://github.com/truedit/customMetadataDateEntryPanel_calculatorExample.

An example Custom Automation Panel can be found at https://github.com/truedit/tewppi.