Configuring an element and how it works on a form
Having written the Javascript and created the required files in your Git repository, and then successfully imported your package so that an Element is available for use, you have done the difficult bit!
Where Elements can be used
Elements can be made available for use in the following pages/forms:
- Landing page
- Object class
- create/edit view display form
- summary view display form
- standalone form
The configuration of an Element in all of the above places is the same.
Example: Elements on the Landing page
The following screenshots show Elements on the Landing page.
Below, you can see that there are numerous Elements available in the side panel, and two of them have been dropped into a section on the Landing page. It is worth noting that, if needed, the same Element can be used more than once on the page.
| Drag the required Element onto the page and click on it. Element Details will be shown in the side panel. The Element properties as seen in the right hand image, are input fields that are generated from each of the parameter objects. These were shown in the article entitled "Everything you need to create an Element" (Git repository requirements) For example, in this case, parameter_name is "end_point" and parameter_description is the text shown below the input field - "Enter the API base url to be used". The paremeter_type is a string, so free text entry. The information typed here will be passed to the application iframe as part of the message data*. You will need to configure the height for the Element. This is measured in pixels. Save the page and check the position and size of the Element. |
On the Landing page itself, the pie chart is being used to show the total number of tasks in the system as a percentage for each status: Completed, Outstanding and Overdue.
Message data passed to the application
The below shows the *message data being passed to the application. The endpoint is populated with the URL of the instance so that the API calls used in rendering the Element are sent to the correct place.
const messageData = {
user_details: {
access_token: "",
first_name: "",
last_name: "",
user_id: 1,
user_name: ""
},
object_record_meta: {
class_id: undefined,
record_id: undefined,
},
endpoint: "https://conference.autologyx.com",
component_parameters: [
{
parameter_description: "Enter the API base url to be used",
parameter_name: "end_point",
parameter_type: "string",
parameter_value: "/api/tasks/"
}
],
parameters: {
end_point: "/api/tasks/",
}
}The class_id and record_id are undefined as this Element is being used on the Landing page. When this same Element is used on an object class form, these ids are passed in as part of the object_record_meta in the messageData.
In this example, the Element is using the record_id to fetch all the tasks relating to this record and displaying the statuses in the donut chart.
const messageData = {
user_details: {
access_token: "",
first_name: "",
last_name: "",
user_id: 1,
user_name: ""
},
object_record_meta: {
class_id: 265,
record_id: 17521,
},
endpoint: "https://conference.autologyx.com",
component_parameters: [
{
parameter_description: "Enter the API base url to be used",
parameter_name: "end_point",
parameter_type: "string",
parameter_value: "/api/tasks/"
}
],
parameters: {
end_point: "/api/tasks/",
}
}
How the message data is received
The message data is passed from Catalyst into the iframe which is running the Element code. In order to receive this message data and have Elements working in your system, you need an event listener.
We have used a hook in our react code to make this work; see the example code below.
import { useState } from "react";
import { MessageData } from "../types/interfaces";
export const useMessageData = () => {
const [messageData, setMessageData] = useState<MessageData | undefined>();
window.addEventListener("message", (event) => {
const messageData: MessageData = event.data || {};
if (messageData.user_details) setMessageData(messageData);
});
return {
messageData,
};
};Whenever the value associated to the message changes, the event listener triggers. The data is saved into the messageData variable. The access token expires every 5 minutes; it is automatically re-passed to the iframe and the message data is updated.
Watch this space for some helpful boilerplate code to help you create and configure your own Elements.