With the Copywriting Module, it's possible to bring any relevant data directly to your copywriting team as they work through copy tasks.
For general information on Copywriting Configurations, Layouts, and Fields, see our article Copywriting: Layouts & Fields.
In this article, we will talk through creating a custom Content Widget, details on connecting an API, testing your API, and deploying your Widget in copywriting tasks.
Creating Widgets
To get started on your Custom Content Widget, head to any Style Guide where a text-type production has been enabled.
If you don’t have a Configuration yet for Copywriting, click ‘Create new’; if you already have an existing Configuration, click ‘Edit’.
Once in the Configuration Builder, select ‘Add fields,' ‘Widget,’ then ‘Create Widget’.
By default, your Widget will be called 'External Content Viewer,' but you can rename it to be any string up to 256 characters.
It is possible to add multiple instances of External Content Viewers, and up to three can be utilized within any one layout.
Setup Menu
After naming the Widget, click ‘Continue’. You will then see the setup menu appear.
In the setup menu, you will find a number of required fields that must be entered in order to create your Custom Content Widget.
Setup Field | Requirement | Details |
API Secret Key |
Enter a new or existing API Secret Key into this field.
Note: It is possible to use the same API Key across multiple Widgets. |
|
API URL |
Enter your API URL here. |
|
Query Parameter |
Use the merge fields to add Product Properties as parameter variables for the request. |
|
API Requirements
The Custom Content Widget only supports JSON-formatted responses with text content in the form of Markdown or plain text.
⚠️ Important: You must follow the format and specifications below to get a successful response.
The response payload can contain 3 different types of element objects in an array.
“elementTitle” // a string rendered as a title inside the Widget at runtime.
“elementText” // provided in Markdown or plain text and rendered accordingly.
“elementImages” // an array of links to image files.
In order for the Custom Display Widget to work, the following JSON schema must be followed in the API response.
{
"metadata": {
"requestId": "c02f0f73-4665-4aae-aac1-c2fbc65365de",
"schemaVersion": "1.0.0"
},
"data": {
"title": "Here you can put a title", //optional
"elements": [{
"elementTitle": "Element 1 Title", //optional
"elementText": [{
"format": "markdown", //plain_text | markdown,
"value": "# This is the text value of a text element."
}
],
"elementImages": [{
"imageUrl": "https://www.domain.com/image_1.jpg",
}, {
"imageUrl": "https://www.domain.com/image_2.jpg",
}, {
"imageUrl": "https://www.domain.com/image_3.jpg"
},
]
}, {
"elementTitle": "Element 2 Title", //optional
"elementText": [{
"format": "markdown", //plain_text | markdown,
"value": "And here's the text value of another text"
}
],
"elementImages": [{
"imageUrl": "https://www.domain.com/image_4.jpg",
},{
"imageUrl": "https://www.domain.com/image_5.jpg",
},{
"imageUrl": "https://www.domain.com/image_6.jpg",
},{
"imageUrl": "https://www.domain.com/image_7.jpg",
},{
"imageUrl": "https://www.domain.com/image_8.jpg",
},{
"imageUrl": "https://www.domain.com/image_9.jpg"
}
]
}
]
}
}
Test Data Response
After filling in the fields, you can select ‘Test’ to check the external integration. After clicking Test, you will see the Data Response box appear.
Here, you will have two tabs: Preview and Raw Response to check the results.
Preview Tab
This tab will show the content rendered exactly as it will appear on the Task Page.
Raw Tab
This tab will show the content rendered in raw format (JSON) from the API response.
📝 Note: The request timeout to the external API is 20 seconds, and the response size must be less than 1 MB.
Response Outputs
If the request to the external API is successful, the response JSON will be parsed into the HTML of the widget and render the JSON elements in the following way.
All content in the JSON file will be presented generically in one single, scrollable view without adding any pagination or anything other than standard styling and positioning of the elements.
Images will be rendered as thumbnails, which can be clicked to open a full-screen preview.
Widget Deployment
Once you have completed configuring the Widget and have tested the test data response, select ‘Save’ on the settings box to apply the Widget to copywriting tasks.
After completion, you can save it as part of a specific Layout in a Copywriting Configuration and deploy it to a Copywriting Style Guide.
When working on a copywriting task, the copywriter will see the data generated from the widget as part of their task view for Productions using Layouts with the Widget:
📝 Note:
We currently support the following markdown elements: Heading, Bold, Italic, Blockquotes, Lists (Ordered/Unordered), Code Block, Link.
If an image is not possible for the widget to load, the image link will be shown, providing the option to access the image via the web browser instead.