An Introduction to Programmable Layouts
Programmable Layouts use server-side JavaScript to enhance your Content and Page Layouts so you can execute scripts at publish time that utilize Terminalfour's native Java API. They are most commonly used to provide a logic and flexibility over the output of content that is not possible using standard T4 Tags .
With Programmable Layouts, you can use your existing JavaScript skills to access powerful features within Terminalfour. Knowledge of Java will give you an added advantage since you can also call Java in the Programmable Layouts.
Here's an example of a Programmable Layout used in a Content Layout to determine the published content based on whether it's the first day of the month and what day of the week it is. A Content Type called 'News Item' contains five elements:
- Name - the name of the piece of content
- Title – the news item title
- News Review – a review of the previous month's posts
- Long News – a long-form version of the news item
- Short News – an abridged version of the news item
Check if a standard layout or a Navigation Object does the job
When the same results can be achieved using a standard layout, avoid using Programmable Layouts. Similarly, if you are using a Programmable Layout to mimic the functionality of existing Terminalfour features like Navigation Objects, Web Objects or Data Objects, then use those features instead of making life unnecessarily complicated.
Warnings about Programmable Layouts
This feature is very powerful. It is important that you follow the development best practice guidelines. We recommend thoroughly testing any code on a development environment before moving the code to a production instance.
Bad practice, poor techniques or code errors can negatively impact system stability and performance. The investigation and resolution of problems introduced by this feature may be outside your support agreement.
API changes
Programmable Layouts use the Terminalfour Java API (you'll need to log-in to the Community site to view) so when you upgrade Terminalfour to a new version, the API may change. This may cause your Programmable Layout code to no longer work so you will need to check them as part of your pre-upgrade testing
Publish times
Since Programmable Layouts execute during publish, they can impact publish performance. Always evaluate the publish times using the Publish Reports both before and after the Programmable Layout is added to ensure that it does not negatively impact the publish time. Using the caching features available within the API is important. When executing the same script multiple times it is possible to add the information to the publish cache. Both techniques will have a positive impact on performance.
Sanitizing input
Sanitizing the input for Text and HTML elements in Programmable Layouts must be implemented in the Programmable Layout itself.
Logging
When editing or creating Programmable Layouts, check the Tomcat catalina.out log file for errors generated during preview and publish. If there are errors being generated to the logs, this can fill the log files and server space quickly.
It's helpful to have errors printed to your pages in a standardized format. While you may not want to do this is in production you should do this in a testing environment, e.g.,
catch (exception) {
document.write ("An error occurred publishing this page: " + exception);
}